DSH (DeepSeek Harness) Architecture Deep Dive: A Composable Agent Runtime

DeepSeek Harness (DSH) is an early‑stage, developer‑preview coding agent that demonstrates a fully composable runtime where "everything is a plugin". The system maintains two parallel structures: a runtime graph that records the current set of models, prompts, tools, and sandboxes, and an event stream that logs what happened during a task. The Agent Loop walks between these two layers on each step.

What DSH Assembles

Through the Web UI you can select a model, workspace, and an Agent Preset, which together form a ready‑to‑use coding agent. Internally, the preset determines which plugins are mounted: model adapters, system prompts, tool directories, file‑system providers, shells, sandboxes, approvals, session storage, sub‑agents, the Agent Loop, and the UI. The deployment profile (e.g., web or headless) and the chosen preset ( standard, code, minimal, or cordis) decide what gets installed, and Cordis turns that configuration into a continuously running plugin graph.

Use DSH as an out‑of‑the‑box coding agent.

Use DSH as a harness runtime to assemble your own agent.

The name "Harness" is more accurate than "Code" because the visible product is just one preset; underneath lies a runtime that coordinates models, tools, state, permissions, and the host.

Comparison with Pi

Both DSH and Pi are coding agents that avoid hard‑coding all capabilities into the main loop, but they place complexity in different places. Pi keeps a very short inner loop (read, write, edit, bash) and pushes extensions into a deep TypeScript extension system. DSH adds an extra runtime‑management layer (Cordis) that tracks plugin dependencies, scopes, replacements, and graceful exits, making the system’s state explicit.

Configuration Layer: Profiles and Presets

DSH distinguishes between a Runtime Profile (e.g., web or headless) that defines how the process runs, and an Agent Preset (e.g., standard, code, minimal, cordis) that determines which tools, prompts, and services a session sees. Multiple sessions can coexist in one process, each picking its own preset while sharing the host’s persistence, model routing, sandbox, and tool registry.

dsh --profile web --dump-default-config

dsh --profile web --dump-config

Inspecting the final merged configuration (after applying bundle patches, the default cordis.patch.yml, user patches, and command‑line overrides) is often more useful than looking at the static import graph.

Runtime Graph and Provider Changes

Cordis introduces four core concepts to manage dynamic composition:

Context : defines the scope and the boundary for service resolution.

Service : a stable interface (e.g., ctx.fs) that plugins consume.

Fiber : the live instance of a mounted plugin.

inject : declares which services a fiber depends on; the fiber activates only when its dependencies are satisfied.

effect : groups listeners, timers, and handles so they can be cleaned up when the fiber unloads.

This model goes beyond a simple registration list; it answers where a plugin lives, which services it can see, when its dependencies are met, and how resources are reclaimed.

Execution Pipeline: Tool Call Flow

model emits tool call
 → Session appends tool/call
 → tools/pre-execute: allow, deny, or ask for approval
 → guards: tighten permissions
 → tools/execute: run with timeout, retry, metrics
 → tools/post-execute: check/replace results
 → finalizeContent: tool finalizes output
 → tools/result: publish immutable real‑time result
 → Session appends tool/result

When a model requests a shell command, DSH first logs tool/call in the session, runs approval and guard checks, executes the tool, records a real‑time tools/result event for plugins, and finally writes a persistent tool/result entry to the session log.

Parallel tool calls are allowed only if the tool declares itself concurrency‑safe; otherwise they are serialized to preserve the original order for replay and debugging.

Event Stream: Session Recovery

Instead of storing only a list of messages, DSH records an append‑only event log with types such as turn/start, turn/end, step/start, step/end, user/message, assistant/chunk, assistant/message, tool/call, tool/result, request/header, and any plugin‑specific events. The log separates "facts" (what actually happened) from the model‑visible surface, ensuring that everything the model can see has been logged, but not every log entry is fed back to the model.

During recovery, DSH replays the logged events, reconstructs the current surface, and marks any incomplete tool calls with TOOL_OUTCOME_UNKNOWN so that external state can be inspected before retrying.

Boundaries: Plugin, Skill, MCP

These three terms refer to distinct concerns:

Plugin : the runtime unit that declares dependencies, scopes, and cleanup logic.

Skill : a model‑consumable description of how to perform a class of task; it can be registered as a plugin but is not an external capability itself.

MCP : the protocol that connects external tools; a MCP client plugin registers remote tools under ctx.tools for the agent to use.

Together they enable a model to know *what* to do (Skill), *where* the capability comes from (MCP), and *how* the capability is integrated into the runtime (Plugin).

Four Presets: What They Change

The four built‑in presets map to four different composition levels:

Standard : a complete coding agent baseline with file access, search, shell, skills, planning, goals, sub‑agents, and workflow.

Code (PTC) : adds a Code Mode that presents tools to the model as a generated TypeScript program, which runs in a worker thread with memory limits and strict JSON‑only messaging.

Minimal : narrows the model’s view to only a few tools (e.g., workspace-write) and disables runtime context injection, useful for baseline experiments.

Cordis (Creative) : exposes dynamic inspection, definition, and execution of packages, allowing on‑the‑fly plugin experiments within the same process.

Choosing a preset depends on the verification goal: quick sanity check (Standard), reduced tool chatter (Minimal), programmatic tool orchestration (Code), or runtime composition research (Cordis).

Hands‑On Walkthrough (≈10 min)

From a project directory run npx @deepseek-ai/[email protected] web to start the Web UI at http://127.0.0.1:3080.

Configure the DeepSeek model API key in Settings → Model; the UI hot‑updates without a restart.

Write a read‑only task description, run it, and observe the logged tool/call and tool/result events.

For a one‑shot job, use the headless profile:

npx @deepseek-ai/[email protected] --profile headless "run the tests"

, which creates a temporary session, runs until idle, prints the final assistant message, and exits.

When DSH Is Worth Introducing

If you have a single model, a fixed toolset, and a stable loop, a simple plugin registry may be sufficient. DSH shines when multiple hosts share the same agent capabilities, different sessions need distinct tool sets or sandboxes, plugins must be dynamically started and stopped with proper resource cleanup, and you need clear visibility into what was actually loaded at runtime.

The trade‑off is added complexity: configuration trees, scopes, provider identity changes, and fiber lifecycles can affect behavior, and debugging requires inspecting the final merged config, the live runtime graph, and the event log.

Conclusion

DSH provides a concrete example of a composable agent runtime. By separating the "what can run now" (runtime graph) from the "what happened" (event log), it makes capability composition, replacement, and graceful exit explicit. The system still needs more large‑scale performance data and robust hot‑update testing, but the architecture offers valuable insights for anyone building long‑running AI agents.