dsh-browser-agent

@try-works/dsh-browser-agent

A DeepSeek Harness (DSH) plugin that hands your agent a real, controllable
web browser — a shared Chrome page, a no-key search & fetch tier, a live
human-watchable pane, and a credential-isolated "Work Mode" for signing in and
filling forms without the agent ever seeing your username or password.

An agent running DSH gets 25 tools — 15 browser tools, 6 net/search tools,
and 4 Work-Mode tools — all driving one shared Chrome page that persists
across calls, plus a live pane docked inside the DSH Web GUI that streams
that page in real time and lets you take over with real mouse and keyboard
input.

What it is

This is a plugin bundle for DeepSeek Harness
(Cordis-composed). It mounts from a single composition row and splits into two
halves:

• Host half (Node process) — runs Chrome (via
  puppeteer-core), registers the
  25 tools, the packaged skills, and the pane's HTTP routes.
• Client half (browser bundle) — the pane UI, mounted into the Web GUI's
  shell.overlay slot.

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).

Why it matters

Agents that only read text struggle with the modern web: JavaScript-rendered
pages, login walls, bot-protection, forms, and anything needing a real browser
session. This plugin closes that gap by giving the agent a real Chrome with
all its capabilities, while keeping a human in the loop through the pane and a
security layer that isolates credentials. Chrome runs as a
separate OS process launched by the plugin, so a browser crash can never
take the harness down — the next call simply relaunches.

What it does

• A real, persistent browser — one shared Chrome with any number of tabs
  and one active. Navigate, read, click, type, wait, screenshot, inspect the
  accessibility tree, and manage tabs; the page stays put between calls.
• Search without keys — plain-HTTP search & fetch with an engine chain
  (DuckDuckGo Lite → Brave HTML → Mojeek, automatic fallback) plus Reddit
  access. No Chrome, no API key, no JS rendering — the cheapest research route.
• A live pane for humans — a right-docked, collapsible, resizable window in
  the DSH Web GUI that streams the shared page via CDP screencast and takes
  your real mouse/keyboard input. Watch the agent browse and take over any
  time.
• Work Mode — credential-isolated web automation: a risky-click approval
  gate, a secret firewall, supervised login, and an encrypted session vault
  (see below).
• Bot-wall friendly — three launch modes: headless (your own), stealth
  (our own headed Chrome, no automation fingerprint), and My Chrome
  (connect to a Chrome you launched, adopting its real logins and identity —
  the mode that clears Cloudflare Turnstile).
• URL normalization — tools and the address bar accept URLs, hostnames,
  localhost:port, local file paths, or plain search text.

Use cases

• Research that needs a real page — read a JS-rendered article, pull
  structured data, compare listings, or scrape an API behind a browser session.
  Start with the no-key net tools; fall back to the browser when a wall appears.
• Test and verify your own web apps — drive a running frontend: navigate,
  fill forms, click, wait for async content, and browser_screenshot the result
  to confirm a render or layout. The live pane lets you and the agent watch the
  same page.
• Sign in on your behalf — without sharing your password — the
  work_login_* flow lets you type credentials into the pane while the agent
  is locked out, then seals only the session cookies into an encrypted vault.
  The agent can restore the session later, never having seen the password.
• Transactional web workflows — booking appointments (DMV, doctor,
  dentist), filing insurance claims, filling multi-field government or vendor
  forms. The risky-click gate pauses before consequential submits so you
  approve them yourself.
• Checking a site behind login — your subscription, dashboard, or inbox
  (Gmail, GitHub, a SaaS console). Sign in once via the pane; the vault keeps
  the session, work_vault_status lists it without exposing values, and the
  agent can re-open it.

The tools at a glance

All 25 tools, grouped:

• Browser (15): browser_goto, browser_evaluate, browser_screenshot,
  browser_click, browser_type, browser_read, browser_wait,
  browser_back, browser_forward, browser_reload, browser_a11y,
  browser_tabs, browser_tab_open, browser_tab_switch, browser_tab_close.
• Net / search (6): browser_fetch, browser_search,
  browser_search_github, browser_search_wikipedia, browser_reddit_search,
  browser_reddit_thread.
• Work Mode (4): work_login_begin, work_login_cancel,
  work_login_status, work_vault_status.

