ChatGPTClaudeGrok / X / CursorGemini

DSH plugin types: augmenting Context, Events, and Config

Plugin DevelopmentPublished 2026-11-05Author: DeepSeek Plugin Market
DSH pluginTypeScriptdeclare moduleContexttype augmentation
ctx.myService is red, event names lack autocomplete, config is any. Three compiler errors, one cause: missing declaration merging.

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.

ts
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:

  1. Compile time only; it disappears after build;
  2. No runtime behavior; it does not register anything;
  3. 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:

ts
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:

ts
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:

LayerActionIf missing
Runtimesuper(ctx, 'metrics') registers the serviceProperty exists but is undefined
Runtimectx.emit('stats/report', ...) fires the eventListener never runs
Compiledeclare module supplies the typeEditor 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:

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

  1. Remove every any, run a type check, and note each error location;
  2. Add declarations until the same file is clean;
  3. Reference the service from another package and confirm the declaration still applies;
  4. Run with the declaration but no registration, and confirm the symptom is undefined, not a crash;
  5. 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.

ChatGPTClaudeGrok / X / CursorGemini

FAQ

I typed ctx.myService in my DSH plugin, but it is still undefined at runtime. Why?

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.

Why does another plugin not see my event types when I only import types?

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.

Two DSH plugin packages declare the same Context property. Is that a conflict?

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.

How should custom DSH plugin event names be written: camelCase or something else?

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