@try-works/dsh-browser-agent

A DeepSeek Harness (DSH) bundle that gives agents a real Chrome browser, a no-key net search tier, and a live window onto the browsing. One shared page, fifteen browser tools, six net tools, and a collapsible browser pane docked inside the DSH Web GUI that streams that page and takes real mouse/keyboard input.

It is a fork of zenbu-labs/terminal-browser with the terminal UI replaced by a DSH tool surface and a web pane — the same idea (pixels out, synthetic input in), built on the harness's own plugin, module, and slot systems. The net search tier ports the no-key engine chain of dabito/pi-lynx (MIT).

What this plugin is and does

• Six net tools for agents — browser_fetch, browser_search, browser_search_github, browser_search_wikipedia, browser_reddit_search, browser_reddit_thread — no-key, plain-HTTP search and fetch (DuckDuckGo Lite → Brave HTML chain with automatic fallback, plus Reddit access). The cheapest routes for research; degrade to the browser tools when a wall appears.
• Fifteen browser tools — navigation, structured DOM interaction, history, capture, accessibility, and tabs — all driving one shared Chrome page that persists across calls, so an agent can navigate, read, interact, and capture.
• A live pane for humans — a right-docked, collapsible, resizable panel in the DSH Web GUI showing that same page in real time. You can watch the agent browse and take over yourself: click, drag, scroll, type, or use the address bar. Everything lands in the page through the Chrome DevTools Protocol.
• Five packaged skills — bundled guidance (plus a search runbook) that teaches agents how to find web sources, navigate, automate pages, verify renders, and manage tabs through the tools.
• URL normalization — tools and address bar accept URLs, hostnames, localhost:port, existing local file paths, or plain search text.

Chrome runs as a separate OS process launched by the plugin (puppeteer-core), so a browser crash can never take the harness down — the next call simply relaunches.

Install

Prerequisites: a DSH deployment with a profile (the Web surface is needed for the pane; the tools work on any surface).

# install from the npm registry into a profile (the DSH CLI forwards to pnpm
# in the profile directory, then reconciles the profile's plugin bundles)
dsh plugin --profile web add @try-works/dsh-browser-agent

The plugin's own bundle patch mounts the row automatically — no manual composition edit is needed. Then restart dsh web and hard-refresh the GUI tab (Ctrl+F5) so the client pane bundle is fetched. The three browser_* tools appear in the agent's tool set, and the pane docks on the right edge of the GUI.

Fresh releases and the supply-chain policy — DSH profiles enable pnpm's minimumReleaseAge check. A version published less than 24 hours ago is rejected unless it is listed in the profile's pnpm-workspace.yaml:

minimumReleaseAgeExclude:
  - '@try-works/dsh-browser-agent@0.2.0||0.2.1'

One rule per package name — multiple versions go in a single || union on the same line; separate lines for the same package shadow each other and only the first applies.

Local development

dsh plugin --profile web add link:D:/path/to/dsh-browser-agent

Configuration

All fields are optional (schemastery defaults fill them). Override via the profile's cordis.patch.yml:

- id: dsh-browser-agent
  config:
    chromePath: 'C:\Program Files\Google\Chrome\Application\chrome.exe'
    viewport: { width: 1920, height: 1080 }
    navTimeoutMs: 45000
    scriptTimeoutMs: 20000
    timeoutMs: 60000
    headed: false
    pane: true

The net tools (no-key search & fetch)

The net tier is a port of the pi-lynx engine chain (browser_search = DuckDuckGo Lite → Brave HTML with automatic fallback), plus a plain-HTTP page fetch and Reddit access — no Chrome, no API key, no JS rendering. These are the cheapest routes for research; the browser-search skill's triage puts them first and degrades to the browser tools when a datacenter IP gets throttled.

The browser tools

The page is shared and persistent: browser_goto to a site, browser_evaluate to interact with its DOM, browser_screenshot to see it — all the same tab.

URL handling

browser_goto and the pane's address bar accept (matching the terminal-browser reference semantics):

