Build a CDP Plugin for Webpage Debugging: Inside the DSH Plugin System

A build log for dsh-plugin-browser-cdp: how a plugin package is put together, how a DevTools connection is driven without a browser-automation dependency, and what it takes to turn a browser into something an agent can debug a page with.

The gap an agent cannot cross

Ask a coding agent to fix a page and it will read the source, find the component, and produce a patch that is syntactically perfect and occasionally wrong. It cannot see that the dropdown is covered by a sticky header, that the button rendered at zero height because a flex parent collapsed, that the click handler never fired because an overlay swallowed the event, or that the API call returned 200 with an error body. Source code describes intent. The rendered page describes what happened.

Removing that gap means giving the agent a browser. Not a headless engine behind a proxy object, and not a screenshot it has to interpret — an actual browser it can query, click, and point at. That is what dsh-plugin-browser-cdp is: a DSH plugin that drives a real, visible Chrome over the Chrome DevTools Protocol, and whose headline capability is the one thing a screenshot cannot give you, a precise, reusable reference to an element the human just pointed at.

Everything below is drawn from the plugin’s own source, because the interesting parts of a browser plugin are not the happy path. They are the failure modes: the profile lock that makes a launch silently futile, the scroll position Chrome restores for a reload but not for a protocol-driven navigation, the shadow root that querySelectorAll cannot reach, and the import that works in your editor and fails in the profile.

What the plugin exposes

Thirteen tools, grouped by the intent behind them rather than by the CDP domain they happen to use. The grouping matters: an agent choosing a tool is answering “what am I trying to learn”, not “which protocol method do I want”.

The pick flow is the part worth reading twice, because it is the only one where the human is the sensor. The agent arms the picker; the user hovers and clicks in a browser they can see; what comes back is not a screenshot but a reference:

Picked element reference
page: https://example.com/pricing
ref: p1
selector: #plan-toggle
xpath: /html/body[1]/main[1]/section[2]/button[1]
tag: button  role=button  name="Compare plans"
text: "Compare plans"

The ref is what every action tool accepts. The selector and XPath are for the human, who will paste them into DevTools or a test. And note what is not in that block: no coordinates, which would go stale on the next layout change; no screenshot, which the agent would have to interpret; no DOM dump, which would blow the context window on a real page.

One package, two halves

The DSH plugin system’s central design decision is that a plugin is a single npm package that may contribute to both sides of the application at once: the Node process where the agent runs, and the browser where the user types. Those are different runtimes with different module systems, and the plugin system does not pretend otherwise — it just lets one package own both.

The client half is declared in package.json, and that single block is the whole registration story — the shell serves the bundle, and the listed packages are what it is allowed to import at runtime:

{
  "name": "dsh-plugin-browser-cdp",
  "main": "lib/index.js",
  "exports": {
    ".": { "default": "./lib/index.js" },
    "./client": { "default": "./lib/client.js" }
  },
  "dsh": {
    "client": {
      "platform": "web",
      "inject": [
        "@deepseek-ai/dsh-client-runtime",
        "@deepseek-ai/dsh-client-connection",
        "@deepseek-ai/dsh-client-ui-conversation"
      ]
    }
  }
}

Installing it is two steps: link the package where the profile resolves bare plugin names, and add one entry to the profile’s patch layer.

# 1. Link the package into the profile's module tree.
ln -s /path/to/dsh-plugin-browser-cdp \
      ~/.dsh/profiles/node_modules/dsh-plugin-browser-cdp

# 2. Add to ~/.dsh/profiles/web/cordis.patch.yml
- insert:
    - id: browser-cdp
      name: dsh-plugin-browser-cdp

Two operational details are worth knowing before you plan a debugging session around it. Editing the patch entry is picked up live by the profile’s patch-layer watcher, so enabling the plugin needs no restart. Editing the plugin’s own files is not watched — they live outside the profile and the module is already in Node’s ESM cache, so a source change needs a restart. Restarting closes the DevTools socket but leaves Chrome and its profile running, so your tabs and logins survive it.

Why CDP and not Playwright

This is the decision that shapes everything else, and it was made against constraints rather than preferences: what the plugin is allowed to install into a profile, and what it must be able to do that a normal automation library cannot.

Playwright’s usual advantages — auto-waiting, resilient locators, a rich test API — are real, and if you are writing a test suite you should probably use it. But they solve a different problem. A test needs to assert things a developer already knows how to name. An agent needs to discover what is on the page and then refer to it reliably, which is a reference problem, not a locating problem. So the plugin replaces Playwright’s locator strategy with something better suited to it: a ref table backed by real DOM node handles, plus generated unique selectors and XPaths for the human.

