DSH plugin capability roles: Definition, Provider, Consumer

When a DSH plugin capability is general enough, the official guidance splits it into three roles: a Service Definition for the contract, a Service Provider for the implementation, and a Consumer that exposes it. This is not architecture for its own sake — it makes swapping implementations a one-line configuration change, because callers only know the Definition. The test for splitting is equally clear: do the three roles need to evolve independently? If not, keep one package; if yes, split. Bash is the canonical example: dsh-shell is the definition, dsh-bash-local is the provider, and dsh-tool-bash is the consumer — together they form one seam.

DSH plugin capability roles: Definition, Provider and Consumer

Bottom line: the Definition owns the contract, the Provider owns the implementation, and the Consumer owns exposure; dependencies are one-way and the last two never depend on each other.

1. Callers know only the contract: a Consumer injects shell and never cares whether execution is local or remote.
2. Swaps happen at composition: changing a Provider is one line in cordis.yml; Definition and Consumer stay as they are.
3. Roles are not packages: they are logical divisions, so one package may hold several roles or be split into three.

Why split a DSH plugin capability into three packages

Bottom line: three payoffs — swappable providers, independent evolution, and decoupled dependencies.

1. Swappable providers: one Definition can have several Providers selected by configuration, with the calling convention unchanged.
2. Independent evolution: the Definition rarely changes once callers depend on it, Providers can optimize performance and safety, and Consumers can change how a capability is presented to the model.
3. Decoupled dependencies: Provider and Consumer never depend on each other, so changes on one side cannot break the other.
4. Clearer diagnosis: when something breaks, identify which role failed — contract mismatch, implementation error, or exposure problem.

Three steps to build a DSH plugin capability

Bottom line: write the Definition with request/result types first, then the Provider, then the Consumer; the order matters.

1. Write the Service Definition:

import { Service, type Context } from '@deepseek-ai/cordis'

declare module '@deepseek-ai/cordis' {
  interface Context { myCap: MyCapService }
}

export abstract class MyCapService extends Service {
  constructor(ctx: Context) { super(ctx, 'myCap') }
  abstract execute(request: MyCapRequest): Promise<MyCapResult>
}

export interface MyCapRequest { input: string }
export interface MyCapResult { output: string }

2. Write the Service Provider:

class MyCapLocal extends MyCapService {
  async execute(request: MyCapRequest): Promise<MyCapResult> {
    return { output: request.input.toUpperCase() }
  }
}
export const name = 'my-cap-local'
export function apply(ctx: Context) { ctx.plugin(MyCapLocal) }

3. Write the Consumer as a model-facing tool:

export const inject = ['tools', 'myCap']
export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'my_cap',
    description: 'Execute my capability.',
    parameters: { input: { type: 'string', required: true } },
    output: { schema: { type: 'string' }, render: (_a, v) => [{ type: 'text', text: v }] },
    async execute(args) { return (await ctx.myCap.execute({ input: args.input })).output },
  }))
}

4. Compose both rows: the provider package and the consumer package, in cordis.yml.
5. Verify swappability: replace the provider with another implementation and change only that row; the tool name and call shape stay identical.

Where to stop splitting a DSH plugin capability

Bottom line: do not split preemptively — only when roles truly evolve independently is the extra package cost worth paying.

1. A simple tool plugin needs no split: there is no alternative implementation, so splitting only adds release and dependency overhead.
2. One provider that will not change soon: keeping Definition and Provider together is simpler.
3. Too many packages: installation, version alignment and debugging all get harder; make one package work first.
4. Split signals: a second Provider is needed, or the Consumer must be reused across scenarios.
5. Team boundaries: when different people own different roles, separate packages unblock release cadence.

DSH plugin composition and swaps at the seam

Bottom line: composition happens in configuration, and swapping a Provider is a configuration change rather than a code change.

1. Mount by package name: list Providers and Consumers in order inside cordis.yml.
2. Swap one row: comment out the old Provider and add a package with the same contract.
3. Verify: call the tool once and confirm the result still matches the Definition's Result shape.
4. Check the seam reference first: built-in capabilities already have seam splits, so look before inventing a new one.

DSH plugin troubleshooting around the three roles

Bottom line: ask which layer broke before asking where the code is wrong.

1. "Service missing" — check that the Provider is mounted and inject is spelled correctly.
2. Type mismatch — ensure request/result types exist in exactly one place: the Definition.
3. Behavior changed after a swap — the implementation violated the contract; align it back to the Definition.
4. A Consumer instantiating the implementation — that breaks the dependency direction and defeats swapping.
5. Splitting too early — ship one package, then split when the need is real.
6. Repair status, stated honestly: the roles, dependency direction and three-step example follow the official Three capability roles page; confirm defineTool fields and Service signatures against the official reference for your version.

Sources: Three capability roles, Services and dependencies, Capability seams.