dsh-plugin-bridge

English | 中文

Halfway through a task and need another tool preset? Switching the produced session in place would leave tool history that belongs to the old assembly. Bridge previews a bounded five-part handoff, opens a clean target, and leaves the original session untouched.

Quick start · Why Bridge · Evidence · Decisions · Compatibility

Quick start

Bridge 0.4.7 replaces per-alpha installation declarations with a bounded 0.2.1 host range while retaining the earlier host terms. Official 0.2.1-alpha.5 Web acceptance passed real preview/edit/migration, restart and removal; representative 0.2.0-rc.2 / alpha.4 backward checks also passed. The acceptance record separates those checks from admission and publication. See Support policy before treating an admitted future version as tested.

Check the Host's actual pnpm executable when installing or removing packages. pnpm 11.22.0 has a known late-worker shutdown bug that can keep a package operation alive after printing Done; natural DSH reproductions isolated the upstream fixes. Use 11.26.0 or later, which includes the upstream fixes, and avoid overlapping package operations. If an operation is pending, wait for it to settle or stop the Host normally before using the offline CLI. Bridge does not bundle pnpm or upgrade your tools automatically.

npm / CLI

Install from npm:

dsh plugin --profile web add dsh-plugin-bridge

On DSH 0.1.5-rc.2, restart dsh web after adding or removing the plugin. On DSH 0.1.6-alpha.2, a first install from the WebUI Plugins page applies live; CLI install and upgrades may still need one restart. DSH 0.1.7-alpha.1 was tested with CLI installation, live disable/enable, and removal followed by a restart; restart-free installation or upgrades were not tested.

On DSH 0.2.1-alpha.3 / 0.2.1-alpha.4 Web with HMR, the running pluginManager service's installBundle() API, including Remote API callers and the agent's plugin_manager tool, returns already-installed for a package already in the profile, even when another version is requested. API replacement uses removeBundle(name) followed by installBundle(spec); honor any restart request. See the upstream upgrade guide.

For CLI replacement, stop the Host using the selected profile, run dsh plugin --profile web remove dsh-plugin-bridge, then dsh plugin --profile web add , and start the Host again. The CLI runs separate profile package operations; the running-API refusal above does not apply to that path.

Before either replacement, finish or save pending handoffs: previews and unconfirmed edits live in memory and stopping or unloading Bridge discards their confirmation state. The source session remains intact; generate a new preview after reinstallation and reapply any saved draft. These Web procedures do not upgrade Desktop; native Desktop acceptance remains recorded separately for 0.2.0-rc.2.

Pinned GitHub fallback:

dsh plugin --profile web add github:Totoro-qaq/dsh-plugin-bridge#v0.4.7

Discover

On DSH versions with Discover (introduced in 0.2.1-alpha.4), you can also install Bridge from the author's index:

1. Open Plugins → Experimental plugins → More and enable Custom plugin markets.
2. Open Discover → Add index source and paste:

https://raw.githubusercontent.com/Totoro-qaq/dsh-plugin-index/main/index.json

1. Choose Bridge, check the package name, version and https://registry.npmjs.org/ in the confirmation, then install and choose Enable now.

First handoff

Then type in the official WebUI:

/bridge                       list target presets
/bridge --doctor              check the host contract after a DSH upgrade
/bridge code                  preview the handoff; change nothing
/bridge code --go             migrate, restate, then wait
/bridge code --go --continue  restate and start work in the same target request

On DSH rc.7 and later, the official WebUI renders /bridge as a native card. Text exposes the fixed five sections as ordinary fields and flat bullet or ordered-list rows while preserving their Markdown markers; Markdown preserves full source freedom; Preview renders Markdown or a complete JSON tree. Long content scrolls inside the card. Confirm migration opens the created target session. Bridge 0.3.10 adds room to keep confirmation reachable above the fixed composer at the tested narrow widths.

UIs that implement the official conversation.chat.commandview slot receive the same card automatically. Other custom UIs retain the complete server result, summary-file workflow, and target title/session-ID fallback; UI authors can reuse the framework-free dsh-plugin-bridge/client-contract export instead of reimplementing the wire. On an older or non-slot client, correct the printed summary file and run:

/bridge code --go --file <path>

