dsh-kimi-webbridge-lunarcac

<h1 align="center">dsh-kimi-webbridge</h1>

<p align="center"> <a href="README.md">English</a> · <a href="README.zh.md">简体中文</a> </p>

<p align="center"> <strong>Drive your real browser from DSH agents through Kimi WebBridge</strong> — navigate, read, click, fill, screenshot with your logged-in sessions.<br/> <a href="https://badgen.net/badge/license/MIT/green"><img src="https://badgen.net/badge/license/MIT/green" alt="license" /></a> <a href="https://badgen.net/badge/format/official%20bundle/8257D0"><img src="https://badgen.net/badge/format/official%20bundle/8257D0" alt="format" /></a> </p>

---

Kimi WebBridge (browser extension + local daemon, default http://127.0.0.1:10086) exposes the user's real browser — with all login sessions — as a local API. This plugin registers each daemon action as a native model Tool (webbridge_*), so a DSH agent can navigate, read, click, fill, screenshot, and interact with any website using the user's actual browser and credentials.

Features

• Official bundle form: declares dsh.bundle, one-command install into the profile layer stack
• Pure ESM, zero runtime deps: uses only the host-provided tools + subprocess services and the system curl
• Cross-platform: Windows / macOS / Linux (system curl required)
• Global scope: registers as a host row in the global tool layer, visible to every session's agent

Install

# 1) Local tarball / directory
dsh plugin --profile web add ./lunarcache-dsh-kimi-webbridge-0.3.0.tgz

# 2) Git source (after publishing to GitHub)
dsh plugin --profile web add github:LunarCache/dsh-kimi-webbridge#main

# 3) npm (after publishing)
dsh plugin --profile web add @lunarcache/dsh-kimi-webbridge

Restart web after installing (bundle layers load at boot; see [Verification](#verification)).

> Pure-cordis alternative (no bundle declaration): after dsh plugin --profile web add <pkg>, add an insert row to $DSH_HOME/profiles/web/cordis.patch.yml (config HMR applies live): > ``yaml > - insert: > - id: dsh-kimi-webbridge > name: '@lunarcache/dsh-kimi-webbridge' > `` > Pick one path only — never both (avoids duplicate mounting).

Verification

# 1) Confirm the composed layer (works before restart)
dsh --profile web --dump-config
# Output should contain:
#   # == @lunarcache/dsh-kimi-webbridge
#   - id: dsh-kimi-webbridge
#     name: @lunarcache/dsh-kimi-webbridge

# 2) After restarting web, new sessions should list all 14 webbridge_* tools

Uninstall

dsh plugin --profile web remove @lunarcache/dsh-kimi-webbridge

One command removes the dependency and drops the bundle from dsh.profile.bundles. Restart web after install/uninstall.

> ⚠️ If pnpm reports ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION (supply-chain check, see [Troubleshooting](#troubleshooting)), add the one-shot override: > ``sh > dsh plugin --profile web remove @lunarcache/dsh-kimi-webbridge --config.minimumReleaseAge=0 > ``

Update

# 1) Bump the version in package.json, then repack
npm pack

# 2) Overwrite-install with the new tarball (replaces dependency + layer), then restart web
dsh plugin --profile web add ./lunarcache-dsh-kimi-webbridge-<new-version>.tgz

> Never hand-edit the profile's package.json/cordis.patch.yml to upgrade — dsh plugin reconciles the layer stack from the installed state.

Configuration

Override in the profile's cordis.patch.yml or the bundle layer:

- insert:
    - id: dsh-kimi-webbridge
      name: '@lunarcache/dsh-kimi-webbridge'
      config:
        defaultSession: my-task
        timeoutMs: 60000

Tools

Every tool accepts an optional session parameter (default dsh-webbridge). One task = one session = one browser tab group; closing tabs is always user-initiated.

How it works

1. The tool's execute spawns the system curl through the injected subprocess service. 2. The JSON body is written to the child's stdin (curl --data-binary @-) — no shell quoting or mojibake. 3. The daemon's { ok, data } is parsed and data returned to the model. 4. Cancellation: exec.signal is forwarded to the child process.

> Do not declare @deepseek-ai/* / cordis dependencies in package.json — the dsh runtime injects them via the profile pnpm closure (nodeLinker: hoisted + autoInstallPeers: false); declaring them makes pnpm fetch version-mismatched packages from the public registry.

Troubleshooting

Daemon not running (connection refused)

# Windows
& "$env:USERPROFILE\.kimi-webbridge\bin\kimi-webbridge.exe" start
# macOS / Linux
~/.kimi-webbridge/bin/kimi-webbridge start

Extension out of date (error contains "Please update the Kimi WebBridge extension") — update the extension from the browser store and retry; do not try to fix versions manually.

pnpm supply-chain check blocks install/uninstall (ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION)

pnpm 11's minimumReleaseAge policy verifies recently-published lockfile entries (unrelated to this plugin — it flags other packages in your environment). Two official one-shot bypasses (no policy config is changed):

# Install: --trust-lockfile or --config.minimumReleaseAge=0
dsh plugin --profile web add ./lunarcache-dsh-kimi-webbridge-0.3.0.tgz --trust-lockfile
dsh plugin --profile web add ./lunarcache-dsh-kimi-webbridge-0.3.0.tgz --config.minimumReleaseAge=0

# Uninstall: remove does not accept --trust-lockfile, use --config.minimumReleaseAge=0
dsh plugin --profile web remove @lunarcache/dsh-kimi-webbridge --config.minimumReleaseAge=0

After the first bypass pnpm auto-adds the flagged entries to minimumReleaseAgeExclude in the profile's pnpm-workspace.yaml, so the flag is usually not needed afterwards.

Clicks / fills ignored on strict sites — pages that enforce event.isTrusted (banking, captchas) ignore synthetic events; manual interaction is required.

Development & release

# Local pack
npm pack                      # lunarcache-dsh-kimi-webbridge-<version>.tgz

# Publishing to GitHub (recommended):
# - description format: DSH plugin: <one-line feature>; official bundle, install via `dsh plugin --profile web add github:LunarCache/dsh-kimi-webbridge#main`
# - topics: dsh / dsh-bundle / deepseek-harness + functional tags (e.g. browser / automation)

Pre-publish checklist: main/exports point to index.js; dsh.bundle.patch → cordis.patch.yml; install commands copy-pasteable; install smoke test passed (install → mount → restart → tools visible).

Prerequisites

• Kimi WebBridge browser extension installed with the daemon running (see [Troubleshooting](#troubleshooting)).
• curl on PATH (Windows 10/11 ships C:\Windows\System32\curl.exe; macOS / Linux ship it).

License

MIT — see [LICENSE](./LICENSE).