@mirasim/computer-use 0.0.0-stage → 0.1.0-rc.3

package/extension/group.js

@@ -0,0 +1,283 @@
+/**
+ * Portions Copyright (c) Microsoft Corporation (Playwright), licensed under the Apache License,
+ * Version 2.0; modified by MIRASIM, INC. See LICENSE and NOTICE.
+ *
+ * The mirasim tab group — which tabs are the AGENT'S OWN, inside the user's browser.
+ *
+ * The agent sees every tab; the Chrome tab group titled "mirasim" says whose each tab is:
+ *  - tabs the bridge creates (popups, Target.createTarget) are pulled into the group;
+ *  - a tab outside the group is the user's: attached and actable, but the driver will not close
+ *    or recycle it, and its targets line says `(user's)` (platform/browser/driver.ts
+ *    `listTargets`, types.ts `TargetInfo.own`).
+ *
+ * The group is deliberately NOT a visibility boundary (a task about a page the user already has
+ * open would need it handed over first): the agent can read anything and close only its own.
+ *
+ * Unlike Playwright's extension (which ungroups on disconnect), the group is DURABLE: tabs and
+ * group stay on disconnect, and the next connection adopts whatever is still in it.
+ *
+ * Mechanism adapted from Microsoft Playwright's browser extension (Apache-2.0).
+ */
+
+import { debugLog } from "./relay.js";
+
+export const GROUP_TITLE = "mirasim";
+const GROUP_COLOR = "cyan";
+/** Where the browser-session nonce lives — see {@link browserSessionId}. */
+const SESSION_KEY = "mirasim-browser-session";
+const NON_DEBUGGABLE_SCHEMES = ["chrome:", "edge:", "devtools:", "chrome-extension:"];
+const CONNECTED_BADGE = { text: "✓", color: "#0e7490", title: "Mirasim agent is connected to this tab" };
+
+export function isNonDebuggableUrl(url) {
+  return !!url && NON_DEBUGGABLE_SCHEMES.some((s) => url.startsWith(s));
+}
+
+/**
+ * A nonce identifying THIS browser session, handed to the bridge on every handshake so it can
+ * tell one reconnection from another (model.ts `onExtensionConnected`). Data, not a decision.
+ *
+ * Chrome tab ids are never reused WITHIN a browser session, so across a worker eviction or
+ * reconnect the bridge may keep what it knew per tab id. After a browser RESTART the ids start
+ * over and the same number can name the user's own page, which `/recycle` must not close.
+ * `chrome.storage.session` has exactly that lifetime (survives eviction, cleared on restart): a
+ * stored nonce says "same browser session", a missing one says "assume nothing".
+ */
+export async function browserSessionId() {
+  const stored = await chrome.storage.session.get(SESSION_KEY).catch(() => ({}));
+  const existing = stored?.[SESSION_KEY];
+  if (typeof existing === "string" && existing) return existing;
+  const minted = crypto.randomUUID();
+  await chrome.storage.session.set({ [SESSION_KEY]: minted }).catch((e) => debugLog("session nonce not stored:", e));
+  return minted;
+}
+
+export class MirasimTabGroup {
+  updateAvailable(version) {
+    this._connection.updateAvailable(version);
+  }
+
+  /**
+   * @param {import("./relay.js").RelayConnection} connection
+   */
+  constructor(connection) {
+    this._connection = connection;
+    this._groupId = null;
+    /** Cached group membership so hot-path checks stay synchronous. */
+    this._groupTabIds = new Set();
+    /**
+     * Tabs attached because they were simply OPEN, not because the agent opened them.
+     * `_onTabAttached` skips these; otherwise the sweep would pull every user tab into the group
+     * (the only record of ownership), and with no current window throw "No current window".
+     */
+    this._userTabIds = new Set();
+    this._onTabCreatedListener = this._onTabCreated.bind(this);
+    this._onTabUpdatedListener = this._onTabUpdated.bind(this);
+    this._onTabRemovedListener = this._onTabRemoved.bind(this);
+    this._onTabReplacedListener = this._onTabReplaced.bind(this);
+
+    /** @type {(() => void) | undefined} */
+    this.onclose = undefined;
+
+    this._connection.onclose = () => this._onConnectionClose();
+    this._connection.ontabattached = (tabId) => this._onTabAttached(tabId);
+    this._connection.ontabdetached = (tabId) => this._onTabDetached(tabId);
+    chrome.tabs.onCreated.addListener(this._onTabCreatedListener);
+    chrome.tabs.onUpdated.addListener(this._onTabUpdatedListener);
+    chrome.tabs.onRemoved.addListener(this._onTabRemovedListener);
+    chrome.tabs.onReplaced.addListener(this._onTabReplacedListener);
+
+    /** Resolves once the initial handshake (adopt + initialized) is done. */
+    this.ready = this._initialize();
+  }
+
+  connectedTabIds() {
+    return [...this._groupTabIds];
+  }
+
+  close(reason) {
+    this._connection.close(reason);
+  }
+
+  /**
+   * Adopt the existing mirasim group's tabs, and open NOTHING: a connect is not a request for a
+   * page (the driver binds a listed tab or opens its own, platform/browser/tabs.ts
+   * `claimSessionTab`), and a seeded blank tab would later count as the user's, unclosable. The
+   * group comes back with the agent's first tab (`_addTabToGroup`). Ends with `didInitialize`,
+   * which unblocks the bridge's CDP side against a populated tab model.
+   */
+  async _initialize() {
+    // Identity BEFORE any tab: the bridge keys what it remembers on the browser session, and a
+    // tab announced ahead of the nonce is a tab the bridge forgets (relay.js `didConnect`).
+    this._connection.didConnect(await browserSessionId());
+    const existing = (await chrome.tabGroups.query({ title: GROUP_TITLE }))[0];
+    if (existing) {
+      this._groupId = existing.id;
+      const tabs = await chrome.tabs.query({ groupId: existing.id });
+      for (const tab of tabs) {
+        if (tab.id === undefined) continue;
+        this._groupTabIds.add(tab.id);
+        if (!isNonDebuggableUrl(tab.url)) this._connection.attachTab(tab);
+      }
+    }
+    // Everything else the browser has open: attached, never grouped. Failures are per tab and
+    // silent by design — an undebuggable page (chrome://, the Web Store) is simply not a surface.
+    await this._attachEverythingElse();
+    this._connection.didInitialize();
+  }
+
+  /**
+   * A tab opened FROM one of the user's tabs (a link, `window.open`) is the user's. Mark it here,
+   * at creation: the bridge attaches it at once as a popup (relay.js), before `_onTabUpdated`
+   * would see it, and `_onTabAttached` would then group it. Bridge-created tabs have no opener;
+   * one opened from a group tab is the agent's, and Chrome groups it itself.
+   */
+  _onTabCreated(tab) {
+    if (tab.id === undefined || tab.openerTabId === undefined) return;
+    if (!this._groupTabIds.has(tab.openerTabId)) this._userTabIds.add(tab.id);
+  }
+
+  _onTabUpdated(tabId, changeInfo, tab) {
+    if (changeInfo.groupId !== undefined) this._onTabGroupChanged(tabId, tab);
+    if (changeInfo.url === undefined && changeInfo.discarded === undefined && changeInfo.status === undefined) return;
+    if (tab.discarded || tab.status === "unloaded") {
+      if (!isNonDebuggableUrl(tab.url)) this._connection.attachTab(tab);
+      return;
+    }
+    // Chrome resets per-tab badge state on navigation; re-apply it.
+    if (this._connection.attachedTabs.has(tabId)) void this._updateBadge(tabId, CONNECTED_BADGE);
+    // Any tab, not just the group's: a tab opened after connect becomes a surface on its first
+    // navigation. Group membership decides OWNERSHIP, not reachability.
+    else if (!isNonDebuggableUrl(tab.url)) {
+      if (!this._groupTabIds.has(tabId)) this._userTabIds.add(tabId);
+      this._connection.attachTab(tab);
+    }
+  }
+
+  /** Single entry point for membership changes, user-dragged or self-inflicted. */
+  _onTabGroupChanged(tabId, tab) {
+    const inOurGroup = this._groupId !== null && tab.groupId === this._groupId;
+    const wasInGroup = this._groupTabIds.has(tabId);
+    if (inOurGroup === wasInGroup) return;
+    if (inOurGroup) {
+      // Dragging a tab in grants OWNERSHIP, not access — every tab is reachable already.
+      this._groupTabIds.add(tabId);
+      this._userTabIds.delete(tabId);
+      if (!isNonDebuggableUrl(tab.url)) this._connection.attachTab(tab);
+    } else {
+      // Dragged out: theirs again. NOT detached — only the agent's claim is taken back.
+      this._groupTabIds.delete(tabId);
+      this._userTabIds.add(tabId);
+    }
+  }
+
+  _onTabRemoved(tabId) {
+    this._groupTabIds.delete(tabId);
+    this._userTabIds.delete(tabId);
+  }
+
+  /** Newer Chrome versions replace the tab id when discarding its renderer. */
+  async _onTabReplaced(addedTabId, removedTabId) {
+    const grouped = this._groupTabIds.has(removedTabId);
+    this._onTabRemoved(removedTabId);
+    let tab;
+    try { tab = await chrome.tabs.get(addedTabId); } catch { return; }
+    this._userTabIds.delete(addedTabId);
+    if (grouped) this._groupTabIds.add(addedTabId);
+    else this._userTabIds.add(addedTabId);
+    if (!isNonDebuggableUrl(tab.url)) this._connection.attachTab(tab);
+  }
+
+  /**
+   * Attach every open tab not already attached — the connect-time sweep. Tabs opened LATER
+   * arrive through `_onTabUpdated`.
+   */
+  async _attachEverythingElse() {
+    let tabs = [];
+    try { tabs = await chrome.tabs.query({}); } catch (e) { debugLog("tab query failed:", e); return; }
+    for (const tab of tabs) {
+      if (tab.id === undefined || this._connection.attachedTabs.has(tab.id)) continue;
+      if (isNonDebuggableUrl(tab.url)) continue;
+      if (!this._groupTabIds.has(tab.id)) this._userTabIds.add(tab.id);
+      this._connection.attachTab(tab);
+    }
+  }
+
+  _onTabAttached(tabId) {
+    void this._updateBadge(tabId, CONNECTED_BADGE);
+    // The user's own tab is attached but NOT grouped: that would relabel it and physically move
+    // it in their window.
+    if (this._userTabIds.has(tabId)) return;
+    void this._addTabToGroup(tabId);
+  }
+
+  /** Detached (drag-out, close, external). Clear the badge; the tab keeps its group
+   *  membership — the user's intent is still there and a navigation re-attaches. */
+  _onTabDetached(tabId) {
+    void this._updateBadge(tabId, { text: "" });
+  }
+
+  _onConnectionClose() {
+    chrome.tabs.onCreated.removeListener(this._onTabCreatedListener);
+    chrome.tabs.onUpdated.removeListener(this._onTabUpdatedListener);
+    chrome.tabs.onRemoved.removeListener(this._onTabRemovedListener);
+    chrome.tabs.onReplaced.removeListener(this._onTabReplacedListener);
+    // Keep the group and its tabs (the next connection adopts them); only clear the badges.
+    for (const tabId of this._groupTabIds) void this._updateBadge(tabId, { text: "" });
+    this._groupTabIds.clear();
+    this.onclose?.();
+  }
+
+  async _updateBadge(tabId, { text, color, title }) {
+    try {
+      await Promise.all([
+        chrome.action.setBadgeText({ tabId, text }),
+        chrome.action.setTitle({ tabId, title: title || "" }),
+        color ? chrome.action.setBadgeBackgroundColor({ tabId, color }) : Promise.resolve(),
+      ]);
+    } catch {
+      /* tab already closed */
+    }
+  }
+
+  /** Move an attached tab into the group, creating the group on first use. */
+  async _addTabToGroup(tabId) {
+    if (this._groupTabIds.has(tabId)) return;
+    // The group can vanish under us: Chrome deletes one whose last tab closed (what `/recycle`
+    // does). A stale `_groupId` would make every join throw and leave the agent's tabs outside
+    // the group, so a failed join drops the id and retries once via the create branch.
+    for (const attempt of [0, 1]) {
+      try {
+        await this._retryOnDrag(async () => {
+          if (this._groupId === null) {
+            this._groupId = await chrome.tabs.group({ tabIds: [tabId] });
+            await chrome.tabGroups.update(this._groupId, { color: GROUP_COLOR, title: GROUP_TITLE });
+          } else {
+            await chrome.tabs.group({ groupId: this._groupId, tabIds: [tabId] });
+          }
+        });
+        this._groupTabIds.add(tabId);
+        return;
+      } catch (e) {
+        if (attempt === 0 && this._groupId !== null) { this._groupId = null; continue; }
+        debugLog("error adding tab to group:", e);
+      }
+    }
+  }
+
+  /** Chrome throws "user may be dragging a tab" mid-drag; retry until it clears. */
+  async _retryOnDrag(fn) {
+    const delays = [0, 100, 200, 400, 800];
+    let lastError;
+    for (const delay of delays) {
+      if (delay) await new Promise((r) => setTimeout(r, delay));
+      try {
+        await fn();
+        return;
+      } catch (e) {
+        if (!String(e?.message).includes("user may be dragging a tab")) throw e;
+        lastError = e;
+      }
+    }
+    throw lastError;
+  }
+}

