@velanir/openclaw-browserbase 0.1.1 → 0.1.2

package/README.md

@@ -27,14 +27,19 @@ browser tool ──cdpUrl http://127.0.0.1:<port>/?token=…──> broker (this
 - Every session is created with the coworker's persistent context
   (`persist: true`), the configured timeout/viewport/captcha/recording policy,
   and `userMetadata` tagging for observability and reaping.
-- On downstream disconnect the broker **lingers**: the session and its
-  upstream connection are held (default 60s) so the next browser action
-  re-attaches instantly — no new mint, no cooldown. OpenClaw's browser tool
-  opens short probe connections and reconnects between actions; without
-  linger every probe minted (and released) a billable session and the
-  post-release cooldown starved the real connection. Explicit release, idle
-  disconnect, linger expiry, and gateway shutdown all still release
-  deterministically; login state survives in the context either way.
+- Sessions are created with **`keepAlive: true`**, so on downstream
+  disconnect the broker **lingers**: it closes the CDP connection but keeps
+  the Browserbase session alive (default 60s) and **re-dials a fresh CDP
+  connection** to it on the next browser action — no new mint, no cooldown,
+  and tabs/login state intact. OpenClaw's browser tool opens short probe
+  connections and reconnects between actions; without linger every probe
+  minted (and released) a billable session and the post-release cooldown
+  starved the real connection. Because each client gets a brand-new CDP
+  connection (fresh id space), a late reply to a previous client's command
+  can never reach the next one. Explicit release, idle disconnect, linger
+  expiry, and gateway shutdown all release the keepAlive session
+  deterministically (keepAlive sessions do not self-terminate, so the reaper
+  also backstops crash leftovers).
 - One session per coworker context at a time (Browserbase forbids concurrent
   sessions on one context), with a short cooldown after release.
 

package/dist/index.js