Anatomy of a CDP client

The protocol is simpler than its reputation, provided you use it the way it is meant to be used: one browser-level socket, with every page multiplexed over it as a flattened session.

The dispatch layer is the part people expect to be hard and is not. One incrementing id, one pending map, one listener set — and the one thing that is easy to get wrong, which is what happens to in-flight commands when the socket goes away:

#nextId = 0
#pending = new Map()   // id -> { resolve, reject, timer }

/** Send one protocol command and await its reply. */
send(method, params = {}, sessionId) {
  if (!this.connected) throw new CdpDisconnectedError(this.closeReason ?? undefined)

  const id = ++this.#nextId
  const message = { id, method, params }
  // Session-scoped commands carry the sessionId; browser-level ones omit it.
  if (sessionId !== undefined) message.sessionId = sessionId

  return new Promise((resolve, reject) => {
    const timer = setTimeout(() => {
      this.#pending.delete(id)
      reject(new CdpError('timed out', -1, method))
    }, COMMAND_TIMEOUT_MS)

    this.#pending.set(id, { resolve, reject, timer })
    this.#ws.send(JSON.stringify(message))
  })
}

/** Replies, protocol errors and events all arrive on the same socket. */
#onMessage(text) {
  const message = JSON.parse(text)

  if (typeof message.id === 'number') {
    const entry = this.#pending.get(message.id)
    if (entry === undefined) return
    this.#pending.delete(message.id)
    clearTimeout(entry.timer)
    if (message.error !== undefined) entry.reject(new CdpError(message.error.message, message.error.code, method))
    else entry.resolve(message.result)
    return
  }

  // No id means an event, tagged with the session that produced it.
  for (const listener of this.#listeners) listener(message)
}

Attaching a page is where “flattened” earns its keep. Without it you would open a second WebSocket per page; with it, one attach call returns a session id that you thread through every subsequent command, and events come back labelled with the page that caused them:

const { targetId } = await browser.send('Target.createTarget', { url: 'about:blank' })
const { sessionId } = await browser.send('Target.attachToTarget', { targetId, flatten: true })

// From here every page-scoped command takes the session, and events
// arrive with the same sessionId attached.
await browser.send('Page.enable', {}, sessionId)
await browser.send('Runtime.enable', {}, sessionId)
await browser.send('Page.navigate', { url: 'https://example.com' }, sessionId)

Two robustness details in the connection are worth copying into any CDP client you write. First, the connection asks for target discovery (Target.setDiscoverTargets) instead of enumerating targets once, so tabs that appear later — a new tab, a window.open, a session restore — are known rather than invisible. Second, it guarantees at least one page exists: Chrome opens its DevTools port slightly before it registers the page target for theabout:blank argument, and a user may have closed every tab, so a tool call would otherwise fail with “no page targets are available” on a browser that is perfectly healthy.

The ref engine: from DOM node to a stable handle

A ref is a short string — e12 from a snapshot, p1 from a pick — and every action tool accepts either. What makes that safe is that a ref is never resolved by re-parsing a string. It is resolved through a real DOM node handle, so it survives ordinary DOM churn and cannot silently match a different element.

/** A selector that uniquely identifies `el` inside its own root node. */
function uniqueSelector(el) {
  const scope = el.getRootNode()      // document OR shadow root
  const tag = el.tagName.toLowerCase()

  if (el.id) {
    const byId = '#' + cssEscapeIdent(el.id)
    if (matchCount(scope, byId) === 1) return byId
  }

  for (const attr of ['data-testid', 'data-test-id', 'data-test', 'data-qa', 'name',
                      'aria-label', 'placeholder', 'title', 'alt', 'type']) {
    const value = el.getAttribute(attr)
    if (!value) continue
    const candidate = tag + '[' + attr + '="' + escapeAttr(value) + '"]'
    if (matchCount(scope, candidate) === 1) return candidate
  }

  // Structural fallback, built one level at a time and only while unique.
  // ...
}

Two consequences fall out of that design, and both are user-visible. Refs accumulate rather than reset: taking another snapshot extends the ref table instead of replacing it, so looking again never invalidates a ref you already hold. And a dead ref reports itself: if the element was removed, the failure says so rather than quietly resolving to whatever now occupies that position.

Real input, and honest answers

The easiest way to build a browser tool is to evaluate element.click() in the page and call it a day. It is also the fastest way to build a tool that lies: script-level clicks fire handlers but skip hit-testing, so any answer about whether a control is actually usable becomes fiction.

