DeepSeek Harness (dsh): an Open-Source, Plugin-Composed Agent Runtime
The first two product case studies were managed harnesses you rent. DeepSeek Harness is the opposite bet: an MIT-licensed harness you own, where the model adapter, tools, sessions, sandboxes, storage, the agent loop and even the UI are all swappable plugins on the Cordis framework, and every model-visible fact is written to an append-only session log. This visual deep dive takes it apart from its repository and documentation — with interactive diagrams and a runnable miniature of its two core ideas.
01 What Is DeepSeek Harness (dsh)?
DeepSeek Harness, dsh for short, is an open-source agent harness from DeepSeek AI: the software between a language model and the outside world that supplies tools, sessions, sandboxing and the loop that keeps a task moving. DeepSeek released v0.1 as a developer preview on 13 August 2026 under the MIT licence, built on Node.js/TypeScript. Its one core idea: everything is a plugin.
npx @deepseek-ai/dsh web.02 The System Boundary: dsh vs External Systems
Unlike the managed harnesses, there is no vendor-operated side: you run dsh, and it talks to models and tools you choose.
dsh web)dsh headless)or direct library use
· subprocess
03 High-Level Architecture
Layers, top to bottom: user surfaces pick a profile; the profile composes bundles on the Cordis plugin runtime; core harness plugins (session log, system prompt, agent loop, tool registry) plus an LLM provider plugin form the harness; execution, MCP, storage and other plugins provide capabilities. Press play:
04 Profiles and Bundles
A running dsh instance is composed from a profile, which lists the bundles it stacks, any out-of-tree plugins it installs, and the user's own cordis.patch.yml. Most profiles stack an app bundle on dsh-base; sdk-minimal deliberately doesn't. Pick one:
05 Cordis: "Everything Is a Plugin"
Cordis is the plugin framework beneath dsh: plugins contribute services, typed events and reversible effects to a shared context. It grew out of the Koishi chatbot framework, built by the developer known as Shigma (Yifan Shi), and describes itself as a "meta-framework of spatiotemporal composability" — formalized with DeepSeek and Peking University researchers in A Programming Paradigm for Spatiotemporal Composability (arXiv:2608.25512). Two properties make hot-swapping safe:
A runnable miniature of both core ideas — reversible plugin effects and an event-sourced session:
"""A miniature of the two ideas at the heart of DeepSeek Harness (dsh), in plain Python.
1. Cordis-style plugins: every effect a plugin registers (a service, an event listener, a tool)
comes with a disposer; unloading the plugin runs its disposers in reverse order, so the
system returns exactly to its previous state. That is what makes hot-swapping safe.
2. An event-sourced session log: an append-only list of events is the source of truth; the
messages sent to the model are *derived* from it, so a turn can be replayed or forked.
This is a teaching model, not dsh's TypeScript code. Standard library only.
"""
class Context:
def __init__(self):
self.services, self.listeners, self.tools = {}, {}, {}
def load(self, plugin):
disposers = []
def effect(do, undo): # every change carries its inverse
do(); disposers.append(undo)
plugin(self, effect)
return lambda: [undo() for undo in reversed(disposers)] # unload = revert in reverse
def state(self):
return f"services={sorted(self.services)} tools={sorted(self.tools)} listeners={sorted(self.listeners)}"
def deepseek_adapter(ctx, effect):
effect(lambda: ctx.services.__setitem__("llm", "deepseek-v4.1-flash"), lambda: ctx.services.pop("llm"))
def openai_adapter(ctx, effect):
effect(lambda: ctx.services.__setitem__("llm", "gpt-6-astra"), lambda: ctx.services.pop("llm"))
def shell_tools(ctx, effect):
effect(lambda: ctx.tools.__setitem__("shell", "run commands"), lambda: ctx.tools.pop("shell"))
effect(lambda: ctx.listeners.__setitem__("tool/call", "audit"), lambda: ctx.listeners.pop("tool/call"))
ctx = Context()
print("start: ", ctx.state())
unload_model = ctx.load(deepseek_adapter)
unload_shell = ctx.load(shell_tools)
print("after loading: ", ctx.state(), "->", ctx.services["llm"])
unload_model(); ctx.load(openai_adapter) # hot-swap the model adapter
print("model swapped: ", ctx.state(), "->", ctx.services["llm"])
unload_shell()
print("shell unloaded: ", ctx.state())
# ── event-sourced session ──
log = [
{"type": "turn/start", "turn": 1},
{"type": "user/message", "text": "Investigate the failing service"},
{"type": "step/start", "step": 1},
{"type": "assistant/message", "text": "Checking pods.", "tool_call": "shell: kubectl get pods"},
{"type": "tool/result", "tool": "shell", "status": "ok", "output": "api-7f 0/1 CrashLoopBackOff"},
{"type": "step/end", "step": 1},
{"type": "assistant/message", "text": "The api pod is crash-looping; reading its logs next."},
{"type": "turn/end", "turn": 1},
]
def project(events):
"""Derive the model-visible messages from the log (the log is the only source of truth)."""
msgs = []
for e in events:
if e["type"] == "user/message": msgs.append(("user", e["text"]))
elif e["type"] == "assistant/message": msgs.append(("assistant", e["text"] + (f" [{e['tool_call']}]" if "tool_call" in e else "")))
elif e["type"] == "tool/result": msgs.append(("tool", e["output"]))
return msgs
print(f"\nsession log: {len(log)} events -> {len(project(log))} model-visible messages")
for role, text in project(log): print(f" {role:<10} {text}")
fork = log[:5] + [{"type": "user/message", "text": "Actually, check the database first"}]
print(f"\nfork at event 5: {len(fork)} events; last derived message -> {project(fork)[-1]}")
print("replaying the same log always yields the same messages:", project(log) == project(list(log)))Output:
start: services=[] tools=[] listeners=[]
after loading: services=['llm'] tools=['shell'] listeners=['tool/call'] -> deepseek-v4.1-flash
model swapped: services=['llm'] tools=['shell'] listeners=['tool/call'] -> gpt-6-astra
shell unloaded: services=['llm'] tools=[] listeners=[]
session log: 8 events -> 4 model-visible messages
user Investigate the failing service
assistant Checking pods. [shell: kubectl get pods]
tool api-7f 0/1 CrashLoopBackOff
assistant The api pod is crash-looping; reading its logs next.
fork at event 5: 6 events; last derived message -> ('user', 'Actually, check the database first')
replaying the same log always yields the same messages: TrueSwapping the model adapter leaves every other plugin untouched, and unloading the shell plugin removes both its tool and its audit listener — nothing leaks. The session half shows why dsh can resume, fork and replay: the model's messages are a pure function of the log.
06 Turns, Steps and Events: the Agent Loop
In dsh a step is one model request plus the tools it calls; a turn is zero or more steps — it opens before its first input is claimed and closes once nothing is owed. The default driver is the core/agent-loop plugin. Watch a turn emit its events:
07 Durable, Event-Sourced Sessions
The session log is append-only and is the source of truth for all agent state; session history — including the messages sent to the model — is derived from it, not stored separately. Its guiding invariant is "model-visible means logged": a runtime check verifies that every model request can be reconstructed from the log. Failed, retried and cancelled attempts are kept too (assistant/attempt). Logs are JSONL files (session.vN.jsonl, optionally zstd-compressed) behind a pluggable SessionPersistence interface.
08 Capability Seams
Each swappable capability is a seam with three roles: a service definition (the interface), one or more service providers (implementations) and consumers. Pick a seam and swap its provider — the consumers never change:
| Core service | Package | Context key |
|---|---|---|
| Session log | core/session | ctx.sessions |
| Prompt assembly | core/system-prompt | ctx.systemPrompt |
| Tool registry | core/tools | ctx.tools |
| Agent registry | core/agent | ctx.agents |
| LLM adapter | llm/llm | ctx.llm |
| Webhooks | webhook/webhook | ctx.webhookRuntime |
09 The Tool Runtime
Tools are plugins that register typed definitions with ctx.tools. Each call passes through validation, permission and policy checks, runs under an execution mode with timeouts, and returns a result that the loop can use — failures included. Pick a call:
dsh-base.10 MCP Architecture (Optional)
dsh can connect to external MCP servers, whose tools are registered in the same tool runtime under server-qualified names such as mcp__github__create_issue. But no MCP server is enabled by default: the MCP client ships as a dependency, and you enable servers deliberately — because each server command is trusted executable code that runs outside the agent sandbox.
11 SDK and Automation Entrypoints
The sdk profile serves SDK clients over newline-delimited JSON-RPC on stdio until shutdown or disconnect; clients exist for TypeScript and Python (deepseek-harness-sdk on PyPI) and any language that speaks JSON-RPC. The acp profile runs an automation-only Agent Client Protocol server that reserves stdout for ACP frames.
12 dsh vs the Managed Harnesses
| Aspect | DeepSeek Harness (dsh) | Claude Agent SDK / Managed Agents | OpenAI Agents API |
|---|---|---|---|
| Who runs it | You (self-hosted) | You (SDK) or Anthropic (Managed) | OpenAI (managed) |
| Licence | MIT, full source | SDK distributed as a library; Managed Agents is a proprietary service | Proprietary service |
| Models | Any, via model-adapter plugins | Claude | OpenAI models |
| Extensibility | Every capability is a swappable plugin | Tools, MCP, hooks, subagents, skills | Tools, MCP, environments |
| Session model | Append-only JSONL log; messages derived | Append-only session log (Managed) | Durable sessions, events/items |
| Maturity | Developer preview (breaking changes) | SDK GA; Managed Agents public beta | Public beta |
| You operate | Everything: hosting, security, upgrades | SDK: runtime; Managed: app only | App, tools, optional environment |
13 End-to-End Example: Investigate a Failing Service and Prepare a Fix
dsh-base. An append-only JSONL session log is the single source of truth, from which everything the model sees is derived and checked. Security defaults are conservative — no MCP servers until you enable them, sandbox and approval policy in the base bundle — but the operational burden is yours. It is the clearest reference implementation of the harness ideas in this series, and, as a developer preview, not yet a stable platform.Next: Product case studies #4–#11 — Foundry, ADK, LangChain, CrewAI, Temporal, E2B, Browserbase and AgentCore compared.
⚠️ Notes
session.start, model.response.delta, tool.result); dsh's documented durable events use slash names — turn/start, step/start, user/message, assistant/message, tool/call, turn/end — and files are named session.vN.jsonl (optionally zstd); (2) profiles — it treats sdk-minimal like the others, but it is the one profile that does not stack dsh-base; (3) MCP — "no MCP server enabled by default" is correct, and the reason matters: server commands are trusted code running outside the agent sandbox; (4) the package families panel is a reasonable summary of the repository's layout, but individual package names change quickly in the preview — rely on the repository. Launch-star figures are one tracker's reported counts; interactive diagrams are simplified and the Python miniature is a teaching model.