@velanir/openclaw-browserbase 0.1.0 → 0.1.1

package/README.md

@@ -27,9 +27,14 @@ 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.
-- Disconnect (task end, idle, gateway restart) releases the session. Login
-  state survives in the context; the next browser action gets a fresh session
-  that is already logged in.
+- 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.
 - One session per coworker context at a time (Browserbase forbids concurrent
   sessions on one context), with a short cooldown after release.
 
@@ -90,8 +95,8 @@ Notes:
 See `openclaw.plugin.json` for the full schema. Defaults implement the locked
 v1 policy: timeout 3600 s, viewport 1280×900, captcha solving on, recording on,
 `ignoreCertificateErrors: false`, per-coworker context with `persist: true`,
-cooldown 10 s, idle disconnect 15 min, reaper every 5 min, no proxies
-(`proxies: []` passes through to session creation when set).
+linger 60 s, cooldown 3 s, idle disconnect 15 min, reaper every 5 min, no
+proxies (`proxies: []` passes through to session creation when set).
 
 ## Agent tools
 

package/dist/index.js

@@ -121,8 +121,18 @@ 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;
@@ -141,38 +151,90 @@ function rawDataToString(data) {
   }
   return Buffer.from(data).toString("utf8");
 }
-var CdpPipe = class {
+var CdpPipe = class _CdpPipe {
   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", (data, isBinary) => {
-      this.lastActivityAt = Date.now();
-      if (!isBinary && this.maybeResolveInjected(data)) {
-        return;
-      }
-      if (downstream.readyState === downstream.OPEN) {
-        downstream.send(data, { binary: isBinary });
-      }
-    });
+    upstream.on("message", this.onUpstreamMessage);
     downstream.on("close", () => this.close("downstream-closed"));
     downstream.on("error", () => this.close("downstream-error"));
-    upstream.on("close", () => this.close("upstream-closed"));
-    upstream.on("error", () => this.close("upstream-error"));
+    upstream.on("close", this.onUpstreamClose);
+    upstream.on("error", this.onUpstreamError);
   }