package/extension/manifest.json

@@ -0,0 +1,36 @@
+{
+  "manifest_version": 3,
+  "name": "Mirasim",
+  "version": "0.1.0",
+  "description": "Connect your browser to Mirasim or the open-source Mirasim Computer Use so your agent can complete web tasks you authorize.",
+  "permissions": [
+    "debugger",
+    "tabs",
+    "downloads",
+    "tabGroups",
+    "storage",
+    "nativeMessaging",
+    "alarms"
+  ],
+  "background": {
+    "service_worker": "background.js",
+    "type": "module"
+  },
+  "icons": {
+    "16": "icons/icon-16.png",
+    "32": "icons/icon-32.png",
+    "48": "icons/icon-48.png",
+    "128": "icons/icon-128.png"
+  },
+  "action": {
+    "default_title": "Mirasim",
+    "default_icon": {
+      "16": "icons/icon-16.png",
+      "32": "icons/icon-32.png"
+    }
+  },
+  "key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAmKZp4T1ESV0xpq+w0n4wH6tCSpSdXGwUyQCM3vmmsxyX8zn1ITThwNgAzu2AK7J7HO9jhqfjJ5brCoKUui/DDOuPPcGLUWM9zcPNGvsqpCpOONd47MAkQL9Tv2hSotcZv27q9M33I8pUOn5S++g38BQXMZbM1f4ZC/dUAmqIQa4uFc0N7VKbCLt7/CxGl7+d0jrvLc/6cFiWIxDX1d73UoZiTbnUiC879wauYcSBSi21MTtiZyooSh5+6hFykbStxTUV1Pa52KD5VEYDMcQmsJHCXOZxk62Ox6wJ2rtdqkZNs6TpwGK5cfpX8irFoWYTNX0Nfvo8kNTxPZh3fZX4cwIDAQAB",
+  "content_security_policy": {
+    "extension_pages": "script-src 'self'; object-src 'self'; connect-src ws://127.0.0.1:* ws://localhost:* http://127.0.0.1:* http://localhost:*"
+  }
+}