Preview edits are temporary until migration is confirmed. Restarting the client or system may discard them; the source session remains untouched, and you can regenerate the preview.

Uninstall with dsh plugin --profile web remove dsh-plugin-bridge, then restart dsh web.

Why Bridge

| Promise | What it means | |---|---| | Preview before execution | /bridge creates no target and changes no source session. Review or edit the five-section handoff first. | | Move state, not tool traces | Decisions, paths, current state, and next steps move to a clean preset. Incompatible calls from the old tool assembly do not. | | Fail closed | The target goal is paused before kickoff. If that cannot be guaranteed, Bridge clears/cancels the target and sends no model request. |

Installing Bridge adds zero prompt tokens to ordinary sessions. It is a host slash command, not a model tool or skill.

Evidence at a glance

The release gate is intentionally small and reproducible; these are regression results, not population guarantees.

| Gate | Result | |---|---:| | Five-part summary facts | 30/30 | | Target restatement / first useful work facts | 60/60 · 60/60 | | Critical facts / obsolete-value resurrection | 90/90 · 0 | | Existing image evidence / unresolved raw image | 5/5 · 5/5 | | Confirm / --continue target request shape | 2 · 1 to first useful work | | Confirm extra, paired nominal median | +8.1% vs --continue | | Summary worker share of clean acceptance components | 20.74% nominal | | Native WebUI repeat gate (preview / target facts) | 3/3 · 3/3, five facts each | | DSH 0.1.2 alpha.2 / alpha.3 / alpha.5 installed WebUI | 13/13 · ordered-list edit · PTC paused · image → text fallback | | DSH 0.1.5-rc.1 installed WebUI, npm Bridge 0.3.4 | 13/13 · 3/3 migrations · edit reached target · PTC paused · raw image → vision target |

The token percentage varies widely with preset, response length, and cache state. The worker share is composition, not causal overhead versus no Bridge; the stable product claim is one additional confirmation request. Read the design and evidence boundaries, full release report, and vision report.

How it works

fold history -> five-part handoff -> preview/edit -> clean target session
             -> pause stored goal -> inject -> restate -> wait or continue
image history -> verbatim assistant evidence; unresolved originals use the attachment gateway

The five sections are Goal, Current state, Key decisions and conventions, Key files, and Next step. The original session is never rewritten; archive the target and return to the source if the handoff is unsatisfactory.

Migration decisions

| Situation | Bridge behavior | Cost / fidelity effect | |---|---|---| | Plugin installed, no /bridge call | No prompt injection or model tool | 0 Bridge prompt tokens | | /bridge code | One bounded summary worker; preview only | No target session is created | | Default --go | Target restates and waits | One explicit confirmation request before useful work | | --go --continue | Confirm the defined next step; restate and work in one target request | Separate approvals and safety limits still apply; no background goal round | | Image already has assistant analysis | Copy that response verbatim | No raw image is resent by default | | Image is unresolved and target accepts images | Copy the original attachment and preserve the source VLM | Vision pricing comes from the selected provider | | Image is unresolved and target is text-only | Prompt admission rejects the image; Bridge sends a visible text fallback | No hidden local VLM and no silent claim of visual understanding |

Compatibility

Support policy

From Bridge 0.4.7, engines.dsh is an installation-admission range, not an exact list of tested releases:

>=0.1.0-rc.7 <0.2.0-0 || 0.2.0-rc.2 || >=0.2.1-alpha.1 <0.2.2-0

The previous host terms are unchanged. The 0.2.1 term admits later alpha/beta/rc builds and final 0.2.1, but not 0.2.2 prereleases or later versions. DSH evaluates this field with includePrerelease: true; the explicit <0.2.2-0 ceiling avoids a caret unintentionally admitting later 0.2.x prereleases.

Admission is not acceptance. The table, version-specific reports and Workshop's exact dshVersions name only exercised hosts. Published package metadata is a snapshot; later passing documentation checks do not silently rewrite an old npm artifact. Compatible 0.2.1 updates need a diff review and short acceptance pass, not a new npm release merely to append an alpha number. Actual code/dependency/packaging fixes still require a release, and a new version family requires reviewing the boundary. The verified exact alpha.4 development SDK baseline is retained; it does not have to advance for every compatible Host. /bridge --doctor helps identify missing capabilities but does not replace migration acceptance.