So clicks are dispatched as real mouse events at the element’s on-screen position, after scrolling it into view — and, critically, the tool reports what was actually topmost at that point:

// Scroll it into view, then read its viewport-relative rect.
await browser.send('DOM.scrollIntoViewIfNeeded', { backendNodeId }, sessionId)
const rect = await elementRect(browser, sessionId, element)   // getBoundingClientRect()
const cx = Math.round(rect.x + rect.w / 2)
const cy = Math.round(rect.y + rect.h / 2)

// Who is really on top at that point? An overlay here is the bug, not a mystery.
const host = await evaluate(`(() => { const el = document.elementFromPoint(${cx}, ${cy});
  return el ? el.tagName.toLowerCase() + ... : null })()`, sessionId)

await browser.send('Input.dispatchMouseEvent', { type: 'mouseMoved', x: cx, y: cy, button: 'none' }, sessionId)
await browser.send('Input.dispatchMouseEvent', { type: 'mousePressed', x: cx, y: cy, button, clickCount }, sessionId)
await browser.send('Input.dispatchMouseEvent', { type: 'mouseReleased', x: cx, y: cy, button, clickCount }, sessionId)

// topmostAtPoint is reported alongside the coordinates and the size.
return { at: { x: cx, y: cy }, size: { w: rect.w, h: rect.h }, topmostAtPoint: host }

The geometry deliberately comes from getBoundingClientRect() rather than DOM.getBoxModel. Input coordinates must be viewport-relative, and the bounding rect is unambiguous about that, whereas the box model’s coordinate space depends on the frame it belongs to. One rule, one fewer class of off-by-a-scrollbar bug.

Zero-area targets — an icon-font node inside a button, a ::before pseudo-element carrier — cannot be clicked by coordinate at all. Those fall back to a script click, and the result says so, so “this control has no clickable area” remains a fact the caller can act on rather than being papered over.

The picker is the point

Everything above is achievable with several tools. The picker is the reason this plugin exists in this form, because it is the one capability that structurally requires a real, visible browser: a human points at something, and the agent receives a machine-usable reference to it. No typing, no ambiguous description, no “the third button in the header”.

Mechanically it is the DevTools Overlay domain, which is to say it is the DevTools element picker, borrowed:

// Put the page into the same "inspect" state DevTools uses.
await browser.send('Overlay.enable', {}, sessionId)
await browser.send('Overlay.setInspectMode', {
  mode: 'searchForNode',
  highlightConfig: {
    showInfo: true,            // the native tag/size tooltip
    showStyles: false,
    showRulers: false,
    contentColor: { r: 111, g: 168, b: 220, a: 0.5 },
    paddingColor: { r: 147, g: 196, b: 125, a: 0.4 },
    borderColor:  { r: 255, g: 229, b: 153, a: 0.5 },
    marginColor:  { r: 246, g: 178, b: 107, a: 0.4 },
  },
}, sessionId)

// The click arrives as an event carrying the chosen node.
browser.on('Overlay.inspectNodeRequested', ({ backendNodeId }) => resolvePick(backendNodeId))
browser.on('Overlay.inspectModeCanceled', () => resolveCancel())   // Esc in the browser

// Then the node becomes a ref, exactly like a snapshot ref.
const { object } = await browser.send('DOM.resolveNode', { backendNodeId }, sessionId)
// ...register in the page ref map under 'p1', and describe it.

Because the highlight is drawn by the browser rather than injected into the page, the user sees the same affordance they already know from DevTools, and the page’s own styles and scripts are never mutated to show it. It also means a picked node is identified by backendNodeId — the protocol’s stable handle — rather than by anything the page could have faked.

The visible feedback during picking is a one-line instruction strip at the top of the page. It is a small piece of code and it produced the article’s favourite bug, because it is a masterclass in CSS inheritance working against you:

host.style.cssText = 'all: initial; position: fixed; z-index: 2147483647; ... pointer-events: none;'

// Inside the shadow root the bar resets everything...
bar.style.cssText = [
  'all: initial',
  // ...which puts pointer-events back to 'auto'. A descendant with 'auto'
  // is STILL a hit-test target underneath a 'none' ancestor, so without the
  // declaration below the strip swallows hover -- and would itself be the
  // element the picker reports for anything underneath it.
  'pointer-events: none',
].join(';')

The strip removes itself after two seconds, because it sits over the page and an instruction should not outstay its usefulness; the DevTools hover highlight stays as the ongoing feedback. Clicking the composer button again cancels, and so does pressing Esc in the browser — both paths disarm the picker and remove the banner, since an armed picker left behind would hijack the user’s next click.

