Skip to content

Commit da8b535

Browse files
committed
docs(browser): document the screenshot auto-attach escape hatch
`browser_execute` attaches every `Page.captureScreenshot` result to the next assistant turn, which is the right default — it saves a `read` call almost every time. But there was no way to capture pixels the agent does not need to look at: bulk capture, or an artifact that only gets written to disk. A bulk task attaches every frame to context with no opt-out. The tap subscribes to `onCallResult`, which fires only from `_call`'s resolve path — the command-response channel. CDP events route through a separate listener list, so pixels delivered as `Page.screencastFrame` are structurally invisible to it. That makes the escape hatch real CDP rather than an invented parameter, so what the agent learns transfers to any client. Verified against Chrome 150.0.7871.187 (--headless=new): - static, already-loaded, idle page: startScreencast delivers a frame in 7ms with no navigation, scroll, or re-layout nudge - screencast frames produce zero attachments; captureScreenshot still attaches - setDeviceMetricsOverride({ width: 1200, height: 630 }) yields a PNG whose header reads exactly 1200x630 Two protocol details found while testing that are deliberately left out of the skill text, recorded here instead: - ack is not needed for navigation-paced capture (3 navigations produced 3 frames unacked). It is required for continuous capture: on an animating page, 3s yielded 3 frames unacked vs 178 acked, so Chrome stalls after a couple of unacked frames. - `sessionId` on the frame event is not a frame counter despite the protocol describing it as "Frame number" — it is constant within a cast and increments per startScreencast.
1 parent bf190ce commit da8b535

1 file changed

Lines changed: 15 additions & 0 deletions

File tree

  • packages/bcode-browser/skills/browser-execute

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

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -149,6 +149,21 @@ await session.Page.captureScreenshot({ format: "png" })
149149
150150
`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.
151151
152+
Not auto-attaching a screenshot: attachment is keyed on the `Page.captureScreenshot` response; pixels that arrive as an event are never attached.
153+
154+
```js
155+
await session.Page.enable()
156+
// Optional: screencast has no `clip`, so override the viewport for exact frame size.
157+
await session.Emulation.setDeviceMetricsOverride({ width: 1200, height: 630, deviceScaleFactor: 1, mobile: false })
158+
const frame = session.waitFor("Page.screencastFrame", { timeoutMs: 10_000 }) // register first
159+
await session.Page.startScreencast({ format: "png" })
160+
try {
161+
const f = await frame // f.data is base64, same as captureScreenshot
162+
} finally {
163+
await session.Page.stopScreencast() // otherwise the cast stays open
164+
}
165+
```
166+
152167
## Reusing code
153168
The agent-workspace is per-project: `./.bcode/agent-workspace/`.
154169
Use this to write memory files, scripts, and helper functions.

0 commit comments

Comments
 (0)