DeepSeek Harness Deep Dive: Everything Is a Plugin, Even the Agent Loop

Overview

DeepSeek Harness (dsh) v0.1.0-rc.5 is presented as an open, locally-assemblable Agent runtime substrate in which "everything is a plugin, even the Agent Loop." The official framing is Model + Harness = Agent: the model is the horse, the harness is the saddle. The codebase is a 49-package TypeScript monorepo (~1,981 TS files, ~198k lines) under MIT, with npx @deepseek-ai/dsh web as the default launcher on http://127.0.0.1:3080. Node ≥ 22.19 is required.

Core Architecture: Cordis Micro-Kernel + Plugin Galaxy

The runtime is built on Cordis, a plugin meta-framework originating in the Koishi ecosystem and grounded in the paper *A Programming Paradigm for Spatiotemporal Composability* (jointly authored by Peking University and DeepSeek researchers). A running dsh instance is fundamentally a Cordis Context in which all capabilities—model adapters, tools, session logging, sandbox/permissions—are registered as services, events, and effects, then composed via a cordis.yml configuration.

Configuration composes through a four-layer pipeline (bundle → profile patch → home patch → --patch) using last-write-wins semantics by id. The dsh --dump-config command synthesizes and prints configuration without starting the runtime or evaluating !!js expressions—configuration is runtime state with no drift.

Three load-bearing mechanisms underpin the system:

1. Session log as the single source of truth: Turn/Step events are logged; deriveMessages() projects the model view as a pure function. The agent-loop invariant stringifies and compares the outgoing request against the log-derived reconstruction on every dispatch, failing on mismatch. 2. Waterfall interception surface: Tools and Agent decisions flow through tools/pre-execute → tools/execute → tools/post-execute → tools/result plus tools/code-dispatch-log. Every listener must explicitly call next(); hooks, approval, permissions, sandbox, and timeout all hang on the same waterfall. 3. Capability Seam: Replaceable capabilities are specified as service definition / service provider / consumer (model-facing tool), enabling execution-world abstraction—filesystem and subprocess share one provider, and pointing the provider at a remote sandbox migrates Bash/terminal/LSP wholesale with zero consumer changes.

Four Operating Modes

The four modes—Standard, Code (PTC), Minimal, Creator—are preset combinations defined in apps/cli/config/agent-presets/, not independent subsystems:

• Standard: full toolset (file editing, shell, search, skills, plan, subagent, workflow).
• Code/PTC: standard + tool-presentation mode:code, which collapses wired tools to a single run_code so the model can write a TS program that orchestrates multiple calls in one round.
• Minimal: persistent bash + str_replace_editor only, with includeRuntimeContext:false.
• Creator: standard + tool-cordis plus authoring skills, enabling runtime introspection and preset composition.

Code-level corrections to common claims:

