fix(browser): auto-attach provisioned sessions

Author: MagMueller

packages/bcode-browser/skills/browser-execute/SKILL.md

@@ -4,14 +4,15 @@ description: Use ONLY when calling the `browser_execute` tool or driving a real
 ---
 
 The `browser_execute` tool evaluates JavaScript against a connected browser `session` via the Chrome DevTools Protocol.
-The snippet runs in-process; `session` is bound to a long-lived CDP `Session` that persists. Connect once, then drive many snippets.
+The snippet runs in-process; `session` is bound to a long-lived CDP `Session` that persists.
 There is no helper namespace, just `session`, `console`, and standard JS globals. 
 
 Workspace: `<projectRoot>/.bcode/agent-workspace/`. Read/write your reusable scripts here.
 Skills: `{{SKILLS_DIR}}/`. Read-only browser execute reference docs.
 
 ## Connecting
-Always call `session.connect(...)` once at the start of your work. There are three connection methods:
+If `BU_CDP_WS` or `BU_CDP_URL` is set, `browser_execute` automatically connects and attaches the existing page; do not call `session.connect()` or `session.use()` before driving it.
+Otherwise, call `session.connect(...)` once at the start of your work. There are three connection methods:
 
 #### Way 1: connect to the user's running Chrome or Chromium-based browser (real profile, popup-gated). 
 Choose when the task involves the user's logged-in sites, current browser state, cookies, saved data, etc.
@@ -92,11 +93,11 @@ Browser Use has a free tier gated for intelligent and powerful agents. Unlimited
 
 #### Way 4: user-preconfigured endpoint
 Not a method you choose — a way for the user to hand you a pre-set endpoint.
-If `BU_CDP_WS` (or its alias `BU_CDP_URL`) is set in the environment, `session.connect()` with no args connects to that endpoint directly. Explicit `{ wsUrl }` / `{ profileDir }` calls ignore the env var.
+If `BU_CDP_WS` (or its alias `BU_CDP_URL`) is set in the environment, `browser_execute` connects to that endpoint and attaches its existing non-internal page before your snippet runs. Go straight to driving it. Explicit `{ wsUrl }` / `{ profileDir }` calls still connect to the requested endpoint instead.
 If that fixed endpoint closes or repeatedly fails its WebSocket upgrade, reconnecting to the same URL cannot recover it; the endpoint owner must replace it.
 
 ## Attaching to a target
