One browser-automation provider abstraction: registry, typed request, one control pair, one host lifecycle

[nedtwigg]

Unifies agent-browser and Playwright behind one provider abstraction on every layer. Adding a provider is now one registry row plus one host provider module, instead of special cases across the webview, control plane, CLI and 8 host transports. Stacked on #775. Items A1–A4 from the browser-stack deep dive.

One provider registry (A2)

dor-lib-common/browser-providers (BROWSER_PROVIDERS) holds each provider's facts: label, CLI alias, render modes, session args and charset, binary env var and default name, install hint, and binary allowlist.

• parseRenderMode / renderModeFor decode the persisted renderMode strings, which are unchanged (they are the public render_mode and dormouse.yml render values).
• The webview's GUI table, the display labels, the port actions, the Display modal rows and dor's passthrough aliases all derive from the registry.

One typed, provider-tagged request (A1)

browser(request: BrowserRequest) replaces the 8 agentBrowser* PlatformAdapter methods and playwright().

• Each host layer has one entry: VS Code browser:request, Tauri browser_request + browser_screenshot, the sidecar browser:request, and the dev harness.
• Nine Rust commands and the base64 crate are gone.
• The webview no longer speaks CLI argv. Its typed browserHandle(provider, binding) gates binaryPath. The agent-browser provider renders each op to a fixed argv, and Playwright maps ops directly (its argv re-parse is deleted).
• The capability probe is browserProviders.

One control pair, binding and identity (A3)

• surface.browser / surface.resolveBrowser serve both providers. surface.agentBrowser / surface.resolveAgentBrowser remain as aliases for one release, for terminals still running an older dor.
• One binding {provider, session, cwd?, binaryPath?}. agent-browser launches now honour cwd, so a project agent-browser.json applies.
• Identity is nativeIdentity for both providers.
• --key finds the Surface by key first, then uses sessionForKey(key, scope). A bare Wall now gets a unique w<8hex> scope, which fixes every VS Code webview sharing dormouse.1.default.
• dor has one runBrowserCli(descriptor). dor ab reads the stream port itself (stream status --json) after every command that may bind and hands it over, as before; the host's state-file lookup serves only GUI attaches. The host never receives a socket directory, because it signals the pid it reads there.

One host lifecycle (A4)

lib/src/host/browser-host.ts owns:

• request validation;
• per-nativeIdentity serialization with generations, and headed tracking;
• the blank-tab sweep and the bounded launch;
• capture transport, edit scripts, JPEG quality, and GUI session minting;
• a first-class closeSession, and shutdown.

The providers are narrow primitives (createAgentBrowserProvider, createPlaywrightProvider), created lazily.

Close/launch ordering is strict on every transport, including Tauri's worker-pool commands:

• A named launch waits for the webview's closes of that session to be answered.
• A close cancels, by a webview-minted request id, the Surface's own launches and attaches that are still unanswered, so one arriving late opens nothing.
• The host still serializes and supersedes by arrival.

The webview-side close bookkeeping from #775 is deleted.

Behaviour changes worth a look

• A named launch into a browser that is already up in the requested mode navigates it; only a browser that is gone, or in the other mode, is relaunched. stop signals a daemon only when its state files prove it live: a pid file written since boot, naming a live process, beside a .stream port that accepts.
• One blank-tab sweep policy now covers every launch of either provider, and agent-browser launches are bounded to fit the transport's wait.
• Context-menu port targets are named by provider label ("agent-browser", "agent-browser popout", …).
• The last launch binary is remembered per provider.
• Captures go to one private dormouse-browser- directory. Each capture is read into memory and its file removed, and every reader deletes the file it was handed.

Specs: docs/specs/dor-browser.md is reorganized into Providers, then Automated Browser (identity, connection, pop-out, a Browser Host contract written once), then the genuine per-provider differences. dor-cli.md has one "Browser Surface Addressing" section. The glossary, transport, vscode, standalone, shortcuts and dor-tool specs and the rationale files are updated.

Testing

• Root pnpm test passes (lib 3900+, dor 190, dor-lib-common 17, vscode-ext 181, standalone, relay, website, and every lint).
• The Argos story runs pass in Chromium and WebKit (294/294 each).
• The race tests run the controller against the real createBrowserHost.
• Every fixed line was mutation-checked.
• Nothing was run against a real agent-browser or Playwright CLI.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NCV5Uq6FeZbBfzfpk3vrpe

[cloudflare-workers-and-pages]

Deploying mouseterm with    Cloudflare Pages

Latest commit:	f24214f
Status:	✅  Deploy successful!
Preview URL:	https://ab206a6f.mouseterm.pages.dev
Branch Preview URL:	https://browser-providers.mouseterm.pages.dev

