@lexmount/dsh-browser

Readme

# `@lexmount/dsh-browser`

Lexmount cloud browser tools for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness). This package is a lightweight DSH Bundle: it registers native model tools and invokes the Rust `browser-cli`, but it does not contain a native executable, run an MCP server, or depend on the Lexmount Node.js SDK.

> Status: Windows x64, macOS Apple Silicon, and Linux x64 native validation is complete. The current stable Bundle version is `0.1.1`.

> **Current platform support:** Windows x64, macOS Apple Silicon, and Linux x64. macOS Intel and Linux ARM64 are not currently supported.

## Runtime architecture

```text
DSH Web / Headless
  → @lexmount/dsh-browser (Bundle and Node adapter only)
  → pinned browser-cli download and user cache
  → browser-cli child process
  → Lexmount API / CDP / cloud browser
```

The Bundle registers tools without accessing the network. On the first tool call it selects the current OS/CPU asset, downloads the pinned `browser-cli` release and `SHA256SUMS` from Lexmount's versioned Tencent COS path, verifies the digest, executable format/architecture, and CLI version, then installs it atomically in a user cache. Later calls and restarts reuse the verified cache, so an already populated cache works offline.

The npm tarball contains no `browser-cli` or `browser-cli.exe` file. End users do not need Rust, Python, a browser driver, or an npm lifecycle script.

## Platform status

| Host | Release asset target | Current status |
| --- | --- | --- |
| Windows x64 | `x86_64-pc-windows-msvc` | Supported |
| macOS Apple Silicon | `aarch64-apple-darwin` | Supported |
| Linux x64 | `x86_64-unknown-linux-musl` | Supported |
| macOS Intel | `x86_64-apple-darwin` | Not currently supported; asset missing |
| Linux ARM64 | — | Not currently supported; asset missing |

`native-source.json` pins `browser-cli` v1.1.15 at commit `952a5e53ff9dd3980342d4dae7f860f80b39a100`. The Windows asset statically links the C runtime, and the Linux x64 asset is a static musl executable. This Bundle uses the three assets published by that immutable release. Adding another platform requires a new browser-cli version and a new npm package version with fresh validation; it will not mutate this release in place.

## Install

The current release requires Node.js `>=22.14.0`, DSH `0.1.0-rc.6`, and a
`pnpm` executable on `PATH`. The commands below use `npx`, so a global DSH
installation is not required. The commands pin the Bundle version so DSH's
dependency release-age policy cannot resolve the request to an older release.

### Windows x64

Open a normal, non-administrator PowerShell in the directory that should become
the DSH workspace, then run:

```powershell
node --version
corepack --version
corepack install --global pnpm@11.22.0
corepack enable pnpm
pnpm --version

npx --yes @deepseek-ai/dsh@0.1.0-rc.6 plugin --profile web add @lexmount/dsh-browser@0.1.1
npx --yes @deepseek-ai/dsh@0.1.0-rc.6 web
```

If `corepack enable pnpm` reports an access error under
`C:\Program Files\nodejs`, run only the Corepack setup commands once from an
administrator PowerShell, close it, and run DSH itself as the normal user. If
port `3080` is already occupied, start DSH on an OS-assigned free port and open
the URL it prints:

```powershell
npx --yes @deepseek-ai/dsh@0.1.0-rc.6 web --port 0
```

### macOS Apple Silicon

This release supports Apple Silicon only. Confirm that the machine reports
`arm64`; `x86_64` means an Intel Mac and is not currently supported. In
Terminal, change to the directory that should become the DSH workspace, then
run:

```bash
uname -m
node --version
corepack --version
corepack install --global pnpm@11.22.0
corepack enable pnpm
pnpm --version

npx --yes @deepseek-ai/dsh@0.1.0-rc.6 plugin --profile web add @lexmount/dsh-browser@0.1.1
npx --yes @deepseek-ai/dsh@0.1.0-rc.6 web
```

If port `3080` is already occupied, use an OS-assigned free port and open the
printed URL:

```bash
npx --yes @deepseek-ai/dsh@0.1.0-rc.6 web --port 0
```

### Linux x64

Confirm that the machine reports `x86_64`, then run:

```bash
uname -m
node --version
corepack --version
corepack install --global pnpm@11.22.0
corepack enable pnpm
pnpm --version

npx --yes @deepseek-ai/dsh@0.1.0-rc.6 plugin --profile web add @lexmount/dsh-browser@0.1.1
npx --yes @deepseek-ai/dsh@0.1.0-rc.6 web
```

If port `3080` is already occupied, use an OS-assigned free port and open the
printed URL:

```bash
npx --yes @deepseek-ai/dsh@0.1.0-rc.6 web --port 0
```

