DSH 0.2 plugin ecosystem: 5 questions after debugging plugins on Windows (notes included)

[qinyangcheng8-lab]

Hi everyone 👋

I've been running DSH on Windows with 0.2.0-rc.2 and spent the last few days debugging plugin issues for my setup. I wrote everything down and open-sourced it here: https://github.com/qinyangcheng8-lab/dsh-field-notes

The notes cover: plugin breakage after the 0.2 upgrade, pnpm lockfile recovery after an interrupted pnpm remove, the 0.2 RPC wire format, Windows sandbox ACL problems, and building client-side (slot-injected) plugins.

A few questions I could not answer from the docs or the code alone:

1. Plugin API migration. 0.2 removed installSettingsSection and settingsNamespace from @deepseek-ai/dsh-settings, and assertNever from @deepseek-ai/dsh-llm. Third-party plugins that statically import those names now fail at module-link time (The requested module ... does not provide an export named ...), so the host half never mounts. What is the recommended migration path — SettingsProvider.installSection on newer hosts? Is there a compat shim, or are settings sections simply unsupported in 0.2?

2. Plugin health check. Is there an official way to list loaded plugins and report load failures? Right now I smoke-test by dynamically import()-ing every package under the profile's node_modules and diffing against dsh.profile.bundles. bundles appears to be the only source of truth for "is this plugin actually enabled" — worth documenting if so.

3. Prompt-cache best practices. In long sessions every step re-sends the context. Any change to the tool set or injected sources breaks the prefix, and the cache hit rate can jump from ~0.1% to >10% (uncached tokens cost roughly 50x more). Is "freeze injected sources and batch all changes into one window" the recommended approach? Is there a recommended way to measure hit rate?

4. "webchat"-style plugins. Plugins that drive the DeepSeek web UI to avoid API billing — is that path still viable on 0.2, or is it deliberately not supported? If not supported, is there any recommended alternative for cheap "quick questions" outside the main session?

