dsh-plugin-dev

dsh Plugin Development

Develop plugins for DeepSeek Harness (dsh), a Cordis-based agent framework. Plugins are TypeScript modules exporting apply(ctx: Context), composed via cordis.yml.

Quick Reference

Plugin Structure

import type { Context } from '@deepseek-ai/cordis'
export const name = 'my-plugin'
export function apply(ctx: Context) { /* register capabilities */ }

Three forms: function (default), object ({ name, inject, apply }), class (extends Service — use only when providing a service to other plugins).

Dependencies: export const inject = ['tools', 'llm'] — framework keeps plugin PENDING until all injected services are ready.

Auto-cleanup: Everything registered through ctx is an effect — unload automatically cleans up. For custom resources (timers, connections), wrap in ctx.effect(() => { ... return () => cleanup }).

Child plugins: const fiber = ctx.plugin(childPlugin) — children inherit parent context; await fiber.dispose() unloads recursively.

Fiber States

PENDING → LOADING → ACTIVE → UNLOADING → DISPOSED
                 ↘ FAILED

PENDING → missing service dependency. FAILED → apply threw or config validation failed. Service disappearing at runtime auto-disposes dependents.

Tools

import { defineTool } from '@deepseek-ai/dsh-tools'
export const inject = ['tools']
export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'greet', description: '...',
    parameters: { name: { type: 'string', required: true } },
    output: { schema: { type: 'string' }, render: (_args, value) => [{ type: 'text', text: value }] },
    async execute(args) { return `Hello, ${args.name}!` },
  }))
}

defineTool converts parameters to JSON Schema, validates args, and auto-unregisters on unload. See references/basic/tool.md for details.

Configuration

import Schema from '@deepseek-ai/schemastery'
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) { /* validated config */ }