package/extension/relay.js

@@ -0,0 +1,361 @@
+/**
+ * Portions Copyright (c) Microsoft Corporation (Playwright), licensed under the Apache License,
+ * Version 2.0; modified by MIRASIM, INC. See LICENSE and NOTICE.
+ *
+ * WebSocket connection to the local mirasim bridge.
+ *
+ * Deliberately dumb: it executes an allow-list of chrome.* commands sent by the
+ * bridge (positional params spread into the call) and forwards the matching
+ * chrome.* events back. All CDP/tab-model logic lives in the bridge process,
+ * where it is testable; the extension is a hand, not a brain.
+ *
+ * Mechanism adapted from Microsoft Playwright's browser extension
+ * (packages/extension, Apache-2.0) — same wire shape, so the failure modes
+ * that implementation already paid for (navigation-detach reattach, drag
+ * bookkeeping, service-worker keepalive) stay solved.
+ */
+
+import { RUNTIME_INFO } from "./runtime-info.js";
+
+export function debugLog(...args) {
+  // eslint-disable-next-line no-console
+  console.log("[mirasim-bridge]", ...args);
+}
+
+/** chrome.* calls the bridge may invoke — anything else is rejected. */
+const ALLOWED_COMMANDS = new Set([
+  "chrome.debugger.attach",
+  "chrome.debugger.detach",
+  "chrome.debugger.sendCommand",
+  "chrome.debugger.getTargets",
+  "chrome.tabs.create",
+  "chrome.tabs.remove",
+  "chrome.tabs.query",
+  "chrome.tabs.reload",
+  "chrome.downloads.search",
+]);
+
+/** chrome.* events forwarded to the bridge (positional args, as the listener got them). */
+const FORWARDED_EVENTS = [
+  "chrome.debugger.onEvent",
+  "chrome.debugger.onDetach",
+  "chrome.tabs.onCreated",
+  "chrome.tabs.onRemoved",
+  "chrome.tabs.onReplaced",
+];
+
+/** How soon after a navigation-caused detach we try to re-attach. */
+const REATTACH_DELAY_MS = 150;
+/** How long we wait for the re-attach to stick before giving up on the tab. */
+const REATTACH_VERIFY_MS = 2500;
+/** A tab that re-detaches within this window is not fought over again. */
+const REATTACH_COOLDOWN_MS = 3000;
+
+/**
+ * How long the bridge may say NOTHING before this connection is presumed dead: three missed
+ * pings, since the bridge pings every 20s even when idle (`server.ts` KEEPALIVE_INTERVAL_MS).
+ *
+ * The only way to notice a peer that is still there but not moving (a host stopped by the OS, a
+ * machine resumed from sleep, a wedged event loop): the port stays open, every flag reads
+ * "connected", and each command dies on its own 30s timeout.
+ */
+const SILENCE_TIMEOUT_MS = 60_000;
+/** Cheap enough to run on a live connection; fine-grained enough that the verdict lands
+ *  within a ping of the deadline. */
+const SILENCE_CHECK_MS = 15_000;
+
+export class RelayConnection {
+  /** @param {import("./transport.js").Transport} transport — native port or ws, same messages */
+  constructor(transport) {
+    this._transport = transport;
+    /** Tabs whose debugger this connection holds. */
+    this._attachedTabs = new Set();
+    this._eventListeners = [];
+    this._closed = false;
+    this._pendingReattach = new Set();
+    this._recentReattach = new Set();
+
+    /** @type {(() => void) | undefined} */
+    this.onclose = undefined;
+    /** @type {((tabId: number) => void) | undefined} */
+    this.ontabattached = undefined;
+    /** @type {((tabId: number) => void) | undefined} */
+    this.ontabdetached = undefined;
+
+    this._lastInbound = Date.now();
+    this._inflightCommands = 0;
+    this._reloading = false;
+    this._silenceTimer = setInterval(() => this._checkSilence(), SILENCE_CHECK_MS);
+
+    this._installEventForwarders();
+    this._transport.onmessage = (message) => void this._onMessage(message);
+    this._transport.onclose = () => this._onClose();
+  }
+
+  /** Nothing from the bridge for {@link SILENCE_TIMEOUT_MS}: drop the line so the worker's
+   *  reconnect loop can build a new one. Closing is safe — a bridge that IS alive answers the
+   *  next connection, and the tab group survives a reconnect. */
+  _checkSilence() {
+    if (this._closed) return;
+    const quiet = Date.now() - this._lastInbound;
+    if (quiet < SILENCE_TIMEOUT_MS) return;
+    debugLog(`bridge silent for ${Math.round(quiet / 1000)}s — treating the connection as dead`);
+    this.close("Bridge stopped answering");
+  }
+
+  /** Which pipe this connection runs on — 'native' or 'ws'. */
+  get transportKind() {
+    return this._transport.kind;
+  }
+
+  get attachedTabs() {
+    return this._attachedTabs;
+  }
+
+  /** Opens the handshake by saying WHICH browser session the tab ids that follow belong to
+   *  (the nonce from group.js `browserSessionId`); the bridge decides what to do with it.
+   *
+   *  It must come BEFORE the first `attachTab`: the bridge drops what it remembers about a
+   *  session it cannot recognise, so a tab announced ahead of the nonce would be forgotten. A
+   *  bridge that predates this logs it as an unknown event and carries on. */
+  didConnect(browserSession) {
+    this._send({ method: "extension.connected", params: [browserSession] });
+  }
+
+  /** Ends the initial handshake: the bridge holds client CDP traffic until this arrives,
+   *  so `Target.setAutoAttach` is always answered from a populated tab model. */
+  didInitialize() {
+    this._send({ method: "extension.initialized", params: [RUNTIME_INFO] });
+  }
+
+  updateAvailable(version) {
+    this._send({ method: "extension.updateAvailable", params: [version] });
+  }
+
+  close(reason) {
+    this._transport.close(reason);
+    // ws.onclose fires asynchronously; run the bookkeeping now so no CDP event
+    // is forwarded to a connection we already decided is gone.
+    this._onClose();
+  }
+
+  /** Announce a tab to the bridge as if it had just been created; the bridge responds by
+   *  attaching the debugger, which flows back through the command channel.
+   *
+   *  Always `{ agent: false }`: tabs the agent opens are created by the bridge, which marks
+   *  them itself (`createTarget`). */
+  attachTab(tab) {
+    if (this._closed || (this._attachedTabs.has(tab.id) && !tab.discarded && tab.status !== "unloaded")) return;
+    this._send({ method: "chrome.tabs.onCreated", params: [tab, { agent: false }] });
+  }
+
+  /** Detach a tab the user dragged out of the group. chrome.debugger.detach does not fire
+   *  onDetach for the caller, so the event the bridge needs is synthesized. */
+  detachTab(tabId) {
+    if (this._closed || !this._attachedTabs.has(tabId)) return;
+    chrome.debugger.detach({ tabId }).catch((e) => debugLog("detach failed:", e));
+    this._notifyDetached(tabId);
+    this._send({ method: "chrome.debugger.onDetach", params: [{ tabId }, "target_closed"] });
+  }
+
+  /**
+   * Release a tab the bridge is done with (its last CDP client went away), WITHOUT
+   * telling the bridge — it already knows; it asked.
+   *
+   * The detach is the point: one debugger session per tab is shared by every client, so a later
+   * client's `Runtime.enable` lands on an already-enabled domain, Chrome replays no execution
+   * contexts, and its `evaluate` hangs forever. A fresh attach brings the replay back. The tab
+   * keeps its group membership.
+   */
+  releaseTab(tabId) {
+    if (this._closed) return;
+    chrome.debugger.detach({ tabId }).catch(() => {}); // already gone is the good case
+    if (this._attachedTabs.has(tabId)) this._notifyDetached(tabId);
+    this._pendingReattach.delete(tabId);
+  }
+
+  _notifyAttached(tabId) {
+    this._attachedTabs.add(tabId);
+    this._pendingReattach.delete(tabId);
+    this.ontabattached?.(tabId);
+  }
+
+  _notifyDetached(tabId) {
+    this._attachedTabs.delete(tabId);
+    this.ontabdetached?.(tabId);
+  }
+
+  _installEventForwarders() {
+    for (const fullMethod of FORWARDED_EVENTS) {
+      const target = resolveChromeMember(fullMethod);
+      const listener = (...args) => this._onChromeEvent(fullMethod, args);
+      target.obj[target.name].addListener(listener);
+      this._eventListeners.push(() => target.obj[target.name].removeListener(listener));
+    }
+  }
+
+  _onClose() {
+    if (this._closed) return;
+    this._closed = true;
+    clearInterval(this._silenceTimer);
+    this._pendingReattach.clear();
+    this._recentReattach.clear();
+    for (const remove of this._eventListeners) remove();
+    this._eventListeners = [];
+    for (const tabId of [...this._attachedTabs]) {
+      chrome.debugger.detach({ tabId }).catch(() => {});
+      this._notifyDetached(tabId);
+    }
+    this.onclose?.();
+  }
+
+
+  /** Forward chrome.* events that concern attached tabs; run detach bookkeeping. */
+  _onChromeEvent(fullMethod, args) {
+    const tabId = this._tabIdForEvent(fullMethod, args);
+    if (tabId === undefined) return;
+    if (!this._attachedTabs.has(tabId) && !this._forwardsWhenDetached(fullMethod)) return;
+    this._send({ method: fullMethod, params: args });
+    if (fullMethod === "chrome.debugger.onDetach") {
+      const reason = args[1];
+      this._notifyDetached(tabId);
+      // A cross-process navigation detaches the debugger with `target_closed` even though
+      // the tab lives on. Re-attach after a beat; a tab that detaches again immediately is
+      // left alone (something else owns it).
+      if (reason === "target_closed" && this._maybeScheduleReattach(tabId)) return;
+    } else if (fullMethod === "chrome.tabs.onReplaced") {
+      this._notifyDetached(tabId);
+    }
+  }
+
+  _maybeScheduleReattach(tabId) {
+    if (this._closed) return false;
+    if (this._recentReattach.has(tabId)) return false;
+    this._recentReattach.add(tabId);
+    setTimeout(() => this._recentReattach.delete(tabId), REATTACH_COOLDOWN_MS);
+    this._pendingReattach.add(tabId);
+    setTimeout(() => void this._tryReattach(tabId), REATTACH_DELAY_MS);
+    return true;
+  }
+
+  async _tryReattach(tabId) {
+    if (this._closed || !this._pendingReattach.has(tabId)) return;
+    let tab;
+    try {
+      tab = await chrome.tabs.get(tabId);
+    } catch {
+      this._pendingReattach.delete(tabId);
+      return;
+    }
+    if (this._closed || !this._pendingReattach.has(tabId)) return;
+    if (this._attachedTabs.has(tabId)) {
+      this._pendingReattach.delete(tabId);
+      return;
+    }
+    this.attachTab(tab);
+    setTimeout(() => {
+      if (this._closed || !this._pendingReattach.has(tabId)) return;
+      this._pendingReattach.delete(tabId);
+      if (!this._attachedTabs.has(tabId)) debugLog("gave up re-attaching tab", tabId);
+    }, REATTACH_VERIFY_MS);
+  }
+
+  _tabIdForEvent(fullMethod, args) {
+    switch (fullMethod) {
+      case "chrome.debugger.onEvent":
+      case "chrome.debugger.onDetach":
+        return args[0]?.tabId;
+      case "chrome.tabs.onCreated":
+        // Only popups opened by an attached tab are the bridge's business.
+        return args[0]?.openerTabId;
+      case "chrome.tabs.onRemoved":
+        return args[0];
+      case "chrome.tabs.onReplaced":
+        return args[1]; // removed id; Chrome assigns a new id when discarding a tab
+      default:
+        return undefined;
+    }
+  }
+
+  /** Does this event still concern the bridge even though we hold no debugger for the tab?
+   *  Closures do: a tab released between tasks is still one the bridge lists and may hand to
+   *  the next client, and a client handed a closed tab waits on a renderer that is gone. */
+  _forwardsWhenDetached(fullMethod) {
+    return fullMethod === "chrome.tabs.onRemoved" || fullMethod === "chrome.tabs.onReplaced";
+  }
+
+  async _onMessage(message) {
+    this._lastInbound = Date.now();
+    this._inflightCommands += 1;
+    const response = { id: message.id };
+    try {
+      response.result = await this._handleCommand(message);
+    } catch (e) {
+      response.error = e?.message ?? String(e);
+    } finally {
+      this._inflightCommands -= 1;
+    }
+    this._send(response);
+  }
+
+  async _handleCommand(message) {
+    if (this._reloading) throw new Error("The Mirasim extension is reloading; reconnect before continuing.");
+    if (message.method === "bridge.reload") {
+      // The bridge also waits for all CDP clients, including clients between tool calls.
+      // This last guard protects against commands or attachments that have not drained yet.
+      if (this._inflightCommands !== 1 || this._attachedTabs.size) throw new Error("The Mirasim extension is busy; finish the browser task before reloading.");
+      this._reloading = true;
+      setTimeout(() => chrome.runtime.reload(), 100); // send the receipt before closing the port
+      return { scheduled: true };
+    }
+    // Application-level keepalive: receiving and answering it resets the MV3
+    // service-worker idle timer in both directions.
+    if (message.method === "bridge.ping") return {};
+    if (message.method === "bridge.releaseTab") {
+      this.releaseTab((message.params ?? [])[0]);
+      return {};
+    }
+    if (!ALLOWED_COMMANDS.has(message.method)) throw new Error(`Unknown method: ${message.method}`);
+    const args = message.params ?? [];
+    if (message.method === "chrome.debugger.attach") {
+      const target = args[0];
+      // A zombie attach from a previous service-worker life throws "Another debugger is
+      // already attached" against ourselves. Clearing our own leftover is safe; a REAL
+      // other debugger (devtools) re-throws on the second try and that error is honest.
+      try {
+        await invokeChromeMethod(message.method, args);
+      } catch (e) {
+        if (!String(e?.message).includes("already attached")) throw e;
+        await chrome.debugger.detach({ tabId: target?.tabId }).catch(() => {});
+        await invokeChromeMethod(message.method, args);
+      }
+      if (target?.tabId !== undefined) this._notifyAttached(target.tabId);
+      return {};
+    }
+    const result = await invokeChromeMethod(message.method, args);
+    return result ?? {};
+  }
+
+  _send(message) {
+    this._transport.send(message);
+  }
+}
+
+/** Resolve chrome.<api>.<member> for reflective invocation and listener setup. */
+function resolveChromeMember(fullMethod) {
+  const parts = fullMethod.split(".");
+  if (parts[0] !== "chrome" || parts.length < 3) throw new Error(`Invalid chrome method: ${fullMethod}`);
+  let obj = chrome;
+  for (let i = 1; i < parts.length - 1; i++) {
+    obj = obj?.[parts[i]];
+    if (obj === undefined) throw new Error(`Unknown chrome path in ${fullMethod}`);
+  }
+  return { obj, name: parts[parts.length - 1] };
+}
+
+async function invokeChromeMethod(fullMethod, args) {
+  const { obj, name } = resolveChromeMember(fullMethod);
+  const fn = obj[name];
+  if (typeof fn !== "function") throw new Error(`Not a function: ${fullMethod}`);
+  return await fn.apply(obj, args);
+}