Since Bridge 0.4.0, Approve in new session is available on the official plan-review card, verified on DSH 0.2.0-rc.2 and 0.2.1-alpha.1 WebUI. Enter /plan and review the plan submitted through exit_plan_mode, then choose the Bridge action. It stops the original planning turn, leaves that session in plan mode, creates a fresh session with the same preset/model/workspace, transfers the approved plan verbatim in its kickoff, and starts implementation there. The host's existing Approve and Request changes controls keep their ordinary behavior. See the approved-plan workflow.

Published Bridge 0.4.1 also passed native macOS Desktop 0.2.0-rc.2 acceptance: installation, edited migration, approved-plan execution, live toggles, uninstall and restart. Desktop and npm WebUI records are separate; native-window pixels and account login are not certified.

| DSH baseline | Server handoff | Native card | Verification boundary | |---|---:|---:|---| | 0.2.1-alpha.5 | Yes (Bridge 0.4.7) | Real edit/confirm/auto-open passed | Official npm Host; no exemption, doctor 13/13, one preview worker, exact 1,856-character UI-reviewed payload into PTC with a paused goal, one target turn and zero target tools. Text/Markdown round-trip, bounded editor scrolling, current-directory placement, toggles, restart, removal and absence of the CLI shim passed. See bounded acceptance; later admitted hosts are not thereby tested. | | 0.1.0-rc.6 | Yes | No | Narrow RPC contract and text compatibility tests | | 0.1.0-rc.7 / rc.8 | Yes | Contract-checked | Client-module/command-slot contract plus server fallback | | 0.1.1-rc.2 | Yes | Yes | Installed official WebUI: doctor 13/13, edit/confirm/auto-open, three-run repeat gate | | 0.1.2-alpha.2 / alpha.3 / alpha.5 | Yes | Yes | Official DSH npm hosts: typed controllers 13/13 and PTC auto-open; the alpha.5 gate installed the branch tarball, retained alpha.3 titles, edited ordered lists, fell back from unresolved image to text, and removed cleanly | | 0.1.2-rc.1 → 0.1.3-alpha.2 | Yes (Bridge 0.3.3+) | Yes (Bridge 0.3.3+) | Real npm-host upgrade, preserved v2 history/title, exact edited payload, PTC paused goal, image fallback and clean removal; see acceptance report | | 0.1.5-alpha.1 | Yes (Bridge 0.3.4+) | Yes (Bridge 0.3.4+) | Official npm host with session format V3: tarball install, served native-card bundle, doctor 13/13 and preset listing on a V3 session; SDK type diff and V3 fold fixtures. Model-backed preview, migration and image fallback were not re-run; see smoke report | | 0.1.5-rc.1 | Yes (Bridge 0.3.4+) | Yes (Bridge 0.3.4+) | Official npm host with the published 0.3.4 unchanged: doctor 13/13, native card rendered, three model-backed migrations to PTC with an exact edited handoff and paused goal, and an unresolved image carried to the vision-capable default model; see acceptance report | | 0.1.6-alpha.1 | Yes (Bridge 0.3.6+) | Yes (Bridge 0.3.6+) | Official npm host: doctor 13/13, native card rendered, ptc still offered after the PTC runtime rename, keyless preview fails closed; the SDK change is additive and lib/ is byte-identical to 0.3.5. Model-backed migration was not re-run; see smoke report | | 0.1.6-alpha.2 | Yes (Bridge 0.3.7+) | Yes (Bridge 0.3.7+) | Official npm host: Bridge 0.3.6 migrates, but its Open target session button fails with ctx.sessions.open is not a function; Bridge 0.3.7 opens the target through uiWorkspace.openSession on alpha.2 and alpha.1, keeps the paused goal, and survives live disable and enable from the Plugins page; see acceptance report | | 0.1.7-alpha.1 | Yes (tested: Bridge 0.3.9) | Yes (tested: Bridge 0.3.9) | Published package unchanged: 13 V3 sessions restored as V4, 12 titles preserved, doctor 13/13, model-backed editing and both migration modes, automatic opening, paused goals, worker cleanup, image-to-text fallback, and live toggles. Removal clears the package/command/CSS but leaves a dangling CLI symlink; see acceptance report. | | 0.1.7-alpha.2 | Yes (Bridge 0.3.10 source) | Yes (Bridge 0.3.10 source) | Official npm host with a locally packed Bridge source build: doctor 13/13, model-backed preview, text/Markdown round-trip, 640/800 px confirmation reachability, exact edited handoff, no target tool calls, auto-open and paused goal. This is source-build evidence, not a registry-install claim; see bounded acceptance. | | 0.1.7-rc.1 | Yes (Bridge 0.3.10) | Yes (Bridge 0.3.10) | Isolated official npm host: fresh-profile install; existing-session WebUI and doctor 13/13; one model-backed text/Markdown handoff to ptc with exact edited payload, auto-open, paused goal, no target tools and unchanged source; 640/800 px confirmation hit-tests. Uninstall/restart passed but a dangling CLI link remained. The host test skipped optional Office packages after registry errors; see bounded acceptance. | | 0.2.0-rc.2 | Yes (tested: Bridge 0.3.10; declared in 0.3.11) | Yes (same runtime) | Isolated official npm WebUI: doctor 13/13, real preview and text/Markdown edits, exact edited handoff, direct and waiting targets, auto-open, paused goals, image transfer/text fallback, live toggles and uninstall/restart. A dangling CLI link remains; optional components and native Desktop behavior are outside this run. See bounded acceptance. | | 0.2.1-alpha.1 | Yes (declared in Bridge 0.4.1) | Yes (unchanged 0.4.0 runtime) | Published Bridge 0.4.0 on an isolated official npm WebUI: doctor 13/13, rendered editing, exact 484-character edited handoff to PTC, auto-open, paused goal, and a real approved-plan click that starts a new standard session and writes/read-verifies an exact 18-byte fixture. Live disable/enable preserves other styles; uninstall/restart removes package and command but retains a dangling CLI link. See bounded acceptance. | | 0.2.1-alpha.2 | Yes (Bridge 0.4.2) | Yes (Bridge 0.4.2) | Official npm WebUI: fresh current-directory placement at preview/confirmation/plan approval, real worker startup, text/Markdown round-trip, exact 2,009-character edited handoff to PTC, auto-open, paused goal, and approved-plan write/read/byte verification in the switched directory. Co-installed Jot, live toggles, removal and restart checked. See bounded acceptance. | | 0.2.1-alpha.3 | Yes (Bridge 0.4.5 declaration) | Yes (unchanged runtime) | Official npm WebUI acceptance used a local 0.4.4 candidate with byte-identical business lib/: 37-second worker in directory A, confirmation in B, exact 2,669-character reviewed handoff once, auto-open, paused goal, no target tools, 375/768/1280 px controls, live toggles, same-business-byte removal/reinstall and same-home restart. The initial mixed-format summary required Text → Markdown fallback and an explicit formatting edit before Text round-trip. See bounded acceptance and release mapping; the historical candidate run does not establish a registry install of 0.4.5. | | 0.2.1-alpha.4 | Yes (Bridge 0.4.6) | Preview, Text/Markdown editing and automatic opening passed | Official npm Host with a local 0.4.6 package: 27-second worker, exact 2,883-character edited handoff, paused goal, one target turn and zero target tools; controls at 375/768/1280 px, style-preserving toggles and bounded restart persistence passed. Natural same-graph DSH removal tests isolated the pnpm 11.22.0 late-worker bug; upstream single-patch controls and unmodified 11.26.0 removed Bridge successfully. The historical operation is not a PASS. See the acceptance and attribution boundaries. |

