ChatGPTClaudeGrok / X / CursorGemini

Designing a DSH plugin service: contract, defaults, naming

Plugin DevelopmentPublished 2026-11-05Author: DeepSeek Plugin Market
DSH pluginService Definitioncustom serviceTypeScriptDeepSeek Harness
An interface review for team capabilities: what belongs in a Service Definition, who owns defaults, and why the service name is the costliest change.

Designing an interface for a capability is rarely a syntax problem. The hard parts are deciding what counts as the contract, who owns defaults, and whether the thing can be changed later.

This follows an interface review: a counterexample first, then what belongs in the definition, then a structure you can copy.

A DSH plugin interface that runs but will be rewritten

A DSH plugin contract written as a bare interface type runs, but registration, defaults, and error semantics force a rewrite. Say the team wants one way to execute code: locally, in a container, remotely, maybe more later. The first version usually looks like this:

ts
export interface Runner {
  run(command: string, cwd?: string, timeout?: number): Promise<string>
}

It reads clean and fails in three places. It is not a service, so ctx has no runner and consumers construct implementations themselves. The timeout default lives in each implementation, so callers never know the effective value. And the return type is a bare string, mixing errors with output, which guarantees error semantics drift when implementations change.

A definition is ready when three questions answer yes: can it be registered, are defaults visible, and are errors separated from results?

The four parts of a DSH plugin definition

A DSH plugin definition has exactly four parts: the service class, request type, result type, and declaration merge. A usable Service Definition contains four things and little else:

  1. An abstract class extending Service, registering the name via super(ctx, 'serviceName');
  2. A request type describing what callers must supply;
  3. A result type describing success, with errors clearly outside it;
  4. A declaration merge giving ctx.serviceName a type.

Written out:

ts
export abstract class RunnerService extends Service {
  constructor(ctx: Context) { super(ctx, 'runner') }
  abstract resolve(request: RunRequest): RunSpec
  abstract run(spec: RunSpec): Promise<RunResult>
}
export interface RunRequest { command: string; cwd?: string; timeoutMs?: number }
export interface RunSpec { command: string; cwd: string; timeoutMs: number }
export interface RunResult { stdout: string; stderr: string; exitCode: number }

Two objects appear here on purpose. RunRequest is what callers pass and may omit fields; RunSpec is the fully resolved form. That split is the declaration of who owns defaults.

The abstract class solves both layers at once. At runtime the base class attaches the instance to ctx; at compile time the abstract methods force every provider to match. An interface alone gives you neither, and an abstract class without exported request types gives you only half.

Why DSH plugin defaults cannot hide in implementations

DSH plugin defaults hidden in providers drift with every implementation, so they belong in resolve(). In the counterexample, each provider owns its timeout. Behavior then varies by implementation: 30 seconds locally today, 60 seconds in a container tomorrow, and every retry policy downstream has to follow.

The recommended shape puts defaults in resolve():

ts
export abstract class RunnerService extends Service {
  constructor(ctx: Context) { super(ctx, 'runner') }
  resolve(request: RunRequest): RunSpec {
    return {
      command: request.command,
      cwd: request.cwd ?? process.cwd(),
      timeoutMs: request.timeoutMs ?? 30000,
    }
  }
  abstract run(spec: RunSpec): Promise<RunResult>
}

Three benefits follow. Providers only handle RunSpec and stop repeating ?? 30000. Consumers read defaults from the definition instead of inspecting implementations. And a default change happens in one place for every provider.

resolve must be on the type. If it is a private helper, a provider can still apply its own defaults and the contract stops meaning anything.

The DSH plugin service name is the most expensive line

The DSH plugin service name is the hardest public contract, and renaming it is a breaking change. The least noticeable line is super(ctx, 'runner'), but runner is the hardest commitment in the design. Consumers write inject: ['runner'], isolate groups are keyed by service name, and PENDING diagnostics report exactly which service is missing — all three only know that string.

Renaming is a breaking change with an unhelpful failure mode: every dependent plugin sits in PENDING, the log says it is waiting for a service, and nothing says the name changed.

A safe rename sequence:

  1. Register the new and old names together, pointing at the same instance;
  2. Move consumers' inject entries to the new name, one at a time;
  3. Remove the old registration once nothing references it;
  4. Note the removal in the changelog with the version.

Name services with nouns. runner, metrics, storage work; doRun and handleCommand make people think they are callable functions.

Three DSH plugin design decisions that come up

Method granularity. Keep closely related operations together, such as run and cancel; split capabilities that merely share a domain. The test is whether a consumer might want only one of them. Sync or async. Always return a promise; a synchronous signature locks every consumer in place the day you add a remote backend.

Errors as exceptions or fields. Keep results for business data and raise exceptions for failure. An error field inside RunResult forces every call site to branch, and its shape drifts as soon as implementations differ.

Verifying the DSH plugin design

Verify a DSH plugin definition end to end; swapping the provider and removing it expose design flaws fastest. Five steps, each with a conclusion:

  1. Write a consumer importing only the definition; confirm it compiles and ctx.runner is typed;
  2. Write two providers implementing only run; confirm neither touches defaults;
  3. Swap the provider row in cordis.yml, restart, and confirm behavior follows the new implementation with the consumer unchanged;
  4. Remove the provider and confirm dependent consumers sit in PENDING with a log mentioning runner;
  5. Temporarily rename the service and confirm the failure points at the name, not at the loader.

Steps 3 and 4 expose design flaws fastest. If swapping requires editing the consumer, the definition is incomplete; if a missing service produces an unreadable failure, the naming or diagnostics convention is weak.

A definition is written for other people. Hand it to someone who has not seen the implementation and ask them to write a consumer. If they can, the interface holds. For what happens when a service disappears at runtime, read service isolation; for the split-or-not decision, read capability roles.

ChatGPTClaudeGrok / X / CursorGemini

FAQ

Why should a custom DSH plugin service use an abstract class instead of a TypeScript interface?

Because a DSH plugin service must be registered at runtime. Extending Service lets the constructor call super(ctx, 'name') to register it; an interface exists only in the type layer. The abstract class carries the runtime and compile-time contract together.

Where should defaults for a custom DSH plugin service live: the definition, a provider, or the caller?

Put them in an explicit DSH plugin definition step such as resolve(request): Spec, so defaults become part of the contract. Providers implement execution only, and callers do not need to know fallback rules, which keeps behavior stable when implementations change.

Does a DSH plugin service name need to match the package name, and is renaming it safe?

A DSH plugin service name does not need to match the package name, but once consumers inject it, the name is a public contract. Renaming breaks every dependent plugin, which then sits in PENDING; add the new name alongside the old one for a release before removing the old.

When a DSH plugin consumer cannot find the custom service, should it fail or degrade?

The answer depends on the DSH plugin requirement. Declare required capabilities in inject so the plugin waits, while optional ones skip inject and query ctx.get('name'), skipping the related feature when the result is empty.

Related Terms

service name
A service name is the key a plugin registers with super(ctx, 'name'); consumers look it up through inject or ctx.get.— DeepSeek Harness docs
abstract class
An abstract class is a TypeScript class that cannot be instantiated directly and declares method signatures, used here to carry both registration and compile-time constraints.— DeepSeek Harness docs
declaration merging
Declaration merging is the technique that extends the Cordis Context interface through declare module so ctx.myService has a type at compile time.— DeepSeek Harness docs
optional dependency
An optional dependency is a service omitted from inject and queried with ctx.get at the use site, letting the plugin run while skipping the feature.— DeepSeek Harness docs

Sources