DSH plugin types: augmenting Context, Events, and Config
Type problems are annoying because they only exist in the editor. The code runs, logs look right, and the red squiggle under ctx.metrics keeps reminding you that something here is any. Three concrete errors explain what declare module can and cannot do.
Three DSH plugin type errors, one cause
All three DSH plugin errors share one cause: runtime registration and compile-time declarations are out of sync.
First: property does not exist. You write ctx.metrics.record(...) and the editor says Property 'metrics' does not exist on type 'Context'. Runtime may be perfectly fine, because the service really is registered; the type system simply does not know. Second: event name mismatch. You write ctx.on('stats/report', handler) and get "no overload matches", or the count parameter is inferred as any.
Third: config is all any. apply(ctx, config) has no hints, a misspelled field does not error, and you find out at runtime as undefined. All three are the same gap: runtime and compile time are out of sync. Runtime relies on registration, compile time on declarations. Do only one and you get "runs but no hints" or "hints but does not run".
What declare module changes for a DSH plugin
It does not change your code; it changes the type table of interfaces Cordis already declared.
declare module '@deepseek-ai/cordis' {
interface Context {
metrics: MetricsService
}
}
This tells TypeScript that every Context now has a metrics property of type MetricsService. Three boundaries matter:
- Compile time only; it disappears after build;
- No runtime behavior; it does not register anything;
- Only declarations in the current compilation count — a file nobody imports might as well not exist.
The third boundary is where people get stuck. The declaration is in an unreferenced file, the editor looks fine, and another package reports the property as missing.
Three DSH plugin places worth augmenting
The first is Context, for service properties. Put it in the Service Definition package, next to the abstract class:
import { Service, type Context } from '@deepseek-ai/cordis'
declare module '@deepseek-ai/cordis' {
interface Context { metrics: MetricsService }
}
export abstract class MetricsService extends Service {
constructor(ctx: Context) { super(ctx, 'metrics') }
abstract record(event: string): void
}
The property name must match the service name. Register metrics and declare metrics; do not mix a property called metricsService with a registration called metrics.
The second is Events, for names and listener signatures. The official pattern adds a method signature to the Events interface:
declare module '@deepseek-ai/cordis' {
interface Events {
'stats/report'(name: string, count: number): void
}
}
Now ctx.emit('stats/report', name, count) and ctx.on('stats/report', (name, count) => ...) are both checked. Prefer namespace/action names; with many events they group by prefix and do not collide with property names.
The third is config, and it needs no declare module. A plugin's Config is constrained by exporting a schema of the same name, and TypeScript infers the second apply parameter from Schema<Config>. Seeing any there usually means the Config type was not exported or the schema and interface disagree.
DSH plugin types without runtime
DSH plugin type declarations never wire runtime behavior, so a typed property can still be undefined.
The most confusing case: the editor is happy and ctx.metrics is undefined at runtime. There is exactly one cause: merging does not wire anything. You must do two separate things:
| Layer | Action | If missing |
|---|---|---|
| Runtime | super(ctx, 'metrics') registers the service | Property exists but is undefined |
| Runtime | ctx.emit('stats/report', ...) fires the event | Listener never runs |
| Compile | declare module supplies the type | Editor complains, code still works |
A blunt way to find which side you missed: delete the declaration temporarily and run. If runtime is fine, only the declaration was missing; if runtime also breaks, registration was never done.
Why a DSH plugin needs import type {}
The empty import type {} line pulls a DSH plugin declaration into the compilation without a runtime import.
A subtle case: the declaration lives in stats.ts, reporter.ts imports only types, and event names still have no autocomplete. The official tutorial adds a line that looks pointless:
import type {} from './stats'
It imports no values; its job is to pull stats.ts into the compilation so TypeScript sees the merge. Without it, the two files do not know each other at the type level. The general rule: declaration merging follows module visibility, not directory structure. Switching packages, entry points, or tsconfig include can make a declaration "suddenly stop working".
A five-minute DSH plugin type check
This five-step check separates DSH plugin type problems from assembly problems.
- Remove every
any, run a type check, and note each error location; - Add declarations until the same file is clean;
- Reference the service from another package and confirm the declaration still applies;
- Run with the declaration but no registration, and confirm the symptom is
undefined, not a crash; - Restore registration and confirm values and types line up.
Step 4 is deliberate. It separates type problems from assembly problems, so the next time you see undefined you will not start editing declarations.
Type augmentation moves errors earlier at the cost of maintaining two truths: the declaration and the registration. Keep them aligned and the editor becomes a real guardrail. For runtime rules of Context and inject, read Cordis primer; for choosing an event dispatch mode, read writing plugin events.
FAQ
Declaration merging affects only the compiler and creates no runtime wiring, so a DSH plugin still needs registration. The service needs an abstract class calling super(ctx, 'myService'), and events still need ctx.emit; with types but no registration, the value stays empty.
A DSH plugin's event types merge only when the declaration file is part of the compilation. The consumer needs a line such as import type {} from './stats' to pull that file into the graph; it emits no runtime import but makes ctx.on and ctx.emit see the signatures.
It conflicts when the types differ and merges when they match, so a DSH plugin should declare the property once. Declare it in the Service Definition package and have providers and consumers import that package instead of copying the declaration.
The official DSH plugin examples use namespace/action, such as stats/report, which keeps a flat event namespace readable and groupable. Plain camelCase compiles but becomes hard to attribute and easy to confuse with property names.
Related Terms
- declaration merging
- Declaration merging is TypeScript folding multiple declarations of the same interface into one type, used here to extend Cordis Context and Events.— DeepSeek Harness docs
- Context interface
- The Context interface is Cordis's type for the plugin context; merging can add custom service properties so ctx is typed.— DeepSeek Harness docs
- Events interface
- The Events interface is Cordis's type for event names and listener signatures; merging makes ctx.emit and ctx.on check arguments against them.— DeepSeek Harness docs
- import type
- `import type` is the syntax that imports only types and disappears after compilation, used to bring declaration merges into the graph without a runtime dependency.— DeepSeek Harness docs
Sources
- DeepSeek Harness docs: Cordis tutorial· deepseek-harness
- DeepSeek Harness docs: events· deepseek-harness
- DeepSeek Harness docs: services and dependencies· deepseek-harness