dsh-plugin-bridge

dsh-plugin-bridge moves a locked session to a new preset through a previewable five-part handoff

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.

A real Bridge migration in the official DeepSeek Harness WebUI

Quick start · Why Bridge · Evidence · Decisions · Compatibility

Quick start

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.

Pinned GitHub fallback:

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

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 <preset>` 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

Bridge 0.4.0 adds Approve in new session to the official plan-review card on the tested DSH 0.2.0-rc.2 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, and starts implementation there. The host's existing Approve and Request changes controls keep their ordinary behavior. See the approved-plan workflow.

DSH baseline	Server handoff	Native card	Verification boundary
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.

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.3.11 declares >=0.1.0-rc.7 <0.2.0-0 || 0.2.0-rc.2: it preserves the 0.1.x range and adds only the tested 0.2.0-rc.2, not untested 0.2 prereleases or stable 0.2.0. 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.

Current limits:

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. 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.

The server command stays the compatibility core. The same package now adds an optional official client half for rendered editing and navigation; if that prerelease client contract fails to load, /bridge still returns the complete server result. See the implementation boundary.

Documentation

Development

npm ci
npm run verify

verify builds and type-checks both plugin halves, runs 211 tests, checks generated lib/ and datasets, then packs, installs, and imports the actual npm tarball. 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

dsh-plugin-bridge

Install

README