5. Sandbox boundary. Under workspace-write, writing to $DSH_HOME/profiles/** fails with EPERM and requires danger-full-access. Is that intended (profiles are protected), or is it an oversight that could be relaxed for plugin management use cases?

Happy to add more detail or reproduce any of these. Thanks for the great tool! 🐋

---

中文摘要（给中文用户）

这篇帖子是在 Windows + DSH 0.2.0-rc.2 上踩了一周插件坑之后整理的，完整笔记开源在这里：https://github.com/qinyangcheng8-lab/dsh-field-notes

想请教 5 个问题：

1. 插件 API 迁移：0.2 移除了 installSettingsSection / settingsNamespace（dsh-settings）和 assertNever（dsh-llm），静态 import 的插件在模块链接期直接报 does not provide an export named ...，host 段根本挂不上。推荐的迁移方式是 SettingsProvider.installSection 吗？有没有兼容层？
2. 插件健康检查：有没有官方的「已加载插件 / 加载失败」查询命令或 RPC？现在只能对 node_modules 逐个 import() 冒烟，再按 dsh.profile.bundles 判断是否启用——如果「bundles 才是唯一启用清单」属实，建议写进文档。
3. 前缀缓存：长会话每步都会重发上下文，工具集或注入源一变，命中率就从 0.1% 级别崩到十几个百分点（未命中价差约 50 倍）。官方是否建议「冻结注入源、所有改动攒到同一窗口」？有没有推荐的量化方式？
4. webchat 类插件：用网页版对话替代 API 计费的插件，在 0.2 上还有没有可行路径？如果没有，有没有别的方式做「低成本快问快答」？
5. 沙箱边界：workspace-write 下写 $DSH_HOME/profiles/** 直接 EPERM，必须 danger-full-access。这是有意保护 profiles，还是可以放宽？

感谢阅读 🙏

[VitorRodi]

Thanks for documenting these findings. Two of the issues you described can be investigated independently of the undocumented parts of the DSH plugin API.

For the plugin migration issue, the important distinction is between a missing export and a plugin initialization failure.

An error such as:

The requested module does not provide an export named 'installSettingsSection'

happens during ES module linking, before the plugin's initialization code executes. This means adding a runtime fallback inside the same module will not help if the removed symbol is still imported statically.

I would approach the migration as follows:

1. Inspect the actual exports of the installed 0.2.x package instead of assuming compatibility with the previous release.
2. Replace removed static imports with the supported API for the installed version.
3. If multiple DSH versions must be supported, isolate version-specific imports into separate adapter modules.
4. Test that the plugin module loads successfully before testing its settings registration or UI integration.

A minimal export inspection can be performed with:

node --input-type=module -e "import('@deepseek-ai/dsh-settings').then(m => console.log(Object.keys(m).sort())).catch(console.error)"

This does not prove that an exported API is supported or compatible, but it helps distinguish an export mismatch from a runtime problem.

For plugin health checks, I would also separate three different states:

• Package installed: the dependency exists and can be resolved.
• Bundle configured: the plugin is enabled in the profile configuration.
• Plugin operational: initialization completed and required services are registered.

A successful dynamic import only verifies the first part of that lifecycle. It does not guarantee that the plugin mounted successfully.

A useful diagnostic tool could compare configured bundle IDs against registered runtime services and initialization errors, then report mismatches explicitly.

Regarding the Windows sandbox issue, I would avoid using danger-full-access as a permanent workaround for ordinary plugin management. If profile directories are intentionally protected, a narrowly scoped management operation would be safer than expanding filesystem permissions for the entire agent session.

My suggestion would be to tackle the missing-export error first, because it is deterministic and can be reproduced without involving sandbox permissions, networking, or the complete plugin runtime.

Have you identified whether SettingsProvider.installSection is actually exported by your installed 0.2.x version, or is that migration path still inferred from the source code?

[qinyangcheng8-lab]

@VitorRodi Thanks — this is exactly the kind of breakdown we needed, and you were right to challenge our assumption. Answering your questions and confirming what we could verify.

Re: SettingsProvider.installSection — it is NOT actually exported. We just inspected the installed 0.2.1-rc.2 runtime:

$ node --input-type=module -e "import('@deepseek-ai/dsh-settings').then(m=>console.log(Object.keys(m).sort()))"
[ 'SettingsConflictError', 'SettingsForms', 'default', 'redactSecrets' ]

default only exposes inject. So there is no installSettingsSection, no settingsNamespace, and no installSection. Our earlier "migrate to installSection" note was inferred from older source / third-party plugins — it does not hold. If settings-section registration is still possible in 0.2.x, is SettingsForms now the entry point, or has that capability moved elsewhere entirely?

Re: link-time vs init-time — agreed, and we now separate them explicitly. We only classify does not provide an export named ... as a link-time break, and track separately the packages that import fine but whose apply() throws.

Re: the three states — this matches what we eventually worked out the hard way. Our current inventory only covers states 1 and 2 (dynamic import() + diffing against dsh.profile.bundles). State 3 (initialization completed, required services registered) is the missing piece; we plan to turn it into a small diagnostic that reports per plugin: installed → bundled → mounted → error.

Re: sandbox — agreed, we stopped treating danger-full-access as a workaround for routine plugin management. Our recent incident was self-inflicted: we upgraded the shared global runtime while the host was running, so the frontend assets and the running host ended up on different versions. Lesson learned — test upgrades against a copied runtime, never the live one.

One follow-up: do you know whether the profile-level compatibility check (the skipping profile bundle "X": incompatible with dsh 0.2.1-rc.2 warnings) can be queried programmatically — e.g. via a plugin-manager RPC or a dsh plugin status style command? We currently only see them on stderr at boot.

Thanks again for the detailed pointers.

[Muguett-DBY]

For your compatibility-check follow-up, rc.2 already has profile-aware manager APIs. Inside a DSH client plugin, these are the calls used by the official plugin-manager UI:

const inventory = await ctx.remote.pluginInventory.list()
const bundles = await ctx.remote.pluginManager.listBundles()
const plugins = await ctx.remote.pluginManager.listPlugins()

Check each RPC result's ok before reading value. The UI checks inventory.value.managementAvailable before using the management calls.

• listBundles() reports selection, availability and admission errors. An incompatible bundle has error.code === 'incompatible-version'; error.incompatible includes its version, runtime version and unmet requirements. enabled: true means selected, so it can coexist with that error.
• listPlugins() reports Loader entries with enabled and fiberPhase (active, failed, pending, etc.). The inventory fields do not include exception stacks.

listBundles() reevaluates the files currently on disk. For the exact load-time skip list, loadProfileDirectory() returns skippedBundles, with { packageName, reason } records.

For the settings migration, SettingsForms projects the plugin's volatile Config fields. A minimal Host-side example is:

import z from '@deepseek-ai/schemastery'

export const Config = z.object({
  label: z.string().default('before').volatile(),
})

The plugin reads config.label.get(). ctx.settings.describe() exposes the form under the Loader entry's id; update(entryId, patch, revision) persists edits through the profile patch. For your custom browser page, the client settings contract provides ctx.configForms.get(entryId) and the settings.section / settings.plugins.tab slots. The base service supplies the forms; a presentation plugin supplies the page.

I checked the published rc.2 backend on Node 24 and 26 with a real Loader and temporary profiles: incompatible, active and disabled entries reported the expected states; a form edit reached the live Config reference and profile patch, preserved ordinary fields, and rejected a stale revision. These checks covered the backend methods and Host forms.