[ben-reitz]

An agent with an Browser can drive it through browserTool, but code running in a Workspace can't. Building a site, opening it, taking screenshots and comparing them takes several model turns instead of one exec.

createBrowserModule() installs the browser as codemode:browser. Its exports are the same browser.* functions browserTool gives its code, so the docs and rules read the same:

"codemode:browser": createBrowserModule({
  browser: this.browser,
  //  default scope: "shared". in pi, scope it to conversation ID.
  scope: ({ metadata }) => (metadata.user ? `user:${metadata.user}` : "shared"),
}),

import * as browser from "codemode:browser";
await browser.cdp({ method: "Page.navigate", params: { url }, sessionId: "active" });

It keeps its browser session in a scoped context, from createCodemodeModule() (#301). A run opens one session on its first call and closes it when the run waits for a person or ends, which saves its tab for the next run or browserTool call. When the run ends, the session's notices go to its stderr, so nothing is written while the code runs and replay still matches. cdp is marked unsafeToRepeat(), (the same thing pi marks on browserTool).

Scope

The browser scope picks the tab. It defaults to "shared", and can be a string or a function of the run's metadata (#291, #292), so runs started for one user can share a tab. Runs in one browser scope take turns, because pi and the AI SDK run a message's tool calls in parallel and would otherwise see each other's navigation. A run gives up waiting after lockTimeoutMs, 45 seconds by default, with its own error before the run times out. A run that browsed and is waiting for a person keeps its browser scope, so other runs fail at once instead of waiting hours for an answer. That includes a run that gets its turn just as the one ahead of it pauses, so it checks again once it has the lock. The module remembers which runs browsed in memory, so after a Durable Object restart a waiting run holds nothing until it resumes.

Every function needs Workspace write access. The browser keeps its logins, so browsing can change things on other sites, and a read-only backend refuses it, as it refuses codemode:container's exec.

Computer types the agents contract by shape and takes no dependency on agents. The module needs agents 0.33.0 or later, which added functionDocs(), session.functions, the session lock and its notices.

The model is told, in the module's description, to save screenshots with node:fs and open them with read, to take about eight per run because host calls share 8 MiB, and to work on several pages in one run. It's also told not to call browserTool through codemode:tools, which would wait for its own turn. That case isn't caught automatically, since neither module can see the other.

Unit tests cover the browser scope options, the paused-run check, the lock timeout, both kinds of close and the description, against a fake browser shaped like the agents one. Two end-to-end tests run it through the real backend: one session per scope, closed on pause, with notices logged at the end; and a second run failing at once while a waiting run holds the browser scope. agents can't be a dev dependency yet: its optional peer range for pi conflicts with the version this repository uses. docs/17_isolate_javascript.md has a new codemode:browser section, which notes that an app writing exec's description by hand must include the module's.

---

[changeset-bot]

🦋 Changeset detected

Latest commit: 73ef9d3

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@cloudflare/computer	Minor
@cloudflare/dofs	Minor
@cloudflare/computer-rpc	Minor
@cloudflare/computerd	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@cloudflare/computer@299

commit: 73ef9d3