• full URLs (https://…, data:, mailto:, about:, view-source:, …)
• host-like input (example.com/docs, localhost:5173 — http:// for localhost/127.0.0.1, https:// otherwise)
• existing absolute or ~-expanded local paths (opened as file://)
• anything else → a Google search

The browser pane

Expanded, the pane docks full-height on the right edge (like a mirrored sidebar); collapsed, it shrinks to a thin vertical rail with a toggle. Its left edge is a drag handle — drag to resize (320 px to 85 % of the window), the width persists across reloads, and the whole GUI reflows around it. The header carries back / forward / reload buttons next to the address bar, and the tab strip ends with a browser-mode toggle.

Browser modes

The Plugin / My Chrome toggle in the tab strip switches which browser the agent drives — live, at any time:

• Plugin — the instance this plugin launches (headless by default, with the configured viewport/profile).
• My Chrome — a Chrome you launched yourself with debugging enabled, connected over CDP. Chrome only opens the debug port on a non-default profile, so launch it with a dedicated profile directory (e.g. the desktop shortcut: chrome.exe --remote-debugging-port=9222 --user-data-dir=C:\Users\you\.dsh\chrome-debug-profile), set connectUrl, and toggle to My Chrome. Log in once inside that Chrome — logins persist there — and it runs alongside your normal Chrome. Because the plugin never touches its identity (no automation flags, no UA/viewport changes), bot-protection walls such as Cloudflare Turnstile see a real session. Switching back only detaches; your Chrome and its tabs are never closed by the plugin. (Profiles cannot be copied between directories: Chrome's App-Bound Encryption drops cookies moved to a different profile path — the dedicated profile is the one to log into.)

The pane is a real two-way remote:

• Frames out — the pane subscribes to GET /browser-pane/stream (SSE). The host half drives Chrome's Page.startScreencast (JPEG frames on visual change only — no screenshot polling) and pushes each frame with the page URL. The screencast follows its subscribers: the first client starts it, the last one stops it, and late subscribers get the current state and last frame replayed immediately.
• Input in — pointer and keyboard events post to /browser-pane/input and land in the page through the CDP Input domain (Input.dispatchMouseEvent / Input.dispatchKeyEvent). Fidelity matches the terminal-browser reference: double/triple-click counting, modifier bitmasks (Shift/Ctrl/Cmd/Alt on mouse and keys), fractional wheel accumulation with line-mode detent scaling, held-key release on focus loss, and focus emulation while the pane owns the page.
• Address bar — POST /browser-pane/goto navigates the shared page.

How it works

One package, two halves, both mounted from a single composition row:

Host half (Node process) — runs the browser, the tools, the skill, and the pane server:

• A BrowserRuntime owns one lazily launched Chrome and a tab session: any number of tabs, one active. On a crash or disconnect the cached handles are cleared and the next call relaunches.
• All fifteen tools register on the host tools registry; the five packaged skills register on skills, each with its bundled skills/<name>/ directory as its resource base.
• The pane server registers the three routes above on the shared web server (ctx.webServer), only when one exists. Request bodies are parsed by schemastery schemas at the route boundary.
• Tabs: popups and target=_blank links open as new tabs (the terminal-browser tabs-as-popups model) and the pane's tab strip mirrors the session, so the pane, the tools, and any headed window never disagree about which page is live. Blank targets are never closed (a page under creation is blank too); foreign targets are adopted once they carry a real URL.
• Background throttling is disabled so frames keep flowing when Chrome is occluded.

Client half (browser bundle) — the pane UI:

• package.json declares dsh.client (platform: "web"), and the built bundle is exported at exports["./client"]. The DSH client-modules host scans enabled entries for dsh.client packages, serves the bundle at /plugins/@try-works/dsh-browser-agent/client.js, and the client kernel adopts it as a cordis plugin — no extra composition row required.
• The pane registers into the frame-wide shell.overlay slot declared by the GUI layout, docked to the right edge. The bundle is written with React.createElement (no JSX); react itself is a shell-seeded platform module, so the bundle carries no framework bytes.

Lifecycle — registration is wrapped in a ctx.effect generator (the dsh-recursive-mode pattern): unloading the plugin unregisters the tools and skill, tears down the pane routes and the screencast, releases held keys, and closes Chrome.

The bundled skills

The bundle registers five packaged skills on ctx.skills (the dsh-plugin packaged-skill standard: each skills/<name>/SKILL.md ships in the package and registers with a directory resourceBase, so relative references resolve against the bundle's copy):

Development

pnpm install     # links the type-only harness devDependencies
pnpm build       # tsc declarations + tsdown: lib/index.js (host) and lib/client.js (client)
pnpm typecheck   # tsc --noEmit
pnpm test        # offline parser/runtime tests (node --import tsx --test test/net.test.ts)

The net tier is TDD'd: test/net.test.ts runs offline against committed fixtures in test/fixtures/, and test/net.live.test.ts exercises the real engines when opted in ($env:DSH_BROWSER_LIVE = '1'; node --import tsx --test test/net.live.test.ts in PowerShell). The live suite tolerates the documented walls — DDG Lite throttling and Reddit 403s from datacenter IPs are accepted as environment states, not failures; the parsers are proven by the offline fixtures.

prepublishOnly runs pnpm build, so npm publish always ships fresh artifacts.

License

ISC — see LICENSE. This package derives from zenbu-labs/terminal-browser (ISC); see NOTICE.