Everything Is a Plugin: The Capability-Seam Architecture Behind DeepSeek Harness

DeepSeek Harness turns the agent runtime into a composition of swappable capability seams, where definitions, providers, and consumers are wired through Cordis reversible effects, so every extension is a plugin rather than a core patch. That sentence is the design claim behind dsh, DeepSeek’s developer-preview harness for agent harness developers, and this guide for NiteAgent readers walks the claim through the official documentation, the architecture guide, the capability-seams doc, and the public repository.

Why DeepSeek Harness is a plugin architecture

DeepSeek Harness states its model as “Agent = Model + Harness” and carries the tagline “Everything is a Plugin,” with models, tools, skills, sessions, sandboxes, storage, loops, scheduling, and UI all listed as swappable capabilities, according to the DeepSeek Harness official announcement, which notes that dsh is in developer preview with source included.

The DeepSeek Harness plugin architecture is not a metaphor. The Cordis kernel manages plugin mounting, unmounting, and dependencies, and agent capabilities live in plugins that are selectable, swappable, and extensible in configuration without touching dsh source, per the same DeepSeek Harness official page. The quick start is npx @deepseek-ai/dsh web, or you can clone the repository directly.

The repository metadata supports the scale of that framing. The project describes itself as “DeepSeek Harness: Everything is a Plugin,” is MIT licensed, and showed 238.7k stars, 28.7k forks, 20,283 commits, and 24 tags as observed on 2026-09-28 at the DeepSeek Harness GitHub repository, with a release commit of release(dsh): 0.2.0-rc.1 the same day. Community plugins are discoverable through the GitHub topic: dsh-plugin.

The Cordis kernel: revertible effects and reactive coeffects

The Cordis kernel manages plugin mounting, unmounting, and dependencies, and the Cordis paper by Shi, Zhang, and Cui from Peking University and DeepSeek-AI defines temporal composability and spatial composability through revertible effects and reactive coeffects, submitted 26 Aug 2026 under cs.PL and cs.SE, per the Cordis paper on arXiv.

Temporal composability is about ordering: a plugin’s contribution can be layered on top of an existing runtime and later unwound without residue. Spatial composability is about adjacency: several plugins sit side by side in one shared context and agree on who owns what. The paper’s two mechanisms, revertible effects and reactive coeffects, unify those two axes in a context paradigm with observational equivalence, and its implementation pairs a core library with a declarative component loader that does config reconciliation and HMR, per the Cordis paper on arXiv.

The architectural consequence in dsh is the phrase “no privileged core to patch.” Plugins contribute services, typed events, and reversible effects to a shared context; the model adapter, tool registry, session log, and agent loop are themselves plugins, and registrations are effects that unwind on unload, per the DeepSeek Harness architecture docs. Nothing in the core needs editing to add a capability.

Capability seams: definition, provider, consumer

ADR 0009 describes capability seams as three separated concerns: a contract definition, an implementation provider, and a consumer API, where seam authors own the ctx.* key and consumers depend on the definition rather than any provider package, while ADR 0010 covers twin LLM adapters, per the Capability seams docs.

The ownership rule is the load-bearing one. The definition package owns its ctx.* key outright, so no provider or consumer may mint that key or reach around it. The dependency rule follows: a consumer declares a dependency on the definition package only, never on a provider package, which is what makes provider replacement a config edit instead of a code change.

The seam doc also ships a generated authoritative graph that draws every seam, its owning package, its implementations, and its direct consumers. Two shapes appear as reference points: ctx.subprocess is a tight hub where many consumers crowd one owner, and ctx.sessionTelemetry is a thin seam whose output leaves the process, per the Capability seams docs.

The canonical three-role split is concrete. dsh-shell is the Service Definition, a Cordis service plus Bash request and result types; dsh-bash-local is the Provider that runs on the local machine; dsh-tool-bash is the Consumer, a model-callable tool with inject = ['shell']. Provider and consumer depend only on the definition, and a provider swap replaces one cordis.yml row while the definition and tool stay unchanged, per the Official practice guide: three-role example.

Profiles, bundles, and the patchable boot tree

A running dsh is a plugin tree composed from ordered layers, where a profile names bundles in the Harness home alongside out-of-tree plugins and a user cordis.patch.yml, and patches apply in bundle, profile, home, then --patch order, per the DeepSeek Harness architecture docs.

A profile is a named composition living in the Harness home. It lists its bundles, holds out-of-tree plugins, and keeps a user cordis.patch.yml. Shipped profile templates are web, headless, sdk, sdk-minimal, and acp. Package manifests declare the relationship with two keys: dsh.profile for a profile’s bundles and dsh.bundle for a bundle’s patch file.