Each is documented in full in the sections below.

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

Field	Default	Purpose
chromePath	system Chrome on Windows	Absolute path to a Chrome/Chromium executable.
viewport	1920 × 1080	Default viewport for new pages (and the headed window size).
navTimeoutMs	45000	page.goto navigation timeout.
scriptTimeoutMs	20000	page.setDefaultTimeout (script/evaluate timeout).
timeoutMs	60000	Per-tool execution timeout.
headed	false	Launch a visible Chrome window instead of headless. The window is the same shared page the pane shows — two views of one browser. Needs a desktop session.
pane	true	Serve the browser pane in the Web GUI. Headless/TUI compositions have no web server, so the pane never mounts there regardless.
userDataDir	'' (temp profile)	Chrome profile directory. Empty = a fresh temporary profile per launch. Set an absolute path to persist cookies, logins, and storage across launches (note: session cookies without an expiry are still session-only).
connectUrl	'' (disabled)	CDP browser URL for My Chrome mode. When set, the pane's mode toggle can connect to a Chrome you launched with chrome.exe --remote-debugging-port=9222 --user-data-dir=<non-default dir>, adopting its real tabs, logins, and fingerprint — the mode that passes bot-protection walls (e.g. Cloudflare Turnstile). Launch flags are ignored in connect mode.
stealth	false	Stealth plugin mode: launch our own Chrome without --enable-automation (so navigator.webdriver is false), headed, AutomationControlled disabled, persistent profile. Much better odds against bot walls than plain puppeteer, though not your personal fingerprint — for the sure thing use My Chrome mode.
searchEngines	'ddg,brave,mojeek'	Engine chain for the net search tools, tried in order: ddg (DuckDuckGo Lite), brave (Brave HTML), and mojeek (Mojeek — most tolerant of datacenter IPs).
siteSearchIntervalMs	3000	Minimum delay between consecutive net searches (rate-limit politeness; applies to every search, not only site-filtered).
fallbackOnEmpty	true	Continue with the next engine when one returns no results.
fetchTimeoutMs	15000	Per-request timeout for the net tools (fetch/search/reddit).

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 → Mojeek 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.

Tool	What it does
browser_fetch	Fetch a URL as readable text over plain HTTP: {url, finalUrl, status, text, truncated, links}.
browser_search	Search the web: ranked {title, snippet, domain, url} rows plus an instant answer when the engine has one. site: "github" | "wikipedia" | <domain>, engine: "auto" | "ddg" | "brave", maxResults.
browser_search_github	browser_search restricted to github.com — repos, issues, discussions.
browser_search_wikipedia	browser_search restricted to en.wikipedia.org.
browser_reddit_search	Reddit post search (old.reddit HTML first, the public JSON search as fallback): title, subreddit, author, score, comments, permalink.
browser_reddit_thread	A Reddit thread via its public .json endpoint: post fields plus the top comments.

The browser tools

Tool	What it does
browser_goto	Navigate the shared page and return {url, finalUrl, status, title, text, links} — up to 6000 chars of extracted heading/paragraph/list text and 25 links.
browser_evaluate	Run a JavaScript expression in page context (document, window, DOM available) and return the JSON-serializable result.
browser_screenshot	Capture the current page as a PNG/JPEG data URL ({dataUrl, mime, bytes}); fullPage for the whole page height.
browser_click	Click the first element matching a CSS selector; returns the clicked tag/text or ok: false with a message.
browser_type	Type text into an input/textarea/select with real key events (React-safe); returns the field value.
browser_read	Inner text of a selector (default: whole body), up to 6000 chars, with the match count.
browser_wait	Wait until a selector appears (async content done), then return its text.
browser_back / browser_forward / browser_reload	History navigation of the active tab.
browser_a11y	Compact accessibility tree (role/name/value, up to 400 nodes) — what screen readers consume.
browser_tabs	List tabs (index, url, title, active); the other tools act on the active tab.
browser_tab_open / browser_tab_switch / browser_tab_close	Manage tabs; popups and target=_blank links open as new tabs.

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 (from a compact ~10 % up
to ~80 % 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.

Route	Purpose
GET /browser-pane/stream	SSE frame + state feed (frame / state events).
POST /browser-pane/input	Synthetic input: {type: mouse-move | mouse-down | mouse-up | wheel | key-down | key-up, …}.
POST /browser-pane/goto	Navigate: {url}.
POST /browser-pane/mode	Switch browser mode: {mode: 'own' | 'connect'}.

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 tools register on the host tools registry; the 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 eight 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):

