description, kind
| description | kind |
|---|---|
| Reload plugin code and profile configuration without overlapping package operations. | package-reference |
@deepseek-ai/dsh-hmr
English | 中文
Summary
Reload plugin source and configuration while an application is running. Module replacements, Include refreshes and registered profile-file handlers share one queue with package mutations. Existing Cordis HMR configuration and events remain available under ctx.hmr.
Table of Contents
- Use this package
- Understand the implementation
- Model Experience
- Known Limitations and Deferred Work
- Dev Note
Use this package
The base bundle enables HMR with root: [] when the launcher supplies profileContext; hosts without that profile context leave this entry disabled. Headless, SDK and ACP bundles disable that entry in YAML; a later profile patch can enable it. Disabling or omitting HMR applies changes on restart. To enable source-module watching, configure the hmr entry supplied by the base bundle in the profile patch before launching:
- id: hmr
disabled: false
config:
root: ["."]
Existing configurations replace the module name @deepseek-ai/cordis-plugin-hmr with @deepseek-ai/dsh-hmr. The hmr service key, baseDir, config, getLinked(), getOuterStack(), hmr/change and hmr/reload remain available. The vendored package remains available; DSH profiles use this package.
Configuration
| Field | Default | Meaning |
|---|---|---|
base |
Context base URL | Base directory for module watching. |
root |
["."] |
Module watch roots; [] retains only explicit configuration watches. |
ignored |
["**/node_modules", "**/.*", "cache", "data"] |
Excluded module paths. |
debounce |
100 |
Milliseconds for combining module changes. |
Chokidar options, including polling, retain their existing meaning. Exact configuration watches also observe additions, removals and initially missing parent directories. They default to awaitWriteFinish: true: edits wait for Chokidar's 2-second write-stability window, avoiding its lossy change-event throttle. Configure awaitWriteFinish to adjust that window; disabling it can miss rapid consecutive edits. Direct Plugin Manager operations apply without waiting for file events.
Understand the implementation
Implementation internals — click to expand
watchConfig() registers an awaited configuration handler. runExclusive() serializes caller-owned mutations with automatic reloads and rejects nested transactions. HMR registers a hmr/before-reload listener that holds the profile file lock around every automatic reload; callers performing mutations acquire their file lock inside runExclusive() in the same order. File events received during a transaction are processed afterward.
App-boot owns profile parsing and patch precedence. HMR reads the launcher’s data-only profileContext, registers the profile manifest and both user patch watches during initialization, and waits for application readiness before processing changes. Its disposal closes the watchers and cancels reloads waiting for startup. HMR also owns module-cache replacement and reload scheduling. Unknown-file notifications do not acquire reload locks, so lock-file events cannot trigger another lock acquisition. No invariant companion is published because the queue and watcher registrations have no independent persisted projection.
Watched module paths use Node ESM resolution's realpathSync() spelling, including Windows short directory names, so file events match the module cache.
The module replacement implementation derives from @cordisjs/plugin-hmr 1.0.15, with Harness Node-loader and lazy-config changes. Its MIT license is retained.
Model Experience
Reloaded plugins
What the model sees
ctx.hmr adds no model-facing tools or messages. Loaded plugins determine subsequent tool and prompt contributions.
Token effect
No direct token contribution.
KV Cache effect
Reloading a contributing plugin can change later request prefixes; HMR does not rewrite conversation history.
Known Limitations and Deferred Work
- Module replacement requires Node loader internals. Framework dependency changes call the host-provided
loader.exit()hook; HMR itself does not restart the process. - Replacing installed package versions still requires a restart through Plugin Manager. The browser Client module graph retains its separate browser-side loading mechanism.
Dev Note
None.