Designing a DSH plugin service: contract, defaults, naming
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:
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:
- An abstract class extending
Service, registering the name viasuper(ctx, 'serviceName'); - A request type describing what callers must supply;
- A result type describing success, with errors clearly outside it;
- A declaration merge giving
ctx.serviceNamea type.
Written out:
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():
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:
- Register the new and old names together, pointing at the same instance;
- Move consumers'
injectentries to the new name, one at a time; - Remove the old registration once nothing references it;
- 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:
- Write a consumer importing only the definition; confirm it compiles and
ctx.runneris typed; - Write two providers implementing only
run; confirm neither touches defaults; - Swap the provider row in
cordis.yml, restart, and confirm behavior follows the new implementation with the consumer unchanged; - Remove the provider and confirm dependent consumers sit in PENDING with a log mentioning
runner; - 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.
FAQ
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.
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.
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.
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
- DeepSeek Harness docs: three capability roles· deepseek-harness
- DeepSeek Harness docs: services and dependencies· deepseek-harness
- deepseek-harness repository· deepseek-ai