Bridge 0.4.2 adds exact 0.2.1-alpha.2 to engines.dsh and fixes two runtime issues: stale working-directory placement and false worker-start detection after a history window trims turn/start. Published 0.4.1 does not contain these fixes. rc.2 Desktop and alpha.1 backward smoke checks are recorded separately from alpha.2 Web acceptance.

Historical declaration: Bridge 0.4.6 added only exact 0.2.1-alpha.4 to the existing host range and built against that SDK with Cordis 4.0.5-alpha.2. Bridge 0.4.5's narrower engine excluded alpha.4 under the Host's installer rules; no compatibility exemption was used. Business source and generated lib/ were unchanged, and keyless backward startup/doctor/client-resource/removal checks passed on official 0.2.0-rc.2 and alpha.3 Web Hosts. The alpha.4 core workflow and fixed-package-manager removal controls passed; the earlier failed operation remains recorded. Local checks, bounded Host results and release/tag/npm publication are separate gates. Later prereleases and stable 0.2 releases were outside that 0.4.6 declaration; the bounded policy above supersedes it from 0.4.7. Hot replacement with different-business-byte packages was not tested, so Workshop activation remains restart-host and hot-reload evidence remains unset. Approved-plan real execution, images, native alpha.4 Desktop, Windows and Linux were not re-certified.

