@velanir/openclaw-browserbase 0.1.0 → 0.1.2

package/README.md

@@ -27,9 +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.
-- 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.
+- 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.
 
@@ -90,8 +100,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

@@ -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 } : {},
@@ -250,8 +256,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 +375,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,
@@ -522,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 = [];
@@ -581,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) {
@@ -734,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}`);
@@ -748,36 +758,33 @@ var BrowserbaseBroker = class {
       }
       return;
     }
-    const minted = held.session;
     if (liveness.gone) {
       liveness.detach();
       socket.destroy();
-      this.holdForAdoption(minted, held.upstream);
+      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);
+      upstream.terminate();
+      this.holdForAdoption(minted);
       return;
     }
     liveness.detach();
@@ -804,6 +811,7 @@ var BrowserbaseBroker = class {
       sessionId: minted.sessionId,
       leaseId: minted.leaseId,
       contextId: minted.contextId,
+      connectUrl: minted.connectUrl,
       ...minted.expiresAt ? { expiresAt: minted.expiresAt } : {},
       startedAt: Date.now(),
       pipe
@@ -813,10 +821,27 @@ 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) {
+      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`);
     void this.releaseQuietly(sessionId, reason).finally(() => {
@@ -828,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;
     }
@@ -845,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();
@@ -907,37 +932,21 @@ var BrowserbaseBroker = class {
       });
     });
   }
-  holdForAdoption(session, upstream) {
+  holdForAdoption(session, 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) for re-dial`
     );
     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) {
-      onUpstreamLost = () => {
-        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");
-        }
-      };
-      upstream.once("close", onUpstreamLost);
-      upstream.once("error", onUpstreamLost);
-    }
-    this.adoptable = {
-      session,
-      ...upstream ? { upstream } : {},
-      ...onUpstreamLost ? { onUpstreamLost } : {},
-      timer
-    };
+    this.adoptable = { session, heldReason: reason, timer };
   }
   takeAdoptable() {
     const held = this.adoptable;
@@ -945,15 +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 } : {}
-    };
+    return held.session;
   }
   // ------------------------------------------------------------- cleanup --
   async releaseQuietly(sessionId, reason) {
@@ -1019,24 +1021,31 @@ 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 ? 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) {
+      this.cooldownUntil = Date.now() + this.config.context.cooldownSeconds * 1e3;
+      void this.releaseQuietly(held.sessionId, "manual-release");
+      return true;
+    }
+    return false;
   }
 };
 
@@ -1063,7 +1072,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 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/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.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",