We Read DeepSeek Harness: What 453K Lines of Agent Runtime Actually Say

Two weeks ago, the DeepSeek Harness was a footnote in the V4-Flash benchmark config: "to be released soon." As of 2026-08-13 it is public. deepseek-ai/deepseek-harness landed on GitHub under MIT, and @deepseek-ai/dsh is live on npm at 0.1.0-rc.6 - one npx @deepseek-ai/dsh web gets you a local web UI on port 3080.

Launch posts will tell you what DeepSeek says it is. We cloned the repo and read the code. This is what it actually is, the three patterns worth stealing for your own agent stack, and the gaps the announcement will not mention.

What dsh actually is#

dsh is not a CLI wrapper around a chat API. It is a full agent runtime - session log, agent loop, tool scheduler, sandbox, web UI, SDK - built as roughly 453,000 lines of TypeScript across about 219 workspace packages (measured on our clone, as of 2026-08-13). The architectural bet, stated in the README, is that everything is a plugin: the model adapter, the tools, the persistence layer, the agent loop itself, and even the web UI are all mountable plugins on Cordis, a plugin/event-bus framework whose design paper the README cites.

DeepSeek did not just depend on Cordis - they source-vendored a fork of it. The vendor/ directory pins cordis 4.0.0-rc.7 (a pre-release upstream version) with 18 logged local patches, renamed into the @deepseek-ai scope so the harness "fully owns its framework layer," in the words of vendor/README.md. That makes DeepSeek the flagship production consumer of the Cordis paradigm, and it also means every future upstream release is a merge exercise against a patched fork.

Composition works in layers, per docs/architecture.md: a profile lists bundles, each bundle is an npm package carrying a config patch, and layers apply in order to an empty root - bundle patches, then the profile's patch, then the home-level patch, then --patch overlays. There is no privileged core to configure around; you replace any row the boot prints with a patch of your own.

Three patterns worth stealing#

1. "Model-visible equals logged" as a runtime invariant#

Most agent frameworks treat their session log as a best-effort record. dsh makes it load-bearing. Every message the model can see must be reconstructable from the append-only session log, and this is enforced at runtime, not by convention: at every LLM dispatch, an invariant in packages/core/agent-loop/src/invariant.ts asserts that the outgoing request's messages byte-match session.deriveMessages(), the projection derived from the log. One layer down, packages/core/session/src/surface.ts throws at append time if a message-producing event arrives without a surface marker saying how it projects into model history.

The payoff is that replay, forking, resume, debugging, and the UI all derive from one artifact, and "what did the model actually see" is never a reconstruction exercise. The cost is real too: the check serializes the full message history twice on every production dispatch. DeepSeek decided auditability was worth that hot-loop tax, and we think they are right.

2. Keyless transcript replay, where the fixture is input and expected output#

The testing story is the part we would port tomorrow. dsh commits real recorded session logs as fixtures, then derives a deterministic mock model from them: the replay harness in packages/test-support/llm-replay splits recorded assistant chunks into per-stream scripts and fails the test if a fixture is underrun. The clever half is in examples/headless-agent/tests/headless.snapshot.ts: the same committed .jsonl log is both the replay input and the expected output. The test boots the real agent subprocess against the mock, lets the full loop-tools-persistence chain run, then diffs the freshly persisted log against the fixture after normalization.

One artifact, two roles - no API keys in CI, no flaky LLM-as-judge for regression coverage, and any drift in the loop's behavior shows up as a log diff. Three modes (replay, record, refresh) make re-baselining a one-flag operation. This composes naturally with pattern 1: the replay trick only works because the log provably contains everything the model saw.

3. A fail-closed sandbox ladder#

Tool execution resolves a sandbox policy per call (read-only, workspace-write, danger-full-access) and confines commands by argv wrapping: Linux probes bubblewrap then falls back to a native Landlock launcher, macOS uses seatbelt, Windows uses a write-restricted token. The detail that matters is the failure mode: if a confined mode is requested and no backend is usable, packages/sandbox/sandbox/src/index.ts throws SANDBOX_UNAVAILABLE and refuses to run the command unconfined. A missing approval service likewise means denial, never a hang.