Use Bridge 0.3.4 or later for DSH 0.1.5-alpha.1: DSH published no 0.1.4, and a caret prerelease range such as ^0.1.3-alpha.2 never matches the next prerelease minor, so 0.3.4 adds ^0.1.5-alpha.1 and builds against that SDK with byte-identical lib/ output. Session format V3 records the system prompt as a system/message surface node; Bridge folds only user, assistant and tool events, so prompt text never enters a handoff. Use Bridge 0.3.3 or later for DSH 0.1.3-alpha.2; Bridge 0.3.2 does not include those compatibility changes. The typed adapter reads the default 240-message history window with one fresh inspect call instead of four; it does not cache running state. doctor checks method availability, not end-to-end compatibility. The same ^0.1.5-alpha.1 range also matches 0.1.5-rc.1 and the 0.1.5 final, so rc.1 needs no new Bridge release.

Since 0.3.5 the summary worker follows the conversation's model by default (modelTier: current). On DSH 0.1.5-rc.1 that is V4.1-Flash, which matched V4-Pro in the tier comparison at about half the summary time. DSH releases before 0.1.5-rc.1 have no V4.1-Flash, so set DSH_BRIDGE_TIER=pro or pass --tier pro there.

Use Bridge 0.3.6 or later for DSH 0.1.6-alpha.1 (only the dependency ranges changed; shipped code was the same as 0.3.5).

Since 0.3.8 the five DSH optional peer ranges are "*"; engines.dsh expresses the host support declaration. Bridge 0.4.1 declares >=0.1.0-rc.7 <0.2.0-0 || 0.2.0-rc.2 || 0.2.1-alpha.1: it preserves the previous range and adds only the newly tested alpha.1, not later 0.2 prereleases or stable 0.2.0/0.2.1. dshmarket evaluates this field with includePrerelease: true; the official 0.2.0-rc.2 installer instead checks DSH peer ranges, so installation alone does not establish verified support.

DSH 0.1.6-alpha.2 removed the client sessions.open. Bridge 0.3.6 still migrates there, but its Open target session button fails with ctx.sessions.open is not a function. Use Bridge 0.3.7 or later: it opens targets through the WebUI navigation service uiWorkspace.openSession and falls back to sessions.open on older hosts.

CI covers Node.js 22 and 24. Run /bridge --doctor after every Harness upgrade; it names missing required gateway methods instead of failing vaguely.

DSH 0.1.7-alpha.1 was verified on macOS with Node 22.23.1 and the published Bridge 0.3.9, without a runtime or dependency change. The V3→V4 test used a copy of an existing test home; back up DSH_HOME, including sessions and profiles, before upgrading. Custom directory-based preset migration, other UI/plugin combinations, and Windows were not covered. This acceptance does not require another Bridge npm release.

Bridge 0.3.10 includes the source build tested on DSH 0.1.7-alpha.2. It fixes two observed edges: an omitting summary worker no longer silently drops narrowly recognized, still-active user prohibitions on using tools or reading/writing files from the editable handoff, and the confirmation control remains clickable in the tested small viewports. Later explicit permission supersedes an earlier prohibition. This is a guard for these explicit forms, not a guarantee that every user constraint is automatically retained; review and edit the handoff before confirming. The confirmed draft is still sent exactly as edited. The linked acceptance predates npm publication and should not be read as registry-install evidence.

The published Bridge 0.3.10 also passed a bounded DSH 0.1.7-rc.1 compatibility run. No Bridge runtime change or new npm release was needed. This does not validate every optional DSH dependency or third-party UI; follow the rc.1 test boundary and run /bridge --doctor after upgrading your own host.

