Introduction

When performing browser automation, the common practice is to let the Agent run in a headless process invisible to the user. The problem is: users have no way to confirm what happened on the page or where the Agent clicked; there is also no natural handoff mechanism when encountering steps requiring login or manual judgment.

dsh-browser-plus targets this problem. It keeps the browser window in front of the user while providing the Agent with reliable CDP operation capabilities. Users can operate directly on the real page, and the Agent can execute, take over, and resume tasks synchronously.

Overview

dsh-browser-plus is an EGO-style visual Agent browser plugin built specifically for DeepSeek Harness (DSH). It is continuously developed and independently maintained by ParticleLight based on the MIT-licensed dsh-browser codebase. The current version is 0.4.1. It is a real Electron visual window, not a headless relay. It supports parallel management and switching of multiple task flows and fully records the Agent’s operation trajectory.

Core Features

Real Visible Window

The browser is rendered based on Electron’s WebContentsView, allowing users to see the page the Agent is operating on directly. Input, clicking, and scrolling all happen on the real page.

Task Isolation and Glass Workspace

All DSH sessions share one visible window, but each retains isolated task views, tabs, and history; browser_space can be used to name browser tasks. Tasks and operation trajectories are independent semi-transparent glass panels that can be opened simultaneously. Each task displays a status of Running, Waiting for User, User Takeover, Failed, or Idle. Thumbnails are refreshed on demand for the currently visible task only when the task panel is open; background tasks retain their last image.

Page chrome and the task manager are injected via closed Shadow DOM, not relying on a second Electron view. Task status and trajectories are synchronized via versioned incremental messages. Background tasks update their own isolated views without stealing the user’s currently visible page.

Human-Machine Collaboration and Handoff

The toolbar is hidden by default above the page and expands upon hovering in the middle of the top. Users can take over tasks from the far right of the toolbar, or explicitly return tasks to the Agent to complete handoff in conjunction with browser_handoff.

Real Input and Toolset

Keyboard, mouse, hover, double-click, and file selection all go through CDP, not the element.click() pseudo-event. The browser_* tools provided by the plugin are grouped by scenario:

Scenario Tool
Open and Read browser_open、browser_snapshot、browser_content、browser_screenshot
Semantic Navigation browser_back、browser_forward、browser_reload、browser_stop、browser_scroll
Snapshot Reference browser_click_ref、browser_scroll_into_view
Page Interaction browser_click、browser_press_key、browser_double_click、browser_hover、browser_type
Forms and Files browser_fill、browser_upload_file、browser_wait_for
Tasks and Handoff browser_tasks、browser_handoff、browser_list_tabs、browser_switch_tab、browser_close_tab、browser_space
Login and Recovery browser_auth、browser_reset_session、browser_history

Recoverability and Stable Baseline

After child recovery, views for the same session are re-materialized. The first screenshot after recovery waits for the compositor to stabilize. Electron version is fixed at 42.9.3; compositor issues in 43.4.1 are rejected by the resolver to avoid introducing known problems. Reliability rules include: not reparenting visible WebContentsView, CDP capture fallback only temporarily handles siblings of the same window and guarantees recovery; dialogs, screenshots, dynamic waiting, and child recovery all have regression tests and real SOAK coverage.

Installation and Activation

Use the official installation command:

dsh plugin --profile web add github:ParticleLight/dsh-browser-plus

If a browser bundle already exists on the machine, read the migration guide docs/MIGRATION.md in the repository first, then restart DSH Web to complete enabling.

Environment requirements: Node >= 22.19. The plugin fixes Electron at 42.9.3, and peerDependencies includes @deepseek-ai/cordis ^4.0.1.

Typical Usage

Snapshot and Reference Operations

Snapshots return short-lived snapshotId and element references. The recommended operation order is as follows:

  1. Open the page with browser_open;
  2. Get the snapshot and element references with browser_snapshot;
  3. Prioritize operating on the references using browser_click_ref or browser_scroll_into_view;
  4. Re-snapshot after the page changes, then continue operations.

Page-level scripts automatically filter out the browser’s own chrome and will not mistakenly operate on the plugin-injected toolbar.

Dialog Handling

alert、confirm、and prompt are automatically accepted to avoid page freezing; the next page operation will record details in the dialog entry of browser_history, allowing both the Agent and the user to trace back.

Workflow Chain

The call chain from tools to window is as follows:

browser_* tools
  -> BrowserRuntime (ctx.browser seam)
  -> ElectronBrowserProvider (CDP)
  -> RemoteElectronViewHost (loopback JSON-RPC)
  -> host-main.js (BrowserWindow + WebContentsView)

Development and Verification

When participating in development, build and verify using the following steps:

npm install
npm run build
npm test
npm run smoke:electron-host

npm run smoke:electron-host requires the local DSH Web to be started and is used to verify navigation and page handoff of the real Electron Host. See docs/SOAK-CHECKLIST.md for the complete runtime checklist, CONTRIBUTING.md for contribution methods, and docs/README.md for more comprehensive usage instructions.

Use Cases and Considerations

Suitable for scenarios where web operations are needed in DSH, but visibility and manual intervention are desired throughout the process, such as page tasks requiring login state, parallel browsing of multiple task flows, and workflows where users and Agents operate the page alternately.

Please note before installation:

  1. The plugin runs with the permissions of the current dsh process; it is recommended to check the repository source code before installing;
  2. The license is MIT, see LICENSE and NOTICE.md in the repository for details;
  3. If migrating from an old browser bundle, be sure to read docs/MIGRATION.md first.

Summary

dsh-browser-plus solves three problems in Agent browser automation: “invisible, uncontrollable, and difficult to recover after disconnection”: a real visible Electron window, task isolation and explicit handoff, and session recovery after child recycling. Installation and verification can be completed by following the steps above. For more details, see the plugin directory page and GitHub repository:

  • Directory Page: https://www.skillhub.cn/plugins/ParticleLight/dsh-browser-plus
  • GitHub: https://github.com/ParticleLight/dsh-browser-plus