dsh-browser-use

---

description: "Repository guide for the dsh-browser-use bundle and its layered browser automation packages." kind: "repository"

dsh-browser-use

中文 | English

Summary

dsh-browser-use provides browser automation for DSH. The project consists of three layers: the Hub defines browser backend contracts and a named registry, each Backend manages browser resources and executes tools, and the Domain selects a backend and publishes its tools and settings to DSH. The repository root owns workspace and bundle assembly; all runtime source lives under packages/browser-use/.

Real task demo

Open the Travel category on Books to Scrape, compare prices across 11 books, find the three cheapest, and check each price on its detail page.

This 17-second GIF shows a scripted task executed through this repository's browser-use-chrome backend. The images were captured from a real Chrome session; step labels and the result card were added during editing, and waiting time was shortened. Books to Scrape uses demo data.

Package layout

See the browser-use package group map for dependency direction and layer ownership.

Architecture

The family keeps composition, semantics, and resources separate:

1. browser-use mounts ctx.browserUse and exposes a name-to-backend registry. It performs no browser IO.
2. A backend plugin injects the Hub, registers an implementation, and publishes browserUse.backend.<name> as a lifecycle-only Cordis service.
3. browser-use-domain waits for the configured lifecycle service, resolves the backend through the registry, and registers its stable tool catalog with ctx.tools.
4. Tool execution passes the initiating Agent object to the backend as an opaque owner, allowing independent MCP sessions and browser resources for each owner.
5. Settings changes are forwarded to the backend; agent disposal releases only that agent's resources, while plugin disposal closes the complete backend.

Cordis service availability controls activation. YAML row order is for readability and is not the synchronization mechanism.

Bundle

The root package is dsh-browser-use. Its cordis.patch.yml mounts the Hub, both Chrome and Edge backends, and Domain, selecting Chrome initially with hot switching through settings.

The effective DSH tool timeout is owned by the Domain configuration. Browser connection settings are also owned by the Domain and forwarded to the selected backend.

Requirements

• Node.js ^22.19.0 or >=24.0.0
• pnpm 11.7.0
• A compatible DeepSeek Harness installation
• Microsoft Edge, or Google Chrome when selecting the Chrome backend

Development

Run all commands from the repository root:

pnpm install
pnpm typecheck
pnpm test
pnpm build
pnpm pack --dry-run
pnpm pack:bundle

The workspace pattern is packages/*/*. Tests live with their owning package, and scripts/build.mjs emits four Host bundles, the Domain client module, and generation-scoped shared runtime helpers. pnpm pack --dry-run only previews the regular package contents and creates no file.

See the development guide for TypeScript project layout, source tests, and the build pipeline.

Install into DSH

This repository does not provide the dsh executable. Plugin management requires pnpm on PATH plus either an installed DSH CLI or a prepared deepseek-harness source checkout.

Install the source checkout

Build this repository first, then add its root directory with an installed CLI:

pnpm build
dsh plugin --profile web add .

When running DSH from source, first run pnpm install and pnpm run build in the deepseek-harness checkout, then invoke its root dsh script and pass this repository as an absolute file: spec:

cd C:\path\to\deepseek-harness
pnpm dsh plugin --profile web add file:C:/path/to/dsh-browser-use

Install a packed bundle

Create a self-contained local-install tarball from this repository:

pnpm install
pnpm pack:bundle

The command builds the workspace, stages the four runtime packages as bundled dependencies, and writes:

.artifacts/pack/dsh-browser-use-0.7.0.tgz

Install that tarball with an installed CLI:

dsh plugin --profile web add file:C:/path/to/dsh-browser-use/.artifacts/pack/dsh-browser-use-0.7.0.tgz

Or use the CLI from a deepseek-harness source checkout:

pnpm --dir C:\path\to\deepseek-harness dsh plugin --profile web add file:C:/path/to/dsh-browser-use/.artifacts/pack/dsh-browser-use-0.7.0.tgz

Use pnpm pack:bundle for an unpublished local installation. A plain pnpm pack rewrites workspace:^ dependencies to registry version ranges and therefore produces a root tarball that works only when the matching browser-use, browser-use-domain, browser-use-chrome, and browser-use-edge packages are available from the configured registry.

pnpm dsh works in the deepseek-harness source root because that package defines the script; it does not work in this plugin repository. Restart a running web profile after adding, removing, or updating a bundle.

Known limitations

• Chrome and Edge run their MCP servers as owned stdio CLIs with Windows Job or Linux/macOS process-group supervision. See the Chrome and Edge lifecycle references.
• In headed Edge sessions, pinned Playwright MCP appends an unsupported AutomationControlled command-line value and Edge displays a stability/security warning. The backend does not inject or rewrite browser arguments; see the known upstream issue.
• Browser settings hot-switch the active backend without restarting. Both provider plugins must be enabled.
• Chrome connects to pinned chrome-devtools-mcp@1.9.0 through managed MCP stdio; upgrades require CLI flags, debug-pipe, shutdown, and tool-protocol checks.
• Chrome and Edge use temporary isolated sessions when userDataDir is empty. Configuring a persistent directory allows saved login and other profile data to be reused from the same directory. After a Host restart, the plugin does not restore old MCP connections or in-flight tool calls.
• Tests cover MCP discovery, the 64 MiB response boundary, and resource lifecycle. Optional Edge, Chrome, switch, and lifecycle smoke flags exercise installed browsers.

License

MIT