Skill	Teaches the agent
browser-search	Finding and reading web sources across both tiers — the net tools first (cheapest), then web_search, then the browser tools — with route triage and a full runbook (references/search-engine-access-guide.md — net-engine walls (DDG burst throttle, Brave 429, Mojeek reliability), SearXNG fallback, the Reddit 403 browser-tier path, Wayback Machine, site search, and API routes).
browser-navigation	Moving around the shared page: URL forms (URLs, hostnames, localhost ports, file paths, search text), reading the browser_goto summary, redirects/statuses/timeouts, and the single shared-page model.
browser-interaction	DOM automation through browser_evaluate: reading state, clicking, typing, form filling, scrolling, waiting for async content, JSON-safe results, and batching reads into one evaluate.
browser-visual-check	Verifying renders with browser_screenshot (viewport/full page, PNG/JPEG) and keeping the shared page presentable for the human watching the live pane.
browser-multitab	Working with several pages at once: tab tools, which tab the other tools act on, popups-as-tabs, and tab discipline.
work-login	The supervised-login flow (sign in without the model seeing credentials): work_login_begin/cancel/status, the pane Sign-in banner, Seal/Abort, and the session vault.
work-appointment	Transactional booking workflows (DMV, doctor, insurance): find the form, fill it, let the risky-click gate handle the consequential submit.
work-forms	Form-filling mechanics and the Work Mode rules: never type a password, never invent personal data, submits ask.

Work Mode

Credential-isolated web automation at ChatGPT Work parity. When enabled
(workMode.enabled: true), four layers keep credentials and consequential
actions out of the model's hands:

1. Risky-click gate (tools/pre-execute) — a click on a form submit,
   a send/delete/cancel verb, or a dollar-amount button is intercepted before
   dispatch and routed through the approval stack. No approval channel = the
   click is denied (fail closed).
2. Secret firewall (tools/post-execute) — document.cookie, JWTs,
   bearer tokens, password=/token= assignments, and Set-Cookie lines in
   browser_evaluate/browser_read/browser_fetch results are redacted to
   [redacted] before the model sees them.
3. Supervised login — work_login_begin (or the pane Sign in button)
   suspends every browser_* tool while the user types credentials directly
   into the live pane (synthetic CDP input — values never enter the model
   context). Seal captures the session cookies; Abort discards.
4. Session vault — sealed sessions persist AES-256-GCM encrypted in
   ~/.dsh/vault (vault.key 0600 + sessions.vault). work_vault_status
   lists origins + cookie names only; restore/revoke are pane routes.

Configuration

- id: dsh-browser-agent
  config:
    workMode:
      enabled: true            # default false
      approveSubmit: true      # ask before form-submit clicks
      approveSend: true        # ask before send-like clicks
      approveAmountsUsd: true  # ask before dollar-amount clicks
      allowlist: []            # hostnames that never ask
    vaultDir: ''               # empty = ~/.dsh/vault

The model's tools

• work_login_begin / work_login_cancel / work_login_status — drive and
  inspect the supervised-login flow (never the credentials).
• work_vault_status — list sealed sessions (origins + cookie names only).

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 tests: net, gates, firewall, login-mode, vault

The tiers are TDD'd: test/net.test.ts runs offline against committed
fixtures in test/fixtures/, test/gates.test.ts / test/firewall.test.ts /
test/login-mode.test.ts / test/vault.test.ts exercise the Work Mode pure
cores, 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.

Publishing

pwsh scripts/publish.ps1 -CheckOnly   # verify the npm token without publishing
pwsh scripts/publish.ps1              # build + publish the current version

The script reads a transient npm automation token (publish access to
@try-works) from the token file, writes it to a local .npmrc for the
duration of the command, and deletes it in finally — the token is never
stored in this repo. After a successful publish, move the profile off the
link: install:

dsh plugin --profile web add @try-works/dsh-browser-agent

License

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