A bundle is the distribution format for Cordis config rows plus the code those rows mount, and rows stay patchable by later layers. The shared first layer is dsh-base, carrying model adapters, tools, persistence, sandbox and approval policy, settings, credentials, and telemetry. App layer bundles are dsh-web-app, dsh-headless, dsh-sdk-app, and dsh-acp-app, while dsh-sdk-minimal is the exception that owns its complete explicit SDK tree and does not apply dsh-base, per the DeepSeek Harness architecture docs.

Patch order is deterministic: each bundle in listed order, then the profile’s cordis.patch.yml, then a home-level patch, then any --patch overlay. A patch targets a row by id and either replaces its entire config or inserts new rows. Hot reload is config-controlled rather than global: base enables config-only dsh-hmr, headless, SDK, and ACP disable it, and sdk-minimal omits it. The command dsh --profile web --dump-config prints the boot tree, and any printed row can be patched.

At a glance: capability seams and runtime shapes

Each capability seam in DeepSeek Harness has a contract owner, at least one provider, and consumers that bind at runtime, so swapping a provider is a configuration edit rather than a source patch; the table below summarizes eight seams and their swap points, drawn from the Capability seams docs.

Capability Contract owner (definition) Example provider Example consumer Swap point
Model adapter ctx.llm contract in dsh-base dsh-base model adapters agent loop replace one cordis.yml row
Tool registry ctx.tools contract in dsh-base dsh-base tool registry dsh-tool-bash and other tools add or remove tool rows
Shell execution dsh-shell Bash request/result types dsh-bash-local dsh-tool-bash replace @deepseek-ai/dsh-bash-local row
Session persistence session store contract in dsh-base dsh-base persistence SessionPersistence methods: create/open/stat/list/export replace persistence row
Skills skills contract in dsh-base dsh-base skills plugins standard mode skill tool add or swap plugin rows
Sandbox / approval policy sandbox contract in dsh-base dsh-base sandbox and approval policy execution tools replace policy row
Subagents ctx.agents contract dsh-base subagent scheduling dsh-background-agents replace or add subagent row
Telemetry ctx.sessionTelemetry contract dsh-base telemetry session log swap telemetry row

Build your own seam: TypeScript definition, provider, and consumer

Building a capability seam means writing three packages plus three config rows: a definition that owns the ctx.myCap key, one provider implementing it, and one consumer mounted behind ctx.tools, which matches the cookbook path of definition plus one provider plus one consumer, per the Extension cookbook.

The procedure is the same for a new capability, a new provider, or a new consumer. For a new capability, author the definition, then one provider, then one consumer. For a new provider, implement the existing interface and register it in cordis.yml. For a new consumer, depend on the definition and mount the tool behind ctx.tools. Start with the definition package, which owns the key and the request and result types:

export abstract class MyCapService extends Service {
  constructor(ctx: Context) {
    super(ctx, 'myCap')
  }

  abstract execute(request: MyCapRequest): Promise<MyCapResult>
}

// MyCapRequest / MyCapResult types are declared in this same package.

Next, the provider package implements that abstract class and registers itself as a plugin:

export const name = '@you/my-cap-local'

class MyCapLocal extends MyCapService {
  async execute(request: MyCapRequest): Promise<MyCapResult> {
    // local implementation
  }
}

export default class extends Service {
  apply(ctx: Context) {
    ctx.plugin(MyCapLocal)
  }
}

Finally, the consumer exposes the capability to the model as a tool, declaring both the tool registry and the capability as injectable dependencies:

class MyCapTool extends Service {
  static inject = ['tools', 'myCap']

  constructor(ctx: Context) {
    super(ctx, 'myCapTool')
    ctx.tools.register(defineTool({
      name: 'my_cap',
      description: '...',
      parameters: {
        // zod/JSON schema
      },
      output: {
        // schema
      },
      render: (r) => {
        // display
      },
      execute: async (req) => ctx.myCap.execute(req),
    }))
  }
}

Mount all three as rows, keeping the provider row isolated so a future swap touches exactly one line:

- name: '@you/my-cap-definition'
- name: '@you/my-cap-local'      # swap this row to change providers
- name: '@you/my-cap-tool'

Session tracing and the four runtime modes

DeepSeek Harness writes an append-only session log recording everything the model sees, including system prompts, reasoning, tool calls and results, subagent scheduling, and context injections, with trajectory, resume, fork, search, and replay all operating on that same event stream, according to the DeepSeek Harness official announcement.