Escalation is designed as model UX, not just enforcement: the bash tool's description teaches the model that a denial is a policy outcome, and that the sanctioned response is one same-turn retry with a wider sandbox_permissions plus a one-sentence justification, which raises the approval prompt that is the user's actual consent. The code is also honest where the sandbox is weak: the Windows backend documents that reads, network, and process visibility stay unrestricted. Confinement there is "token-limited," not sandboxed, and the source says so.

What it signals about the V4 line#

The harness is the first-party consumer of DeepSeek's models, so its DeepSeek adapter is worth reading as a statement of intent. The default catalog in packages/llm/llm-deepseek/src/index.ts ships exactly two models, deepseek-v4-flash and deepseek-v4-pro, and the defaults in packages/llm/llm-deepseek/src/adapter.ts set DEFAULT_CONTEXT_WINDOW = 1_000_000 and DEFAULT_MAX_TOKENS = 256_000 - a 1M-token context window with a 256K output cap, with reasoning effort levels off, high, and max. Those numbers are what DeepSeek's own tooling assumes about V4, as of 2026-08-13.

The interoperability posture is also legible from the package tree: hook bridges for Claude Code and Codex ship in packages/hooks/, and MCP support is client-only - dsh consumes MCP servers, it does not present itself as one.

The honest gaps#

BENCHMARK.md is a 3-line stub. A heading, and a pointer to the Python SDK guide for running your own tasks. No methodology, no scores, no SWE-bench, no eval harness anywhere in the tree. An AI lab shipped an agent runtime with zero evaluation claims - read that as restraint or as a gap, but either way you are benchmarking this yourself. Given that V4-Flash's launch numbers were produced with this harness's minimal mode, we expected the eval tooling to be the headline. It is absent.

The history is one commit. git rev-list --count HEAD returns 1: the entire estimated two months of internal development arrived as one squashed merge of PR #2519, "feat/npm-public," opened and landed on release day. No review trail, no blame, no archaeology for contributors. The 1,372 bilingual decision records in .agents/notes/ - an RFC corpus written by and for the agents that built this - partially compensate, but a squash this size is a contributor-hostile way to open a project.

It is a preview, and it behaves like one. The README warns in bold that there will be compatibility-breaking changes. The repo sits at 0.1.0-rc.5 while npm serves rc.6, the license flipped from BSD-3-Clause to MIT mid-release-candidate, and the Python SDK on PyPI is versioned 0.0.0.dev0 - a stdio driver around a bundled Node executable, not a runtime port. Nothing here is stable enough to build a product on this quarter.

The takeaway#

The harness core - the logging doctrine, the replay-driven testing, the fail-closed sandbox - is some of the most disciplined agent-runtime engineering we have read, and all three patterns port to any stack without adopting dsh itself. What DeepSeek did not ship is everything above the loop: no eval tooling, no artifacts surface, no session sharing, no metering. The runtime layer is now open-source table stakes. The competition moved up a floor.

Continue Reading#

• DeepSeek V4 Flash 0731: The Budget Tier Just Overtook Pro Preview on Agent Benchmarks - the release where this harness was still "to be released soon," and the benchmark config it ran
• Agent Sandbox Architecture: How to Choose the Right Runtime Boundary - how other runtimes draw the same confinement ladder dsh implements
• Agent Replays with TraceTrail: Loom for Agent Runs - the replay-and-observability problem dsh solves with its session log
• DeepSeek V4: The Developer's Guide to Flash and Pro - the models this harness is built to drive
• Loop Engineering: How to Design Agent Loops That Actually Converge - the turn/step loop design space dsh's agent-loop package sits in

Sources#

• deepseek-ai/deepseek-harness - GitHub (cloned and read 2026-08-13, HEAD 47f9438)
• docs/architecture.md - profile/bundle/patch composition
• BENCHMARK.md - the 3-line stub
• @deepseek-ai/dsh - npm (version 0.1.0-rc.6 as of 2026-08-13)
• Cordis - cordiverse (the vendored framework, pinned at 4.0.0-rc.7)