@@ -35,9 +35,8 @@
 // Level-2 hook in packages/opencode is a thin adapter.
 
 import fs from "fs/promises"
-import path from "path"
 import { Effect, Schema } from "effect"
-import { Session } from "./cdp/session"
+import { SessionStore } from "./session-store"
 
 const DEFAULT_TIMEOUT_MS = 60 * 1000
 const MAX_TIMEOUT_MS = 10 * 60 * 1000
@@ -54,6 +53,10 @@ export const parameters = Schema.Struct({
 export type Parameters = Schema.Schema.Type<typeof parameters>
 
 export interface ExecuteContext {
+  // Identifies the per-opencode-session CDP Session to bind into the snippet.
+  // Shared with `browser_open_cloud` via the SessionStore so a cloud-attach
+  // call's Session is driven by subsequent `browser_execute` calls.
+  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
   // standard read/write/edit tools and imports them at runtime via
@@ -92,14 +95,13 @@ const serialize = (v: unknown): string => {
   }
 }
 
-// Per-opencode-session Session singleton. Connects lazily on first snippet;
-// closed on session end via the caller's scope finalizer.
+// Snippet executor. The CDP Session is resolved per-call from `SessionStore`
+// keyed on `ctx.sessionID` so a Session attached via `browser_open_cloud` is
+// the same one a follow-up `browser_execute` drives.
 export const make = Effect.fn("BrowserExecute.make")(function* () {
-  const session = new Session()
-  yield* Effect.addFinalizer(() => Effect.sync(() => session.close()))
-
   const execute = (args: Parameters, ctx: ExecuteContext) =>
     Effect.gen(function* () {
+      const session = SessionStore.get(ctx.sessionID)
       yield* Effect.promise(() => fs.mkdir(ctx.workspaceDir, { recursive: true }))
 
       const wrapped = yield* Effect.try({
@@ -144,7 +146,7 @@ export const make = Effect.fn("BrowserExecute.make")(function* () {
       }),
     )
 
-  return { parameters, execute, session }
+  return { parameters, execute }
 })
 
 export * as BrowserExecute from "./browser-execute"
@@ -0,0 +1,109 @@
+// Cloud-browser attach (decisions §3.3 / §6 — single API key, BU cloud
+// surfaces). Provisions a Browser Use cloud browser via the public
+// /api/v3/browsers REST surface and connects a `Session` to its `cdpUrl`.
+//
+// Three calls per attach:
+//   1. POST /api/v3/browsers           → { id, cdpUrl, liveUrl }
+//   2. (caller) session.connect({ wsUrl: cdpUrl })
+//   3. PATCH /api/v3/browsers/<id>     → { state: "stop" }   (finalizer)
+//
+// `BROWSER_USE_API_KEY` must be set; we fail fast if absent so the Level-2
+// wrapper can render a one-line error pointing at our docs without
+// constructing a bad request.
+
+import { Effect, Schema } from "effect"
+import { SessionStore } from "./session-store"
+
+const API_BASE = "https://api.browser-use.com/api/v3/browsers"
+
+export const provisionParameters = Schema.Struct({
+  profileId: Schema.optional(Schema.String).annotate({
+    description: "Existing BU cloud profile id to attach to. Omit for a fresh ephemeral profile.",
+  }),
+  proxyCountryCode: Schema.optional(Schema.String).annotate({
+    description: "ISO-2 country code for the proxy pool (e.g. \"us\", \"de\").",
+  }),
+})
+
+export type ProvisionParameters = Schema.Schema.Type<typeof provisionParameters>
+
+export interface ProvisionResult {
+  readonly id: string
+  readonly cdpUrl: string
+  readonly liveUrl: string
+}
+
+const apiKey = () => {
+  const k = process.env.BROWSER_USE_API_KEY
+  if (!k) {
+    throw new Error(
+      "BROWSER_USE_API_KEY is not set. Cloud browsers require a Browser Use API key — get one at https://browser-use.com.",
+    )
+  }
+  return k
+}
+
+const provision = (args: ProvisionParameters) =>
+  Effect.tryPromise({
+    try: async () => {
+      const res = await fetch(API_BASE, {
+        method: "POST",
+        headers: {
+          "X-Browser-Use-API-Key": apiKey(),
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          profile_id: args.profileId,
+          proxy_country_code: args.proxyCountryCode,
+        }),
+      })
+      if (!res.ok) throw new Error(`provision failed: ${res.status} ${await res.text()}`)
+      const body = (await res.json()) as { id: string; cdp_url?: string; cdpUrl?: string; live_url?: string; liveUrl?: string }
+      const cdpUrl = body.cdpUrl ?? body.cdp_url
+      const liveUrl = body.liveUrl ?? body.live_url
+      if (!cdpUrl || !liveUrl) throw new Error(`provision response missing cdpUrl/liveUrl: ${JSON.stringify(body)}`)
+      return { id: body.id, cdpUrl, liveUrl } satisfies ProvisionResult
+    },
+    catch: (err) => (err instanceof Error ? err : new Error(String(err))),
+  })
+
+const stop = (id: string) =>
+  Effect.tryPromise({
+    try: async () => {
+      const res = await fetch(`${API_BASE}/${id}`, {
+        method: "PATCH",
+        headers: {
+          "X-Browser-Use-API-Key": apiKey(),
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ state: "stop" }),
+      })
+      if (!res.ok) throw new Error(`stop failed: ${res.status} ${await res.text()}`)
+    },
+    catch: (err) => (err instanceof Error ? err : new Error(String(err))),
+  })
+
+// Provisions a cloud browser, connects the per-opencode-session `Session` to
+// it, and registers a stop-callback with `SessionStore` so the browser is
+// torn down when the session is evicted (or, in practice, at process exit
+// since opencode doesn't currently call evict — that's a known gap matching
+// today's `uv run` subprocess shape, where a stuck Python interpreter also
+// outlives the bcode session). The Session is shared with `browser_execute`
+// via `SessionStore`. Returns the public bits the agent needs.
+export const open = Effect.fn("CloudBrowser.open")(function* (
+  sessionID: string,
+  args: ProvisionParameters,
+) {
+  const { id, cdpUrl, liveUrl } = yield* provision(args)
+  const session = SessionStore.get(sessionID)
+  SessionStore.onEvict(sessionID, () =>
+    Effect.runPromise(stop(id).pipe(Effect.ignore)),
+  )
+  yield* Effect.tryPromise({
+    try: () => session.connect({ wsUrl: cdpUrl }),
+    catch: (err) => (err instanceof Error ? err : new Error(String(err))),
+  })
+  return { id, liveUrl } as const
+})
+
+export * as CloudBrowser from "./cloud-browser"
@@ -0,0 +1,52 @@
+// Process-scope per-opencode-session CDP Session map.
+//
+// Both `browser_execute` and `browser_open_cloud` look up the same `Session`
+// by `sessionID` so a snippet that follows a `browser_open_cloud` call drives
+// the cloud browser, not a freshly-auto-detected local one.
+//
+// Lifetime: Sessions persist for the life of the opencode process (or until
+// the underlying WebSocket closes). We don't have a clean session-end hook
+// in opencode's tool layer; the WS closes naturally on browser exit and the
+// agent can call `session.close()` from a snippet if needed. Sessions held in
+// the map after their browser exits become unusable but are cheap (just an
+// idle WS reference until the next snippet replaces them).
+//
+// Evicted via `evict(sessionID)` if a future hook is added.
+
+import { Session } from "./cdp/session"
+
+interface Entry {
+  readonly session: Session
+  // Cleanup callbacks registered alongside the Session — e.g. cloud-browser
+  // stop calls. Run sequentially on `evict`. Each is fire-and-forget and
+  // must not throw outwards (errors are logged, not propagated).
+  readonly cleanup: Array<() => Promise<void>>
+}
+
+const sessions = new Map<string, Entry>()
+
+export const get = (sessionID: string): Session => {
+  const existing = sessions.get(sessionID)
+  if (existing) return existing.session
+  const fresh = new Session()
+  sessions.set(sessionID, { session: fresh, cleanup: [] })
+  return fresh
+}
+
+export const onEvict = (sessionID: string, fn: () => Promise<void>): void => {
+  const entry = sessions.get(sessionID)
+  if (!entry) throw new Error(`SessionStore.onEvict: no session ${sessionID}`)
+  entry.cleanup.push(fn)
+}
+
+export const evict = async (sessionID: string): Promise<void> => {
+  const entry = sessions.get(sessionID)
+  if (!entry) return
+  sessions.delete(sessionID)
+  for (const fn of entry.cleanup) {
+    try { await fn() } catch (err) { console.error(`SessionStore evict cleanup failed for ${sessionID}:`, err) }
+  }
+  entry.session.close()
+}
+
+export * as SessionStore from "./session-store"
@@ -0,0 +1,58 @@
+// Smoke test for the documented workspace-import pattern: agent writes
+// .ts files to <projectDir>/.bcode/agent-workspace/, then imports them
+// at runtime from a `browser_execute` snippet via
+// `await import("/abs/path?t=" + Date.now())`. We don't run a real
+// `browser_execute` here — the point is to verify the dynamic-import
+// mechanism behaves as the BROWSER.md prompt claims.
+//
+// All four scenarios run against a real tmp dir, real .ts files, and
+// the real Bun module loader. No mocks.
+
+import { afterAll, beforeAll, expect, test } from "bun:test"
+import fs from "fs/promises"
+import os from "os"
+import path from "path"
+
+let workspace: string
+
+beforeAll(async () => {
+  workspace = await fs.mkdtemp(path.join(os.tmpdir(), "bcode-ws-"))
+})
+
+afterAll(async () => {
+  await fs.rm(workspace, { recursive: true, force: true })
+})
+
+test("await import(absPath) returns the workspace .ts module", async () => {
+  const file = path.join(workspace, "scrape.ts")
+  await fs.writeFile(file, `export const run = async () => "v1"\n`, "utf8")
+  const m = await import(file)
+  expect(await m.run()).toBe("v1")
+})
+
+test("edit + cache-bust returns the fresh module", async () => {
+  const file = path.join(workspace, "fresh.ts")
+  await fs.writeFile(file, `export const run = async () => "before"\n`, "utf8")
+  const a = await import(`${file}?t=${Date.now()}`)
+  expect(await a.run()).toBe("before")
+  await fs.writeFile(file, `export const run = async () => "after"\n`, "utf8")
+  const b = await import(`${file}?t=${Date.now() + 1}`)
+  expect(await b.run()).toBe("after")
+})
+
+test("syntax error in workspace file surfaces a clean rejection", async () => {
+  const file = path.join(workspace, "broken.ts")
+  await fs.writeFile(file, `export const run = (\n`, "utf8")
+  expect(async () => {
+    await import(`${file}?t=${Date.now()}`)
+  }).toThrow()
+})
+
+test("nested workspace paths import the same way", async () => {
+  const subdir = path.join(workspace, "scrapers", "social")
+  await fs.mkdir(subdir, { recursive: true })
+  const file = path.join(subdir, "tweet.ts")
+  await fs.writeFile(file, `export const run = async () => "nested"\n`, "utf8")
+  const m = await import(file)
+  expect(await m.run()).toBe("nested")
+})
@@ -45,6 +45,7 @@ export const BrowserExecuteTool = Tool.define(
           const workspaceDir = workspaceDirOf(instance.directory)
 
           const result = yield* impl.execute(args, {
+            sessionID: ctx.sessionID,
             workspaceDir,
             // Stream chunks to the TUI as they arrive — same pattern as bash.
             onChunk: (output) =>
 
@@ -0,0 +1,35 @@
+// browser_open_cloud — Level-2 hook (decisions.md §1c, §3.3, §6).
+//
+// Provisions a Browser Use cloud browser and binds the per-opencode-session
+// CDP Session to it. After this tool returns, `browser_execute` snippets
+// drive the cloud browser instead of any local Chrome.
+
+import { Effect, Schema } from "effect"
+import { CloudBrowser } from "@browser-use/bcode-browser/cloud-browser"
+import * as Tool from "./tool"
+import DESCRIPTION from "./browser-open-cloud.txt"
+
+export const BrowserOpenCloudTool = Tool.define(
+  "browser_open_cloud",
+  Effect.gen(function* () {
+    return {
+      description: DESCRIPTION,
+      parameters: CloudBrowser.provisionParameters,
+      execute: (args: Schema.Schema.Type<typeof CloudBrowser.provisionParameters>, ctx: Tool.Context) =>
+        Effect.gen(function* () {
+          yield* ctx.ask({
+            permission: "browser_open_cloud",
+            patterns: ["*"],
+            always: ["*"],
+            metadata: {},
+          })
+          const { id, liveUrl } = yield* CloudBrowser.open(ctx.sessionID, args)
+          return {
+            title: "browser_open_cloud",
+            output: `Cloud browser ready.\nbrowserId: ${id}\nliveUrl: ${liveUrl}`,
+            metadata: { browserId: id, liveUrl },
+          }
+        }).pipe(Effect.orDie),
+    }
+  }),
+)
@@ -0,0 +1,12 @@
+Provision a Browser Use cloud browser and bind it to this session.
+
+After this tool returns, every subsequent `browser_execute` snippet drives the cloud browser via the same `session` object — there is no per-snippet attach step. The cloud browser is automatically stopped when the bcode session ends.
+
+Use this when:
+- You need a browser the user cannot see (autonomous, long-running, or background tasks).
+- You need a clean profile, geo-located proxy, or cookie isolation.
+- You need to scrape sites that fingerprint local Chrome installs.
+
+Requires `BROWSER_USE_API_KEY`. Without it the call fails with a one-line error pointing at https://browser-use.com.
+
+Output includes a `liveUrl` — a Browser Use URL that streams the live browser pixels to a viewer; share it with the user when they want to watch the agent work.
@@ -11,6 +11,7 @@ import { TodoWriteTool } from "./todo"
 import { WebFetchTool } from "./webfetch"
 import { WriteTool } from "./write"
 import { BrowserExecuteTool } from "./browser-execute"
+import { BrowserOpenCloudTool } from "./browser-open-cloud"
 import { InvalidTool } from "./invalid"
 import { SkillTool } from "./skill"
 import * as Tool from "./tool"
@@ -115,6 +116,7 @@ export const layer: Layer.Layer<
     const patchtool = yield* ApplyPatchTool
     const skilltool = yield* SkillTool
     const browserExecute = yield* BrowserExecuteTool
+    const browserOpenCloud = yield* BrowserOpenCloudTool
     const agent = yield* Agent.Service
 
     const state = yield* InstanceState.make<State>(
@@ -209,6 +211,7 @@ export const layer: Layer.Layer<
           search: Tool.init(websearch),
           skill: Tool.init(skilltool),
           browserExecute: Tool.init(browserExecute),
+          browserOpenCloud: Tool.init(browserOpenCloud),
           patch: Tool.init(patchtool),
           question: Tool.init(question),
           lsp: Tool.init(lsptool),
@@ -232,6 +235,7 @@ export const layer: Layer.Layer<
             tool.search,
             tool.skill,
             tool.browserExecute,
+            tool.browserOpenCloud,
             tool.patch,
             ...(Flag.OPENCODE_EXPERIMENTAL_LSP_TOOL ? [tool.lsp] : []),
             ...(Flag.OPENCODE_EXPERIMENTAL_PLAN_MODE && Flag.OPENCODE_CLIENT === "cli" ? [tool.plan] : []),