@velanir/openclaw-browserbase 0.1.0

package/README.md

@@ -0,0 +1,134 @@
+# @velanir/openclaw-browserbase
+
+OpenClaw gateway plugin that puts a session broker between the bundled
+`browser` tool and [Browserbase](https://www.browserbase.com). The agent keeps
+using the normal `browser` tool; this plugin owns the Browserbase session
+lifecycle that a static `wss://connect.browserbase.com?apiKey=…` profile cannot
+provide: explicit session creation with the right options, a persistent
+per-coworker browser context (durable logins), deterministic release, idle
+disconnect, and stale-session reaping.
+
+Canonical design: `docs/plans/openclaw-browserbase-session-broker-design.md`
+in the platform repo (architecture, mint policy, edge-case matrix, decisions).
+
+## How it works
+
+```
+browser tool ──cdpUrl http://127.0.0.1:<port>/?token=…──> broker (this plugin)
+                                                            │  mint on WS connect
+                                                            ▼
+                                       Browserbase POST /v1/sessions + CDP pipe
+```
+
+- `GET /json/version` never creates a session — discovery and `browser status`
+  probes are free. A Browserbase session is minted only when OpenClaw opens
+  the advertised WebSocket (first real browser action), then CDP frames are
+  piped byte-for-byte.
+- 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.
+- One session per coworker context at a time (Browserbase forbids concurrent
+  sessions on one context), with a short cooldown after release.
+
+## OpenClaw config
+
+```json5
+{
+  browser: {
+    enabled: true,
+    defaultProfile: "browserbase",
+    remoteCdpTimeoutMs: 5000,
+    remoteCdpHandshakeTimeoutMs: 20000,
+    profiles: {
+      browserbase: {
+        cdpUrl: "http://127.0.0.1:18920/?token=${OCT8_BB_BROKER_TOKEN}",
+        attachOnly: true,
+        color: "#F97316"
+      },
+      main: { cdpPort: 18910, color: "#EF4444" }
+    }
+  },
+  plugins: {
+    allow: ["browser", "velanir-browserbase"],
+    entries: {
+      "velanir-browserbase": {
+        enabled: true,
+        config: {
+          projectId: "<browserbase project id>",
+          apiKey: "${OCT8_BROWSERBASE_API_KEY}",
+          listenPort: 18920,
+          token: "${OCT8_BB_BROKER_TOKEN}"
+        }
+      }
+    }
+  }
+}
+```
+
+Notes:
+
+- `attachOnly: true` is mandatory: a loopback `cdpUrl` without it is treated
+  as an OpenClaw-managed local browser.
+- `apiKey` and `token` must use `${ENV}` substitution so no secret lives in
+  `openclaw.json` on disk. Both env vars belong in the gateway service
+  environment (EC2: `/etc/oct8/<profile>.env`, mode 0600).
+- The broker `token` must be **URL-safe** (`[A-Za-z0-9._~-]`) because it rides
+  in the cdpUrl query string on both the profile and the broker-advertised
+  WebSocket URL. Generate it with base64url or hex; reserved characters like
+  `+ & # = /` change meaning across the URL parse boundaries and break auth.
+  The broker refuses to start with a non-URL-safe token.
+- The broker binds `127.0.0.1` only and requires the token on every request
+  and WebSocket upgrade.
+- Keep a local Chrome profile (`main` above) as fallback; OpenClaw never
+  auto-falls back — switching profiles is a model decision.
+
+## Config reference
+
+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).
+
+## Agent tools
+
+- `browserbase_session_status` — session id, expiry, idle time, context id.
+- `browserbase_live_view` — interactive Live View URL for human 2FA/SSO
+  handoff. The URL controls the browser; share it only with the human who
+  must act.
+- `browserbase_session_release` — release the session when browser work is
+  done; logins persist in the context.
+
+## Operations
+
+- Sessions carry `userMetadata`: `broker: "velanir-browserbase"`, a stable
+  per-gateway `instance` key, `bootId`, `leaseId`, plus any configured
+  `metadata` tags (org, coworker). The reaper only ever touches sessions whose
+  `instance` matches its own gateway.
+- Gateway stop releases the active session (bounded); a boot-time sweep plus
+  the interval reaper release crash leftovers.
+- The per-coworker context id persists in
+  `<state-dir>/velanir-browserbase/state.json` (0600). Deleting it forces a
+  fresh context (one-time re-login on every site).
+- Logs redact the API key, broker token, and URL secrets.
+- Known limitation: `/json/list` responses carry no per-target
+  `webSocketDebuggerUrl` (the broker exposes one multiplexed connection), so
+  OpenClaw's per-target JS-termination recovery path no-ops on this profile.
+  Tab management itself is unaffected — OpenClaw drives tabs Playwright-first
+  over the piped connection, with these HTTP endpoints as fallback.
+
+## Development
+
+```bash
+pnpm --filter @velanir/openclaw-browserbase build
+pnpm --filter @velanir/openclaw-browserbase check-types
+pnpm --filter @velanir/openclaw-browserbase test
+```
+
+Live integration tests are skipped unless `BROWSERBASE_API_KEY`,
+`BROWSERBASE_PROJECT_ID` (and optionally `BROWSERBASE_API_URL`) are set in the
+environment. They mint real (billed) sessions tagged `broker: "velanir-browserbase"`
+with a dedicated test instance key and release them on completion.

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+type PluginLogger = {
+    debug?: (message: string) => void;
+    info?: (message: string) => void;
+    warn?: (message: string) => void;
+    error?: (message: string) => void;
+};
+type OpenClawPluginToolResult = {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+};
+type OpenClawPluginTool = {
+    name: string;
+    label?: string;
+    description: string;
+    parameters: unknown;
+    execute: (toolCallId: string, params: Record<string, unknown>) => Promise<OpenClawPluginToolResult> | OpenClawPluginToolResult;
+};
+type OpenClawPluginServiceContext = {
+    stateDir: string;
+    logger: PluginLogger;
+};
+type OpenClawPluginService = {
+    id: string;
+    start: (ctx: OpenClawPluginServiceContext) => void | Promise<void>;
+    stop?: (ctx: OpenClawPluginServiceContext) => void | Promise<void>;
+};
+type OpenClawPluginApi = {
+    pluginConfig?: Record<string, unknown>;
+    logger: PluginLogger;
+    registerService: (service: OpenClawPluginService) => void;
+    registerTool: (tool: OpenClawPluginTool, opts?: {
+        optional?: boolean;
+    }) => void;
+};
+
+declare const PLUGIN_ID = "velanir-browserbase";
+declare const _default: {
+    id: string;
+    name: string;
+    description: string;
+    register(api: OpenClawPluginApi): void;
+};
+
+export { PLUGIN_ID, _default as default };