DeepSeek Harness under the hood: everything is a plugin, and the log is the contract
How DeepSeek Harness uses Cordis, capability seams, and a durable session log to compose an agent runtime, plus its unique design secret and a lesson for harness builders.
DeepSeek Harness (dsh) takes an unusually explicit stance on architecture: it is not “an agent with plugins,” it is a system where the agent loop, session log, model adapters, tools, and policies are all composed as plugins. That stance is powered by Cordis, a framework built around shared context, typed events, and reversible effects.
This makes dsh feel less like a single product binary and more like a runtime you assemble. The payoff is flexibility, but the deeper story is discipline: when everything is replaceable, you need strong contracts for what stays true.
Composition before behavior
A running dsh instance is built from ordered layers. Profiles (such as web, headless, SDK, ACP variants) select bundles, and bundles mount Cordis config rows and code. Patches can target rows, replace config, or insert new components. In other words, the application itself is a composed graph, not a fixed core with optional extras.
This composition model extends down into the runtime’s main subsystems:
- Session/log: append-only session events and in-memory state.
- System prompt: prompt and tool-schema assembly.
- Tools: scoped registry and guarded execution pipeline.
- Agent + agent loop: live agent interface/registry and the default driver.
- LLM seam: message/stream vocabulary and adapter interface.
Because these are services and plugins with declared boundaries, behavior can be swapped by changing composition rather than forking internals.
The turn flow as explicit events
dsh describes turns and steps in terms of durable session events and live extension points. A turn opens, input is claimed and assembled, the request is prepared and streamed, tool calls pass through pre/execute/post pipelines, results are recorded, and the turn ends when nothing is owed. Some events are durable facts in the session log; others are live waterfalls or hooks where plugins can observe or intercept.
This separation is important. Durable events answer “what happened in this session’s truth?” Live events answer “where can behavior be extended right now?” Keeping both explicit helps the system stay extensible without losing replayability.
The unique secret point: model-visible means logged
The secret at the heart of DeepSeek Harness is a strict contract: if the model can see it, the session must be able to account for it.
Architecture docs emphasize that the session log is the source of the context the model sees, and model history is derived from it. Durable settlements (messages, attempts, tool results, system/user events) are what make fork, resume, transcripts, telemetry, and replay trustworthy. Live streaming exists for UI incrementality, but the durable record is what defines reality.
This “model-visible means logged” rule is a powerful constraint. It forces the harness to treat prompt assembly, tool outcomes, and state transitions as first-class data, not incidental side effects. In a plugin-heavy system, that contract is what prevents flexibility from turning into chaos.
Capability seams make replacement practical
The other half of the story is seams. dsh frames swappable capabilities through service definitions, providers, and consumers. Filesystem, subprocess, LLM adapters, subagent providers, and policy layers can vary behind interfaces, while the rest of the system depends on the seam rather than a concrete implementation.
That is how “everything is a plugin” becomes more than a slogan. Replacing behavior is viable when the boundaries are typed, observable, and enforced by composition.
Lesson for anyone building a harness
The transferable lesson from DeepSeek Harness is: make reproducibility a contract, then build extensibility on top of it.
Plugin systems are attractive, but without strong invariants they produce debugging nightmares. dsh points to a better order of operations:
- define what must be durable and replayable (session events, model-visible context, tool outcomes),
- separate durable facts from live extension hooks,
- design capability seams so providers can change without rewriting consumers,
- and let composition wire the system instead of hiding behavior in a privileged core.
If you want a harness that can evolve, do not start by making everything configurable. Start by deciding what the system must always be able to explain. Once the log and seams are trustworthy, flexibility becomes an asset instead of a risk.
Sources
- DeepSeek Harness repository
- Architecture
- Core subsystem
- Cordis tutorial
- Event producers and consumers
- Tool execution pipeline
Weekly series
Read the posts in order:
- Adding a blog to my personal site (without starting over) - 2026-11-11
- Why PostHog is one of the first tools I add to a new product - 2026-11-18
- Anatomy of a coding harness: what makes AI coding agents work - 2026-11-11
- Context management in coding harnesses: what gets sent, and why it matters - 2026-11-18
- Goose under the hood: an MCP-native harness with a protocol at the center - 2026-11-11
- Pi under the hood: a minimal harness built around session trees and primitives - 2026-11-18
- OpenCode under the hood: one loop, many models, real environment feedback - 2026-11-11
- DeepSeek Harness under the hood: everything is a plugin, and the log is the contract (this post) - 2026-11-18
Previous: OpenCode under the hood: one loop, many models, real environment feedback