DSH plugin isolation: DeepSeek Harness inject and isolate

A DSH plugin "service" is a named capability a plugin mounts on ctx and exposes to other plugins, inject declares which services it needs, and isolate in cordis.yml gives different plugin groups their own instance (source). This article covers how to write required versus optional dependencies, the runtime behavior when a required service disappears and returns, and isolate multi-instance isolation plus type declaration merging; a Cordis primer is in the Cordis primer, and the writing split between inject and ctx.get is in the plugin spec, while this article covers dependency runtime behavior and isolation.

Required and optional dependencies in a DSH plugin

In Harness, tools, llm, and agents are services — named capabilities mounted on ctx (ctx.tools / ctx.llm / ctx.agents) — and any plugin can provide a service for other plugins to consume (source). There are two ways to consume a service, and the difference is when the plugin loads:

1. Required dependency — export const inject = ['tools']. The framework guarantees every service declared by inject is ready when apply runs; if a service is not ready, the plugin waits instead of running.
2. Optional dependency — omit inject and query with ctx.get() at the use site, with optional chaining as a fallback:

// Required: the plugin does not load while the service is absent.
export const inject = ['tools']

// Optional: omit inject and query with ctx.get() at the use site.
export function apply(ctx: Context) {
  const metrics = ctx.get('metrics')
  metrics?.record('plugin_loaded', 1)
}

To provide a service, use the Service base class from @deepseek-ai/cordis: extend it, call super(ctx, 'metrics') in the constructor to set the service name, and optionally declare static inject = ['llm'] since a service may depend on other services; consumers then access it as ctx.metrics. To type it correctly, use TypeScript declaration merging:

declare module '@deepseek-ai/cordis' {
  interface Context {
    metrics: MetricsService
  }
}

DSH plugin runtime behavior when a service disappears and returns

If a required service disappears while the application is running, for example because its provider unloads, dependent plugins dispose automatically to release resources, and they load again when the service returns (source). The point of this behavior is to prevent a plugin from calling a service that no longer exists.

In other words, declaring a service as a required dependency is not only a startup-time "wait until it is ready" constraint but also a runtime availability contract — changes in service availability propagate automatically to the loading state of dependents. That is why the choice between required and optional depends on whether your plugin can tolerate absence: if it can, use ctx.get() for an optional dependency; if it cannot, let inject have the framework manage the lifecycle.

DSH plugin cordis.yml isolate multi-instance isolation

cordis.yml can isolate services so separate plugin groups see separate instances of the same service (source). The typical pattern gives two group: true plugin groups their own isolated copy of a same-named service:

- id: group-a
  name: '@deepseek-ai/cordis-plugin-group'
  group: true
  isolate:
    shell: true
  config:
    - name: '@deepseek-ai/dsh-bash-local'
      config:
        timeoutMs: 5000
    - name: './src/plugin-a.ts'

- id: group-b
  name: '@deepseek-ai/cordis-plugin-group'
  group: true
  isolate:
    shell: true
  config:
    - name: '@deepseek-ai/dsh-bash-local'
      config:
        timeoutMs: 60000
    - name: './src/plugin-b.ts'

plugin-a and plugin-b each see the Bash instance in their own group, with no cross-group effect — group-a's timeoutMs: 5000 and group-b's timeoutMs: 60000 never overwrite each other. This is exactly the landing spot for "one capability interface, multiple isolated implementations," and it pairs with the layering in capability seams.

One last discipline for looking up services: the repository generates built-in Harness service names, public methods, and source locations into each service's subsystem page (such as the core subsystem page). While developing a plugin, use those generated regions and the service's TypeScript interface, and do not maintain a second static list, which would drift from the generated interface.

Three self-checks when done: can this dependency tolerate the service being absent (deciding inject versus ctx.get()); did you add a type declaration merge for the service name; and, under isolation, did you place the same-named service inside the right plugin group's isolate. To find plugins commonly paired with isolation (local shell, model adapters), search the DSH Plugin Hub; for extension-point ownership see the feature-to-mechanism map.