Dsh Plugin

DSH plugin development

A DSH plugin is a cordis plugin: an ES module exporting apply(ctx, config), packaged with a dsh.bundle.patch declaration so dsh plugin add promotes it into a profile's layer stack.

When to use

• Adding a tool the model can call (ctx.tools.register(defineTool(...))).
• Hooking harness events (tools/pre-execute, agent/pre-step, session/event, ...).
• Providing a service (class X extends Service), an LLM adapter, or a user-facing surface (ctx.settings.register for a settings card, ctx.webServer.register for a route).
• Diagnosing a plugin that installs but never loads, or whose config is ignored.

Do not use for editing DSH itself, or for ~/.dsh/profiles/<p>/cordis.yml (always []; edit cordis.patch.yml instead).

Environment (verified)

DSH="$HOME/.dsh/profiles/node_modules/@deepseek-ai/dsh/lib/bin.js"   # no PATH shim; $HOME, never ~
# profiles: $HOME/.dsh/profiles/web, $HOME/.dsh/profiles/headless
# installed: cordis 4.0.1, schemastery 3.18.1, dsh-tools/dsh-llm/dsh-session 0.1.1-rc.2

Reference implementation, known-good and installable: /Users/charlesqin/orca/projects/DSH-Project/dsh-pi-review.

Quick start

SKILL=/Users/charlesqin/orca/projects/DSH-Project/.claude/skills/dsh-plugin
# $DSH is the handle defined under "Environment" above

# 1. scaffold (writes package.json, tsconfig.json, cordis.patch.yml, src/, test/)
node $SKILL/scripts/scaffold.mjs dsh-hello --dir $HOME/code --profile web

# 2. install deps + build (dist/ MUST exist before install — a link: install runs no prepare)
cd $HOME/code/dsh-hello && npm install && npm run build

# 3. verify before touching the profile
node $SKILL/scripts/verify.mjs $HOME/code/dsh-hello --profile web

# 4. install into the profile (-w is MANDATORY for `add`)
cd $HOME/code && $DSH plugin --profile web add -w ./dsh-hello

# 5. confirm it composed into the tree
$DSH --profile web --dump-config | tail -20      # look for "# == dsh-hello"

After every source edit: npm run build, then restart the profile. The profile holds a symlink, so a stale dist/ is one cause of "my change did nothing" — but module HMR is off in both stock profiles (root: []), so a rebuilt dist/ is never hot-reloaded even when it is fresh. Only ~/.dsh/profiles/<p>/cordis.patch.yml and ~/.dsh/cordis.patch.yml reload live. See references/install-and-verify.md §5.

Uninstall: $DSH plugin --profile web remove dsh-hello (no -w needed; remove by package name).

The plugin contract

src/index.ts — the whole minimal plugin:

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

export const name = 'dsh-hello'

// Every entry in `inject` is REQUIRED and blocking. apply() re-runs whenever one
// of these services is replaced. There is no required/optional object split in
// cordis 4.0.1 — for an optional dep, omit it here and use ctx.get('name').
export const inject = ['tools']

// Config must be BOTH a TS interface and a same-named runtime Schema (declaration
// merging). A plain object here does not work — cordis needs a Standard Schema.
export interface Config {
  greeting: string
  loud: boolean
}
export const Config: Schema<Config> = Schema.object({
  greeting: Schema.string().default('Hello').description('Prefix for the reply.'),
  loud: Schema.boolean().default(false),
})

export function apply(ctx: Context, config: Config) {
  // Anything registered through ctx (listeners, tools, timers) is disposed
  // automatically. Only external resources need an explicit effect:
  ctx.effect(() => () => { /* kill child processes, close handles */ })
}

cordis.patch.yml — name must be the installed package name, id is the stable handle later patch layers target:

- insert:
    - id: hello
      name: dsh-hello
      config:
        greeting: Hello

package.json essentials: "type": "module", main/types pointing at dist/, "files": ["dist", "cordis.patch.yml"], and "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }. Without dsh.bundle.patch the package installs as a plain dependency and activates nothing.

Adding a tool

import { defineTool, type ToolRunContext } from '@deepseek-ai/dsh-tools'

ctx.tools.register(defineTool({
  name: 'hello_greet',
  description: 'Greet a person. Use when the user asks for a greeting.',

  // `parameters` is an IMPLICIT open object: write the property map directly,
  // never wrap it in { type: 'object', properties: ... }.
  parameters: {
    who: {
      type: 'string',
      required: true,          // per-property annotation; there is NO `required: [...]` array
      description: 'Name to greet.',
    },
    style: {
      type: 'string',
      enum: ['plain', 'loud'], // inline literal array infers 'plain' | 'loud' (no `as const` needed)
      description: 'Delivery style.',
    },
    opts: {
      type: 'object',
      additionalProperties: false,   // MANDATORY on every explicit object node
      properties: { times: { type: 'number' } },
    },
  },

  output: {
    schema: { type: 'string' },
    render: (_args, value) => [{ type: 'text', text: value }],
  },

  // exec.signal is a REQUIRED AbortSignal — thread it into every subprocess/fetch.
  async execute(args, exec: ToolRunContext) {
    exec.signal.throwIfAborted()
    const text = `Hello, ${args.who}!`
    return args.style === 'loud' ? text.toUpperCase() : text
  },
}))