@@ -25,7 +25,13 @@ function buildSessionPayload(config, mint) {
     projectId: config.projectId,
     region: config.region,
     timeout: Math.round(config.defaults.timeoutSeconds),
-    keepAlive: false,
+    // keepAlive lets the session survive a CDP disconnect so the broker can
+    // close the old connection and re-dial a FRESH one for the next client
+    // (linger) — no mint, and a fresh CDP id space so stale replies are
+    // impossible by construction. The broker is responsible for explicit
+    // release (linger expiry, idle, shutdown, reaper), since keepAlive
+    // sessions do not self-terminate on disconnect.
+    keepAlive: true,
     // Omit `proxies` entirely when unset so Browserbase applies plain direct
     // egress rather than an empty routing array.
     ...config.proxies.length > 0 ? { proxies: config.proxies } : {},
@@ -121,18 +127,8 @@ var BrowserbaseClient = class {
 
 // src/cdp-pipe.ts
 var INJECTED_ID_BASE = 19e8;
-var INJECTED_ID_PIPE_STRIDE = 1e6;
-var INJECTED_ID_PIPE_SLOTS = 200;
 var INJECTED_RESPONSE_MAX_BYTES = 4096;
 var DEFAULT_INJECTION_TIMEOUT_MS = 2e3;
-var STALE_REPLY_TTL_MS = 15e3;
-var MAX_TRACKED_CLIENT_IDS = 256;
-var FRAME_HEAD_ID_RE = /"id"\s*:\s*(\d+)/;
-function frameHeadId(data) {
-  const head = Buffer.isBuffer(data) ? data.subarray(0, 64).toString("utf8") : Array.isArray(data) ? Buffer.concat(data).subarray(0, 64).toString("utf8") : Buffer.from(data).subarray(0, 64).toString("utf8");
-  const match = FRAME_HEAD_ID_RE.exec(head);
-  return match ? Number(match[1]) : null;
-}
 function rawDataByteLength(data) {
   if (Buffer.isBuffer(data)) {
     return data.byteLength;
@@ -151,90 +147,38 @@ function rawDataToString(data) {
   }
   return Buffer.from(data).toString("utf8");
 }
-var CdpPipe = class _CdpPipe {
+var CdpPipe = class {
   constructor(downstream, upstream, opts) {
     this.downstream = downstream;
     this.upstream = upstream;
     this.opts = opts;
-    const ttl = Date.now() + STALE_REPLY_TTL_MS;
-    for (const id of opts.suppressStaleIds ?? []) {
-      this.suppressStale.set(id, ttl);
-    }
     downstream.on("message", (data, isBinary) => {
       this.lastActivityAt = Date.now();
-      if (!isBinary && this.clientPendingIds.size < MAX_TRACKED_CLIENT_IDS) {
-        const id = frameHeadId(data);
-        if (id !== null && id < INJECTED_ID_BASE) {
-          this.clientPendingIds.add(id);
-        }
-      }
       if (upstream.readyState === upstream.OPEN) {
         upstream.send(data, { binary: isBinary });
       }
     });
-    upstream.on("message", this.onUpstreamMessage);
+    upstream.on("message", (data, isBinary) => {
+      this.lastActivityAt = Date.now();
+      if (!isBinary && this.maybeResolveInjected(data)) {
+        return;
+      }
+      if (downstream.readyState === downstream.OPEN) {
+        downstream.send(data, { binary: isBinary });
+      }
+    });
     downstream.on("close", () => this.close("downstream-closed"));
     downstream.on("error", () => this.close("downstream-error"));
-    upstream.on("close", this.onUpstreamClose);
-    upstream.on("error", this.onUpstreamError);
+    upstream.on("close", () => this.close("upstream-closed"));
+    upstream.on("error", () => this.close("upstream-error"));
   }
-  static pipeSeq = 0;
-  nextInjectedId = INJECTED_ID_BASE + _CdpPipe.pipeSeq++ % INJECTED_ID_PIPE_SLOTS * INJECTED_ID_PIPE_STRIDE;
+  nextInjectedId = INJECTED_ID_BASE;
   pending = /* @__PURE__ */ new Map();
   closeReason = null;
-  upstreamClaimed = false;
-  /** Downstream command ids sent upstream with no reply seen yet. */
-  clientPendingIds = /* @__PURE__ */ new Set();
-  /** Stale ids from the previous client on this upstream → suppression deadline. */
-  suppressStale = /* @__PURE__ */ new Map();
   lastActivityAt = Date.now();
-  // Named so takeUpstream() can detach exactly the pipe's listeners from a
-  // claimed (lingering) upstream without disturbing the hold's own listeners.
-  onUpstreamMessage = (data, isBinary) => {
-    this.lastActivityAt = Date.now();
-    if (!isBinary) {
-      const id = frameHeadId(data);
-      if (id !== null) {
-        this.clientPendingIds.delete(id);
-        const deadline = this.suppressStale.get(id);
-        if (deadline !== void 0) {
-          this.suppressStale.delete(id);
-          if (Date.now() <= deadline) {
-            return;
-          }
-        }
-      }
-      if (this.maybeResolveInjected(data)) {
-        return;
-      }
-    }
-    if (this.downstream.readyState === this.downstream.OPEN) {
-      this.downstream.send(data, { binary: isBinary });
-    }
-  };
-  onUpstreamClose = () => this.close("upstream-closed");
-  onUpstreamError = () => this.close("upstream-error");
   get closed() {
     return this.closeReason !== null;
   }
-  /**
-   * Claim the upstream socket out of the pipe while it is still OPEN —
-   * callable from inside the onClose handler so the broker can keep the
-   * Browserbase session alive (linger) instead of releasing on downstream
-   * disconnect. Returns null when the upstream is already gone or claimed.
-   * staleClientIds are the old client's still-unanswered command ids; the
-   * next pipe on this upstream must suppress their late replies.
-   */
-  takeUpstream() {
-    if (this.upstreamClaimed || this.upstream.readyState !== this.upstream.OPEN) {
-      return null;
-    }
-    this.upstreamClaimed = true;
-    this.upstream.off("message", this.onUpstreamMessage);
-    this.upstream.off("close", this.onUpstreamClose);
-    this.upstream.off("error", this.onUpstreamError);
-    return { socket: this.upstream, staleClientIds: [...this.clientPendingIds] };
-  }
   /** Send a broker-owned CDP command on the piped connection and await its reply. */
   inject(method, params) {
     if (this.closeReason !== null || this.upstream.readyState !== this.upstream.OPEN) {
@@ -290,9 +234,7 @@ var CdpPipe = class _CdpPipe {
       entry.reject(new Error(`CDP pipe closed: ${reason}`));
     }
     this.pending.clear();
-    this.opts.onClose(reason);
-    const sockets = this.upstreamClaimed ? [this.downstream] : [this.downstream, this.upstream];
-    for (const socket of sockets) {
+    for (const socket of [this.downstream, this.upstream]) {
       if (socket.readyState === socket.OPEN || socket.readyState === socket.CLOSING) {
         try {
           socket.close(1e3);
@@ -303,6 +245,7 @@ var CdpPipe = class _CdpPipe {
         socket.terminate();
       }
     }
+    this.opts.onClose(reason);
   }
 };
 
@@ -587,6 +530,9 @@ var BrowserbaseBroker = class {
   idleSweepIntervalMs;
   server = null;
   active = null;
+  // A live keepAlive session held resumable (by connectUrl) for a window —
+  // re-dialed on the next connect (linger) or retry (adoption), released on
+  // expiry.
   adoptable = null;
   cooldownUntil = 0;
   timers = [];
@@ -646,8 +592,7 @@ var BrowserbaseBroker = class {
       clearTimeout(this.adoptable.timer);
       const held = this.adoptable;
       this.adoptable = null;
-      held.upstream?.terminate();
-      await this.releaseQuietly(held.session.sessionId, "shutdown-unattached");
+      await this.releaseQuietly(held.session.sessionId, "shutdown-resumable");
     }
     const active = this.active;
     if (active) {
@@ -799,9 +744,9 @@ var BrowserbaseBroker = class {
       socket.destroy();
       return;
     }
-    let held;
+    let minted;
     try {
-      held = await this.acquireSession(leaseId);
+      minted = await this.acquireSession(leaseId);
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       this.logger.warn?.(`session acquire failed: ${message}`);
@@ -813,45 +758,41 @@ var BrowserbaseBroker = class {
       }
       return;
     }
-    const minted = held.session;
     if (liveness.gone) {
       liveness.detach();
       socket.destroy();
-      this.holdForAdoption(minted, held.upstream, { staleClientIds: held.staleClientIds ?? [] });
+      this.holdForAdoption(minted);
       return;
     }
-    let upstream = held.upstream && held.upstream.readyState === held.upstream.OPEN ? held.upstream : null;
-    if (upstream === null) {
-      held.upstream?.terminate();
-      try {
-        upstream = await this.dialUpstream(minted.connectUrl);
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        this.logger.warn?.(`upstream dial failed for session ${minted.sessionId}: ${message}`);
-        await this.releaseQuietly(minted.sessionId, "upstream-dial-failed");
-        this.cooldownUntil = Date.now() + this.config.context.cooldownSeconds * 1e3;
-        liveness.detach();
-        if (liveness.gone) {
-          socket.destroy();
-        } else {
-          destroyWithHttpError(socket, 502, "Bad Gateway", `Browserbase connect failed: ${message}`);
-        }
-        return;
+    let upstream;
+    try {
+      upstream = await this.dialUpstream(minted.connectUrl);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      this.logger.warn?.(`upstream dial failed for session ${minted.sessionId}: ${message}`);
+      await this.releaseQuietly(minted.sessionId, "upstream-dial-failed");
+      this.cooldownUntil = Date.now() + this.config.context.cooldownSeconds * 1e3;
+      liveness.detach();
+      if (liveness.gone) {
+        socket.destroy();
+      } else {
+        destroyWithHttpError(socket, 502, "Bad Gateway", `Browserbase connect failed: ${message}`);
       }
+      return;
     }
     if (liveness.gone) {
       liveness.detach();
       socket.destroy();
-      this.holdForAdoption(minted, upstream, { staleClientIds: held.staleClientIds ?? [] });
+      upstream.terminate();
+      this.holdForAdoption(minted);
       return;
     }
     liveness.detach();
-    const staleClientIds = held.staleClientIds ?? [];
     this.wss.handleUpgrade(req, socket, head, (downstream) => {
-      this.attachPipe(downstream, upstream, minted, staleClientIds);
+      this.attachPipe(downstream, upstream, minted);
     });
   }
-  attachPipe(downstream, upstream, minted, staleClientIds = []) {
+  attachPipe(downstream, upstream, minted) {
     if (upstream.readyState !== upstream.OPEN || downstream.readyState !== downstream.OPEN) {
       upstream.terminate();
       if (downstream.readyState === downstream.OPEN) {
@@ -864,8 +805,7 @@ var BrowserbaseBroker = class {
       return;
     }
     const pipe = new CdpPipe(downstream, upstream, {
-      onClose: (reason) => this.onPipeClosed(minted.sessionId, reason),
-      ...staleClientIds.length ? { suppressStaleIds: staleClientIds } : {}
+      onClose: (reason) => this.onPipeClosed(minted.sessionId, reason)
     });
     this.active = {
       sessionId: minted.sessionId,
@@ -888,21 +828,19 @@ var BrowserbaseBroker = class {
     this.active = null;
     const downstreamGone = reason === "downstream-closed" || reason === "downstream-error";
     if (downstreamGone && !this.stopping && this.config.lingerSeconds > 0) {
-      const claimed = active.pipe.takeUpstream();
-      if (claimed) {
-        this.holdForAdoption(
-          {
-            sessionId: active.sessionId,
-            connectUrl: active.connectUrl,
-            contextId: active.contextId,
-            leaseId: active.leaseId,
-            ...active.expiresAt ? { expiresAt: active.expiresAt } : {}
-          },
-          claimed.socket,
-          { windowMs: this.config.lingerSeconds * 1e3, reason: "linger", staleClientIds: claimed.staleClientIds }
-        );
-        return;
-      }
+      this.holdForAdoption(
+        {
+          sessionId: active.sessionId,
+          connectUrl: active.connectUrl,
+          contextId: active.contextId,
+          leaseId: active.leaseId,
+          ...active.expiresAt ? { expiresAt: active.expiresAt } : {}
+        },
+        { windowMs: this.config.lingerSeconds * 1e3, reason: "linger" }
+      );
+      this.logger.info?.(`session ${sessionId} disconnected (${reason}); lingering for re-dial (keepAlive)`);
+      this.onActiveReleased?.();
+      return;
     }
     this.cooldownUntil = Date.now() + this.config.context.cooldownSeconds * 1e3;
     this.logger.info?.(`session ${sessionId} disconnected (${reason}); releasing`);
@@ -915,7 +853,7 @@ var BrowserbaseBroker = class {
     const adopted = this.takeAdoptable();
     if (adopted) {
       this.logger.info?.(
-        `adopting held session ${adopted.session.sessionId} (minted for lease ${adopted.session.leaseId}, requested by lease ${leaseId})`
+        `resuming held session ${adopted.sessionId} (minted for lease ${adopted.leaseId}, requested by lease ${leaseId})`
       );
       return adopted;
     }
@@ -932,7 +870,7 @@ var BrowserbaseBroker = class {
     if (cooldownRemaining > 0) {
       await sleep(cooldownRemaining);
     }
-    return { session: await this.mintSession(leaseId) };
+    return this.mintSession(leaseId);
   }
   async mintSession(leaseId) {
     const contextId = await this.ensureContext();
@@ -994,43 +932,21 @@ var BrowserbaseBroker = class {
       });
     });
   }
-  holdForAdoption(session, upstream, opts = {}) {
+  holdForAdoption(session, opts = {}) {
     const reason = opts.reason ?? "adoption";
     const windowMs = opts.windowMs ?? ADOPTION_WINDOW_MS;
     this.logger.info?.(
-      `holding session ${session.sessionId} (${reason}, ${Math.round(windowMs / 1e3)}s window, upstream ${upstream ? "open" : "not dialed"})`
+      `holding session ${session.sessionId} (${reason}, ${Math.round(windowMs / 1e3)}s window) for re-dial`
     );
     const timer = setTimeout(() => {
       if (this.adoptable?.session.sessionId === session.sessionId) {
-        const held = this.adoptable;
         this.adoptable = null;
-        held.upstream?.terminate();
         this.cooldownUntil = Date.now() + this.config.context.cooldownSeconds * 1e3;
         void this.releaseQuietly(session.sessionId, `${reason}-expired`);
       }
     }, windowMs);
     timer.unref();
-    let onUpstreamLost;
-    if (upstream) {
-      onUpstreamLost = () => {
-        if (this.adoptable?.session.sessionId === session.sessionId && this.adoptable.upstream === upstream) {
-          clearTimeout(this.adoptable.timer);
-          this.adoptable = null;
-          this.cooldownUntil = Date.now() + this.config.context.cooldownSeconds * 1e3;
-          void this.releaseQuietly(session.sessionId, `${reason}-upstream-lost`);
-        }
-      };
-      upstream.once("close", onUpstreamLost);
-      upstream.once("error", onUpstreamLost);
-    }
-    this.adoptable = {
-      session,
-      heldReason: reason,
-      ...upstream ? { upstream } : {},
-      ...opts.staleClientIds?.length ? { staleClientIds: opts.staleClientIds } : {},
-      ...onUpstreamLost ? { onUpstreamLost } : {},
-      timer
-    };
+    this.adoptable = { session, heldReason: reason, timer };
   }
   takeAdoptable() {
     const held = this.adoptable;
@@ -1038,16 +954,8 @@ var BrowserbaseBroker = class {
       return null;
     }
     clearTimeout(held.timer);
-    if (held.upstream && held.onUpstreamLost) {
-      held.upstream.off("close", held.onUpstreamLost);
-      held.upstream.off("error", held.onUpstreamLost);
-    }
     this.adoptable = null;
-    return {
-      session: held.session,
-      ...held.upstream ? { upstream: held.upstream } : {},
-      ...held.staleClientIds?.length ? { staleClientIds: held.staleClientIds } : {}
-    };
+    return held.session;
   }
   // ------------------------------------------------------------- cleanup --
   async releaseQuietly(sessionId, reason) {
@@ -1118,7 +1026,7 @@ var BrowserbaseBroker = class {
     };
   }
   async getLiveViewUrls() {
-    const sessionId = this.active && !this.active.pipe.closed ? this.active.sessionId : this.adoptable?.upstream ? this.adoptable.session.sessionId : null;
+    const sessionId = this.active && !this.active.pipe.closed ? this.active.sessionId : this.adoptable ? this.adoptable.session.sessionId : null;
     if (!sessionId) {
       return null;
     }
@@ -1133,9 +1041,8 @@ var BrowserbaseBroker = class {
     }
     const held = this.takeAdoptable();
     if (held) {
-      held.upstream?.terminate();
       this.cooldownUntil = Date.now() + this.config.context.cooldownSeconds * 1e3;
-      void this.releaseQuietly(held.session.sessionId, "manual-release");
+      void this.releaseQuietly(held.sessionId, "manual-release");
       return true;
     }
     return false;
@@ -1165,7 +1072,7 @@ function createBrowserbaseTools(getBroker) {
         const status = broker.getStatus();
         if (!status.active) {
           const lines2 = [
-            status.held?.reason === "linger" ? `Browserbase session ${status.held.sessionId} is lingering for instant resume \u2014 the next browser action re-attaches to it (same tabs may be gone, login state intact).` : NO_SESSION,
+            status.held?.reason === "linger" ? `Browserbase session ${status.held.sessionId} is paused (keepAlive) for resume \u2014 the next browser action reconnects to it with your tabs and login state intact.` : NO_SESSION,
             `Region: ${status.region}. Recording: ${status.recordSession ? "on" : "off"}.`,
             status.contextId ? `Browser context: ${status.contextId}` : "Browser context: created on first use."
           ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velanir/openclaw-browserbase",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "OpenClaw plugin that brokers Browserbase sessions behind a loopback CDP endpoint: explicit session creation with per-coworker persistent contexts, deterministic release, and stale-session reaping.",
   "license": "UNLICENSED",
   "type": "module",