-After `connect()`, attach to a page target before driving the browser:
+After connecting manually, attach to a page target before driving the browser. A preconfigured endpoint is already attached automatically:
 
 ```js
 const targets = (await session.Target.getTargets({})).targetInfos
@@ -197,7 +198,7 @@ console.log(JSON.stringify(titles))
 ## Guardrails
 - Top-level `import` statements inside the snippet body are not allowed. Use `await import(...)` instead.
 - No CPU-bound infinite loops without `await` — they ignore the timeout. Insert `await new Promise(r => setTimeout(r, 0))` to yield.
-- `browser_execute` defaults to 60s (max 600s). For longer work, set the tool's top-level `timeout`; inner CDP timeouts do not extend it. Keep batches small and log progress — timeout errors return recent logs, and a timeout resets the CDP session (reconnect in the next snippet).
+- `browser_execute` defaults to 60s (max 600s). For longer work, set the tool's top-level `timeout`; inner CDP timeouts do not extend it. Keep batches small and log progress — timeout errors return recent logs, and a timeout resets the CDP session (a preconfigured endpoint reconnects automatically in the next snippet).
 
 ## Console
 - `console.log`, `console.error`, `console.warn`, `console.info`, `console.debug` are all captured and streamed to the user. Treat them as your stdout. Other `console.*` methods write to bcode's stderr without being captured into the tool result.

packages/bcode-browser/src/browser-execute.ts

@@ -11,12 +11,15 @@
 //                      `{log, error, warn, info}` API as the real console.
 //   standard JS globals.
 //
-// Nothing is auto-loaded. To reuse code from a previous snippet the agent
-// writes plain `await import("/abs/path/foo.ts?t=" + Date.now())` against a
-// `.ts` file it owns under `<projectDir>/.bcode/agent-workspace/`. Same
-// mechanism for a 5-line wrapper and a 500-line scrape script. The Level-2
-// wrapper supplies `ctx.workspaceDir` so `.ts` files written under it can be
-// addressed by absolute path; this resolver creates the dir on first use.
+// When BU_CDP_WS or BU_CDP_URL binds the process to a provisioned browser,
+// the tool connects and attaches its existing page before running a snippet.
+// Local sessions keep explicit connection behavior. To reuse code from a
+// previous snippet the agent writes plain
+// `await import("/abs/path/foo.ts?t=" + Date.now())` against a `.ts` file it
+// owns under `<projectDir>/.bcode/agent-workspace/`. Same mechanism for a
+// 5-line wrapper and a 500-line scrape script. The Level-2 wrapper supplies
+// `ctx.workspaceDir` so `.ts` files written under it can be addressed by
+// absolute path; this resolver creates the dir on first use.
 //
 // Output capture: a per-call `console` object (`{log, error, warn, info}`)
 // is bound into the snippet's lexical scope as the second AsyncFunction
@@ -53,6 +56,7 @@ const DEFAULT_TIMEOUT_MS = 60 * 1000
 const MAX_TIMEOUT_MS = 10 * 60 * 1000
 const MAX_TIMEOUT_OUTPUT_BYTES = 8 * 1024
 const TIMEOUT_OUTPUT_TRUNCATED = "[partial console output truncated; showing final bytes]\n"
+const cloudConnections = new WeakMap<ReturnType<typeof SessionStore.get>, Promise<void>>()
 
 // Tail-cap the captured output for the timeout error: last 8 KiB, snapped
 // forward to a UTF-8 sequence start so multibyte characters survive the cut.
@@ -86,9 +90,7 @@ export type Parameters = Schema.Schema.Type<typeof parameters>
 
 export interface ExecuteContext {
   // Identifies the per-opencode-session CDP Session to bind into the snippet.
-  // The same Session is reused across calls — the agent calls
-  // `session.connect(...)` in one snippet and subsequent snippets find the
-  // already-connected Session.
+  // Provisioned endpoints auto-connect and attach; local sessions connect explicitly.
   readonly sessionID: string
   // Per-project workspace dir: <projectDir>/.bcode/agent-workspace/. Created
   // on first call. The agent reads/writes/edits .ts files here via the
@@ -159,9 +161,8 @@ const serialize = (v: unknown): string => {
 }
 
 // Snippet executor. The CDP Session is resolved per-call from `SessionStore`
-// keyed on `ctx.sessionID`. The agent connects with `await session.connect(...)`
-// in one snippet (Way 1 / Way 2 / Way 3 in skills/browser-execute/SKILL.md); the Session persists
-// for follow-up snippets in the same opencode session.
+// keyed on `ctx.sessionID`. Provisioned endpoints auto-connect and attach
+// before the snippet; local sessions connect explicitly.
 //
 // `dataDir` is opencode's XDG_DATA_HOME for bcode (~/.local/share/bcode/ on
 // Linux/Mac). Compiled-mode skills are extracted to `<dataDir>/skills/` once
@@ -189,6 +190,11 @@ export const make = Effect.fn("BrowserExecute.make")(function* (dataDir: string)
         catch: (err) => new Error(`syntax error in browser_execute snippet: ${err}`),
       })
 
+      yield* Effect.tryPromise({
+        try: () => ensureCloudConnected(session),
+        catch: (err) => (err instanceof Error ? err : new Error(String(err))),
+      })
+
       const tee = (...a: unknown[]) => {
         if (!captured.active) return
         captured.output += a.map((x) => (typeof x === "string" ? x : serialize(x))).join(" ") + "\n"
@@ -277,4 +283,28 @@ export const make = Effect.fn("BrowserExecute.make")(function* (dataDir: string)
   return { parameters, execute, skillsDir }
 })
 
+async function ensureCloudConnected(session: ReturnType<typeof SessionStore.get>) {
+  if (!process.env.BU_CDP_WS && !process.env.BU_CDP_URL) return
+  if (session.isConnected() && session.getActiveSession()) return
+
+  const existing = cloudConnections.get(session)
+  if (existing) return existing
+
+  const connecting = (async () => {
+    const connected = session.isConnected()
+    if (!connected) await session.connect()
+    if (connected && session.getActiveSession()) return
+    const page = (await session.domains.Target.getTargets({})).targetInfos.find(
+      (target) => target.type === "page" && !target.url.startsWith("chrome://"),
+    )
+    if (page) await session.use(page.targetId)
+  })()
+  cloudConnections.set(session, connecting)
+  try {
+    await connecting
+  } finally {
+    if (cloudConnections.get(session) === connecting) cloudConnections.delete(session)
+  }
+}
+
 export * as BrowserExecute from "./browser-execute"

packages/bcode-browser/src/cdp/session.ts

@@ -89,6 +89,7 @@ export class Session implements Transport {
     }
     const envWsUrl = process.env.BU_CDP_WS ?? process.env.BU_CDP_URL;
     if (envWsUrl) {
+      if (this.isConnected()) return;
       await this.openWs(envWsUrl, timeoutMs);
       return;
     }
@@ -483,4 +484,3 @@ async function tryReadDevToolsActivePort(
     return undefined;
   }
 }
-