From 9a2da04d59e771aac671305c259e64c84f5b5070 Mon Sep 17 00:00:00 2001 From: MagMueller Date: Thu, 23 Jul 2026 13:56:39 -0700 Subject: [PATCH] docs(browser): add CDP recovery boundaries --- packages/bcode-browser/skills/browser-execute/SKILL.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/packages/bcode-browser/skills/browser-execute/SKILL.md b/packages/bcode-browser/skills/browser-execute/SKILL.md index 1e6ae048b0..39e1e3d06a 100644 --- a/packages/bcode-browser/skills/browser-execute/SKILL.md +++ b/packages/bcode-browser/skills/browser-execute/SKILL.md @@ -93,6 +93,7 @@ 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 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: @@ -104,6 +105,8 @@ const page = targets.find(t => t.type === "page" && !t.url.startsWith("chrome:// await session.use(page.targetId) ``` +If a target-scoped command throws `CdpError` code `-32001` (`Session with given id not found`), the browser connection is still usable but the target session is stale. List targets again, `session.use(...)` the intended page, and retry the rejected command once. Repeated `session.connect()` calls do not replace a stale target session. + ## Driving a page Domain methods follow `session..(params)` and return Promises. The full surface (652 commands) is the Chrome DevTools Protocol. @@ -142,6 +145,8 @@ await session.Page.captureScreenshot({ format: "png" }) // for the rare case you want to process it programmatically. ``` +`Page.navigate` can return a non-empty `errorText` instead of throwing. Treat it as a failed navigation. If `ERR_TUNNEL_CONNECTION_FAILED` persists, reloading, reattaching, or reconnecting to the same endpoint cannot change its proxy route; use another source or replace the cloud browser instead of retrying it. + ## Reusing code The agent-workspace is per-project: `./.bcode/agent-workspace/`. Use this to write memory files, scripts, and helper functions.