register() returns the exact disposer; cordis calls it on unload. The reserved name run_code and duplicate names within one layer both throw. See references/tools.md for the full schema DSL, presentCall/presentResult views, finalizeContent, timeoutMs, and testing a tool directly.

Hooking an event

ctx.on('agent/session-start', ({ source }) => {   // emit mode: observe, return nothing
  ctx.logger('dsh-hello').info('session start: %s', source)
})

ctx.on('tools/pre-execute', async (exec, next) => {      // waterfall mode: MUST return next()
  if (exec.name === 'bash') return { kind: 'deny', reason: 'blocked by dsh-hello' }
  return next()                                          // ...unless deliberately vetoing
})

Event names are exact and typed — agent/step does not exist (agent/pre-step does). Listeners are fiber-owned: unload removes them, no manual disposer.

Providing a service

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

declare module '@deepseek-ai/cordis' {
  interface Context { metrics: MetricsService }   // types ctx.metrics for consumers
}

export default class MetricsService extends Service {
  constructor(ctx: Context, public config: Config) {
    super(ctx, 'metrics')      // registers ctx.metrics now; unregisters with the fiber
  }
  record(event: string, value: number) { /* ... */ }
}

Consumers write export const inject = ['metrics']. Ship the declare module block in your published .d.ts or ctx.metrics stays untyped downstream. Depth for both: references/services-and-events.md.

Verification ladder

Run in order; each rung catches a class the next cannot. node $SKILL/scripts/verify.mjs <plugin-dir> --profile web runs rungs 1-5 for you.

Rung 4 is the cheapest positive proof: defineTool() throws on a malformed schema node, and mod.Config({}) shows the exact defaults the harness hands to apply(). Rung 6 is only negative evidence that apply() ran — the default log level hides plugin info lines. Rung 7 is the only end-to-end proof: pass if the tool's rendered output appears in the printed reply. It spends real provider tokens (trivial task, once, at the end), and it requires the plugin to inject nothing web-only — injecting a service headless never provides means apply() never runs there, which just looks like "the model ignored my tool". Web-only fallback: references/install-and-verify.md §4.4.

Non-negotiable rules

1. Pin devDeps to the profile's versions. npm view @deepseek-ai/dsh-tools dist-tags → latest: 0.0.1-rc.1, but the profile runs 0.1.1-rc.2 (next tag). "*" or a bare npm i gives you a different API. Pin ^0.1.1-rc.2 / cordis ^4.0.1 / schemastery ^3.18.1. Harness packages go in peerDependencies as "*" and devDependencies pinned.
2. dsh plugin add needs -w. The profile dir is a pnpm workspace root; without -w pnpm fails ERR_PNPM_ADDING_TO_ROOT and dsh exits 1. remove does not need it.
3. Rebuild before every install and after every source edit. A directory spec installs as link: (symlink), so prepare/build never runs.
4. additionalProperties: boolean is mandatory on every explicit {type:'object'} schema node — but never write it at the parameters root, which is an implicit open object.
5. Requiredness is a per-property required: true annotation. No JSON-Schema required: [...] array. It is legal only on a key of parameters or of an object node's properties — not on items, oneOf branches, or a schema root.
6. Use type aliases, not interface, for anything returned through a {type:'json'} output node or assigned to meta. An interface has no implicit index signature and is not assignable to JsonValue. Also: no optional members — an undefined property fails a JSON node; use null.
7. ctx.effect(() => () => cleanup()) for external resources only (child processes, sockets, watchers). Everything registered via ctx is disposed automatically. Disposers run in reverse order.
8. No dsh on PATH. Invoke $HOME/.dsh/profiles/node_modules/@deepseek-ai/dsh/lib/bin.js directly, via the $DSH handle. Never DSH="~/..." — a tilde inside double quotes is not expanded. Keep node OUT of the handle: DSH="node /path" then $DSH --version breaks under zsh, which does not word-split an unquoted parameter. lib/bin.js is the package's declared bin, so it is executable on its own.
9. export const reusable / disposable / using do not exist in cordis 4.0.1. Neither does Service.start()/stop(), nor a third immediate arg to super(ctx, name). The complete module export set is name, Config, inject, provide, intercept, apply.
10. "type": "module" and files: ["dist", "cordis.patch.yml"]. Omitting the patch from files makes a published install a silent non-bundle.

Deeper reference