DeepSeek Harness: A Fully Pluggable Agent Runtime Built on Cordis

Why DeepSeek Harness Is Not a End‑User Coding Assistant

Developers who have built Agents often hit a wall: the framework’s built‑in loop, tool execution flow, and session storage work smoothly in demos but become brittle in real‑world use. DeepSeek Harness (CLI command dsh), released on 2026‑08‑13 under the MIT license, answers this by removing any single "kernel" and exposing every Agent capability as a replaceable plugin.

Four Run Modes Reveal the Intent

Standard : the full toolset for a coding Agent, the default for most users.

PTC (Programmatic Tool Calling): lets the model write TypeScript to call tools instead of sending structured tool‑call messages.

Minimal : only bash and editor tools are loaded, intended for benchmark experiments.

Creative : allows custom Agent presets and runtime inspection of internal state.

The Minimal mode exists essentially as a statement: the platform is meant for researchers who need a controllable baseline, not for end‑users who just want a "two‑tool" scoring bot.

Writing a Plugin Is Just an apply Function

A Harness plugin is a TypeScript module that exports an apply function receiving a Context object. The framework calls apply during loading, and the plugin registers its abilities through the context.

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

export const name = 'hello-plugin'

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

The framework does not require init or destroy hooks; cleanup is automatic. Resources registered via ctx (event listeners, tools, timers) are reclaimed when the plugin unloads. If a plugin holds external resources unknown to the framework, it can register a teardown with ctx.effect():

export function apply(ctx: Context) {
  ctx.effect(() => {
    const timer = setInterval(() => console.log('heartbeat'), 5000)
    return () => clearInterval(timer)
  })
}

Dependencies are declared with an inject array, guaranteeing that required services are available before the plugin runs, eliminating the need for defensive checks such as if (!ctx.tools) return.

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

export function apply(ctx: Context) {
  ctx.tools.register(/* ... */)
}

Object‑oriented or class‑based plugins are also supported for cases where a plugin must expose services to other plugins.

Event System: Five Dispatch Semantics Determine How Deep You Can Plug In

ctx.emit()

– synchronous dispatch, ignores return values (pure notification). ctx.parallel() – runs all listeners concurrently, resolves after all settle (independent side‑effects). ctx.serial() – awaits listeners in order, stops on a bail (ordered processing chain). ctx.bail() – calls listeners sequentially, stops when a non‑null/false/undefined value is returned (intercept / short‑circuit). ctx.waterfall() – each listener receives a next function; calling it continues the chain, not calling it vetoes (middleware / wrapper pattern).

The waterfall semantics are the most expressive, mirroring the onion model used by Koa or Express middleware, allowing a plugin to modify behavior before and after a call or to cut the chain entirely.

Listeners are registered with ctx.on() or ctx.once(), both returning a disposer. EventOptions offers two important switches: prepend (insert before existing listeners) and global (receive events regardless of context filtering).

Tool Execution Pipeline: Three Waterfalls Enable Fine‑Grained Control

A tool call passes through a series of water‑fall stages:

tools/pre-execute → monotonic guards → tools/execute → tools/post-execute → finalizeContent → tools/result

Each waterfall can rewrite the call once. In practice, you can adjust parameters before execution ( pre‑execute), replace the entire implementation ( execute), or tamper with the result before it reaches the model ( post‑execute and tools/result). Approval logic is placed before the monotonic guard, while owner policies are registered as immutable guards, ensuring that safety checks cannot be reordered.

Provider Configuration: Immutable IDs and Physical Credential Isolation

Model providers can be selected from built‑in DeepSeek, cloud services (Anthropic, OpenAI, AWS Bedrock, Google Vertex, Azure, Codex), or a custom provider defined by an ID, base URL, API protocol, credentials, and at least one model. Provider IDs are permanent; changing a name requires creating a new ID and deleting the old one, preserving the integrity of session replay logs.

API keys are stored in $DSH_HOME/.credentials.yaml and referenced from settings.yaml, allowing the settings file to be safely committed to version control without exposing secrets.

When adding a custom provider, the input field in settings.yaml must explicitly declare supported modalities (text, image) because the framework cannot auto‑detect them.

Capability Seams: Swappable Implementations Without Code Changes

The architecture classifies services into three categories: fixed core services, pluggable capability seams, and composable packages/bundles. A capability seam defines an interface whose implementation can be swapped without altering consumer code. Examples include ctx.llm (model implementations), ctx.subprocess, ctx.shell, ctx.fs, and ctx.web. The system enforces uniqueness and integrity when registering implementations.

Append‑Only Logs and Trajectory View: Making Debugging Possible

Every model interaction is recorded in an append‑only session log containing prompts, reasoning chains, tool calls, and sub‑Agent scheduling. The accompanying Trajectory view lets developers trace the exact execution path. This design is essential for answering questions like “what did the model see at step 7?” and for performing regression testing via replay.

State is split into two namespaces: session/event (persistent, replay‑able facts) and agent/* (real‑time control state). Work is divided into turn (full task) and step (single model request), with events attached at various points (e.g., turn/start, agent/pre-step, llm/stream, tool/execute, turn/end).

Compression plugins (e.g., dsh-compaction-basic) run before the request is sent, while agent/request-error handles overflow. Retry logic only triggers a new turn if compression or summarisation actually advances the state, preventing endless costly retries.

Key Takeaways for Teams Building Agents

Assess whether the framework’s extension points are sufficient before judging feature completeness; a simple emit hook is far less powerful than a full waterfall middleware system.

Append‑only logs and replay capabilities are a debugging baseline; storing the exact input seen by the model at each step pays off when troubleshooting.

Immutable provider IDs and non‑reorderable guards are design disciplines that trade flexibility for trustworthiness.

Reusing a mature plugin system (Cordis) avoids reinventing dependency injection, lifecycle, and event‑bus mechanisms.

DeepSeek Harness is still in developer preview and may undergo breaking changes. Its higher entry cost is justified for teams that need a long‑term, fork‑free runtime where deep customisation points are explicitly exposed.