dsh-cua-preview
English | 中文
A DeepSeek Harness plugin that drives a browser, with
every navigating or acting call gated by a DSH approval — and with the current screen captured as a
screenshot the user reviews before the action runs.
The approval architecture follows ZCode's cua-permission-broker as a design borrowing; no ZCode source
is copied.
What it does
| Tool | Approval | Returns |
|---|
browser_navigate | yes | the loaded page, after navigation |
browser_act (click / fill / submit) | yes | the page after the action |
browser_snapshot | no | the current URL, title and visible text |
browser_screenshot | no | the current screen as an image |
The read-only pair never raises an approval, because neither can change the page. The gated pair asks
first, in one line of the UI's own language, and does nothing at all unless the answer is "allow once".
Install
Requirements: Node ≥ 22.12 (this is what puppeteer-core requires) and a Chrome or Chromium
executable. Nothing is downloaded at install time — the plugin drives the Chrome you already have, and
reports an actionable error instead of silently fetching one.
A DSH plugin is installed into a profile with dsh plugin, which forwards its arguments to the
package manager in that profile's directory:
# By name
dsh plugin --profile demo add dsh-cua-preview
# From a checkout
dsh plugin --profile demo add ./dsh-cua-preview
dsh --profile demo --dump-config # the layer appears as "# == dsh-cua-preview"
dsh --profile demo # boot
The package is a DSH bundle — it ships a configuration layer, and a profile is what boots it. To
attach it to an existing profile without a reinstall, use an overlay instead, which is also what the
tests do:
- insert:
- id: cua-preview
name: 'dsh-cua-preview'
config:
artifactsDir: '/tmp/cua-artifacts' # optional
headless: true # optional, default true
chromePath: '/usr/bin/google-chrome-stable' # optional, auto-detected
Configuration
| Key | Default | Meaning |
|---|
artifactsDir | $DSH_HOME/cua-preview/artifacts | where screenshot evidence PNGs are written |
headless | true | run Chrome headless |
chromePath | auto-detected | explicit Chrome/Chromium executable |
Chrome is looked up through $DSH_CUA_CHROME_PATH and the usual Linux install paths
(/usr/bin/google-chrome-stable, /usr/bin/google-chrome, /usr/bin/chromium,
/usr/bin/chromium-browser, /snap/bin/chromium), and is launched with the standard
container-safe flags.
The browser library choice: Puppeteer
The task allowed Puppeteer or Playwright. Puppeteer was chosen, and specifically puppeteer-core:
puppeteer-core downloads nothing — no ~150 MB browser fetch at install time, and no version
guess about which Chromium to pair with which library release.- It drives the Chrome that is already on the machine, so what the user reviews is the same browser
they could open themselves.
- The plugin's whole dependency on it is one module,
src/browser.js; swapping to another library
would change that file and nothing else.
The screenshot model, in one paragraph
The approval happens before the action, so two frames exist and each is named for what it is. The
post-action frame is what the model receives as its result image, because a model that reads a
pre-action frame as "the result" concludes the action failed. The approval-time frame is what the
user is shown while deciding; it is carried on a log-only session event of the plugin's own, read by the
Client half, and painted in the same row as the result — so during a pending approval the picture is
already on screen. result.meta keeps the audit pointer without being painted. On a refusal there is
no post-action state, so the one image returned is the approval-time frame. A screen that is genuinely
blank (an unloaded, empty tab) emits no frame at all rather than a useless white rectangle.
docs/design.md explains the mechanisms, and why the frame cannot travel inside the
approval request.
What the model is told when the user says no
A refusal is a successful tool result, not an error — an error reads as "the call failed, try
again", and an error is exactly what once caused a model to retry an action the user had just rejected.
The notice leads with the shipped gating path's own sentence, quoted verbatim in both languages, and
adds what that sentence does not say: that this is a human decision rather than a failure, and that the
expected next move is to stop and ask.
browser_act 未执行：用户在审批中拒绝了这次操作。
the user rejected tool "browser_act" —— 这是人的决定，不是调用失败、页面问题，也不是本插件故障。
操作没有执行，页面保持原样。不要重试这个动作或等价动作；请停下来询问用户要改什么、或者下一步做什么。
The three non-granting outcomes are worded differently, so the model can tell a human "no" from an
absent channel: rejected and cancelled are described as the user's decision, while unavailable
states explicitly that it was not. The same rule is in the gated tools' descriptions, so it reaches
the model before it acts rather than only afterwards.
Repeat prompting is not suppressed: the plugin does not police the model's retries, and a user who
changes their mind can still approve a later attempt. Suppressing an identical repeat would end the
popup loop mechanically, but it can also block a user who has since said "go ahead", and a tool
execution carries no turn identity with which to scope the suppression to one model turn.
Tests
From a source checkout (the test entries are development-only and are not part of the published
package, so they are absent after npm install dsh-cua-preview):
npm install
npm test
Three entries, aimed at three different layers:
| Entry | Layer | Needs | Checks |
|---|
npm run test:client | the Client half, in isolation | Node only | 79 |
npm run test:acceptance | the Host half, against the real DSH services | Chrome | 107 |
npm run test:real-load | both halves, inside a real dsh process | a dsh CLI + Chrome | 18 |
That is 204 checks, 0 failures — all three entries need npm install first. The last entry boots the
shipped dsh binary with the plugin patched in on an OS-assigned free port — so it cannot collide with
any profile you have running — and runs a probe plugin inside that process which reads the live
registries. It reports clearly and exits non-zero if no dsh CLI is available.
CI runs the Client-bundle verifier and the packaging check on every push, because both are reproducible
without a browser. The browser suites are not part of that gate — they need a Chrome executable and,
for the last entry, a dsh CLI — so they are exposed as a manually triggered job instead.
Local test page
examples/test-page/ is a small page with a field, a button and a form, used by the acceptance checks
and handy for trying the plugin by hand:
node examples/test-page/serve.mjs --port 3097 --host 127.0.0.1
Documentation
| Document | Contents |
|---|
| docs/design.md | how it works and why: the two frames, the image channels, the hidden carrier node, the slots this plugin refuses to touch, the locale and refusal rules |
| CHANGELOG.md | what changed |
License
MIT. This is an unofficial community work, not affiliated with, authorized, sponsored or
endorsed by Z.AI Co., Ltd or DeepSeek. "ZCode" and "DeepSeek Harness" are the trademarks of their
respective owners and are used here only to describe where a design came from and what this plugin
runs on.
