dsh 0.1.1 upgrade breaks third-party plugins with no compat check: registration.adapter.prepareCall is not a function

[rngfbbbffhjgggd-commits]

Summary

Upgrading @deepseek-ai/dsh from 0.1.0-rc.6 to 0.1.1-rc.2 silently breaks third-party plugins that were written against the rc.6/rc.7 adapter contract. In our case, the community plugin dsh-vision-router v1.6.2 crashed the web UI on the first message with:

registration.adapter.prepareCall is not a function (UNKNOWN)

This is a breaking API change in dsh 0.1.1 (prepareCall was added to the adapter contract) with no detection, warning, or migration path for installed plugins.

Environment

• OS: Windows 10
• dsh: 0.1.0-rc.6 → 0.1.1-rc.2 (via npm install -g @deepseek-ai/dsh)
• Plugin: dsh-vision-router v1.6.2 (community, at ~/.dsh/profiles/*/node_modules, pnpm-managed)

Steps to reproduce

1. Install dsh 0.1.1-rc.2 with a plugin (e.g. dsh-vision-router v1.6.2) that predates the prepareCall contract.
2. Start dsh web, send any message (or trigger context injection / memory recall that reaches the adapter).
3. Observe crash: registration.adapter.prepareCall is not a function.

Root cause

• dsh 0.1.1 introduced a required prepareCall method on registered adapters.
• The plugin's adapter, written for rc.6/rc.7, does not implement it.
• No startup-time validation or upgrade-time compatibility check exists, so the failure only surfaces at runtime on first use.

Workaround (verified)

Upgrading the plugin to v1.7.6 (commit dae05e10, "support DSH 0.1.1 prepareCall adapter contract") fixes the crash.

Feature request: plugin compatibility self-check after upgrade

Since DSH's design philosophy is "Everything is a Plugin", upgrade-time plugin compatibility is a first-class UX concern. Proposals:

1. Runtime contract probe (recommended, minimal): at boot, verify required adapter methods (e.g. prepareCall) exist on every registered plugin adapter; on failure, emit an actionable error naming the plugin, its version, and the required dsh version — instead of a bare is not a function.
2. Upgrade-time check / notice: after upgrading dsh, scan profiles/*/node_modules for plugins and report which ones may need a companion upgrade (like a dsh doctor command).
3. Docs: change the "command not recognized → reopen window" guidance to "run npm install -g @deepseek-ai/dsh to repair" where applicable.

Bonus (minor)

dsh web spawns a markitdown-mcp child process; when the process is interrupted, it prints a large misleading KeyboardInterrupt traceback. Clean child-process exit handling would help.

[weijiafu14]

I hit this exact contract change from the other side — maintaining a bridge that has to run on both generations — so here is the fix pattern for plugin authors, and a note on your proposal.

The fix is not "implement prepareCall", it's "inherit it"

The trap is that prepareCall looks like a method you should add. If a plugin adds its own, it pins itself to 0.1.1 and breaks on rc.8 — the mirror image of the bug you just hit.

What actually works across both generations: build the adapter on the host's own LlmAdapter base class, resolved through a peer dependency rather than a hard one.

// package.json
"peerDependencies": {
  "@deepseek-ai/dsh-llm": "^0.1.0-rc.8 || ^0.1.1-rc.1"
}

import { LlmAdapter } from '@deepseek-ai/dsh-llm'
class MyAdapter extends LlmAdapter { /* ... */ }

Because the peer resolves to whichever generation the host has installed, prepareCall is simply inherited when it exists and absent when it doesn't. One published artifact, both generations, no version sniffing.

The failure mode you saw comes from adapters registered as plain object literals — an object literal has no base class to inherit from, so on 0.1.1 it dies with exactly your message.

For anyone writing the compat check

Your proposal 1 (runtime contract probe) is the right shape. One refinement from doing it in anger: probe the capability, never the version string. We branch on

typeof LlmAdapter.prototype.prepareCall === 'function'

which stays correct across rc's, backports and forks, where a semver comparison does not.

I'd also widen it beyond adapters: the same generation gap moved several waterfalls (system-prompt/assemble, tools/pre-execute) from agent-loop into their own subsystems, and changed attachment storage to re-encode images rather than store bytes verbatim. Event names and semantics stayed the same, so those did not break us — but a probe that only checks adapter methods would not have caught them either. A boot-time report of "these installed plugins register adapters / listeners whose contract version differs from the host" would cover more than a single method check.

The honest bit

None of this fixes the underlying UX problem you are actually raising — that an upgrade silently arms a runtime crash. That is DSH's to solve; a plugin author can only make their own package survive it. Your dsh-vision-router upgrade to v1.7.6 was the right immediate answer.

Disclosure: I maintain pi2dsh, which is unrelated to dsh-vision-router — I'm posting the pattern because we paid for it, and every third-party adapter author is going to hit the same wall.