One browser, by construction

Agents are concurrent. Two tool calls can arrive in the same millisecond, a scheduled job can fire while a human is clicking a composer button, and every one of them wants a browser. The plugin’s answer is not best-effort locking but structure: four layers, each of which would be sufficient on a good day.

The fourth layer is the interesting one, because Chrome’s per-profile lock is not only a backstop — it is readable, and reading it converts the single most baffling failure in browser automation into a sentence a human can act on:

// Chrome permits one instance per --user-data-dir and enforces it with a
// SingletonLock symlink pointing at "<hostname>-<pid>".
export function readProfileOwner(userDataDir) {
  try {
    const raw = readlinkSync(join(userDataDir, 'SingletonLock'))
    const dash = raw.lastIndexOf('-')
    return { host: raw.slice(0, dash), pid: Number(raw.slice(dash + 1)) }
  } catch {
    return null
  }
}

With that, the plugin can tell the user something specific: a Chrome already owns this profile but is not exposing a DevTools port — you opened the automation profile by hand, or an earlier Chrome is still around. Launching in that situation is futile, because Chrome forwards the request to the existing process and exits 0 while the port never opens. Instead of waiting out a thirty-second launch timeout and reporting a generic failure, the plugin fails immediately and names the pid that owns the profile, plus the remedy: close that window, or start it yourself with --remote-debugging-port=<port> and the plugin will attach to it.

Keeping the reader’s place

Here is a bug report any agent-driven browser produces within an hour of real use: “I was reading halfway down a long page, the agent refreshed it, and I was back at the top.” The cause is a quiet asymmetry in Chrome. It restores scroll for a reload and for a history traversal by itself, but not for a plain Page.navigate — which is exactly how an agent refreshes or revisits a page.

The whole design is one rule: restore only when the new document is at the very top. If the browser already positioned the page, or the URL carries a #fragment that asked for a specific spot, the plugin does nothing at all. That single condition is what keeps it from fighting Chrome’s own restoration or overriding an explicit anchor.

The details that took the most iterations are the ones a first implementation gets wrong in ways that only appear on real sites:

• Positions are keyed by URL without the fragment, because #install is a position within a page, not a different page.
• Restoration retries for about a second. A document is often too short to accept the offset when load fires — lazy images and deferred content arrive later — and a single scrollTo would be silently clamped to the top.
• A failed restore does not overwrite the memory. Recording the clamped top would erase the very position a later attempt should retry.
• The memory is bounded to 200 URLs, evicting the least recently used, so a long debugging session cannot grow it without limit.

And then there is the race. Navigations the page starts by itself — a link, a form, a self-reload — are caught by a load watcher that reads the outgoing document’s position as the navigation begins. That read can lose: the new document may commit before it is processed, and the reading is then the destination’s scroll, usually zero, which would be stamped onto the destination’s own URL and destroy the position the restore needs. Two things prevent it. The capture happens on Page.frameRequestedNavigation, which fires earlier thanframeStartedLoading; and any reading that already shows the destination URL is discarded rather than recorded. Navigations the plugin drives skip the watcher entirely, because they capture deterministically before issuing the navigation and restore explicitly afterwards.

Why this plugin imports nothing

There is not a single import of @deepseek-ai/* anywhere in the plugin’s lib/. That is not minimalism for its own sake; it is a consequence of how ESM resolves plugins installed into a profile.

A plugin installed through a symlink in the profile’s node_modules is reached via that symlink, but Node resolves ES module specifiers from a module’s real path. So import '@deepseek-ai/dsh-tools' inside the package resolves against the package’s own directory chain, not the profile’s, and fails with ERR_MODULE_NOT_FOUND — the loader’s bare-specifier hook covers the plugin entry point only, not its nested imports. Depending on the profile’s layout would also tie the plugin to internal package paths that move between releases, and would break any install that links the package rather than copying it.

The fix is a small local toolkit that reproduces the two things the plugin actually needed from the framework: schema-shaped tool definitions and argument validation. The observable behaviour mirrors the real defineTool — a parameter spec map compiled into an object-rooted JSON Schema with a required list, and execute validating arguments before running the body:

/** Compile a { property: spec } map into an object-rooted JSON Schema. */
export function parameterSpecToJsonSchema(spec) {
  const properties = {}
  const required = []

  for (const [key, definition] of Object.entries(spec ?? {})) {
    const { required: isRequired, ...rest } = definition ?? {}
    properties[key] = rest
    if (isRequired === true) required.push(key)
  }

  return {
    type: 'object',
    properties,
    ...(required.length > 0 ? { required } : {}),
  }
}