View logs

[dormouse-bot]

This is feedback on a draft, not a merge verdict. Mark the PR ready when you want the full review.

1. Re-announcing a Tool now kills the agent's browser daemon. When a Tool re-announces (new port or path), toolBrowserLaunchParams sets launchSession to the session the Tool already has, and the controller sends a named launch. On base, agent-browser's open → coldLaunch ran open <url> on the live daemon. Now launch calls p.stop, which runs close, then killDaemon (SIGTERM, then SIGKILL after 2 s). An agent driving that Tool loses its tabs, page state and CDP clients every time the dev server moves, and any dor ab command in flight fails or starts a daemon mid-relaunch. The comment above updateParams in use-tool-serving.ts still says a changed destination "just navigates". The PR body lists stop-first as a deliberate change, so you have two options: have tool-serving navigate the live session instead of relaunching it, or accept the new behaviour and fix that comment.

This path also widens who reaches killDaemon. Before, only pop-out/pop-in killed, and only a live session's pid. Now a first Tool serve, or a swap restore with a leftover <session>.pid (after a reboot, say), signals whatever process now owns that pid.

2. dor ab may no longer open a pane on an agent-browser that writes no state files. dor ab now reads the stream port itself only under a custom AGENT_BROWSER_SOCKET_DIR (callerStreamStatus). Otherwise the host's find decides, and it reads only <session>.pid / <session>.stream. readStateNumber itself notes those files can be absent for "an older CLI". With such a CLI, find answers "not running" and dor ab open … prints the could-not-open warning and opens no pane. On base, dor ab always ran stream status --json itself. The fix is either a stream status fallback in find when there is no pid file, or a stated minimum agent-browser version.

3. Playwright frames on standalone now reuse one file per browser. On base, Playwright's requestFile wrote a fresh random .frame each time, and Rust deleted it after reading. Now it writes to the shared capturePath(id, …) name (here), and browser_screenshot leaves the file in place. This has two effects:

• joinInFlight drops its entry when the capture answers, before Rust reads the file. A second capture of the same session in that gap (a second pane, or the modal beside the loop) truncates and rewrites the file under the read, which gives a torn or empty frame.
• forgetInFlight rotates the name without unlinking the old file. Each closed session's last frame of the user's page therefore stays in the capture directory until shutdown.

agent-browser had the first effect already. For Playwright, both are new.

4. Playwright --key sessions can now collide after a Workspace transfer. On base, a Playwright key minted dormouse.pw.<uuid>. Now BrowserBindingReservations.resolve uses sessionForKey(key, scope), but the key lookup searches only the answering Wall. So after dor pw --key foo open in ws1, moving that pane to ws2 and running the same command in ws1 again finds no pane and binds a second one to the same dormouse.ws1.foo. Closing either pane then closes the other's browser. agent-browser already worked this way, but for Playwright it is new.

[argos-ci]

The latest updates on your projects. Learn more about Argos notifications ↗︎

Build	Status	Details	Updated (UTC)
storybook-chromium (Inspect)	👍 Approved by Ned Twigg	17 changed	Sep 24, 2026, 4:04 PM
storybook-webkit (Inspect)	👍 Approved by Ned Twigg	18 changed	Sep 24, 2026, 4:04 PM

Deployment	Status	Branch	Updated (UTC)
preview (Open)	Ready	browser-providers	Sep 24, 2026, 4:05 PM

[dormouse-bot]

These two points are new since the draft review. The four points in that review still apply to this commit.

1. dor ab can now warn about a bind that later succeeds. On base, dor ab sent the port it had read itself, so surface.agentBrowser answered immediately. Now the host handler awaits browser.attach() for agent-browser too. That call goes through bringUp, so it waits behind any launch, relaunch or close of the same session, and a launch can hold that slot for up to about 38 s (REQUEST_BUDGET_MS). Meanwhile browserSurface still uses the client's default 5 s deadline.

So if an agent runs dor ab --key default snapshot while a restored pane is relaunching its session, or just after a pop-out/pop-in, the command succeeds but prints Warning: could not open the Dormouse browser surface: …timed out. The host then binds the pane anyway. Agents read stderr, so the false warning misleads them. Playwright had the same exposure on base; this PR extends it to dor ab. Raising this call's timeout above the host's request budget would fix it, as awaitSurface does with its per-call timeoutMs. The control server's reaper already allows 10 s beyond whatever timeout the client sets.

2. A stuck agent-browser close now blocks every later request for that session. closeSession runs bound.p.close(bound.b) inside serialize(bound.id, …) and passes no timeout. agent-browser's close forwards that undefined to spawnAndCapture, so the call has no time limit. The launch deadline check only runs once the queue reaches the launch, so it cannot help here.

