@openacme/browser 0.4.0 → 0.5.1

package/dist/manager.js

@@ -1,129 +1,173 @@
-import { killChrome, launchChrome, resolveExecutableOrThrow, resolveUserDataDir, } from "./chrome.js";
 import { connectOverCdp, isRecoverableDisconnect } from "./cdp.js";
 import { refLocator } from "./refs.js";
 import { ariaSnapshot } from "./snapshot.js";
 const MAX_CONSOLE_PER_PAGE = 200;
 /**
- * Owns the single managed Chrome process for the OpenAcme workforce.
+ * Per-agent browser orchestrator. Each agent that calls a browser tool
+ * gets its own session — a separate Chrome process for the local provider,
+ * a separate cloud session for Browserbase / Browser-Use / Firecrawl.
+ * Sessions are lazy and acquired on first tool call.
  *
- * One Chrome under `<dataDir>/browser-profile/`; one shared default
- * `BrowserContext` so all agents share cookies / login state. Tabs are
- * partitioned per-agent: each agent gets its own `t1`, `t2`, ... alias
- * space. Cross-agent tab access is refused.
- *
- * Lazy: nothing happens until the first tool call. CDP disconnect on
- * sleep/wake is recovered transparently — `cachedBrowser` is invalidated
- * by the `disconnected` listener and re-established on next call.
+ * Why per-agent: shared cookies cascade bans across the workforce, and
+ * shared fingerprints get the whole org flagged on social-media-style
+ * sites. Each agent is a distinct persona; the runtime should reflect that.
  */
 export class BrowserManager {
-    userDataDir;
-    cfg;
-    running = null;
-    cachedBrowser = null;
-    connectingPromise = null;
-    launchingPromise = null;
-    // Tab ownership: targetId -> owning agentId
-    tabOwnership = new Map();
-    // Per-agent alias spaces (tN ids stable within an agent)
-    agentTabs = new Map();
-    // The agent's currently-active tab
-    activeTabByAgent = new Map(); // agentId -> targetId
-    // Per-page transient state (console buffer, pending dialog policy)
-    pageState = new WeakMap();
+    provider;
+    resolveOverrides;
+    ensureOverrides;
+    instances = new Map();
+    connecting = new Map();
     constructor(opts) {
-        this.userDataDir = resolveUserDataDir(opts.dataDir);
-        this.cfg = opts.config;
+        this.provider = opts.provider;
+        this.resolveOverrides = opts.resolveOverrides ?? null;
+        this.ensureOverrides = opts.ensureOverrides ?? null;
+    }
+    get providerName() {
+        return this.provider.name;
     }
     // ───────────────────────── lifecycle ─────────────────────────
-    async ensureChrome() {
-        if (this.running && this.running.proc.exitCode === null)
-            return this.running;
-        if (this.launchingPromise)
-            return this.launchingPromise;
-        const exe = resolveExecutableOrThrow(this.cfg);
-        this.launchingPromise = launchChrome({
-            exe,
-            cdpPort: this.cfg.port,
-            userDataDir: this.userDataDir,
-            headless: this.cfg.headless,
-            noSandbox: this.cfg.noSandbox,
-        })
-            .then((r) => {
-            r.proc.once("exit", () => {
-                if (this.running === r) {
-                    this.running = null;
-                    this.cachedBrowser = null;
-                    this.resetAllTabState();
-                }
+    async getInstance(agentId) {
+        if (!agentId)
+            throw new Error("BrowserManager calls require an agentId");
+        const existing = this.instances.get(agentId);
+        if (existing && this.isInstanceAlive(existing))
+            return existing;
+        if (existing) {
+            this.instances.delete(agentId);
+            try {
+                await existing.acquired.release();
+            }
+            catch {
+                // best-effort
+            }
+        }
+        const inflight = this.connecting.get(agentId);
+        if (inflight)
+            return inflight;
+        const p = this.connectFor(agentId).finally(() => this.connecting.delete(agentId));
+        this.connecting.set(agentId, p);
+        return p;
+    }
+    isInstanceAlive(inst) {
+        // CDP path: rely on the underlying Browser's connection state.
+        // Pre-built context path: by construction, the provider/manager's
+        // close listener already drops the entry.
+        if (inst.browser)
+            return inst.browser.isConnected();
+        return true;
+    }
+    async connectFor(agentId) {
+        let overrides = this.resolveOverrides?.(agentId);
+        // Lazy provisioning: if the agent doesn't have a profile yet for the
+        // active provider, give AgentManager a chance to create one now and
+        // persist it back. First-acquire pays the provision cost; subsequent
+        // acquires skip this because the agent def now has the field.
+        if (this.ensureOverrides) {
+            try {
+                overrides = await this.ensureOverrides(agentId, overrides);
+            }
+            catch {
+                // best-effort — fall through with whatever we had
+            }
+        }
+        const acquired = await this.provider.acquire(agentId, { overrides });
+        let browser = null;
+        let context;
+        try {
+            if (acquired.preBuiltContext) {
+                context = acquired.preBuiltContext;
+            }
+            else if (acquired.cdpUrl) {
+                browser = await connectOverCdp({
+                    wsUrl: acquired.cdpUrl,
+                    onDisconnected: (b) => {
+                        const inst = this.instances.get(agentId);
+                        if (inst && inst.browser === b)
+                            this.instances.delete(agentId);
+                    },
+                });
+                const ctxs = browser.contexts();
+                if (ctxs.length === 0)
+                    throw new Error("CDP browser has no contexts");
+                context = ctxs[0];
+            }
+            else {
+                throw new Error("Provider returned neither cdpUrl nor preBuiltContext");
+            }
+        }
+        catch (e) {
+            // Avoid leaking the upstream session when the initial attach fails.
+            try {
+                await acquired.release();
+            }
+            catch {
+                // best-effort
+            }
+            throw e;
+        }
+        const instance = {
+            acquired,
+            browser,
+            context,
+            agentTabs: { next: 1, byTabId: new Map(), byPage: new Map() },
+            activeTabId: null,
+            pageState: new WeakMap(),
+        };
+        // For pre-built contexts, mirror what the CDP `disconnected` listener
+        // does — drop the cache when the context closes.
+        if (!browser) {
+            context.once("close", () => {
+                if (this.instances.get(agentId) === instance)
+                    this.instances.delete(agentId);
             });
-            this.running = r;
-            return r;
-        })
-            .finally(() => {
-            this.launchingPromise = null;
-        });
-        return this.launchingPromise;
-    }
-    async getBrowser() {
-        if (this.cachedBrowser)
-            return this.cachedBrowser;
-        if (this.connectingPromise)
-            return this.connectingPromise;
-        this.connectingPromise = this.connectFresh().finally(() => {
-            this.connectingPromise = null;
-        });
-        return this.connectingPromise;
-    }
-    async connectFresh() {
-        const running = await this.ensureChrome();
-        const browser = await connectOverCdp({
-            wsUrl: running.cdpUrl,
-            onDisconnected: (b) => {
-                if (this.cachedBrowser === b)
-                    this.cachedBrowser = null;
-            },
-        });
-        this.cachedBrowser = browser;
-        return browser;
-    }
-    async sharedContext() {
-        const browser = await this.getBrowser();
-        const contexts = browser.contexts();
-        if (contexts.length === 0) {
-            // Should never happen with connectOverCDP — Chrome always exposes
-            // the default context — but defensive.
-            throw new Error("No BrowserContext available on the connected Chrome.");
         }
-        const ctx = contexts[0];
-        return ctx;
-    }
-    resetAllTabState() {
-        this.tabOwnership.clear();
-        this.agentTabs.clear();
-        this.activeTabByAgent.clear();
-    }
-    async close() {
-        if (this.cachedBrowser) {
+        this.instances.set(agentId, instance);
+        return instance;
+    }
+    async contextFor(agentId) {
+        const inst = await this.getInstance(agentId);
+        return { inst, ctx: inst.context };
+    }
+    /** Release one agent's browser session. Idempotent. */
+    async closeAgent(agentId) {
+        const inst = this.instances.get(agentId);
+        if (inst) {
+            this.instances.delete(agentId);
             try {
-                await this.cachedBrowser.close();
+                if (inst.browser)
+                    await inst.browser.close();
+                // Pre-built context lifetime is owned by the provider; releaseAgent
+                // below closes it.
             }
             catch {
-                // ignore — we're shutting down
+                // best-effort
             }
-            this.cachedBrowser = null;
         }
-        if (this.running) {
-            await killChrome(this.running);
-            this.running = null;
+        try {
+            await this.provider.releaseAgent(agentId);
+        }
+        catch {
+            // best-effort
+        }
+    }
+    /** Release every agent and shut down the provider. */
+    async close() {
+        const ids = Array.from(this.instances.keys());
+        await Promise.all(ids.map((id) => this.closeAgent(id)));
+        try {
+            await this.provider.releaseAll();
+        }
+        catch {
+            // best-effort
         }
-        this.resetAllTabState();
     }
     // ───────────────────────── per-page observation ─────────────────────────
-    observePage(page) {
-        if (this.pageState.has(page))
+    observePage(inst, page) {
+        if (inst.pageState.has(page))
             return;
         const state = { console: [], dialogHandler: null };
-        this.pageState.set(page, state);
+        inst.pageState.set(page, state);
         page.on("console", (msg) => {
             if (state.console.length >= MAX_CONSOLE_PER_PAGE)
                 state.console.shift();
@@ -144,132 +188,91 @@ export class BrowserManager {
             });
         });
     }
-    // ───────────────────────── tab ownership ─────────────────────────
-    agentTabsFor(agentId) {
-        let s = this.agentTabs.get(agentId);
-        if (!s) {
-            s = { next: 1, byTargetId: new Map(), byTabId: new Map() };
-            this.agentTabs.set(agentId, s);
-        }
-        return s;
-    }
-    assignTabAlias(agentId, targetId) {
-        const s = this.agentTabsFor(agentId);
-        const existing = s.byTargetId.get(targetId);
-        if (existing)
+    // ───────────────────────── tab tracking ─────────────────────────
+    /**
+     * Tab identity is the Page object itself — stable for the page's
+     * lifetime in Playwright. Avoids CDP-specific calls (`newCDPSession`)
+     * so Firefox-based backends (Camoufox) work the same as Chromium.
+     */
+    trackPage(inst, page) {
+        const existing = inst.agentTabs.byPage.get(page);
+        if (existing) {
+            this.observePage(inst, page);
+            inst.activeTabId = existing;
             return existing;
-        const id = `t${s.next}`;
-        s.next += 1;
-        s.byTargetId.set(targetId, id);
-        s.byTabId.set(id, targetId);
-        this.tabOwnership.set(targetId, agentId);
-        return id;
-    }
-    trackPageForAgent(agentId, page, targetId) {
-        this.observePage(page);
-        const tabId = this.assignTabAlias(agentId, targetId);
-        this.activeTabByAgent.set(agentId, targetId);
+        }
+        this.observePage(inst, page);
+        const tabId = `t${inst.agentTabs.next}`;
+        inst.agentTabs.next += 1;
+        inst.agentTabs.byTabId.set(tabId, page);
+        inst.agentTabs.byPage.set(page, tabId);
+        inst.activeTabId = tabId;
         page.once("close", () => {
-            this.releaseTab(targetId);
+            inst.agentTabs.byTabId.delete(tabId);
+            inst.agentTabs.byPage.delete(page);
+            if (inst.activeTabId === tabId)
+                inst.activeTabId = null;
         });
         return tabId;
     }
-    releaseTab(targetId) {
-        const owner = this.tabOwnership.get(targetId);
-        if (!owner)
-            return;
-        this.tabOwnership.delete(targetId);
-        const s = this.agentTabs.get(owner);
-        if (s) {
-            const alias = s.byTargetId.get(targetId);
-            if (alias) {
-                s.byTabId.delete(alias);
-                s.byTargetId.delete(targetId);
-            }
-        }
-        if (this.activeTabByAgent.get(owner) === targetId) {
-            this.activeTabByAgent.delete(owner);
-        }
-    }
-    async targetIdOf(page) {
-        const session = await page.context().newCDPSession(page);
-        try {
-            const info = (await session.send("Target.getTargetInfo"));
-            const id = info.targetInfo?.targetId;
-            if (!id)
-                throw new Error("Target.getTargetInfo returned no targetId");
-            return id;
-        }
-        finally {
-            await session.detach().catch(() => { });
-        }
-    }
-    /**
-     * Resolve the Page for `tabId` (or the active tab if omitted) and verify
-     * the agent owns it. Throws on missing tab / cross-agent access.
-     */
     async resolvePage(agentId, tabId, opts) {
-        const s = this.agentTabsFor(agentId);
-        let targetId;
+        const { inst, ctx } = await this.contextFor(agentId);
+        let page = null;
+        let resolvedTabId = null;
         if (tabId) {
-            targetId = s.byTabId.get(tabId);
-            if (!targetId) {
+            const candidate = inst.agentTabs.byTabId.get(tabId);
+            if (!candidate)
                 throw new Error(`Tab ${tabId} not found for this agent.`);
+            if (candidate.isClosed()) {
+                inst.agentTabs.byTabId.delete(tabId);
+                inst.agentTabs.byPage.delete(candidate);
+                if (inst.activeTabId === tabId)
+                    inst.activeTabId = null;
+                throw new Error(`Tab ${tabId} is no longer open.`);
             }
+            page = candidate;
+            resolvedTabId = tabId;
         }
-        else {
-            targetId = this.activeTabByAgent.get(agentId);
-        }
-        const ctx = await this.sharedContext();
-        if (targetId) {
-            const page = await this.findPageByTargetId(ctx, targetId);
-            if (page) {
-                this.observePage(page);
-                const resolvedTabId = s.byTargetId.get(targetId);
-                return { page, tabId: resolvedTabId, targetId };
+        else if (inst.activeTabId) {
+            const candidate = inst.agentTabs.byTabId.get(inst.activeTabId);
+            if (candidate && !candidate.isClosed()) {
+                page = candidate;
+                resolvedTabId = inst.activeTabId;
             }
-            // The target id we remember is gone (page closed externally,
-            // Chrome respawned, etc.). Clean up and fall through.
-            this.releaseTab(targetId);
-            targetId = undefined;
-        }
-        if (!opts.createIfNone) {
-            throw new Error("No tabs owned by this agent. Call browser_navigate first to open one.");
-        }
-        const page = await ctx.newPage();
-        const newTargetId = await this.targetIdOf(page);
-        const newTabId = this.trackPageForAgent(agentId, page, newTargetId);
-        return { page, tabId: newTabId, targetId: newTargetId };
-    }
-    async findPageByTargetId(ctx, targetId) {
-        for (const p of ctx.pages()) {
-            try {
-                const tid = await this.targetIdOf(p);
-                if (tid === targetId)
-                    return p;
+            else {
+                if (candidate) {
+                    inst.agentTabs.byTabId.delete(inst.activeTabId);
+                    inst.agentTabs.byPage.delete(candidate);
+                }
+                inst.activeTabId = null;
             }
-            catch {
-                // ignore — the page may have closed mid-iteration
+        }
+        if (!page) {
+            if (!opts.createIfNone) {
+                throw new Error("No tabs open for this agent. Call browser_navigate first to open one.");
             }
+            page = await ctx.newPage();
+            resolvedTabId = this.trackPage(inst, page);
         }
-        return null;
+        this.observePage(inst, page);
+        return { inst, page, tabId: resolvedTabId };
     }
     /**
      * Run an action with one-shot reconnect on transient CDP disconnects.
-     * The action gets a fresh `page` resolution on retry.
+     * Drops the agent's instance + cloud session before retrying so we
+     * don't reuse a server-side session that the provider already killed.
      */
     async withReconnect(agentId, tabId, opts, fn) {
         try {
             const r = await this.resolvePage(agentId, tabId, opts);
-            return await fn(r.page, { tabId: r.tabId, targetId: r.targetId });
+            return await fn(r.page, { tabId: r.tabId });
         }
         catch (e) {
             if (!isRecoverableDisconnect(e))
                 throw e;
-            // Invalidate connection + tab state and retry once.
-            this.cachedBrowser = null;
+            await this.closeAgent(agentId);
             const r = await this.resolvePage(agentId, tabId, opts);
-            return await fn(r.page, { tabId: r.tabId, targetId: r.targetId });
+            return await fn(r.page, { tabId: r.tabId });
         }
     }
     // ───────────────────────── public API ─────────────────────────
@@ -324,10 +327,7 @@ export class BrowserManager {
     async waitFor(agentId, p) {
         return this.withReconnect(agentId, p.tabId, { createIfNone: false }, async (page, ids) => {
             if (p.text) {
-                await page
-                    .getByText(p.text, { exact: false })
-                    .first()
-                    .waitFor({ timeout: 30_000 });
+                await page.getByText(p.text, { exact: false }).first().waitFor({ timeout: 30_000 });
             }
             else if (p.textGone) {
                 await page
@@ -343,15 +343,14 @@ export class BrowserManager {
     }
     async evaluate(agentId, p) {
         return this.withReconnect(agentId, p.tabId, { createIfNone: false }, async (page, ids) => {
-            // `function` is treated as an expression body — the model writes
-            // something like `document.title` or `(() => Array.from(document.images).length)()`.
             const result = await page.evaluate(p.function);
             return { tabId: ids.tabId, result };
         });
     }
     async consoleMessages(agentId, p) {
         return this.withReconnect(agentId, p.tabId, { createIfNone: false }, async (page, ids) => {
-            const state = this.pageState.get(page);
+            const { inst } = await this.contextFor(agentId);
+            const state = inst.pageState.get(page);
             const messages = state ? [...state.console] : [];
             if (p.clear && state)
                 state.console = [];
@@ -360,26 +359,16 @@ export class BrowserManager {
     }
     // ── tabs ──
     async tabsList(agentId) {
-        const ctx = await this.sharedContext();
-        const s = this.agentTabsFor(agentId);
-        const active = this.activeTabByAgent.get(agentId);
+        const { inst } = await this.contextFor(agentId);
         const out = [];
-        for (const page of ctx.pages()) {
-            let targetId;
-            try {
-                targetId = await this.targetIdOf(page);
-            }
-            catch {
-                continue;
-            }
-            const tabId = s.byTargetId.get(targetId);
-            if (!tabId)
+        for (const [tabId, page] of inst.agentTabs.byTabId) {
+            if (page.isClosed())
                 continue;
             out.push({
                 tabId,
                 url: page.url(),
                 title: await page.title().catch(() => ""),
-                active: targetId === active,
+                active: tabId === inst.activeTabId,
             });
         }
         out.sort((a, b) => {
@@ -390,12 +379,11 @@ export class BrowserManager {
         return out;
     }
     async tabsNew(agentId, p) {
-        const ctx = await this.sharedContext();
+        const { inst, ctx } = await this.contextFor(agentId);
         const page = await ctx.newPage();
         if (p.url)
             await page.goto(p.url, { waitUntil: "domcontentloaded" });
-        const targetId = await this.targetIdOf(page);
-        const tabId = this.trackPageForAgent(agentId, page, targetId);
+        const tabId = this.trackPage(inst, page);
         return {
             tabId,
             url: page.url(),
@@ -404,28 +392,34 @@ export class BrowserManager {
         };
     }
     async tabsClose(agentId, p) {
-        const s = this.agentTabsFor(agentId);
-        const targetId = s.byTabId.get(p.tabId);
-        if (!targetId)
+        const { inst } = await this.contextFor(agentId);
+        const page = inst.agentTabs.byTabId.get(p.tabId);
+        if (!page)
             throw new Error(`Tab ${p.tabId} not found for this agent.`);
-        const ctx = await this.sharedContext();
-        const page = await this.findPageByTargetId(ctx, targetId);
-        if (page)
+        if (!page.isClosed()) {
+            // page.close() fires the trackPage close handler which drops the maps.
             await page.close();
-        this.releaseTab(targetId);
+        }
+        else {
+            inst.agentTabs.byTabId.delete(p.tabId);
+            inst.agentTabs.byPage.delete(page);
+            if (inst.activeTabId === p.tabId)
+                inst.activeTabId = null;
+        }
     }
     async tabsSelect(agentId, p) {
-        const s = this.agentTabsFor(agentId);
-        const targetId = s.byTabId.get(p.tabId);
-        if (!targetId)
+        const { inst } = await this.contextFor(agentId);
+        const page = inst.agentTabs.byTabId.get(p.tabId);
+        if (!page)
             throw new Error(`Tab ${p.tabId} not found for this agent.`);
-        const ctx = await this.sharedContext();
-        const page = await this.findPageByTargetId(ctx, targetId);
-        if (!page) {
-            this.releaseTab(targetId);
+        if (page.isClosed()) {
+            inst.agentTabs.byTabId.delete(p.tabId);
+            inst.agentTabs.byPage.delete(page);
+            if (inst.activeTabId === p.tabId)
+                inst.activeTabId = null;
             throw new Error(`Tab ${p.tabId} is no longer open.`);
         }
-        this.activeTabByAgent.set(agentId, targetId);
+        inst.activeTabId = p.tabId;
         await page.bringToFront().catch(() => { });
         return {
             tabId: p.tabId,
@@ -467,10 +461,6 @@ export class BrowserManager {
             return { tabId: ids.tabId };
         });
     }
-    /**
-     * Arm a one-shot dialog handler on the page. The handler resolves the
-     * NEXT dialog event with accept/dismiss + optional prompt text.
-     */
     async handleDialog(agentId, p) {
         return this.withReconnect(agentId, p.tabId, { createIfNone: false }, async (page, ids) => {
             await new Promise((resolve, reject) => {
@@ -495,10 +485,7 @@ export class BrowserManager {
                 };
                 page.once("dialog", onDialog);
             });
-            return {
-                tabId: ids.tabId,
-                result: p.accept ? "accepted" : "dismissed",
-            };
+            return { tabId: ids.tabId, result: p.accept ? "accepted" : "dismissed" };
         });
     }
     async resize(agentId, p) {
@@ -522,9 +509,7 @@ export class BrowserManager {
     async saveAsPdf(agentId, p) {
         return this.withReconnect(agentId, p.tabId, { createIfNone: false }, async (page, ids) => {
             const filename = p.filename ?? `browser-${ids.tabId}-${Date.now()}.pdf`;
-            const outPath = filename.includes("/")
-                ? filename
-                : `/tmp/${filename}`;
+            const outPath = filename.includes("/") ? filename : `/tmp/${filename}`;
             await page.pdf({ path: outPath, format: "Letter" });
             return { tabId: ids.tabId, path: outPath };
         });