Because the log is append-only, inspection and mutation are separate concerns. The trajectory view reads the stream by source, so you can attribute each entry to the prompt, the reasoning trace, a tool call, a subagent schedule, or a context injection. Resume, fork, search, and replay all operate on that same event stream, which means a fork is a new head over identical history rather than a copied file.

The four runtime modes differ by what is mounted. Standard carries the full toolset: file editing, shell, file and web search, skills, planning, goals, subagents, and workflows. Code exposes capabilities through the Code Mode SDK so the model composes multi-step operations in a single TypeScript program. Minimal is a two-tool coding agent with persistent bash and str_replace_editor, intended for model benchmarking. Creator is Standard plus runtime inspection, in-memory plugin experiments, and preset-authoring guidance, per the DeepSeek Harness official announcement. Skills are ordinary artifacts too: a committed dsh-code-review skill lives under .agents/skills in the repository, per the dsh-code-review skill in repo.

FAQ

These five questions cover what DeepSeek Harness is, what the plugin claim actually covers, how a capability seam divides work, how providers swap in configuration, and what revertible effects and reactive coeffects contribute, with each answer drawn from official sources such as the DeepSeek Harness official pages.

What is DeepSeek Harness exactly?

DeepSeek Harness is a developer-preview agent harness for harness developers with source included, published under the tagline “Everything is a Plugin” and the framing “Agent = Model + Harness,” runnable via npx @deepseek-ai/dsh web or a repository clone, per DeepSeek Harness official.

What does the phrase “everything is a plugin” cover?

It covers models, tools, skills, sessions, sandboxes, storage, loops, scheduling, and UI, all selectable and swappable in configuration through the Cordis kernel, and community entries are curated in awesome-deepseek-harness and the GitHub topic: dsh-plugin, where dsh-background-agents scopes tools per child and dsh-team-rooms keeps a shared task board.

How does a capability seam split responsibilities?

The definition owns the ctx.* key and declares the contract, the provider implements that contract, and the consumer exposes it to the model, with consumers depending only on the definition and never a provider package, as described in Capability seams docs.

How does provider swapping work in configuration?

A patch targets a config row by id and replaces its whole config or inserts new rows, so swapping shell execution means replacing the @deepseek-ai/dsh-bash-local row with another package implementing the same service while the definition and tool stay unchanged, per the Official practice guide: three-role example.

What do revertible effects and reactive coeffects give me?

They give temporal and spatial composability in a shared context paradigm with observational equivalence, so registrations unwind when a plugin unloads and there is no privileged core to patch, a result stated at abstract level in the Cordis paper on arXiv without an empirical evaluation.

The Bottom Line

Treating every capability as a seam-backed plugin lets you change models, tools, persistence, sandbox policy, and scheduling through configuration rows in an ordered boot tree, which is the practical payoff of the DeepSeek Harness architecture docs for anyone shipping a production agent harness.

The working pattern is narrow and repeatable: define the contract and own the ctx.* key, implement one provider behind that contract, mount one consumer that depends only on the definition, then keep everything patchable by id in cordis.yml so later layers can replace any row. Start from dsh --profile web --dump-config, read the printed boot tree, and treat every row as an extension point rather than fixed plumbing. That is the whole DeepSeek Harness plugin architecture in one habit.

How This Guide Was Built

This guide is desk research over official documentation and the public repository only. The scope statement and a note on what is not established follow, alongside entry points such as the DeepSeek Harness docs index and the DeepSeek Harness developer docs home for SDK, CLI, and config reference.

This guide was built as desk research on official DeepSeek Harness documentation, the architecture guide, the capability-seams doc, the practice guide, the arXiv paper, and the public repository; the author did not run dsh, benchmark it, or install it.

What is not established, and is not asserted here: no performance overhead figures for effect revert, coeffect resolution, or plugin-tree boot cost; no authoritative plugin ecosystem count; no named production adopters or deployment case studies; the full contents of ADR 0009 and ADR 0010 were not supplied; the Cordis paper’s formal result is stated at abstract level only with no empirical evaluation; no versioning, semver, or stability policy for Service Definitions; and no sandbox or approval policy security details beyond dsh-base naming. Third-party commentary claiming “95,000 stars in 2 days” or “4,000+ plugins over four years” is unverified and is explicitly not presented as fact in this guide.

Related coverage and reference material live on the NiteAgent blog.

Related guides

← Back to all posts