DeepSeek Harness plugin: how to write capabilities with ctx

How to write a DeepSeek Harness plugin comes down to one sentence: export an apply function from a TypeScript module and register every capability through ctx inside it — you never import framework internals, because ctx is the only entry point. The same shape applies to every DSH plugin.

DSH plugin mental model: module + apply + ctx

A DSH plugin is not a base class you extend; it is a plain module that exports apply. The framework calls apply on load and passes a ctx context object where you register capabilities (source):

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

export const name = 'my-plugin'

export function apply(ctx: Context) {
  // Register capabilities here.
}

That snippet is the complete configuration — nothing else is required. Remember three roles: name is the unique identifier, apply is the load entry, and ctx is the only entry point to framework capabilities. For the fuller decision of function versus object versus class form, see the development guide.

DSH plugin snippet 1: the smallest runnable skeleton

Prove the plugin loads with a single log line before adding anything. Create src/my-plugin.ts:

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

export const name = 'hello-plugin'

export function apply(ctx: Context) {
  console.log('[hello-plugin] plugin loaded!')
}

If that line prints at startup, your module export and the load path both work. Always write code in the order "make apply run → then register capabilities", otherwise a failure cannot be attributed to loading versus capability setup.

DSH plugin snippet 2: register a tool

A capability for the model is a tool, and inject plus defineTool are both required. Declare the dependency, then register:

import { defineTool } from '@deepseek-ai/dsh-tools'
import type { Context } from '@deepseek-ai/cordis'

export const name = 'my-tool-plugin'
export const inject = ['tools']

export function apply(ctx: Context) {
  // ctx.tools is ready here.
  ctx.tools.register(defineTool({
    name: 'my_cap',
    description: 'Execute my capability.',
    parameters: {
      input: { type: 'string', required: true },
    },
    output: {
      schema: { type: 'string' },
      render: (_args, value) => [{ type: 'text', text: value }],
    },
    async execute(args) {
      return args.input.toUpperCase()
    },
  }))
}

description is written for the model, not for humans — it is how the model decides when to call the tool. For parameter types, output rendering, and error handling, see how to write a tool plugin.

DSH plugin snippet 3: let the plugin accept config

Declare configuration with a Config type plus a same-named Schemastery schema, defaults included, then take a second argument in apply:

import Schema from '@deepseek-ai/schemastery'
import type { Context } from '@deepseek-ai/cordis'

export interface Config {
  greeting: string
  maxRetries: number
}

export const Config: Schema<Config> = Schema.object({
  greeting: Schema.string().default('Hello'),
  maxRetries: Schema.number().default(3),
})

export function apply(ctx: Context, config: Config) {
  console.log(config.greeting)
}

The framework validates configuration against the schema and fills defaults, so config inside apply is always complete. How config maps to UI rendering is covered in plugin configuration.

DSH plugin snippet 4: listen to events and clean up manually

Register listeners with ctx.on, and give manual resources a disposer via ctx.effect(). Everything registered through ctx is cleaned up automatically, but timers and connections need an explicit disposer:

export function apply(ctx: Context) {
  ctx.effect(() => {
    const timer = setInterval(() => console.log('heartbeat'), 5000)
    // The returned function runs when the plugin unloads.
    return () => clearInterval(timer)
  })
}

Events have several trigger modes (broadcast, short-circuit, ordered, pipeline), and a pipeline event only continues if you call next(). Choosing the wrong mode shows up as "the logic is written but never runs" — see the events section of the development guide.

Self-checking a DSH plugin: three mistakes and a --patch verification

Self-check these three first; they catch most load failures and resource leaks.

1. Mixing export styles — function form uses a named export (export const name plus export function apply), while object and class form use a default export. Mixing them makes the loader unable to identify the form.
2. Using ctx.tools without inject — the framework only guarantees a dependency is ready after you declare it; omitting it can yield undefined under some startup orders.
3. Forgetting ctx.effect() for manual resources — a setInterval, a connection pool, or a file handle keeps running after the plugin unloads.

These are hard checklist items in the development spec; the full list is in the DSH plugin development spec.

Then run it once to confirm it loads. The lightest local method is a --patch overlay in three steps:

1. Capture the absolute path — run pwd in the plugin project root. Expect: the absolute path that the name field below needs.
2. Write the overlay config — create a cordis.yml whose insert section points name at the plugin source:

- insert:
    - id: hello
      name: '/absolute/path/to/scratch-plugin/src/my-plugin.ts'

3. Start and watch the log — run pnpm dsh web --patch ./scratch-plugin/cordis.yml. Expect: the console.log from your plugin prints, which means the module export and the load path both work.

That only proves "the code is written right," not "it can be distributed" — to verify distribution, install into a profile following the last three steps of the development tutorial, then check the installed list in DSH Plugin Hub to confirm the plugin appears and its config renders.