@oharness/engine 0.7.0 → 0.8.0

package/dist/browser/session.js

@@ -0,0 +1,837 @@
+import { BrowserError } from "../core/errors.js";
+import { browserProviderFor } from "./provider.js";
+import { buildSnapshot } from "./snapshot.js";
+import { LoginImportMemory, externalBrowserName, hostInSite, listExternalSites, normalizeSite, readSiteLoginState, } from "./login-import.js";
+/**
+ * The browser, for the length of one agent session.
+ *
+ * Allocated for an agent session and launched at first use. That split is the
+ * point of this class: registering the tools has to be free, because most
+ * sessions never touch a browser and a scheduled routine that starts Chrome to
+ * run a shell command would be indefensible — but once a tool is called, every
+ * later call in the session has to land on the same browser, or a login on one
+ * step is gone by the next.
+ *
+ * It also holds the two things that make the tools usable rather than merely
+ * present: the ref table from the last snapshot, and the console and network
+ * rings. Those rings are why this exists at all for most users — the common
+ * errand is not "book me a flight", it is "open my dev server and tell me what
+ * the error is", and the answer to that is in the console.
+ */
+const CONSOLE_LIMIT = 200;
+const NETWORK_LIMIT = 200;
+function emptySide() {
+    return { refs: new Map(), wired: new WeakSet() };
+}
+/** How long a "is this site open in your browser?" answer is trusted. */
+const SUGGESTION_TTL_MS = 60_000;
+let sharedLoginMemory;
+export class BrowserSession {
+    /**
+     * Both browsers' state, each started only when first used. Everything below
+     * reads the one in use through the accessors, so a call that switches
+     * browsers finds the other one's tab, refs and origin exactly as it left
+     * them — the built-in browser keeps its page while the person's is used.
+     */
+    sides = { builtin: emptySide(), extension: emptySide() };
+    get side() {
+        return this.sides[this.mode];
+    }
+    get target() { return this.side.target; }
+    set target(value) { this.side.target = value; }
+    get starting() { return this.side.starting; }
+    set starting(value) { this.side.starting = value; }
+    get active() { return this.side.active; }
+    set active(value) { this.side.active = value; }
+    get pageStarting() { return this.side.pageStarting; }
+    set pageStarting(value) { this.side.pageStarting = value; }
+    get refs() { return this.side.refs; }
+    set refs(value) { this.side.refs = value; }
+    get wired() { return this.side.wired; }
+    set wired(value) { this.side.wired = value; }
+    get currentOrigin() { return this.side.currentOrigin; }
+    set currentOrigin(value) { this.side.currentOrigin = value; }
+    consoleLog = [];
+    network = [];
+    opts;
+    sessionId;
+    label;
+    /** The browser in use now. */
+    mode;
+    /** Which browsers this session may use. */
+    policy;
+    /** Said once, with the next tool result: a fallback the model should know about. */
+    notices = [];
+    importing = false;
+    probing;
+    suggestions = new Map();
+    constructor(opts = {}) {
+        this.opts = opts;
+        this.policy = opts.mode === "extension" || opts.mode === "auto" ? opts.mode : "builtin";
+        // Auto starts where a browser costs the person nothing: the built-in one.
+        this.mode = this.policy === "extension" ? "extension" : "builtin";
+        this.label = opts.label;
+    }
+    /** Name the conversation this browser works for. Read lazily, so it may change. */
+    setLabel(label) {
+        this.label = label;
+    }
+    /** Bind the lazily-created browser to its owning conversation. */
+    bind(sessionId) {
+        if (this.target || this.starting)
+            throw new Error("cannot rebind a running browser session");
+        this.sessionId = sessionId;
+    }
+    /** Whether a browser is running, without starting one to find out. */
+    get running() {
+        return this.target !== undefined;
+    }
+    /**
+     * The origin the permission engine asks about.
+     *
+     * Undefined before the first navigation, which is what makes the very first
+     * `browser_navigate` the call that gets asked: after that the origin is known
+     * and an approval for it covers the clicking and typing that follow.
+     */
+    origin() {
+        return this.currentOrigin;
+    }
+    async page() {
+        if (this.active)
+            return this.active;
+        // The pane asks for URL and viewport together, and models often batch
+        // browser tools. Until the first page has been adopted all of those calls
+        // can arrive here at once. Share that first lookup/creation so read-only
+        // callers cannot accidentally leave several about:blank tabs behind.
+        this.pageStarting ??= (async () => {
+            const target = await this.start();
+            const existing = await target.pages();
+            const page = existing[0] ?? (await target.newPage());
+            await this.adopt(page);
+            return page;
+        })();
+        try {
+            return await this.pageStarting;
+        }
+        finally {
+            this.pageStarting = undefined;
+        }
+    }
+    async start() {
+        if (this.target)
+            return this.target;
+        const side = this.mode;
+        // Concurrent first calls must not race two browsers into existence; the
+        // tools are concurrency-safe on paper and the model does batch them.
+        this.starting ??= (async () => {
+            const factory = this.opts.target ?? browserProviderFor(this.mode, this.opts.providers, {
+                headless: this.opts.headless ?? true,
+                ...(this.opts.logger ? { logger: this.opts.logger } : {}),
+            }).createTarget;
+            const target = await factory({
+                ...(this.sessionId ? { sessionId: this.sessionId } : {}),
+                ...(this.label ? { label: this.label } : {}),
+                ...(this.opts.cwd ? { cwd: this.opts.cwd } : {}),
+            });
+            this.target = target;
+            return target;
+        })();
+        try {
+            return await this.starting;
+        }
+        catch (err) {
+            // A failed launch must not poison the session: the person may be about
+            // to install a browser, or set OHARNESS_BROWSER_PATH, and try again.
+            this.sides[side].starting = undefined;
+            // Batched calls all wait on the one launch. Whichever got here first
+            // has already fallen back; the rest follow it rather than fail.
+            if (this.policy === "auto" && side === "extension" && this.mode === "builtin")
+                return this.start();
+            // In auto, the person's browser being out of reach is not the end of
+            // the task: the built-in one can do it, with its own sign-ins, and the
+            // model is told so it can say as much. The other way round is never
+            // taken on its own — moving into someone's signed-in browser is a
+            // choice the model makes in the open, and asks permission for.
+            if (this.policy === "auto" && side === "extension") {
+                this.mode = "builtin";
+                this.notices.push(`The user's own browser could not be reached (${errorText(err)}), so this ran in the built-in browser instead. Its sign-ins are separate from the user's.`);
+                return this.start();
+            }
+            if (this.policy === "auto" && side === "builtin") {
+                throw new BrowserError(`the built-in browser could not start (${errorText(err)}). To work in the user's own browser instead, call again with browser: "yours".`, err);
+            }
+            throw err;
+        }
+    }
+    /**
+     * Which browser a call that can open a page will use.
+     *
+     * Pure and synchronous, because the permission check asks it before the
+     * call runs: what is approved has to be what then happens. A fixed policy
+     * always answers itself. In auto, the call's own `browser` wins — the model
+     * reads the person's intent, and says "yours" when the task needs their
+     * accounts or a page they have open. Without one, the conversation stays in
+     * the browser it is already working in, so a task never changes browsers
+     * halfway and loses the page it was on.
+     */
+    sideFor(request) {
+        if (this.policy !== "auto")
+            return this.policy;
+        if (request)
+            return request === "yours" ? "extension" : "builtin";
+        return this.mode;
+    }
+    /** The browser in use now, and which ones this session may use. */
+    current() {
+        return { side: this.mode, policy: this.policy };
+    }
+    /**
+     * Move to the browser a call asked for, before it runs. A request a fixed
+     * policy cannot honour is answered with why, rather than ignored.
+     */
+    use(request) {
+        const side = this.sideFor(request);
+        if (request && this.policy !== "auto" && side !== (request === "yours" ? "extension" : "builtin")) {
+            this.notices.push(side === "builtin"
+                ? "Settings keep browser use in the built-in browser, so this ran there."
+                : "Settings keep browser use in the user's own browser, so this ran there.");
+        }
+        this.mode = side;
+    }
+    /** What the model has not been told yet. Each notice is handed out once. */
+    takeNotices() {
+        return this.notices.splice(0);
+    }
+    /** Make `page` the one the tools act on, wiring its log streams once. */
+    async adopt(page) {
+        this.active = page;
+        await this.target?.activate?.(page);
+        this.refs = new Map();
+        if (this.wired.has(page))
+            return;
+        this.wired.add(page);
+        page.on("Runtime.consoleAPICalled", (params) => {
+            const args = Array.isArray(params["args"]) ? params["args"] : [];
+            const text = args
+                .map((arg) => {
+                const record = arg;
+                const value = record["value"] ?? record["description"] ?? record["unserializableValue"];
+                return value === undefined ? String(record["type"] ?? "") : String(value);
+            })
+                .join(" ");
+            this.record(this.consoleLog, { level: String(params["type"] ?? "log"), text, at: Date.now() }, CONSOLE_LIMIT);
+        });
+        page.on("Log.entryAdded", (params) => {
+            const entry = (params["entry"] ?? {});
+            this.record(this.consoleLog, {
+                level: String(entry["level"] ?? "info"),
+                text: String(entry["text"] ?? ""),
+                ...(typeof entry["url"] === "string" ? { url: entry["url"] } : {}),
+                at: Date.now(),
+            }, CONSOLE_LIMIT);
+        });
+        page.on("Runtime.exceptionThrown", (params) => {
+            const details = (params["exceptionDetails"] ?? {});
+            const thrown = (details["exception"] ?? {});
+            this.record(this.consoleLog, {
+                level: "error",
+                text: String(thrown["description"] ?? details["text"] ?? "uncaught exception"),
+                at: Date.now(),
+            }, CONSOLE_LIMIT);
+        });
+        page.on("Network.requestWillBeSent", (params) => {
+            const request = (params["request"] ?? {});
+            this.record(this.network, {
+                requestId: String(params["requestId"] ?? ""),
+                method: String(request["method"] ?? "GET"),
+                url: String(request["url"] ?? ""),
+                at: Date.now(),
+            }, NETWORK_LIMIT);
+        });
+        page.on("Network.responseReceived", (params) => {
+            const response = (params["response"] ?? {});
+            const entry = this.network.find((item) => item.requestId === String(params["requestId"] ?? ""));
+            if (!entry)
+                return;
+            entry.status = Number(response["status"] ?? 0);
+            entry.mimeType = String(response["mimeType"] ?? "");
+        });
+        page.on("Network.loadingFailed", (params) => {
+            const entry = this.network.find((item) => item.requestId === String(params["requestId"] ?? ""));
+            if (entry)
+                entry.failed = String(params["errorText"] ?? "failed");
+        });
+        await page.send("Network.enable").catch(() => { });
+    }
+    record(ring, entry, limit) {
+        ring.push(entry);
+        if (ring.length > limit)
+            ring.splice(0, ring.length - limit);
+    }
+    async navigate(url) {
+        const page = await this.page();
+        const before = await this.tabUrl(page).catch(() => "");
+        let redirected;
+        for (let attempt = 0; attempt < 2; attempt++) {
+            const result = await page.send("Page.navigate", { url });
+            const error = result["errorText"];
+            if (typeof error !== "string" || error === "") {
+                await this.settle(page);
+                break;
+            }
+            // Chromium reports ERR_ABORTED when a navigation is replaced by its
+            // redirect or another renderer-initiated navigation. It is not a failure
+            // if the page actually moved; if it did not, one retry handles the brief
+            // overlap without hiding a real error forever.
+            if (error === "net::ERR_ABORTED") {
+                redirected = await this.waitForUrlChange(page, before);
+                if (redirected)
+                    break;
+                if (attempt === 0)
+                    continue;
+            }
+            throw new BrowserError(`could not load ${url}: ${error}`);
+        }
+        const current = redirected ?? await this.tabUrl(page);
+        this.currentOrigin = originOf(current);
+        this.refs = new Map();
+        return { url: current };
+    }
+    async waitForUrlChange(page, before, timeoutMs = 1_200) {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            const current = await this.tabUrl(page).catch(() => "");
+            if (current && current !== before && !current.startsWith("chrome-error://"))
+                return current;
+            await new Promise((resolve) => setTimeout(resolve, 50));
+        }
+        return undefined;
+    }
+    async reload() {
+        const page = await this.page();
+        await page.send("Page.reload");
+        await this.settle(page);
+        const url = await this.url();
+        this.currentOrigin = originOf(url);
+        this.refs = new Map();
+        return { url };
+    }
+    /**
+     * Wait for the page to stop changing, with a ceiling.
+     *
+     * `Page.loadEventFired` is the signal, but a single-page app may never fire
+     * another one after the first route, so the timeout is the real contract: this
+     * returns when the page looks ready *or* soon, and never blocks a turn on a
+     * page that streams forever.
+     */
+    async settle(page, timeoutMs = 10_000) {
+        await new Promise((resolve) => {
+            const done = () => {
+                clearTimeout(timer);
+                off();
+                resolve();
+            };
+            const timer = setTimeout(done, timeoutMs);
+            const off = page.on("Page.loadEventFired", done);
+        });
+    }
+    async url() {
+        const page = await this.page();
+        const result = await page.send("Runtime.evaluate", {
+            expression: "location.href",
+            returnByValue: true,
+        });
+        const value = (result["result"] ?? {});
+        return String(value["value"] ?? "");
+    }
+    async snapshot(opts = {}) {
+        const page = await this.page();
+        const result = await page.send("Accessibility.getFullAXTree");
+        const nodes = (Array.isArray(result["nodes"]) ? result["nodes"] : []);
+        const snapshot = buildSnapshot(nodes, opts);
+        // Refs are only meaningful against the tree they came from, so each
+        // snapshot replaces the table rather than adding to it: a stale ref should
+        // fail loudly, not click whatever now occupies that slot.
+        this.refs = snapshot.refs;
+        this.currentOrigin = originOf(await this.url());
+        return snapshot;
+    }
+    /** Where a ref sits on screen, in viewport coordinates. */
+    async locate(ref) {
+        const page = await this.page();
+        const backendNodeId = this.refs.get(ref);
+        if (backendNodeId === undefined) {
+            throw new BrowserError(`no such element ${ref}. Call browser_read_page to get current refs — they are replaced on every snapshot.`);
+        }
+        await page.send("DOM.scrollIntoViewIfNeeded", { backendNodeId }).catch(() => { });
+        const box = await page.send("DOM.getBoxModel", { backendNodeId }).catch(() => undefined);
+        const model = (box?.["model"] ?? {});
+        const quad = Array.isArray(model["content"]) ? model["content"] : undefined;
+        if (!quad || quad.length < 8) {
+            throw new BrowserError(`${ref} is not visible on the page`);
+        }
+        return {
+            x: (quad[0] + quad[2] + quad[4] + quad[6]) / 4,
+            y: (quad[1] + quad[3] + quad[5] + quad[7]) / 4,
+        };
+    }
+    async resolveObject(ref) {
+        const page = await this.page();
+        const backendNodeId = this.refs.get(ref);
+        if (backendNodeId === undefined)
+            throw new BrowserError(`no such element ${ref}`);
+        const result = await page.send("DOM.resolveNode", { backendNodeId });
+        const object = (result["object"] ?? {});
+        const objectId = object["objectId"];
+        if (typeof objectId !== "string")
+            throw new BrowserError(`could not address ${ref}`);
+        return objectId;
+    }
+    /** Every open tab. Starts the browser if nothing has yet. */
+    async tabs() {
+        const target = await this.start();
+        return target.pages();
+    }
+    /**
+     * Every open tab, described without attaching to any. Starts the browser if
+     * nothing has yet. In the person's own browser this is the whole window
+     * list, and a tab is only attached — and bannered — once it is selected.
+     */
+    async tabList() {
+        const target = await this.start();
+        if (!target.pageInfos)
+            return (await this.paneTabs()).map((tab) => ({ ...tab, mine: true }));
+        const infos = await target.pageInfos();
+        const mine = target.opened ? new Set((await target.pages()).map((page) => page.id)) : undefined;
+        return infos.map((page) => ({ ...page, active: page.id === this.active?.id, mine: !mine || mine.has(page.id) }));
+    }
+    /** Open a tab and make it the active one. */
+    async newTab(url) {
+        const target = await this.start();
+        const page = await target.newPage(url);
+        await this.adopt(page);
+        if (url)
+            this.currentOrigin = originOf(url);
+        return page;
+    }
+    /** Where a specific tab is, without switching to it. */
+    async tabUrl(page) {
+        const result = await page.send("Runtime.evaluate", {
+            expression: "location.href",
+            returnByValue: true,
+        });
+        const value = (result["result"] ?? {});
+        return String(value["value"] ?? "");
+    }
+    /** A non-launching description of the tabs for the session Browser pane. */
+    async paneTabs() {
+        if (!this.target)
+            return [];
+        if (this.target.pageInfos) {
+            const infos = await this.target.pageInfos();
+            // In the person's own browser the pane is this conversation's tab strip:
+            // the tabs it opened or was pointed at, never the rest of their window.
+            const mine = this.target.opened ? new Set((await this.target.pages()).map((page) => page.id)) : undefined;
+            const opened = this.target.opened?.bind(this.target);
+            return infos
+                .filter((page) => !mine || mine.has(page.id))
+                .map((page) => ({
+                ...page,
+                active: page.id === this.active?.id,
+                // One of the person's own tabs this conversation was pointed at:
+                // closing it from the strip only lets go of it, so it says so.
+                ...(opened && !opened(page.id) ? { mine: false } : {}),
+            }));
+        }
+        const pages = await this.target.pages();
+        return Promise.all(pages.map(async (page) => {
+            const result = await page.send("Runtime.evaluate", {
+                expression: "({ url: location.href, title: document.title })",
+                returnByValue: true,
+            }).catch(() => ({}));
+            const remote = (result["result"] ?? {});
+            const value = (remote["value"] ?? {});
+            const url = typeof value["url"] === "string" ? value["url"] : await this.tabUrl(page).catch(() => "");
+            const title = typeof value["title"] === "string" ? value["title"].trim() : "";
+            return { id: page.id, url, ...(title ? { title } : {}), active: page === this.active };
+        }));
+    }
+    /** Switch the pane and subsequent browser tools to an already-open tab. */
+    async selectPaneTab(id) {
+        if (!this.target)
+            throw new BrowserError("no browser is running");
+        const page = this.target.pageById
+            ? await this.target.pageById(id)
+            : (await this.target.pages()).find((candidate) => candidate.id === id);
+        if (!page)
+            throw new BrowserError(`no tab ${id}`);
+        await this.adopt(page);
+        const url = await this.tabUrl(page);
+        this.currentOrigin = originOf(url);
+        return { id: page.id, url };
+    }
+    /**
+     * Give this conversation one of the person's own tabs, because they asked —
+     * from the extension's side panel, on the tab in front of them. Their asking
+     * is what makes it this conversation's tab; it is not a permission to act on
+     * the site, which the first action there still asks for as ever.
+     */
+    async adoptYourTab(id) {
+        if (this.policy === "builtin") {
+            throw new BrowserError("settings keep browser use in the built-in browser, so a tab of your own cannot be handed to it");
+        }
+        this.mode = "extension";
+        await this.start();
+        return this.selectPaneTab(id);
+    }
+    /**
+     * Close one page without disturbing its siblings; the last one releases the
+     * target. A tab the person had open before the conversation was pointed at
+     * it is let go of rather than closed — it was theirs, not the agent's.
+     */
+    async closePaneTab(id) {
+        if (!this.target)
+            throw new BrowserError("no browser is running");
+        const target = this.target;
+        const page = target.pageById
+            ? await target.pageById(id)
+            : (await target.pages()).find((candidate) => candidate.id === id);
+        if (!page)
+            throw new BrowserError(`no tab ${id}`);
+        const wasActive = page === this.active;
+        const released = Boolean(target.opened && target.release && !target.opened(id));
+        if (released)
+            await target.release(page);
+        else
+            await page.close();
+        if (wasActive)
+            this.active = undefined;
+        // What is left to work in: in the person's own browser only this
+        // conversation's tabs count, so closing its last one never lands the agent
+        // on one of theirs.
+        const infos = target.pageInfos && !target.opened ? await target.pageInfos() : undefined;
+        const remaining = infos ? infos.length : (await target.pages()).length;
+        if (remaining === 0) {
+            await this.closeSide(this.mode);
+            return { closed: id, ...(released ? { released } : {}), running: false };
+        }
+        if (wasActive) {
+            const next = infos
+                ? await target.pageById?.(infos.at(-1).id)
+                : (await target.pages()).at(-1);
+            if (next) {
+                await this.adopt(next);
+                this.currentOrigin = originOf(await this.tabUrl(next));
+            }
+        }
+        return { closed: id, ...(released ? { released } : {}), ...(this.active ? { active: this.active.id } : {}), running: true };
+    }
+    /**
+     * What a pane needs to draw itself without starting anything.
+     *
+     * Asked on an interval by every open page, so it must never be the call that
+     * launches a browser: somebody who opened the pane to look at it has not
+     * asked for Chrome, and a pane that started one would make the feature cost
+     * memory for people who never use it.
+     */
+    state() {
+        return {
+            running: this.running,
+            mode: this.mode,
+            policy: this.policy,
+            ...(this.currentOrigin ? { origin: this.currentOrigin } : {}),
+            ...(this.target?.presentation ? { presentation: this.target.presentation } : {}),
+        };
+    }
+    /**
+     * The page's own coordinate space.
+     *
+     * A screencast frame is not the page: Chrome scales it down, so a 1280-wide
+     * viewport arrives as a 756-wide picture. A pane that treated the picture's
+     * pixels as the page's would put every human click in the wrong place — near
+     * enough to look plausible, far enough to miss the button. This is what the
+     * pane scales by.
+     */
+    async viewport() {
+        if (!this.target)
+            return undefined;
+        try {
+            const page = await this.page();
+            const metrics = await page.send("Page.getLayoutMetrics");
+            const box = (metrics["cssLayoutViewport"] ?? metrics["layoutViewport"] ?? {});
+            const width = Number(box["clientWidth"]);
+            const height = Number(box["clientHeight"]);
+            if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0)
+                return undefined;
+            return { width, height };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Frames for a viewer. Starts nothing — an idle session yields nothing. */
+    async *frames(opts = {}) {
+        if (!this.target)
+            return;
+        const page = await this.page();
+        yield* page.frames(opts);
+    }
+    /**
+     * Input from a person who has taken the pane over.
+     *
+     * The same channel the tools use, deliberately: a human click and a model
+     * click arrive at the page identically, so there is no second code path that
+     * can drift, and no state the page can be in that only one of them reaches.
+     */
+    async forward(event) {
+        if (!this.target)
+            return;
+        const page = await this.page();
+        await page.input(event);
+    }
+    consoleEntries() {
+        return this.consoleLog;
+    }
+    networkEntries() {
+        return this.network;
+    }
+    /** Let go of both browsers: the built-in one closes, the person's is detached. */
+    async close() {
+        this.consoleLog.length = 0;
+        this.network.length = 0;
+        await Promise.all([this.closeSide("builtin"), this.closeSide("extension")]);
+    }
+    /** Let go of one browser, leaving the other as it is. */
+    async closeSide(side) {
+        const target = this.sides[side].target;
+        this.sides[side] = emptySide();
+        await target?.close().catch(() => { });
+    }
+    /**
+     * Change which browsers this session may use.
+     *
+     * Takes effect on the next browser call. Pinning it to one browser lets go
+     * of the other — the built-in one closes, the person's is only detached,
+     * their tabs never closed. Moving to auto keeps whatever is open, since
+     * either browser is now fair game.
+     */
+    async setMode(mode) {
+        this.policy = mode;
+        if (mode === "auto")
+            return;
+        const other = mode === "builtin" ? "extension" : "builtin";
+        await this.closeSide(other);
+        this.mode = mode;
+    }
+    /**
+     * The external browser a sign-in can be imported from, and the sites it has
+     * open. Lists tabs only — nothing is attached, so the person's browser shows
+     * no debugging banner just because the dialog was opened.
+     */
+    async loginImportSources() {
+        const found = await this.withExternal(async (external) => ({
+            browser: await externalBrowserName(external),
+            sites: await listExternalSites(external),
+        }));
+        const current = this.mode === "builtin" && this.currentOrigin ? normalizeSite(this.currentOrigin) : undefined;
+        return { ...found, ...(current ? { current } : {}) };
+    }
+    /**
+     * Copy the chosen sites' sign-in into the built-in browser's profile.
+     *
+     * Only ever called from the confirmation dialog. In extension mode this is
+     * also the migration: the session lets go of the person's browser (detaching,
+     * never closing their tabs) and continues in the built-in one, on the site it
+     * just imported.
+     */
+    async importLogin(sites) {
+        const wanted = [...new Set(sites.map((site) => normalizeSite(site)).filter((site) => Boolean(site)))];
+        if (wanted.length === 0)
+            throw new BrowserError("choose at least one website to import");
+        if (this.importing)
+            throw new BrowserError("an import is already running");
+        this.importing = true;
+        try {
+            const { browser, states } = await this.withExternal(async (external) => {
+                const states = [];
+                for (const site of wanted)
+                    states.push(await readSiteLoginState(external, site));
+                return { browser: await externalBrowserName(external), states };
+            });
+            const migrated = this.mode === "extension";
+            if (migrated) {
+                // Closing an extension target detaches; it never closes the person's tabs.
+                await this.closeSide("extension");
+                this.mode = "builtin";
+                // Pinned to the person's browser, the session now works on in the
+                // built-in one it just moved to, as it asked to.
+                if (this.policy === "extension")
+                    this.policy = "builtin";
+            }
+            const page = await this.page();
+            const imported = [];
+            for (const state of states) {
+                if (state.cookies.length)
+                    await page.send("Network.setCookies", { cookies: state.cookies });
+                let stored = 0;
+                for (const origin of state.origins) {
+                    if (!origin.localStorage.length)
+                        continue;
+                    await this.seedLocalStorage(page, origin);
+                    stored += origin.localStorage.length;
+                }
+                imported.push({ site: state.site, cookies: state.cookies.length, localStorage: stored, ...(state.origins[0] ? { url: state.origins[0].url } : {}) });
+                await this.loginMemory().add(state.site);
+            }
+            // Land where the sign-in shows: reload a page that belongs to an imported
+            // site, open the first site on a blank browser, and otherwise leave the
+            // page the agent is working on alone.
+            const here = await this.tabUrl(page).catch(() => "");
+            const hereSite = /^https?:/i.test(here) ? normalizeSite(here) : undefined;
+            if (hereSite && imported.some((entry) => hostInSite(hereSite, entry.site))) {
+                await this.navigate(here);
+            }
+            else if (!hereSite) {
+                const first = imported[0];
+                await this.navigate(first.url ?? `https://${first.site}/`);
+            }
+            return { browser, imported, migrated, url: await this.tabUrl(page).catch(() => here) };
+        }
+        finally {
+            this.importing = false;
+        }
+    }
+    /**
+     * Offer an import when the built-in browser reaches a site the person has
+     * open in their own browser.
+     *
+     * Asked by the pane's state poll, so it never waits on the extension: the
+     * first call for a site starts one probe and answers nothing, and a later poll
+     * picks the result up. The probe lists tabs only and attaches to none.
+     */
+    loginImportSuggestion() {
+        if (this.mode !== "builtin" || !this.target || !this.currentOrigin)
+            return undefined;
+        const site = normalizeSite(this.currentOrigin);
+        if (!site || this.importing)
+            return undefined;
+        const known = this.suggestions.get(site);
+        if (known && Date.now() - known.at < SUGGESTION_TTL_MS)
+            return known.value;
+        if (!this.probing) {
+            this.probing = (async () => {
+                let value;
+                try {
+                    if (!(await this.loginMemory().has(site))) {
+                        value = await this.withExternal(async (external) => {
+                            const open = (await listExternalSites(external)).some((entry) => hostInSite(entry.site, site) || hostInSite(site, entry.site));
+                            return open ? { site, browser: await externalBrowserName(external) } : undefined;
+                        });
+                    }
+                }
+                catch {
+                    // No extension, or it is busy with another session: nothing to offer.
+                }
+                this.suggestions.set(site, { at: Date.now(), ...(value ? { value } : {}) });
+            })().finally(() => {
+                this.probing = undefined;
+            });
+        }
+        return known?.value;
+    }
+    /**
+     * Whether the person has this site open in their own browser, while this
+     * session works on it in the built-in one without its sign-in. The model is
+     * told, and decides; nothing moves on the strength of it. Lists tabs only,
+     * attaches to none, and gives up quickly when the extension is not there.
+     */
+    async openInYourBrowser(url, timeoutMs = 1_500) {
+        if (this.policy !== "auto" || this.mode !== "builtin")
+            return false;
+        const site = normalizeSite(url);
+        // A local dev server is the built-in browser's own business.
+        if (!site || site === "localhost" || /^127\.|^\[?::1\]?$/.test(site))
+            return false;
+        if (await this.loginMemory().has(site).catch(() => false))
+            return false;
+        const probe = this.withExternal(async (external) => (await listExternalSites(external)).some((entry) => hostInSite(entry.site, site) || hostInSite(site, entry.site))).catch(() => false);
+        let timer;
+        const late = new Promise((resolve) => {
+            timer = setTimeout(() => resolve(false), timeoutMs);
+            timer.unref?.();
+        });
+        try {
+            return await Promise.race([probe, late]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /** "Don't ask again" for one site, remembered with the shared profile. */
+    async dismissLoginImport(site) {
+        const normalized = normalizeSite(site);
+        if (!normalized)
+            return;
+        this.suggestions.set(normalized, { at: Date.now() });
+        await this.loginMemory().add(normalized);
+    }
+    loginMemory() {
+        return this.opts.loginMemory ?? (sharedLoginMemory ??= new LoginImportMemory());
+    }
+    /**
+     * The external browser, for the length of one read.
+     *
+     * In extension mode that is the session's own target. Otherwise a connection
+     * is opened for the read and closed after it, so the extension is free again
+     * and the person's tabs are detached, not closed.
+     */
+    async withExternal(fn) {
+        const own = this.sides.extension.target;
+        if (own)
+            return fn(own);
+        const provider = browserProviderFor("extension", this.opts.providers);
+        const target = await provider.createTarget({ ...(this.sessionId ? { sessionId: this.sessionId } : {}) });
+        try {
+            return await fn(target);
+        }
+        finally {
+            await target.close().catch(() => { });
+        }
+    }
+    /**
+     * Put localStorage in place before the site's own scripts run.
+     *
+     * Written from a script injected ahead of the document rather than after the
+     * load: a signed-out page that loaded first could overwrite the keys it finds
+     * missing, and would then need a reload that sees the same state it wrote.
+     */
+    async seedLocalStorage(page, origin) {
+        const source = `(() => { if (location.origin !== ${JSON.stringify(origin.origin)}) return; try { for (const [key, value] of ${JSON.stringify(origin.localStorage)}) localStorage.setItem(key, value); } catch {} })();`;
+        const added = await page.send("Page.addScriptToEvaluateOnNewDocument", { source });
+        try {
+            await this.navigate(origin.url);
+        }
+        finally {
+            if (typeof added["identifier"] === "string") {
+                await page.send("Page.removeScriptToEvaluateOnNewDocument", { identifier: added["identifier"] }).catch(() => { });
+            }
+        }
+    }
+}
+export function originOf(url) {
+    try {
+        const parsed = new URL(url);
+        // A file: or about: URL has no host, and `origin` reads "null" for them —
+        // which would collapse every local file into one permission subject.
+        if (parsed.protocol === "http:" || parsed.protocol === "https:")
+            return parsed.origin;
+        return parsed.protocol === "about:" ? undefined : parsed.protocol;
+    }
+    catch {
+        return undefined;
+    }
+}
+function errorText(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=session.js.map