DSH plugin extension points: DeepSeek Harness core and seams

A DSH plugin capability is not attached at random: the official docs split packages with a service declaration into core spine services (core), swappable capability seams (seam), and bundle/composition points (bundle), each with its own extension point and constraints (source). This article covers those three boundaries, what the single-implementation constraint really means, and where to attach a new capability; the three roles (Definition / Provider / Consumer) are already covered in the site's DSH plugin guide, so this article does not repeat them.

Core services, seams, and bundles in a DSH plugin: three kinds of extension points

The official docs group packages by service declaration into three kinds, where core is the pipeline spine, seam is a swappable capability, and bundle is the composition layer of a product form (source). The comparison:

1. The spine is the agent loop itself — the official docs mark agent-loop as "the one concrete loop plugin" and state that extension packages should depend on dsh-agent events and services rather than on this package. Expect: change the flow through events, not by editing the spine implementation.
2. A seam is a capability boundary — filesystem, shell, LLM, and the workflow engine are all exposed as seams with swappable providers. Expect: swapping an implementation leaves the consumer untouched.
3. The composition layer picks the provider — profiles and bundles decide which provider is loaded at assembly time. Expect: product differences live in the composition, not in scattered code branches.

The test is "what are you replacing": to replace the implementation of a capability, plug into the matching seam; to extend a pipeline stage, go through events instead of replacing a spine service — see DSH plugin events.

The single-implementation constraint in a DSH plugin: one active implementation per ctx key

The single-implementation constraint is Cordis service-registration semantics: inside one context, one ctx.<key> maps to a single active service instance (source). A Service subclass registers with super(ctx, name) on construction, the registration takes effect immediately, and it is removed automatically with its owning fiber. Three direct consequences:

1. A seam being swappable means replacing, not coexisting — only the provider currently loaded is in place, and swapping an implementation changes "who is loaded." Expect: never mount two providers on the same key.
2. A core service has no parallel implementation — the Implementations column is empty for core rows in the official table; they are single-owner. Expect: to extend a spine capability, add events or a new service, not a second implementation under the same name.
3. Incompatible Host and Client declarations must not reuse the same Context key — even when the two use independent runtime contexts, TypeScript declaration merging still sees both types. Expect: naming conflicts are avoided at the type level.

This yields two rules for plugin authors: keep every subscription and registration inside apply so it rolls back with the fiber, and when you need alternative behavior, swap the provider through the composition layer instead of mounting a second implementation in parallel.

Choosing a DSH plugin extension point: which seam to attach to

When adding a capability, choose the extension point by "what are you replacing" and plug into an existing seam rather than building a parallel system. The decision steps:

1. Replace the implementation of a capability — plug into an existing seam, such as ctx.llm (model capability, see LLM adapter), ctx.fs and ctx.shell (files and commands), ctx.workflowEngine (workflow script engine), ctx.codeRuntime (code execution), or ctx.sessionPersistence (session persistence). Expect: zero changes to upper tools.
2. Extend a pipeline stage — go through events without replacing a spine service. Expect: the extension point is reversible and unloadable.
3. Assemble a product form — use composition packages and bundle points to pick a provider in configuration. Expect: swapping an implementation only touches the composition.
4. None of the above — implement it as a cohesive standalone domain service, for example a domain-scoped registry. Expect: no confusion with the spine or a seam.

After choosing the extension point, keep the naming and packaging conventions: interface packages use the capability name, implementation packages add a mechanism / protocol / environment / vendor qualifier; singular ctx keys for single services like engine, runtime, and policy, and plural keys for registry and multi-member services. Run three self-checks after writing: is the capability correctly classified as core, seam, or composition; are two implementations fighting over the same key; did you plug into an existing seam instead of building a parallel system. To revisit the underlying framework, read the Cordis primer; to compare community DeepSeek Harness plugin implementations on the same seam, search the DSH Plugin Hub; for package structure, see adding a workspace package.