-  nextInjectedId = INJECTED_ID_BASE;
+  static pipeSeq = 0;
+  nextInjectedId = INJECTED_ID_BASE + _CdpPipe.pipeSeq++ % INJECTED_ID_PIPE_SLOTS * INJECTED_ID_PIPE_STRIDE;
   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) {
@@ -228,7 +290,9 @@ var CdpPipe = class {
       entry.reject(new Error(`CDP pipe closed: ${reason}`));
     }
     this.pending.clear();
-    for (const socket of [this.downstream, this.upstream]) {
+    this.opts.onClose(reason);
+    const sockets = this.upstreamClaimed ? [this.downstream] : [this.downstream, this.upstream];
+    for (const socket of sockets) {
       if (socket.readyState === socket.OPEN || socket.readyState === socket.CLOSING) {
         try {
           socket.close(1e3);
@@ -239,7 +303,6 @@ var CdpPipe = class {
         socket.terminate();
       }
     }
-    this.opts.onClose(reason);
   }
 };
 
@@ -250,8 +313,9 @@ var DEFAULT_TIMEOUT_SECONDS = 3600;
 var MIN_TIMEOUT_SECONDS = 60;
 var MAX_TIMEOUT_SECONDS = 21600;
 var DEFAULT_VIEWPORT = { width: 1280, height: 900 };
-var DEFAULT_CONTEXT_COOLDOWN_SECONDS = 10;
+var DEFAULT_CONTEXT_COOLDOWN_SECONDS = 3;
 var DEFAULT_CONTEXT_WAIT_MS = 1e4;
+var DEFAULT_LINGER_SECONDS = 60;
 var DEFAULT_IDLE_DISCONNECT_MINUTES = 15;
 var DEFAULT_REAPER_INTERVAL_MINUTES = 5;
 var DEFAULT_API_BASE_URL = "https://api.browserbase.com";
@@ -368,6 +432,7 @@ function normalizeConfig(raw) {
       waitMs: readNumber(context.waitMs, DEFAULT_CONTEXT_WAIT_MS, 0, 6e4)
     },
     proxies: readProxies(root.proxies),
+    lingerSeconds: readNumber(root.lingerSeconds, DEFAULT_LINGER_SECONDS, 0, 600),
     idleDisconnectMinutes: readNumber(root.idleDisconnectMinutes, DEFAULT_IDLE_DISCONNECT_MINUTES, 0, 1440),
     reaperIntervalMinutes: readNumber(root.reaperIntervalMinutes, DEFAULT_REAPER_INTERVAL_MINUTES, 0, 1440),
     apiBaseUrl: readString(root.apiBaseUrl) ?? DEFAULT_API_BASE_URL,
@@ -752,7 +817,7 @@ var BrowserbaseBroker = class {
     if (liveness.gone) {
       liveness.detach();
       socket.destroy();
-      this.holdForAdoption(minted, held.upstream);
+      this.holdForAdoption(minted, held.upstream, { staleClientIds: held.staleClientIds ?? [] });
       return;
     }
     let upstream = held.upstream && held.upstream.readyState === held.upstream.OPEN ? held.upstream : null;
@@ -777,15 +842,16 @@ var BrowserbaseBroker = class {
     if (liveness.gone) {
       liveness.detach();
       socket.destroy();
-      this.holdForAdoption(minted, upstream);
+      this.holdForAdoption(minted, upstream, { staleClientIds: held.staleClientIds ?? [] });
       return;
     }
     liveness.detach();
+    const staleClientIds = held.staleClientIds ?? [];
     this.wss.handleUpgrade(req, socket, head, (downstream) => {
-      this.attachPipe(downstream, upstream, minted);
+      this.attachPipe(downstream, upstream, minted, staleClientIds);
     });
   }
-  attachPipe(downstream, upstream, minted) {
+  attachPipe(downstream, upstream, minted, staleClientIds = []) {
     if (upstream.readyState !== upstream.OPEN || downstream.readyState !== downstream.OPEN) {
       upstream.terminate();
       if (downstream.readyState === downstream.OPEN) {
@@ -798,12 +864,14 @@ var BrowserbaseBroker = class {
       return;
     }
     const pipe = new CdpPipe(downstream, upstream, {
-      onClose: (reason) => this.onPipeClosed(minted.sessionId, reason)
+      onClose: (reason) => this.onPipeClosed(minted.sessionId, reason),
+      ...staleClientIds.length ? { suppressStaleIds: staleClientIds } : {}
     });
     this.active = {
       sessionId: minted.sessionId,
       leaseId: minted.leaseId,
       contextId: minted.contextId,
+      connectUrl: minted.connectUrl,
       ...minted.expiresAt ? { expiresAt: minted.expiresAt } : {},
       startedAt: Date.now(),
       pipe
@@ -813,10 +881,29 @@ var BrowserbaseBroker = class {
     );
   }
   onPipeClosed(sessionId, reason) {
-    if (this.active?.sessionId !== sessionId) {
+    const active = this.active;
+    if (active?.sessionId !== sessionId) {
       return;
     }
     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.cooldownUntil = Date.now() + this.config.context.cooldownSeconds * 1e3;
     this.logger.info?.(`session ${sessionId} disconnected (${reason}); releasing`);
     void this.releaseQuietly(sessionId, reason).finally(() => {
@@ -907,18 +994,21 @@ var BrowserbaseBroker = class {
       });
     });
   }
-  holdForAdoption(session, upstream) {
+  holdForAdoption(session, upstream, opts = {}) {
+    const reason = opts.reason ?? "adoption";
+    const windowMs = opts.windowMs ?? ADOPTION_WINDOW_MS;
     this.logger.info?.(
-      `holding session ${session.sessionId} for adoption (client disconnected mid-handshake, upstream ${upstream ? "open" : "not dialed"})`
+      `holding session ${session.sessionId} (${reason}, ${Math.round(windowMs / 1e3)}s window, upstream ${upstream ? "open" : "not dialed"})`
     );
     const timer = setTimeout(() => {
       if (this.adoptable?.session.sessionId === session.sessionId) {
         const held = this.adoptable;
         this.adoptable = null;
         held.upstream?.terminate();
-        void this.releaseQuietly(session.sessionId, "adoption-expired");
+        this.cooldownUntil = Date.now() + this.config.context.cooldownSeconds * 1e3;
+        void this.releaseQuietly(session.sessionId, `${reason}-expired`);
       }
-    }, ADOPTION_WINDOW_MS);
+    }, windowMs);
     timer.unref();
     let onUpstreamLost;
     if (upstream) {
@@ -926,7 +1016,8 @@ var BrowserbaseBroker = class {
         if (this.adoptable?.session.sessionId === session.sessionId && this.adoptable.upstream === upstream) {
           clearTimeout(this.adoptable.timer);
           this.adoptable = null;
-          void this.releaseQuietly(session.sessionId, "adoption-upstream-lost");
+          this.cooldownUntil = Date.now() + this.config.context.cooldownSeconds * 1e3;
+          void this.releaseQuietly(session.sessionId, `${reason}-upstream-lost`);
         }
       };
       upstream.once("close", onUpstreamLost);
@@ -934,7 +1025,9 @@ var BrowserbaseBroker = class {
     }
     this.adoptable = {
       session,
+      heldReason: reason,
       ...upstream ? { upstream } : {},
+      ...opts.staleClientIds?.length ? { staleClientIds: opts.staleClientIds } : {},
       ...onUpstreamLost ? { onUpstreamLost } : {},
       timer
     };
@@ -952,7 +1045,8 @@ var BrowserbaseBroker = class {
     this.adoptable = null;
     return {
       session: held.session,
-      ...held.upstream ? { upstream: held.upstream } : {}
+      ...held.upstream ? { upstream: held.upstream } : {},
+      ...held.staleClientIds?.length ? { staleClientIds: held.staleClientIds } : {}
     };
   }
   // ------------------------------------------------------------- cleanup --
@@ -1019,24 +1113,32 @@ var BrowserbaseBroker = class {
         startedAt: new Date(active.startedAt).toISOString(),
         ...active.expiresAt ? { expiresAt: active.expiresAt } : {},
         idleMs: Date.now() - active.pipe.lastActivityAt
-      } : null
+      } : null,
+      held: this.adoptable ? { sessionId: this.adoptable.session.sessionId, reason: this.adoptable.heldReason } : null
     };
   }
   async getLiveViewUrls() {
-    const active = this.active;
-    if (!active || active.pipe.closed) {
+    const sessionId = this.active && !this.active.pipe.closed ? this.active.sessionId : this.adoptable?.upstream ? this.adoptable.session.sessionId : null;
+    if (!sessionId) {
       return null;
     }
-    return this.client.getDebugUrls(active.sessionId);
+    return this.client.getDebugUrls(sessionId);
   }
   /** Returns true when there was an active session to release. */
   releaseActiveSession() {
     const active = this.active;
-    if (!active || active.pipe.closed) {
-      return false;
+    if (active && !active.pipe.closed) {
+      active.pipe.close("manual-release");
+      return true;
     }
-    active.pipe.close("manual-release");
-    return true;
+    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");
+      return true;
+    }
+    return false;
   }
 };
 
@@ -1063,7 +1165,7 @@ function createBrowserbaseTools(getBroker) {
         const status = broker.getStatus();
         if (!status.active) {
           const lines2 = [
-            NO_SESSION,
+            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,
             `Region: ${status.region}. Recording: ${status.recordSession ? "on" : "off"}.`,
             status.contextId ? `Browser context: ${status.contextId}` : "Browser context: created on first use."
           ];

package/openclaw.plugin.json

@@ -8,7 +8,6 @@
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
-    "required": ["projectId", "apiKey", "listenPort"],
     "properties": {
       "projectId": {
         "type": "string",
@@ -20,7 +19,12 @@
       },
       "region": {
         "type": "string",
-        "enum": ["us-west-2", "us-east-1", "eu-central-1", "ap-southeast-1"],
+        "enum": [
+          "us-west-2",
+          "us-east-1",
+          "eu-central-1",
+          "ap-southeast-1"
+        ],
         "default": "us-west-2"
       },
       "listenPort": {
@@ -38,7 +42,9 @@
       },
       "metadata": {
         "type": "object",
-        "additionalProperties": { "type": "string" }
+        "additionalProperties": {
+          "type": "string"
+        }
       },
       "defaults": {
         "type": "object",
@@ -54,28 +60,63 @@
             "type": "object",
             "additionalProperties": false,
             "properties": {
-              "width": { "type": "number", "minimum": 320, "maximum": 3840 },
-              "height": { "type": "number", "minimum": 320, "maximum": 2160 }
+              "width": {
+                "type": "number",
+                "minimum": 320,
+                "maximum": 3840
+              },
+              "height": {
+                "type": "number",
+                "minimum": 320,
+                "maximum": 2160
+              }
             }
           },
-          "solveCaptchas": { "type": "boolean", "default": true },
-          "recordSession": { "type": "boolean", "default": true },
-          "logSession": { "type": "boolean", "default": true },
-          "ignoreCertificateErrors": { "type": "boolean", "default": false }
+          "solveCaptchas": {
+            "type": "boolean",
+            "default": true
+          },
+          "recordSession": {
+            "type": "boolean",
+            "default": true
+          },
+          "logSession": {
+            "type": "boolean",
+            "default": true
+          },
+          "ignoreCertificateErrors": {
+            "type": "boolean",
+            "default": false
+          }
         }
       },
       "context": {
         "type": "object",
         "additionalProperties": false,
         "properties": {
-          "persist": { "type": "boolean", "default": true },
-          "cooldownSeconds": { "type": "number", "default": 10, "minimum": 0, "maximum": 120 },
-          "waitMs": { "type": "number", "default": 10000, "minimum": 0, "maximum": 60000 }
+          "persist": {
+            "type": "boolean",
+            "default": true
+          },
+          "cooldownSeconds": {
+            "type": "number",
+            "default": 3,
+            "minimum": 0,
+            "maximum": 120
+          },
+          "waitMs": {
+            "type": "number",
+            "default": 10000,
+            "minimum": 0,
+            "maximum": 60000
+          }
         }
       },
       "proxies": {
         "type": "array",
-        "items": { "type": "object" },
+        "items": {
+          "type": "object"
+        },
         "default": []
       },
       "idleDisconnectMinutes": {
@@ -87,6 +128,12 @@
         "type": "number",
         "default": 5,
         "minimum": 0
+      },
+      "lingerSeconds": {
+        "type": "number",
+        "default": 60,
+        "minimum": 0,
+        "maximum": 600
       }
     }
   },
@@ -120,6 +167,10 @@
     "idleDisconnectMinutes": {
       "label": "Idle Disconnect (min)",
       "help": "Close and release the Browserbase session after this many minutes without CDP traffic. 0 disables. Login state survives via the persistent context."
+    },
+    "lingerSeconds": {
+      "label": "Linger (s)",
+      "help": "Keep the session and its connection alive after a disconnect so the next browser action re-attaches instantly instead of minting a new session. 0 releases immediately."
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velanir/openclaw-browserbase",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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",