Example: a Surface closes session S while S's open is stalled on a slow page. The daemon queues close behind the open, and if the daemon hangs, the close never returns. From then on, every attach, relaunch and pop-in/pop-out of S waits forever, and each webview request gives up after 40 s. At shutdown, Promise.allSettled(lifecycle.values()) never settles either. On base, the webview's close went through the unqueued command() path, so a stuck close only stalled itself. A bounded timeout on this close, like the budget launch already gives p.stop, would keep one hung daemon from wedging the session.

[nedtwigg]

Thanks. All six points from the draft review and the full review are addressed in 43f3ade.

1. A Tool re-announce killed the agent's daemon; a stale pid could be killed.

• A named launch into a browser that is already up in the mode it asks for now navigates that browser, without stopping it or waiting on the page (reuse in browser-host.ts). Only a browser that is gone, or is in the other mode (pop-out/pop-in), is relaunched. The "just navigates" comment in use-tool-serving.ts is true again. agent-browser can't report its mode, so a browser this host didn't launch headed counts as headless.
• stop now signals a pid only when the state files prove it is the session's live daemon: a pid file written since this boot, naming a live process, next to a .stream port that accepts. This is checked before close. A state file older than the boot reads as absent, so a <session>.pid left over from before a reboot never leads to a signal.
• Tests: a Tool re-announce navigates and stops nothing; a pre-boot pid file, and a live pid with no accepting stream, are never signalled; a proven daemon gets SIGTERM.

2. Older agent-browser without state files. dor ab again reads the stream port itself (stream status --json) after every command that may bind, and hands it over, as on base. The Surface streams from that port without asking the host. The special case for a custom socket directory is gone. The host's state-file find is kept only for GUI attaches.

3. Capture files.

• Every capture is read into memory and its capture file removed. Each caller then gets a fresh private file (file transport) or the bytes (VS Code).
• Rust's browser_screenshot and the dev harness delete the file after reading it.
• A browser's close or relaunch deletes its frames that were never read, and each new frame deletes any unread frame older than the 40 s request timeout.
• Tests: a second capture taken while the first is still unread never rewrites it (both providers); joined callers get separate copies; no files are left behind.

4. --key collisions. Minting a key's session now checks the whole Window, through a new WallHandle.browserSessions(provider), plus the other keys' reservations for that provider. If the name is taken, it takes the first free .2, .3, …. The numbering is deterministic, so the key resolves to the same session again. Tests: a reservation unit test, and a Wall test where a Surface in another Workspace holds the key's session and the same command here gets .2.

5. The false "could not open" warning. dor's surface.browser call now waits BROWSER_REQUEST_TIMEOUT_MS + 5 s. That constant moved to dor-lib-common, so dor, lib and the transports share it. With point 2, agent-browser binds skip the host's attach entirely; a Playwright bind may still queue behind a launch. Test: a host that answers after the client's default deadline still binds.

6. An unbounded close. Every provider call a browser's lifecycle queue waits on is now bounded:

• a close at 10 s (agent-browser's close had been forwarded with no timeout);
• the stream-port read that ends a launch, by the launch's deadline;
• the stop, as before.

Shutdown waits on the queue for at most 10 s. Tests: a hung close holds up a later launch only for its bound, and shutdown finishes within 10 s even when a close ignores its bound.

The dor-browser, dor-cli and standalone specs and their rationale state each rule. Root pnpm test, both Argos browsers and cargo check pass, and each of the 18 mutation checks turns its test red.

[dormouse-bot]

The fixes in 43f3ade cover all six earlier points. The PR description now contradicts the code on two of them, and a maintainer judges this merge from that description:

• Under Behaviour changes worth a look, it says a named launch "closes the session and stops its daemon before relaunching; it no longer reuses a running daemon." reuse in browser-host.ts now navigates a browser that is already up in the requested mode. It relaunches only a browser that is gone or in the other mode.
• Under One control pair, binding and identity (A3), it says dor ab "reads its stream port itself only under a custom AGENT_BROWSER_SOCKET_DIR." callerStreamStatus is gone. dor ab now runs stream status --json after every command that may bind, as base did, and the host's state-file find serves only GUI attaches.

Both bullets should describe the new behaviour. The first could also say that stop signals only a daemon its state files prove live.

[nedtwigg]

Updated the PR description: both bullets now describe the new behaviour (a named launch navigates a live browser in the requested mode, stop signals only a daemon its state files prove live, and dor ab reads its own stream port after every command that may bind). The captures bullet also covers read-then-delete now.