DSH RC.6 delegates plugin installation to a `pnpm` executable on `PATH`; it does
not bundle that executable. If Corepack cannot create the shim, install pnpm
through the normal Node package-manager setup and verify `pnpm --version`
first.

If DSH was already running while the Bundle was installed or updated, stop and
restart it before testing. Package installation does not hot-load a new Bundle
into an existing Web process.

For unattended use, install the same Bundle into the Headless profile:

```bash
npx --yes @deepseek-ai/dsh@0.1.0-rc.6 plugin --profile headless add @lexmount/dsh-browser@0.1.1
```

The supported Harness range is `>=0.1.0-rc.6 <0.2.0`. DSH remains a release
candidate, so each DSH upgrade requires installation and tool-registration
regression testing.

## First use and cache

1. Run `lexmount_doctor`. The first call may download the current platform executable.
2. If credentials are missing, run `lexmount_auth_login` from the interactive Web profile and approve access in the system browser.
3. Create a temporary Session, or select/create a persistent Context when login state must be reused.
4. Navigate, inspect with `lexmount_browser_snapshot`, then use typed wait/click/fill tools.
5. Close temporary Sessions when finished.

Default cache locations are:

| Platform | Cache root |
| --- | --- |
| Windows | `%LOCALAPPDATA%\Lexmount\dsh-browser` |
| macOS | `~/Library/Caches/Lexmount/dsh-browser` |
| Linux | `$XDG_CACHE_HOME/lexmount/dsh-browser` or `~/.cache/lexmount/dsh-browser` |

Set `LEXMOUNT_BROWSER_CLI_CACHE_DIR` to choose another cache root. `LEXMOUNT_BROWSER_CLI_PATH` is an explicit administrator/developer override for a preinstalled CLI; that path is still checked for format and version, but its trust is controlled by whoever sets the environment variable.

The login flow stores credentials at the existing `browser-cli` location and never asks the user to paste an API key into chat. Headless runs must authenticate beforehand because the PKCE flow requires an interactive system browser.

## Tool surface

The Bundle registers 31 native tools:

- diagnostics and authentication: version, doctor, auth status/login/logout;
- Sessions: create/get/list/close/keepalive/targets;
- downloads: list/get/archive/delete;
- Contexts: create/get/list/fork/delete/force-release;
- browser actions: open URL, wait selector/text, click, fill, snapshot, screenshot, PDF;
- escape hatches: arbitrary page JavaScript and raw CDP.

Screenshot results are persisted through the DSH image attachment service. PDF and download tools write to the requested host path and return that path because DSH `0.1.0-rc.6` has no generic binary attachment content block.

## Security and behavior

- Downloads use a fixed HTTPS origin and version path. The matching `SHA256SUMS` entry, executable format, platform architecture, expected CLI version, and cache metadata are verified before execution.
- A cancelled first call cancels its download when no other call is waiting. Plugin disposal cancels downloads and terminates owned child processes.
- Model input is passed as a child-process argument array with `shell: false`; it is never concatenated into a shell command.
- API keys, Authorization fields, `ws`, and Chrome DevTools WebSocket URLs are removed from returned data and diagnostics.
- Tool guidance tells the model to obtain user confirmation before purchases, publication, destructive remote actions, and account/security changes.
- JavaScript evaluation and raw CDP remain model-visible for advanced browser automation.

DSH RC.6 does not expose MCP-style side-effect annotations on native tools. UI presentation categories are not permission enforcement.

## Known browser-cli limitations

The first release intentionally retains the existing browser-cli behavior:

- URL, form value, JavaScript, metadata, and raw CDP params are visible in local process argv;
- each action connects independently and selects the first page target;
- ordinary interaction is limited to wait, click, and fill; there is no ACE, hover, press, select, check, drag, or file upload;
- CDP commands do not have complete internal deadlines or reconnect/replay behavior;
- snapshot returns complete page text and HTML;
- credential writes and Windows ACL behavior are unchanged;
- Windows binaries are not Authenticode-signed in the first release;
- output paths are not restricted by an additional plugin sandbox.

## Development

```bash
npm install
npm run check
npm run package:verify
```

On a currently supported host, test a locally built v1.1.15 CLI without changing the package:

```bash
LEXMOUNT_BROWSER_CLI_PATH=/absolute/path/to/browser-cli npm run test:native
```

Verify the pinned remote assets, then run the real current-platform integration test on Windows x64, macOS Apple Silicon, or Linux x64:

```bash
npm run native:assets
npm run test:native
```

The `browser-cli-rs` repository owns native builds, macOS signing/notarization, checksums, and COS publication. This repository verifies those immutable inputs and publishes only the lightweight npm wrapper.