• "Creator mode lets the Agent rewrite its own Harness" is half-true: cordis_* provides seven tools (cordis_define, cordis_run, cordis_stop, cordis_undefine, cordis_inspect_list|query|self). Dynamic packages are immutable in memory only—lost on process restart. Pure host-half activation requires no approval; only client-half unprivileged packages trigger await-approval. "Self-modification" means in-session temporary addition/version swap plus writing new presets to disk via tool-fs (requires remount). There is no hot-swapping of the currently loaded composition.
• "No privileged core" is true but bounded: the Cordis service layer uses a whitelist facade and forbids service returns of Context (denyContext), but host-half node:vm is self-described as "not containment"—OS-level isolation depends on packages/sandbox. A "factual core" persists at the contract-semantics layer (ctx.* keys, agent/* events, SessionEvent types, waterfall dispatch).
• "Long-term memory / adaptive context compression ACP / causal graph retrieval" is roadmap only: only CompactionEngine and BasicCompactionEngine are implemented. The claim has no trace in v0.1 code or docs.

Multi-Agent Orchestration

dsh's multi-agent layer follows a hierarchical Supervisor–Worker model with strict parent↔child communication and no sibling or peer-to-peer primitives (maxDepth:3 by default). Four mechanisms are provided:

• Spawn (subagent-spawn-in-process): fresh-context child, inheritsParentContext=false, no seed.
• Fork (subagent-fork-in-process): one-time snapshot of parent's completed events prefix, inheritsParentContext=true.
• Ralph (tool-ralph): hardcoded JS loop with structured-output children per iteration; requireFreshProvider forces spawn-only.
• Workflow (tool-workflow): model-authored JS executed in a worker-thread vm.Context with no fs/net/timer; exposes agent/parallel/pipeline/phase/log/args hooks.

The ctx.subagents registry is a named provider interface. Six providers ship: spawn, fork, claude-code (Anthropic Agent SDK CLI), codex (codex app-server stdio), acp (any ACP subprocess, permission defaults to reject), and dsh-sdk (full dsh runtime via TS SDK). Only spawn/fork are enabled by default—Claude Code and Codex can be delegated through the same subagent tool via opt-in. This unification is architecturally significant but is not a Swarm: repository-wide greps for swarm/self-organ/blackboard/peer-to-peer/negotiat return zero matches in orchestration code.

Unified Event Stream and Observability

SessionEventMap defines the event boundaries: Turn contains zero or more Steps; a Step is one model request plus tool calls. The invariant model-visible means logged is enforced mechanically: before each llm/stream dispatch, agent-loop/src/invariant.ts compares options.messages against session.deriveMessages() via JSON.stringify and fails on divergence.

• Fork: deep-copies the source session's prefix events as child seed.
• Resume: consumes the full stored log.
• Replay/retrieval: read the same SessionEvent stream.
• Crash repair: repair.ts synthesizes TOOL_OUTCOME_UNKNOWN / TOOL_NOT_STARTED for orphaned tool calls and produces step/end and turn/end{interrupted} events.

A repository-level Trajectory view (no single service named Trajectory exists) is composed from surface + request/header + session-query + ui-trajectory, with user/message.source distinguishing user|plugin|model|tool and plugin carrying ContextForm (instructions/catalog/snapshot/notice/relay/recall).

Sandbox: OS-Level, Not Application-Level

Sandboxing is OS-enforced, not "self-disciplined":

• Windows: CreateRestrictedToken (DISABLE_MAX_PRIVILEGE | LUA_TOKEN | WRITE_RESTRICTED) via native FFI; fails closed.
• Linux: Landlock via @deepseek-ai/node-addon-landlock-run, or bwrap with --ro-bind / / --die-with-parent.
• macOS: Seatbelt (sandbox-exec SBPL).

Comparative Positioning

| Dimension | dsh (Plugin-Centric) | Claude Code | Codex | Anthropic Managed Agents | |---|---|---|---|---| | Kernel | Privileged-free microkernel (Cordis) | Closed-source monolith | Rust monolith + CLI/cloud | Decoupled Agent/Environment/Session | | Multi-Agent | Hierarchical Supervisor–Worker | Sub-agent delegation | Sub-agent / sandbox | Managed, externally orchestrable | | External delegation | Same SubagentProvider accepts claude-code/codex/acp | Itself delegated to | Itself delegated to | Aligned via ACP | | In-situ scripting | Yes (workflow JS in vm, no fs/net) | No | No | No | | Stability layer | Contract-semantics "factual core" | Product itself | Closed source | Public interface (wake/emitEvent) | | License | MIT, model-agnostic | Closed-source commercial | Open-source CLI + closed cloud | Cloud service component |

dsh is a Concrete-harness (implementation provided, replaceable); Managed Agents are Meta-harness (interface defined, implementation open). They are not substitutes—a dsh Loop is a replaceable service, and a Managed Agents provider that implements wake/emitEvent can run on dsh; conversely, Managed Agents can be absorbed as a dsh Subagent. The real competition is at the ecosystem standard layer: whoever defines the de facto event semantics and interface shape owns the stability layer.

Risks and Strategic Reading

Five structural costs come with deep plugin boundaries, especially in v0.1:

1. Interface stability: the contract-semantics factual core (ctx.* / agent/* / SessionEvent) must not move or the ecosystem breaks; README explicitly flags breaking changes ahead. 2. Dependency management: 49 packages, high migration cost for early adopters. 3. Performance overhead: waterfall interceptors, event-projection logging, cumulative cost on long tasks. 4. Debugging complexity: errors scatter across plugins, requiring Trajectory replay to localize. 5. Ecosystem governance: external PRs are not currently accepted; community plugin quality and cross-version stability are unproven.

Strategically, dsh and the DeepSeek model are softly complementary: the default adapter routes to DeepSeek, but no hard binding exists. This echoes DeepSeek's open-weight strategy—commoditize the complement so demand flows to the best model. The trade-off: MIT + model-agnostic seams mean competitors can integrate at zero cost, so the harness cannot become a model moat. The architecture leaves room for commercial differentiation as a closed Bundle on the open core—an open-core model of "open platform + private cloud Profile." Concurrent signal: V4-Pro released the same day, with the V4-Pro API price rising ~4.6× from 2026-08-16—razor-and-blade: give away the runtime, charge for inference.

Key points

• dsh v0.1.0-rc.5 is verified at the source-code level as a privileged-free, plugin-centric Agent runtime built on Cordis, with model-agnostic adapters and MIT licensing.
• The four modes are preset compositions, not separate systems; Creator mode allows in-memory dynamic package definition and new-preset authoring, but not hot-replacement of the running composition.
• Multi-agent orchestration is hierarchical Supervisor–Worker; Claude Code/Codex/ACP/dsh-SDK can all be plugged into the same SubagentProvider interface, but Swarm primitives are absent.
• Observability is mechanically enforced: session events are the single source of truth, and model-visible means logged via an agent-loop invariant.
• Sandbox isolation is OS-enforced (Landlock/Seatbelt/Windows restricted tokens); the host-half node:vm sandbox is self-described as "not containment."
• Long-term memory, adaptive context compression ACP, and causal graph retrieval are roadmap items only—only CompactionEngine is implemented in v0.1.
• dsh occupies a Concrete-harness position versus Anthropic's Meta-harness; the competitive battleground is the ecosystem stability layer.
• Commercial strategy is open-core: open MIT runtime + closed cloud Bundle, paired with a ~4.6× V4-Pro API price increase from 2026-08-16.

References

• Repository: github.com/deepseek-ai/deepseek-harness (v0.1.0-rc.5, MIT)
• Cordis framework: Koishi ecosystem; paper *A Programming Paradigm for Spatiotemporal Composability* (Peking University × DeepSeek)
• Concurrent model release: DeepSeek V4-Pro (2026-08-13); V4-Pro API price change effective 2026-08-16
• Detailed code citations: see local report files deepseek-harness-research/report-{甲,乙,丙,丁}.md