The same reasoning applies to configuration. The plugin deliberately does not declare a Config schema, because that would mean importing the profile’s schemastery. The loader passes configuration through untouched when a plugin declares none, so validation happens in the plugin, where the error message can name the offending key. The payoff is a package whose only runtime requirements are Node’s built-ins and a Chrome-family browser — which is also why it is easy to test in isolation.

Debugging a page with it

All of that machinery exists to answer ordinary questions. These are the six that come up most often, and the tool that answers each:

A worked example, from a real session on a staging checkout — the bug was “the Apply coupon button does nothing”:

browser_navigate  → https://staging.example.com/cart
browser_snapshot  → finds the ref for the coupon input and the Apply button
browser_type      → ref e41, value "SPRING10"        (real insertText, React state updates)
browser_click     → ref e52, returns:
                    { at: { x: 812, y: 604 }, size: { w: 128, h: 44 },
                      topmostAtPoint: "div.cookie-banner" }   ← the answer
browser_eval      → getComputedStyle(document.querySelector('.cookie-banner')).zIndex  → "9999"
browser_screenshot→ the banner overlapping the button, visible in the capture

The click succeeded at the protocol level — mouse events at the right coordinates — and the page did nothing, because a consent banner with a higher stacking context was on top. A script-level click() would have hit the button and reported success, sending the agent off to debug the coupon API for an hour. That difference, between executing an action and reporting what actually received it, is most of the value of driving a browser honestly.

Testing a browser plugin for real

A plugin that drives Chrome cannot be tested with mocked protocol replies and still be trusted, because the bugs live in the parts a mock does not have: real compositing, real shadow roots, real timing. So the suite splits by what actually needs a browser.

Two techniques in there are worth stealing. The picker is exercised by dispatching a genuine click into the session that armed it, because that is what the user’s mouse does — a synthetic call to the pick handler would test everything except the part that can break. And the client bundle is loaded the way the shell loads it: evaluate the bundle against a stubbed window.__ModuleLoader__, then call the registered factory with a require bound to React.

Configuration and limits

Every key is optional, and the defaults are chosen so that the common case — a developer on a laptop debugging a staging site — needs no configuration at all.

The environment variables matter for containers and CI: CHROME_PATH (or DSH_CHROME_PATH) overrides browser discovery, and CHROME_EXTRA_ARGS="--no-sandbox" is the concession for environments where Chrome’s own sandbox cannot run. That one is a test-environment escape hatch and never a default — turning off the browser sandbox to make an automated browser work is how a debugging tool becomes a security incident.

What to copy if you build your own

The plugin is roughly four thousand eight hundred lines across ten files, and the interesting thing is how little of it is protocol code. If you are building something similar, these are the decisions that paid for themselves:

• Refs, not selectors, as the agent-facing handle. Generate selectors for humans; resolve refs through real node handles for machines. Refs that survive a later snapshot remove an entire class of “the element moved” failures.
• Real events at real coordinates, plus a topmost report. Any tool that acts on a page should state what actually received the action. Without that, a tool that cannot see an overlay confidently reports success.
• Two halves, one RPC channel, loopback authority. Let the UI ask the host to do privileged work instead of duplicating capability in the browser, and use the host’s own trust fence rather than inventing an auth scheme.
• Structure over locking for singleton resources. One port, one profile, attach-before-launch, a launch mutex, and an honest read of the browser’s own lock. Concurrency bugs in this area look like random failures and are miserable to debug later.
• Zero host imports. Reimplement the two helpers you need. Your plugin then survives host releases, works when linked rather than copied, and can be tested without the host present.
• Test against real Chrome, including the ugly paths. The picker cancel path, a refused launch on a locked profile, a document that grows after load, an overlay swallowing a click — those are the tests that find bugs.

Conclusion

A plugin system earns its keep when it lets one package span both sides of an application without pretending the two sides are the same. This plugin is a fair test of that: a host half that owns a DevTools connection and thirteen tools, a client half that owns two buttons in the composer, and a narrow RPC channel between them. The plugin system handles the wiring; the interesting engineering is all inside.

And that inside work is mostly about honesty. The ref engine exists so that “the button” becomes a handle that cannot drift. Real input events exist so that a click means what it means for a user. The topmost-element report exists so that a silent overlay is a fact rather than a mystery. The scroll memory exists so that the agent’s refresh does not cost you your place. None of it is clever; all of it is what separates a browser tool you can debug with from one that tells you a comfortable story while your production page stays broken.