For DSH 0.2.0-rc.2, Bridge 0.3.11 updates the support metadata and documentation; the migration runtime remains unchanged from the tested published 0.3.10. The acceptance record separates real-model/WebUI evidence from packaging checks. It does not certify stable DSH 0.2.0, native Desktop login/quit, all optional components, or third-party UIs.

For DSH 0.2.1-alpha.1, Bridge 0.4.1 updates support metadata and documentation; server/client code, generated lib/, SDK pins and dependencies remain unchanged from 0.4.0. The acceptance record documents real-model flows and lifecycle checks. Images, native Desktop, later alpha versions and arbitrary plugin/UI combinations were not re-certified in this run.

The proposed OMDSH intake declaration only adds author metadata around the existing Profile Bundle. It is not Hub approval or Registry installation authority and does not change the runtime or compatibility range.

Current limits:

• an alpha.4 mixed-profile removal exposed pnpm 11.22.0's known late-worker shutdown mechanism. Natural DSH calls reproduced it twice; isolated upstream single-patch controls and unmodified 11.26.0 returned applied/exit 0. The historical operation is not a PASS, and its original PID's exact package/thread was not retrospectively recovered. Use the Host's actual pnpm 11.26.0 or later, avoid overlapping package operations, and save pending handoffs before stopping the Host;
• installing with the CLI (dsh plugin --profile web add) may need one WebUI restart; on DSH 0.1.6-alpha.2 a first install from the WebUI Plugins page (add the package name dsh-plugin-bridge) applies live, while upgrading an existing install there needs a restart;
• on DSH 0.1.7-alpha.1 with pnpm 11.22.0, CLI removal left a dangling node_modules/.bin/dsh-bridge symlink and package-manager metadata in both an upgraded and a clean profile; 0.1.7-rc.1 and WebUI removal on 0.2.0-rc.2 also left the dangling link while the package and dependency declaration were removed and WebUI restarted. Final alpha.3 candidate removal again left that dangling link and package-manager caches while removing runtime contributions and preserving data. This is not a zero-disk-trace uninstall;
• the native card opens the created target through the WebUI navigation service (uiWorkspace.openSession, with sessions.open as the fallback on older hosts); older clients still receive the title and session ID fallback;
• progress appears immediately while the worker runs; the earlier three-run native-card sample took 7.4–12.8 seconds of worker time. Timings depend on the host/model and input; previewTimeoutMs remains the hard bound;
• text-only models cannot inspect unresolved images;
• the native-card repeat gate is still only three fixed runs, so it is release evidence rather than a statistical guarantee.

Documentation

• Design, safety, image policy, cost, and evidence
• Chinese install, configuration, rollback, and FAQ
• Release acceptance report
• Vision migration report
• Native WebUI repeat acceptance
• DSH 0.1.2-alpha.2 compatibility acceptance
• DSH 0.1.5-rc.1 compatibility acceptance
• Summary worker tier comparison on DSH 0.1.5-rc.1
• DSH 0.1.6-alpha.1 compatibility smoke
• DSH 0.1.6-alpha.2 compatibility acceptance
• DSH 0.1.7-alpha.1 compatibility acceptance
• DSH 0.1.7-alpha.2 source-build acceptance
• DSH 0.1.7-rc.1 compatibility acceptance
• DSH 0.2.0-rc.2 compatibility acceptance
• DSH 0.2.1-alpha.1 compatibility acceptance
• DSH 0.2.1-alpha.2 candidate acceptance
• DSH 0.2.1-alpha.3 candidate acceptance
• DSH 0.2.1-alpha.4 candidate record
• Historical compression benchmark

Development

npm ci
npm run verify

verify builds and type-checks both plugin halves, runs the regression suite, checks generated lib/ and datasets, then packs, installs, and imports the actual npm tarball. The SDK guards check installed manifests as well as package and lockfile declarations. Tests spend no model tokens. prepublishOnly runs the same gate; GitHub releases also require the tag to match package.json before trusted npm publishing.

Community listings: Awesome DSH Plugin · Awesome DeepSeek Harness

Ecosystem discovery: dsh-TUI. Bridge remains a standard DSH plugin; TUI/std conformance is tracked separately.

License

MIT