@velanir/openclaw-browserbase 0.1.0

package/dist/index.js

@@ -0,0 +1,1173 @@
+// src/api.ts
+import { definePluginEntry as defineOpenClawPluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+function definePluginEntry(entry) {
+  return defineOpenClawPluginEntry(entry);
+}
+
+// src/broker.ts
+import { createHash, randomUUID, timingSafeEqual } from "crypto";
+import { createServer } from "http";
+import { WebSocket, WebSocketServer } from "ws";
+
+// src/browserbase-client.ts
+var BrowserbaseApiError = class extends Error {
+  constructor(message, status, retryAfterMs) {
+    super(message);
+    this.status = status;
+    this.retryAfterMs = retryAfterMs;
+  }
+  get isRateLimit() {
+    return this.status === 429;
+  }
+};
+function buildSessionPayload(config, mint) {
+  return {
+    projectId: config.projectId,
+    region: config.region,
+    timeout: Math.round(config.defaults.timeoutSeconds),
+    keepAlive: false,
+    // Omit `proxies` entirely when unset so Browserbase applies plain direct
+    // egress rather than an empty routing array.
+    ...config.proxies.length > 0 ? { proxies: config.proxies } : {},
+    browserSettings: {
+      // persist defaults to false upstream; durable logins require it explicit.
+      context: { id: mint.contextId, persist: config.context.persist },
+      viewport: { ...config.defaults.viewport },
+      solveCaptchas: config.defaults.solveCaptchas,
+      recordSession: config.defaults.recordSession,
+      logSession: config.defaults.logSession,
+      // Upstream default is true; credentialed SaaS browsing must not
+      // silently accept bad TLS.
+      ignoreCertificateErrors: config.defaults.ignoreCertificateErrors
+    },
+    userMetadata: {
+      ...config.metadata,
+      broker: "velanir-browserbase",
+      instance: mint.instanceKey,
+      bootId: mint.bootId,
+      leaseId: mint.leaseId
+    }
+  };
+}
+var DEFAULT_REQUEST_TIMEOUT_MS = 1e4;
+var BrowserbaseClient = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  async request(method, path2, body) {
+    const fetchFn = this.opts.fetchFn ?? fetch;
+    const timeoutMs = this.opts.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    let response;
+    try {
+      response = await fetchFn(`${this.opts.baseUrl}${path2}`, {
+        method,
+        headers: {
+          "X-BB-API-Key": this.opts.apiKey,
+          "Content-Type": "application/json"
+        },
+        signal: AbortSignal.timeout(timeoutMs),
+        ...body === void 0 ? {} : { body: JSON.stringify(body) }
+      });
+    } catch (err) {
+      const name = err instanceof Error ? err.name : "";
+      if (name === "TimeoutError" || name === "AbortError") {
+        throw new BrowserbaseApiError(`Browserbase ${method} ${path2} timed out after ${timeoutMs}ms`, 408);
+      }
+      throw err;
+    }
+    if (!response.ok) {
+      const retryAfterHeader = response.headers.get("retry-after");
+      const retryAfterSeconds = retryAfterHeader ? Number(retryAfterHeader) : Number.NaN;
+      const detail = await response.text().catch(() => "");
+      throw new BrowserbaseApiError(
+        `Browserbase ${method} ${path2} failed: ${response.status} ${detail.slice(0, 300)}`,
+        response.status,
+        Number.isFinite(retryAfterSeconds) ? retryAfterSeconds * 1e3 : void 0
+      );
+    }
+    if (response.status === 204) {
+      return void 0;
+    }
+    return await response.json();
+  }
+  createContext() {
+    return this.request("POST", "/v1/contexts", { projectId: this.opts.projectId });
+  }
+  createSession(payload) {
+    return this.request("POST", "/v1/sessions", payload);
+  }
+  /** REQUEST_RELEASE is the only supported mid-session mutation. */
+  async releaseSession(sessionId) {
+    await this.request("POST", `/v1/sessions/${sessionId}`, {
+      projectId: this.opts.projectId,
+      status: "REQUEST_RELEASE"
+    });
+  }
+  getSession(sessionId) {
+    return this.request("GET", `/v1/sessions/${sessionId}`);
+  }
+  /**
+   * RUNNING sessions for the key's project. Metadata filtering happens
+   * client-side so the reaper does not depend on the list endpoint's
+   * query-string syntax (verified counts are small per project).
+   */
+  listRunningSessions() {
+    return this.request("GET", "/v1/sessions?status=RUNNING");
+  }
+  getDebugUrls(sessionId) {
+    return this.request("GET", `/v1/sessions/${sessionId}/debug`);
+  }
+};
+
+// src/cdp-pipe.ts
+var INJECTED_ID_BASE = 19e8;
+var INJECTED_RESPONSE_MAX_BYTES = 4096;
+var DEFAULT_INJECTION_TIMEOUT_MS = 2e3;
+function rawDataByteLength(data) {
+  if (Buffer.isBuffer(data)) {
+    return data.byteLength;
+  }
+  if (Array.isArray(data)) {
+    return data.reduce((sum, chunk) => sum + chunk.byteLength, 0);
+  }
+  return data.byteLength;
+}
+function rawDataToString(data) {
+  if (Buffer.isBuffer(data)) {
+    return data.toString("utf8");
+  }
+  if (Array.isArray(data)) {
+    return Buffer.concat(data).toString("utf8");
+  }
+  return Buffer.from(data).toString("utf8");
+}
+var CdpPipe = class {
+  constructor(downstream, upstream, opts) {
+    this.downstream = downstream;
+    this.upstream = upstream;
+    this.opts = opts;
+    downstream.on("message", (data, isBinary) => {
+      this.lastActivityAt = Date.now();
+      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 });
+      }
+    });
+    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"));
+  }
+  nextInjectedId = INJECTED_ID_BASE;
+  pending = /* @__PURE__ */ new Map();
+  closeReason = null;
+  lastActivityAt = Date.now();
+  get closed() {
+    return this.closeReason !== null;
+  }
+  /** 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) {
+      return Promise.reject(new Error("CDP pipe is not connected"));
+    }
+    const id = this.nextInjectedId;
+    this.nextInjectedId += 1;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`Injected CDP command timed out: ${method}`));
+      }, this.opts.injectionTimeoutMs ?? DEFAULT_INJECTION_TIMEOUT_MS);
+      this.pending.set(id, { resolve, reject, timer });
+      this.upstream.send(JSON.stringify({ id, method, ...params ? { params } : {} }));
+    });
+  }
+  maybeResolveInjected(data) {
+    if (this.pending.size === 0 || rawDataByteLength(data) > INJECTED_RESPONSE_MAX_BYTES) {
+      return false;
+    }
+    let message;
+    try {
+      message = JSON.parse(rawDataToString(data));
+    } catch {
+      return false;
+    }
+    const id = typeof message.id === "number" ? message.id : null;
+    if (id === null || id < INJECTED_ID_BASE) {
+      return false;
+    }
+    const entry = this.pending.get(id);
+    if (!entry) {
+      return true;
+    }
+    this.pending.delete(id);
+    clearTimeout(entry.timer);
+    if (message.error) {
+      entry.reject(new Error(message.error.message ?? "CDP command failed"));
+    } else {
+      entry.resolve(
+        typeof message.result === "object" && message.result !== null ? message.result : {}
+      );
+    }
+    return true;
+  }
+  close(reason) {
+    if (this.closeReason !== null) {
+      return;
+    }
+    this.closeReason = reason;
+    for (const [, entry] of this.pending) {
+      clearTimeout(entry.timer);
+      entry.reject(new Error(`CDP pipe closed: ${reason}`));
+    }
+    this.pending.clear();
+    for (const socket of [this.downstream, this.upstream]) {
+      if (socket.readyState === socket.OPEN || socket.readyState === socket.CLOSING) {
+        try {
+          socket.close(1e3);
+        } catch {
+          socket.terminate();
+        }
+      } else if (socket.readyState === socket.CONNECTING) {
+        socket.terminate();
+      }
+    }
+    this.opts.onClose(reason);
+  }
+};
+
+// src/config.ts
+var BROWSERBASE_REGIONS = ["us-west-2", "us-east-1", "eu-central-1", "ap-southeast-1"];
+var DEFAULT_REGION = "us-west-2";
+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_WAIT_MS = 1e4;
+var DEFAULT_IDLE_DISCONNECT_MINUTES = 15;
+var DEFAULT_REAPER_INTERVAL_MINUTES = 5;
+var DEFAULT_API_BASE_URL = "https://api.browserbase.com";
+var DEFAULT_UPSTREAM_CONNECT_TIMEOUT_MS = 15e3;
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
+}
+function readBoolean(value, fallback) {
+  return typeof value === "boolean" ? value : fallback;
+}
+function readNumber(value, fallback, min, max) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return fallback;
+  }
+  return Math.min(max, Math.max(min, value));
+}
+function readStringMap(value) {
+  if (!isRecord(value)) {
+    return {};
+  }
+  const entries = {};
+  for (const [key, raw] of Object.entries(value)) {
+    if (typeof raw === "string" && raw.trim().length > 0) {
+      entries[key] = raw.trim();
+    }
+  }
+  return entries;
+}
+function readProxies(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.filter(isRecord);
+}
+function readRegion(value) {
+  const region = readString(value);
+  return region && BROWSERBASE_REGIONS.includes(region) ? region : DEFAULT_REGION;
+}
+var BrowserbaseConfigError = class extends Error {
+};
+var URL_SAFE_TOKEN_PATTERN = /^[A-Za-z0-9._~-]+$/;
+function isUrlSafeBrokerToken(token) {
+  return URL_SAFE_TOKEN_PATTERN.test(token);
+}
+var URL_SAFE_TOKEN_ADVICE = "must be URL-safe ([A-Za-z0-9._~-]); characters like + & # = / change meaning in the cdpUrl query string and break broker auth. Generate it with base64url or hex.";
+function normalizeConfig(raw) {
+  const root = isRecord(raw) ? raw : {};
+  const projectId = readString(root.projectId);
+  if (!projectId) {
+    throw new BrowserbaseConfigError(
+      "velanir-browserbase: config.projectId is required (the Browserbase project to mint sessions in)."
+    );
+  }
+  const apiKey = readString(root.apiKey);
+  if (!apiKey) {
+    throw new BrowserbaseConfigError(
+      'velanir-browserbase: config.apiKey is required. Use ${ENV} substitution (e.g. "${OCT8_BROWSERBASE_API_KEY}") so the key never lives in openclaw.json.'
+    );
+  }
+  if (apiKey.startsWith("${")) {
+    throw new BrowserbaseConfigError(
+      `velanir-browserbase: config.apiKey looks like an unsubstituted env reference (${apiKey}). The referenced environment variable is not set in the gateway service environment.`
+    );
+  }
+  const listenPortRaw = root.listenPort;
+  const listenPort = typeof listenPortRaw === "number" && Number.isInteger(listenPortRaw) ? listenPortRaw : Number.NaN;
+  if (!Number.isInteger(listenPort) || listenPort <= 0 || listenPort > 65535) {
+    throw new BrowserbaseConfigError(
+      "velanir-browserbase: config.listenPort must be an integer between 1 and 65535."
+    );
+  }
+  const token = readString(root.token);
+  if (token?.startsWith("${")) {
+    throw new BrowserbaseConfigError(
+      `velanir-browserbase: config.token looks like an unsubstituted env reference (${token}). The referenced environment variable is not set in the gateway service environment; accepting it would make the loopback broker's bearer token a predictable public string.`
+    );
+  }
+  if (token && !isUrlSafeBrokerToken(token)) {
+    throw new BrowserbaseConfigError(`velanir-browserbase: config.token ${URL_SAFE_TOKEN_ADVICE}`);
+  }
+  const defaults = isRecord(root.defaults) ? root.defaults : {};
+  const viewport = isRecord(defaults.viewport) ? defaults.viewport : {};
+  const context = isRecord(root.context) ? root.context : {};
+  return {
+    projectId,
+    apiKey,
+    region: readRegion(root.region),
+    listenPort,
+    ...token ? { token } : {},
+    ...readString(root.instanceKey) ? { instanceKey: readString(root.instanceKey) } : {},
+    metadata: readStringMap(root.metadata),
+    defaults: {
+      timeoutSeconds: readNumber(
+        defaults.timeoutSeconds,
+        DEFAULT_TIMEOUT_SECONDS,
+        MIN_TIMEOUT_SECONDS,
+        MAX_TIMEOUT_SECONDS
+      ),
+      viewport: {
+        width: readNumber(viewport.width, DEFAULT_VIEWPORT.width, 320, 3840),
+        height: readNumber(viewport.height, DEFAULT_VIEWPORT.height, 320, 2160)
+      },
+      solveCaptchas: readBoolean(defaults.solveCaptchas, true),
+      recordSession: readBoolean(defaults.recordSession, true),
+      logSession: readBoolean(defaults.logSession, true),
+      ignoreCertificateErrors: readBoolean(defaults.ignoreCertificateErrors, false)
+    },
+    context: {
+      persist: readBoolean(context.persist, true),
+      cooldownSeconds: readNumber(context.cooldownSeconds, DEFAULT_CONTEXT_COOLDOWN_SECONDS, 0, 120),
+      waitMs: readNumber(context.waitMs, DEFAULT_CONTEXT_WAIT_MS, 0, 6e4)
+    },
+    proxies: readProxies(root.proxies),
+    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,
+    upstreamConnectTimeoutMs: readNumber(
+      root.upstreamConnectTimeoutMs,
+      DEFAULT_UPSTREAM_CONNECT_TIMEOUT_MS,
+      1e3,
+      6e4
+    )
+  };
+}
+
+// src/context-store.ts
+import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "fs";
+import path from "path";
+var EMPTY_STATE = { contexts: {} };
+var ContextStore = class {
+  filePath;
+  constructor(stateDir) {
+    const dir = path.join(stateDir, "velanir-browserbase");
+    mkdirSync(dir, { recursive: true });
+    this.filePath = path.join(dir, "state.json");
+  }
+  read() {
+    try {
+      const raw = JSON.parse(readFileSync(this.filePath, "utf8"));
+      if (typeof raw === "object" && raw !== null && !Array.isArray(raw) && typeof raw.contexts === "object" && raw.contexts !== null) {
+        return raw;
+      }
+    } catch {
+    }
+    return { ...EMPTY_STATE, contexts: {} };
+  }
+  getContextId(projectId) {
+    return this.read().contexts[projectId]?.contextId;
+  }
+  setContextId(projectId, contextId) {
+    const state = this.read();
+    state.contexts[projectId] = { contextId, createdAt: (/* @__PURE__ */ new Date()).toISOString() };
+    const tmpPath = `${this.filePath}.tmp`;
+    writeFileSync(tmpPath, `${JSON.stringify(state, null, 2)}
+`, { encoding: "utf8", mode: 384 });
+    renameSync(tmpPath, this.filePath);
+    chmodSync(this.filePath, 384);
+  }
+};
+
+// src/redact.ts
+var SENSITIVE_QUERY_PARAMS = /* @__PURE__ */ new Set(["apikey", "api_key", "token", "signingkey", "signing_key", "sessionid"]);
+function redactUrlSecrets(text2) {
+  return text2.replace(/([?&])([A-Za-z0-9_-]+)=([^&\s"']+)/g, (match, sep, key, _value) => {
+    return SENSITIVE_QUERY_PARAMS.has(key.toLowerCase()) ? `${sep}${key}=[redacted]` : match;
+  });
+}
+function createRedactor(secrets) {
+  const literals = secrets.filter((value) => typeof value === "string" && value.length >= 6);
+  return (text2) => {
+    let out = redactUrlSecrets(text2);
+    for (const literal of literals) {
+      out = out.split(literal).join("[redacted]");
+    }
+    return out;
+  };
+}
+function createRedactedLogger(logger, redact) {
+  const wrap = (fn) => fn ? (message) => fn(redact(message)) : void 0;
+  return {
+    debug: wrap(logger.debug),
+    info: wrap(logger.info),
+    warn: wrap(logger.warn),
+    error: wrap(logger.error)
+  };
+}
+
+// src/broker.ts
+var WS_MAX_PAYLOAD_BYTES = 256 * 1024 * 1024;
+var ADOPTION_WINDOW_MS = 15e3;
+var BUSY_POLL_INTERVAL_MS = 250;
+var SHUTDOWN_RELEASE_BUDGET_MS = 5e3;
+var RATE_LIMIT_RETRY_BUDGET_MS = 8e3;
+var DEFAULT_IDLE_SWEEP_INTERVAL_MS = 3e4;
+var JSON_VERSION_BODY = {
+  Browser: "Chrome/138.0.0.0",
+  "Protocol-Version": "1.3",
+  "User-Agent": "Velanir Browserbase session broker",
+  "V8-Version": "13.8",
+  "WebKit-Version": "537.36"
+};
+var BrokerStartError = class extends Error {
+};
+function sha256Short(input) {
+  return createHash("sha256").update(input).digest("hex").slice(0, 12);
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function writeJson(res, status, body) {
+  const payload = JSON.stringify(body);
+  res.writeHead(status, { "content-type": "application/json", "content-length": Buffer.byteLength(payload) });
+  res.end(payload);
+}
+function destroyWithHttpError(socket, status, statusText, message) {
+  const body = JSON.stringify({ error: message });
+  socket.write(
+    `HTTP/1.1 ${status} ${statusText}\r
+content-type: application/json\r
+content-length: ${Buffer.byteLength(body)}\r
+connection: close\r
+\r
+${body}`
+  );
+  socket.destroy();
+}
+var BrowserbaseBroker = class {
+  constructor(config, deps) {
+    this.config = config;
+    const token = config.token ?? process.env.OCT8_BB_BROKER_TOKEN?.trim();
+    if (!token) {
+      throw new BrokerStartError(
+        'velanir-browserbase: no broker token. Set plugins.entries.velanir-browserbase.config.token ("${OCT8_BB_BROKER_TOKEN}") or export OCT8_BB_BROKER_TOKEN in the gateway service environment; the browser profile cdpUrl must carry the same value as ?token=.'
+      );
+    }
+    if (token.startsWith("${")) {
+      throw new BrokerStartError(
+        `velanir-browserbase: broker token looks like an unsubstituted env reference (${token}); refusing to start with a predictable bearer token.`
+      );
+    }
+    if (!isUrlSafeBrokerToken(token)) {
+      throw new BrokerStartError(`velanir-browserbase: broker token ${URL_SAFE_TOKEN_ADVICE}`);
+    }
+    this.token = token;
+    this.instanceKey = config.instanceKey ?? sha256Short(deps.stateDir);
+    const redact = createRedactor([config.apiKey, token]);
+    this.logger = createRedactedLogger(deps.logger, redact);
+    this.contextStore = new ContextStore(deps.stateDir);
+    this.client = new BrowserbaseClient({
+      apiKey: config.apiKey,
+      baseUrl: config.apiBaseUrl,
+      projectId: config.projectId,
+      ...deps.fetchFn ? { fetchFn: deps.fetchFn } : {}
+    });
+    this.wss = new WebSocketServer({ noServer: true, maxPayload: WS_MAX_PAYLOAD_BYTES, perMessageDeflate: false });
+    this.idleSweepIntervalMs = deps.idleSweepIntervalMs ?? DEFAULT_IDLE_SWEEP_INTERVAL_MS;
+  }
+  client;
+  contextStore;
+  logger;
+  token;
+  instanceKey;
+  bootId = randomUUID();
+  wss;
+  idleSweepIntervalMs;
+  server = null;
+  active = null;
+  adoptable = null;
+  cooldownUntil = 0;
+  timers = [];
+  stopping = false;
+  // Upgrade flows run strictly one at a time. This is what makes the
+  // one-session-per-context invariant airtight: a second connect (OpenClaw's
+  // 5s/7s/9s retry ladder, profile races) can never mint concurrently with an
+  // in-flight mint/dial — it queues, then adopts the held session or fails
+  // fast on the busy check.
+  upgradeChain = Promise.resolve();
+  async start() {
+    const server = createServer((req, res) => {
+      void this.handleRequest(req, res);
+    });
+    server.on("upgrade", (req, socket, head) => {
+      this.handleUpgrade(req, socket, head);
+    });
+    await new Promise((resolve, reject) => {
+      server.once("error", (err) => {
+        reject(
+          new BrokerStartError(
+            err.code === "EADDRINUSE" ? `velanir-browserbase: listen port ${this.config.listenPort} is already in use on 127.0.0.1. Free the port or change config.listenPort (and the browser profile cdpUrl) for this gateway.` : `velanir-browserbase: failed to bind 127.0.0.1:${this.config.listenPort}: ${err.message}`
+          )
+        );
+      });
+      server.listen(this.config.listenPort, "127.0.0.1", () => {
+        server.removeAllListeners("error");
+        server.on("error", (err) => this.logger.error?.(`broker server error: ${String(err)}`));
+        resolve();
+      });
+    });
+    this.server = server;
+    if (this.idleSweepIntervalMs > 0 && this.config.idleDisconnectMinutes > 0) {
+      const idleTimer = setInterval(() => this.sweepIdle(), this.idleSweepIntervalMs);
+      idleTimer.unref();
+      this.timers.push(idleTimer);
+    }
+    if (this.config.reaperIntervalMinutes > 0) {
+      const reaperTimer = setInterval(() => {
+        void this.reapStaleSessions("interval");
+      }, this.config.reaperIntervalMinutes * 6e4);
+      reaperTimer.unref();
+      this.timers.push(reaperTimer);
+      void this.reapStaleSessions("boot");
+    }
+    this.logger.info?.(
+      `velanir-browserbase broker listening on 127.0.0.1:${this.config.listenPort} (project ${this.config.projectId}, region ${this.config.region}, instance ${this.instanceKey})`
+    );
+  }
+  async stop() {
+    this.stopping = true;
+    for (const timer of this.timers) {
+      clearInterval(timer);
+    }
+    this.timers = [];
+    if (this.adoptable) {
+      clearTimeout(this.adoptable.timer);
+      const held = this.adoptable;
+      this.adoptable = null;
+      held.upstream?.terminate();
+      await this.releaseQuietly(held.session.sessionId, "shutdown-unattached");
+    }
+    const active = this.active;
+    if (active) {
+      const released = new Promise((resolve) => {
+        this.onActiveReleased = resolve;
+      });
+      active.pipe.close("shutdown");
+      await Promise.race([released, sleep(SHUTDOWN_RELEASE_BUDGET_MS)]);
+      this.onActiveReleased = null;
+    }
+    await new Promise((resolve) => {
+      if (!this.server) {
+        resolve();
+        return;
+      }
+      this.server.close(() => resolve());
+      this.server.closeAllConnections?.();
+    });
+    this.server = null;
+  }
+  onActiveReleased = null;
+  // ---------------------------------------------------------------- HTTP --
+  isAuthorized(url) {
+    const provided = url.searchParams.get("token");
+    if (provided === null) {
+      return false;
+    }
+    const a = createHash("sha256").update(provided).digest();
+    const b = createHash("sha256").update(this.token).digest();
+    return timingSafeEqual(a, b);
+  }
+  async handleRequest(req, res) {
+    const url = new URL(req.url ?? "/", `http://127.0.0.1:${this.config.listenPort}`);
+    if (!this.isAuthorized(url)) {
+      writeJson(res, 401, { error: "missing or invalid token" });
+      return;
+    }
+    const pathname = url.pathname.replace(/\/$/, "") || "/";
+    try {
+      if (pathname === "/json/version") {
+        const leaseId = randomUUID();
+        writeJson(res, 200, {
+          ...JSON_VERSION_BODY,
+          webSocketDebuggerUrl: `ws://127.0.0.1:${this.config.listenPort}/devtools/broker/${leaseId}?token=${this.token}`
+        });
+        return;
+      }
+      if (pathname === "/json" || pathname === "/json/list") {
+        writeJson(res, 200, await this.listTargets());
+        return;
+      }
+      if (pathname === "/json/new") {
+        await this.handleNewTab(url, res);
+        return;
+      }
+      if (pathname.startsWith("/json/close/")) {
+        await this.handleCloseTab(pathname.slice("/json/close/".length), res);
+        return;
+      }
+      writeJson(res, 404, { error: "not found" });
+    } catch (err) {
+      writeJson(res, 500, { error: err instanceof Error ? err.message : String(err) });
+    }
+  }
+  async listTargets() {
+    const active = this.active;
+    if (!active || active.pipe.closed) {
+      return [];
+    }
+    const result = await active.pipe.inject("Target.getTargets");
+    const infos = Array.isArray(result.targetInfos) ? result.targetInfos : [];
+    return infos.filter((info) => typeof info === "object" && info !== null).filter((info) => info.type === "page").map((info) => ({
+      id: String(info.targetId ?? ""),
+      type: "page",
+      title: String(info.title ?? ""),
+      url: String(info.url ?? "")
+    }));
+  }
+  async handleNewTab(url, res) {
+    const active = this.active;
+    if (!active || active.pipe.closed) {
+      writeJson(res, 503, { error: "no active Browserbase session; run a browser action to connect first" });
+      return;
+    }
+    let target = url.searchParams.get("url");
+    if (target === null) {
+      const bare = url.search.replace(/^\?/, "").split("&").filter((part) => !part.startsWith("token=")).join("&");
+      target = bare ? decodeURIComponent(bare) : null;
+    }
+    const targetUrl = target?.trim() || "about:blank";
+    const result = await active.pipe.inject("Target.createTarget", { url: targetUrl });
+    writeJson(res, 200, {
+      id: String(result.targetId ?? ""),
+      type: "page",
+      url: targetUrl
+    });
+  }
+  async handleCloseTab(targetId, res) {
+    const active = this.active;
+    if (!active || active.pipe.closed || !targetId) {
+      writeJson(res, 404, { error: "no such target" });
+      return;
+    }
+    await active.pipe.inject("Target.closeTarget", { targetId });
+    res.writeHead(200, { "content-type": "text/plain" });
+    res.end("Target is closing");
+  }
+  // ------------------------------------------------------------- upgrade --
+  handleUpgrade(req, socket, head) {
+    socket.on("error", () => socket.destroy());
+    const url = new URL(req.url ?? "/", `http://127.0.0.1:${this.config.listenPort}`);
+    if (!this.isAuthorized(url)) {
+      destroyWithHttpError(socket, 401, "Unauthorized", "missing or invalid token");
+      return;
+    }
+    const match = /^\/devtools\/broker\/([A-Za-z0-9-]+)$/.exec(url.pathname);
+    if (!match) {
+      destroyWithHttpError(socket, 404, "Not Found", "unknown websocket path");
+      return;
+    }
+    if (this.stopping) {
+      destroyWithHttpError(socket, 503, "Service Unavailable", "broker is shutting down");
+      return;
+    }
+    const leaseId = match[1];
+    const markGone = () => {
+      liveness.gone = true;
+    };
+    const liveness = {
+      gone: false,
+      detach: () => {
+        socket.off("close", markGone);
+        socket.off("end", markGone);
+      }
+    };
+    socket.once("close", markGone);
+    socket.once("end", markGone);
+    this.upgradeChain = this.upgradeChain.then(() => this.runUpgradeFlow(req, socket, head, leaseId, liveness)).catch(() => {
+    });
+  }
+  async runUpgradeFlow(req, socket, head, leaseId, liveness) {
+    if (this.stopping) {
+      liveness.detach();
+      destroyWithHttpError(socket, 503, "Service Unavailable", "broker is shutting down");
+      return;
+    }
+    if (liveness.gone || socket.destroyed) {
+      liveness.detach();
+      socket.destroy();
+      return;
+    }
+    let held;
+    try {
+      held = await this.acquireSession(leaseId);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      this.logger.warn?.(`session acquire failed: ${message}`);
+      liveness.detach();
+      if (liveness.gone) {
+        socket.destroy();
+      } else {
+        destroyWithHttpError(socket, 503, "Service Unavailable", message);
+      }
+      return;
+    }
+    const minted = held.session;
+    if (liveness.gone) {
+      liveness.detach();
+      socket.destroy();
+      this.holdForAdoption(minted, held.upstream);
+      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;
+      }
+    }
+    if (liveness.gone) {
+      liveness.detach();
+      socket.destroy();
+      this.holdForAdoption(minted, upstream);
+      return;
+    }
+    liveness.detach();
+    this.wss.handleUpgrade(req, socket, head, (downstream) => {
+      this.attachPipe(downstream, upstream, minted);
+    });
+  }
+  attachPipe(downstream, upstream, minted) {
+    if (upstream.readyState !== upstream.OPEN || downstream.readyState !== downstream.OPEN) {
+      upstream.terminate();
+      if (downstream.readyState === downstream.OPEN) {
+        downstream.close(1011, "upstream connection lost during attach");
+      } else {
+        downstream.terminate();
+      }
+      this.cooldownUntil = Date.now() + this.config.context.cooldownSeconds * 1e3;
+      void this.releaseQuietly(minted.sessionId, "attach-aborted");
+      return;
+    }
+    const pipe = new CdpPipe(downstream, upstream, {
+      onClose: (reason) => this.onPipeClosed(minted.sessionId, reason)
+    });
+    this.active = {
+      sessionId: minted.sessionId,
+      leaseId: minted.leaseId,
+      contextId: minted.contextId,
+      ...minted.expiresAt ? { expiresAt: minted.expiresAt } : {},
+      startedAt: Date.now(),
+      pipe
+    };
+    this.logger.info?.(
+      `attached session ${minted.sessionId} (lease ${minted.leaseId}, context ${minted.contextId})`
+    );
+  }
+  onPipeClosed(sessionId, reason) {
+    if (this.active?.sessionId !== sessionId) {
+      return;
+    }
+    this.active = null;
+    this.cooldownUntil = Date.now() + this.config.context.cooldownSeconds * 1e3;
+    this.logger.info?.(`session ${sessionId} disconnected (${reason}); releasing`);
+    void this.releaseQuietly(sessionId, reason).finally(() => {
+      this.onActiveReleased?.();
+    });
+  }
+  // ---------------------------------------------------------------- mint --
+  async acquireSession(leaseId) {
+    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})`
+      );
+      return adopted;
+    }
+    const busyDeadline = Date.now() + this.config.context.waitMs;
+    while (this.active && !this.active.pipe.closed) {
+      if (Date.now() >= busyDeadline) {
+        throw new Error(
+          "context busy: another Browserbase session is active for this coworker; retry after it finishes"
+        );
+      }
+      await sleep(BUSY_POLL_INTERVAL_MS);
+    }
+    const cooldownRemaining = this.cooldownUntil - Date.now();
+    if (cooldownRemaining > 0) {
+      await sleep(cooldownRemaining);
+    }
+    return { session: await this.mintSession(leaseId) };
+  }
+  async mintSession(leaseId) {
+    const contextId = await this.ensureContext();
+    const payload = buildSessionPayload(this.config, {
+      contextId,
+      leaseId,
+      bootId: this.bootId,
+      instanceKey: this.instanceKey
+    });
+    let session;
+    try {
+      session = await this.client.createSession(payload);
+    } catch (err) {
+      if (err instanceof BrowserbaseApiError && err.isRateLimit && err.retryAfterMs !== void 0 && err.retryAfterMs <= RATE_LIMIT_RETRY_BUDGET_MS) {
+        this.logger.warn?.(`Browserbase rate limited; retrying mint in ${err.retryAfterMs}ms`);
+        await sleep(err.retryAfterMs);
+        session = await this.client.createSession(payload);
+      } else {
+        throw err;
+      }
+    }
+    if (!session.connectUrl) {
+      await this.releaseQuietly(session.id, "missing-connect-url");
+      throw new Error(`Browserbase session ${session.id} returned no connectUrl`);
+    }
+    this.logger.info?.(`minted session ${session.id} (lease ${leaseId}, context ${contextId})`);
+    return {
+      sessionId: session.id,
+      connectUrl: session.connectUrl,
+      contextId,
+      leaseId,
+      ...session.expiresAt ? { expiresAt: session.expiresAt } : {}
+    };
+  }
+  async ensureContext() {
+    const existing = this.contextStore.getContextId(this.config.projectId);
+    if (existing) {
+      return existing;
+    }
+    const created = await this.client.createContext();
+    this.contextStore.setContextId(this.config.projectId, created.id);
+    this.logger.info?.(`created Browserbase context ${created.id} for project ${this.config.projectId}`);
+    return created.id;
+  }
+  dialUpstream(connectUrl) {
+    return new Promise((resolve, reject) => {
+      const upstream = new WebSocket(connectUrl, {
+        handshakeTimeout: this.config.upstreamConnectTimeoutMs,
+        maxPayload: WS_MAX_PAYLOAD_BYTES,
+        perMessageDeflate: false
+      });
+      upstream.once("open", () => {
+        upstream.removeAllListeners("error");
+        resolve(upstream);
+      });
+      upstream.once("error", (err) => {
+        upstream.terminate();
+        reject(err instanceof Error ? err : new Error(String(err)));
+      });
+    });
+  }
+  holdForAdoption(session, upstream) {
+    this.logger.info?.(
+      `holding session ${session.sessionId} for adoption (client disconnected mid-handshake, 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");
+      }
+    }, ADOPTION_WINDOW_MS);
+    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
+    };
+  }
+  takeAdoptable() {
+    const held = this.adoptable;
+    if (!held) {
+      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 } : {}
+    };
+  }
+  // ------------------------------------------------------------- cleanup --
+  async releaseQuietly(sessionId, reason) {
+    try {
+      await this.client.releaseSession(sessionId);
+      this.logger.info?.(`released session ${sessionId} (${reason})`);
+    } catch (err) {
+      this.logger.debug?.(`release of ${sessionId} failed (${reason}): ${String(err)}`);
+    }
+  }
+  sweepIdle() {
+    const active = this.active;
+    if (!active || this.config.idleDisconnectMinutes <= 0) {
+      return;
+    }
+    const idleMs = Date.now() - active.pipe.lastActivityAt;
+    if (idleMs >= this.config.idleDisconnectMinutes * 6e4) {
+      this.logger.info?.(
+        `idle for ${Math.round(idleMs / 1e3)}s; disconnecting session ${active.sessionId} (login state persists in context)`
+      );
+      active.pipe.close("idle-disconnect");
+    }
+  }
+  async reapStaleSessions(trigger) {
+    let sessions;
+    try {
+      const listed = await this.client.listRunningSessions();
+      if (!Array.isArray(listed)) {
+        this.logger.warn?.(`reaper list returned a non-array response (${trigger}); skipping sweep`);
+        return;
+      }
+      sessions = listed;
+    } catch (err) {
+      this.logger.warn?.(`reaper list failed (${trigger}): ${String(err)}`);
+      return;
+    }
+    for (const session of sessions) {
+      const meta = session.userMetadata;
+      const isOurs = typeof meta === "object" && meta !== null && meta.broker === "velanir-browserbase" && meta.instance === this.instanceKey;
+      if (!isOurs) {
+        continue;
+      }
+      if (session.id === this.active?.sessionId || session.id === this.adoptable?.session.sessionId) {
+        continue;
+      }
+      this.logger.warn?.(`reaper releasing stale session ${session.id} (${trigger})`);
+      await this.releaseQuietly(session.id, `reaper-${trigger}`);
+    }
+  }
+  // --------------------------------------------------------------- tools --
+  getStatus() {
+    const active = this.active;
+    return {
+      running: this.server !== null && !this.stopping,
+      listenPort: this.config.listenPort,
+      region: this.config.region,
+      projectId: this.config.projectId,
+      ...this.contextStore.getContextId(this.config.projectId) ? { contextId: this.contextStore.getContextId(this.config.projectId) } : {},
+      recordSession: this.config.defaults.recordSession,
+      cooldownRemainingMs: Math.max(0, this.cooldownUntil - Date.now()),
+      active: active && !active.pipe.closed ? {
+        sessionId: active.sessionId,
+        startedAt: new Date(active.startedAt).toISOString(),
+        ...active.expiresAt ? { expiresAt: active.expiresAt } : {},
+        idleMs: Date.now() - active.pipe.lastActivityAt
+      } : null
+    };
+  }
+  async getLiveViewUrls() {
+    const active = this.active;
+    if (!active || active.pipe.closed) {
+      return null;
+    }
+    return this.client.getDebugUrls(active.sessionId);
+  }
+  /** Returns true when there was an active session to release. */
+  releaseActiveSession() {
+    const active = this.active;
+    if (!active || active.pipe.closed) {
+      return false;
+    }
+    active.pipe.close("manual-release");
+    return true;
+  }
+};
+
+// src/tools.ts
+import { Type } from "typebox";
+var NO_PARAMS = Type.Object({}, { additionalProperties: false });
+function text(message) {
+  return { content: [{ type: "text", text: message }] };
+}
+var NOT_RUNNING = "The Browserbase broker is not running on this gateway. Browser tasks use the local profile until it is configured.";
+var NO_SESSION = "No active Browserbase session. The next browser action starts one automatically; saved logins persist in this coworker's browser context.";
+function createBrowserbaseTools(getBroker) {
+  return [
+    {
+      name: "browserbase_session_status",
+      label: "Browserbase Session Status",
+      description: "Show the current Browserbase cloud-browser session for this coworker: session id, started/expires timestamps, idle time, and the persistent browser-context id. Use before long browser tasks to check remaining session time.",
+      parameters: NO_PARAMS,
+      execute: () => {
+        const broker = getBroker();
+        if (!broker) {
+          return text(NOT_RUNNING);
+        }
+        const status = broker.getStatus();
+        if (!status.active) {
+          const lines2 = [
+            NO_SESSION,
+            `Region: ${status.region}. Recording: ${status.recordSession ? "on" : "off"}.`,
+            status.contextId ? `Browser context: ${status.contextId}` : "Browser context: created on first use."
+          ];
+          return text(lines2.join("\n"));
+        }
+        const lines = [
+          `Active Browserbase session ${status.active.sessionId}`,
+          `Started: ${status.active.startedAt}`,
+          status.active.expiresAt ? `Expires: ${status.active.expiresAt} (the session ends then even mid-task; finish or checkpoint before that)` : "Expires: unknown",
+          `Idle: ${Math.round(status.active.idleMs / 1e3)}s`,
+          `Context: ${status.contextId ?? "unknown"} (login state persists here across sessions)`,
+          `Recording: ${status.recordSession ? "on" : "off"}. Region: ${status.region}.`
+        ];
+        return text(lines.join("\n"));
+      }
+    },
+    {
+      name: "browserbase_live_view",
+      label: "Browserbase Live View",
+      description: "Get the interactive Live View URL for the current Browserbase session so a human can watch or take over the browser \u2014 required when a login needs a human to complete 2FA/SSO. Treat the URL like a credential: share it only with the human who must act, never in shared channels.",
+      parameters: NO_PARAMS,
+      execute: async () => {
+        const broker = getBroker();
+        if (!broker) {
+          return text(NOT_RUNNING);
+        }
+        let urls;
+        try {
+          urls = await broker.getLiveViewUrls();
+        } catch (err) {
+          return text(`Could not fetch Live View URLs from Browserbase: ${String(err)}. Retry in a few seconds.`);
+        }
+        if (!urls) {
+          return text(`${NO_SESSION}
+Open the page that needs human help first, then call this tool again.`);
+        }
+        const lines = ["Browserbase Live View (interactive; anyone with this URL controls the browser):"];
+        if (urls.debuggerFullscreenUrl) {
+          lines.push(`Fullscreen: ${urls.debuggerFullscreenUrl}`);
+        }
+        if (urls.debuggerUrl) {
+          lines.push(`Debugger: ${urls.debuggerUrl}`);
+        }
+        for (const page of urls.pages ?? []) {
+          if (page.debuggerFullscreenUrl && page.url) {
+            lines.push(`Tab ${page.title || page.url}: ${page.debuggerFullscreenUrl}`);
+          }
+        }
+        if (lines.length === 1) {
+          return text("The session is active but Browserbase returned no Live View URLs; retry in a few seconds.");
+        }
+        return text(lines.join("\n"));
+      }
+    },
+    {
+      name: "browserbase_session_release",
+      label: "Browserbase Session Release",
+      description: "Release the current Browserbase session immediately when browsing for this task is done. Saved logins persist in the coworker's browser context; the next browser action starts a fresh session. Use for cost hygiene after finishing browser work.",
+      parameters: NO_PARAMS,
+      execute: () => {
+        const broker = getBroker();
+        if (!broker) {
+          return text(NOT_RUNNING);
+        }
+        const released = broker.releaseActiveSession();
+        return text(
+          released ? "Browserbase session released. Login state is saved in the persistent context; the next browser action starts a fresh session." : "No active Browserbase session to release."
+        );
+      }
+    }
+  ];
+}
+
+// src/index.ts
+var PLUGIN_ID = "velanir-browserbase";
+var index_default = definePluginEntry({
+  id: PLUGIN_ID,
+  name: "Velanir Browserbase Sessions",
+  description: "Brokers Browserbase sessions behind a loopback CDP endpoint for the bundled browser tool: explicit session creation with a persistent per-coworker context, deterministic release, idle disconnect, and stale-session reaping.",
+  register(api) {
+    const shared = {};
+    api.registerService({
+      id: "browserbase-session-broker",
+      async start(ctx) {
+        const config = normalizeConfig(api.pluginConfig);
+        const broker = new BrowserbaseBroker(config, {
+          logger: ctx.logger,
+          stateDir: ctx.stateDir
+        });
+        await broker.start();
+        shared.broker = broker;
+      },
+      async stop() {
+        const broker = shared.broker;
+        shared.broker = void 0;
+        await broker?.stop();
+      }
+    });
+    for (const tool of createBrowserbaseTools(() => shared.broker)) {
+      api.registerTool(tool);
+    }
+  }
+});
+export {
+  PLUGIN_ID,
+  index_default as default
+};