DeepSeek Harness: Inside the 1,600-Line Model Exoskeleton

1. Core Positioning: Harness, Not Horse

DeepSeek Harness (command dsh) is an open-source agent harness — a runtime that wraps around LLMs to handle session management, tool execution, filesystem, shell, sandbox, approval, persistence, and UI. The model only reasons; the harness connects that reasoning to the real world. It is not a model, not a chat app (the Web UI is just one profile), and not an orchestration library like LangChain (which gives you parts to build your own car; dsh gives you a drivable car with hot-swappable parts). Current version: 0.1.2-alpha.1 (developer preview, MIT license).

2. Everything Is a Plugin: No Privileged Kernel

The running dsh is a plugin tree. Model adapter ( ctx.llm), tool registry ( ctx.tools), session log ( ctx.sessions) are plugins — but crucially, the agent loop itself is a plugin ( ctx.agentLoop), replaceable in whole. The underlying plugin framework is Cordis (vendored, pinned to avoid upstream drift), from the Koishi ecosystem, with a formal paper on spatiotemporal composability (arXiv:2608.25512). Five core concepts:

Plugins implement Services; lifecycle managed by framework.

Context is a service container: each service at a stable ctx.<key>, looked up by key, not import.

Dependencies declared via inject; load order derived from dependency graph.

Events are typed with five dispatch modes: emit (observe), waterfall (cascade, can short-circuit), parallel (fan-out), serial (sequential), bail (stop on bail value).

Registration is side-effect: all contributions via ctx.effect(), auto-revoked on unload. waterfall semantics: listeners receive (...args, next); calling next() delegates downstream, skipping it short-circuits. In single-decision events, short-circuit is intentional — a strategy listener can return a decision without waiting for others.

Pluginization goes further: self-modification is productized . The extensions package lets an agent inspect mounted plugins/services at runtime and mount/unmount plugins it writes itself.

Assembly Model: Profiles & Composition Packages

Profiles ( web, headless, sdk, acp) are different plugin trees assembled by the same launcher. dsh-base provides shared foundation (model adapter, tools, persistence, sandbox, approval). dsh-web-app adds browser app; dsh-headless adds one-shot runner. Configuration layers: composition packages by profile order → profile patch → home patch → --patch CLI override. dsh --profile web --dump-config prints the full config tree; web profile supports patch hot-reload.

3. Capability Seams: Swap Providers, Move Bash Entirely Into Sandbox

A seam is a fully replaceable capability composed of three roles:

Service Definition : declares interface, owns ctx.<key> (e.g., ShellExecutor abstract class).

Service Provider : implements interface (e.g., dsh-bash-local for local exec, dsh-bash-sandbox for sandbox exec).

Consumer : uses capability, typically a model-facing tool (e.g., dsh-tool-bash).

Shell capability group exemplifies this: dsh-shell defines interface, two providers implement, dsh-tool-bash consumes. Power: filesystem and process providers share the same execution world. Swapping provider from local to remote sandbox moves Bash, PTY, LSP together — consumer code unchanged. Subagent capability works similarly: provider can spawn a child agent or delegate the whole turn to another product.

4. Source Walkthrough: 1,546 Lines for the Agent Loop

Core loop lives in packages/core/agent-loop/src: index.ts: 714 lines agent.ts: 543 lines tool-calls.ts: 289 lines

Entry point (simplified):

export class AgentLoop extends Service implements AgentFactory {  // Declare five dependencies; Cordis injects via dependency graph  static inject = ['agents', 'sessions', 'llm', 'tools', 'systemPrompt']  }

AgentLoop

is a factory producing ReactLoopAgent. The "React" in the name is deliberate: source shows FiberState.UNLOADING / DISPOSED / FAILED — fiber concept borrowed from React's scheduling. Each agent is a small state machine with phases (idle, maintenance, running); input flows through an Inbox message queue (insert, discard, claim callbacks dispatch events); each agent owns a Scope for natural isolation.

Cancellation handling stands out: FactoryOwnership unifies three cancellation sources — caller cancel, host fiber unload, factory teardown — into a single AbortController. This area is notoriously leak-prone in concurrent cleanup logic.

Module JSDoc's second sentence is the design mantra: "Every request is derived from the session log." No hidden second truth in memory. maxParallelToolCalls concurrency is not hardcoded; it's wired into Settings, runtime-adjustable.

Author's view: 1,546 lines for a loop plus tool dispatch is right-sized; frameworks with tens of thousands of lines usually have unclean separation of concerns.

5. Turn Lifecycle & The Iron Law

Definitions: step = one model request + its tool calls; turn = zero or more steps, opens before claiming input, closes when no more work owed.

Typical turn skeleton (events with dispatch modes):

turn/start    claim next input + queued message  assemble prompt fragments + tool schemas  agent/pre-step  -> waterfall (reject or pass with messages)  step/start    agent/request -> llm/stream -> assistant/chunk* -> assistant/message  tool/call* -> tools/pre-execute -> tools/execute -> tools/post-execute -> tool/result*  step/end    agent/turn-stopping -> serial (ask each if should stop)  turn/end

agent/pre-step

, agent/request, llm/stream, three tools/* use waterfall (can intercept/modify). agent/turn-stopping uses serial (sequential inquiry). To add a pre-request quality gate, attach a listener to the waterfall.

Iron law: "Model visible means already recorded." Model-visible context comes from deriveMessages() projecting the session log. Log is the source of truth, not a side record — even raw assistant/chunk events stay in log for replay and faithful UI. Forking, checkpoint resume, transcript export, telemetry all derive from this event stream.

Runtime assertion enforces it: any input reaching the model request must be reconstructible from the log. Add a new model-visible input → must add corresponding session event, or assertion fails. Most frameworks rely on luck for session recovery; here it's an invariant.

6. HTTP Headers Ambition: The Data Loop

This is where a model vendor building its own harness shows. dsh-llm-deepseek adapter sends proprietary extensions to the official endpoint. HTTP headers:

user-agent: <product/version>  x-deepseek-harness-user-id: <stable anonymous UUID from Harness home>  x-deepseek-harness-session-id: <session id>  x-deepseek-harness-compact: 1  # only on compaction requests

Two dsh_ -prefixed fields in request body (outside messages, system prompt, tool schemas — no token cost): dsh_plugin_packages (default on): full inventory of live plugin packages, name+version, deduped, sorted. dsh_session_log (default off): continuous session log suffix from afterSeq to throughSeq. dsh_session_log engineering: at-least-once delivery; on 2xx response, a delivery-accepted watermark event is appended; crash retries produce duplicates, never gaps. Note: any gateway configured via baseURL receives identical values.

Intent: Anthropic has Claude Code — they close the loop on how their model is used. DeepSeek previously only had the API layer, blind to user harness interactions. Now, by building the harness, they regain that data view. dsh_plugin_packages defaults on; enabling dsh_session_log streams full session logs back (default off, relatively restrained).

User must decide: accept anonymous ID + plugin list default upload? Enable dsh_session_log or not?

7. Engineering Quality & Ecosystem Position

60+ package pnpm monorepo, ~50 capability groups under packages/. CI constraints are strict:

Coverage gate: per-file 100% , not average.

TypeScript strict + noImplicitAny; every export requires JSDoc, enforced by gate.

Snapshot tests replay recorded sessions (no API key needed); real e2e only with DEEPSEEK_API_KEY.

No hardcoded tunables — deployment differences must be cordis.yml config fields.

Non-trivial changes require Agent Note; agent-loop changes must sync architecture docs.

Nice touch: CLAUDE.md is a symlink to AGENTS.md — human and AI contributors read the same rules.

Ecosystem: not reinventing wheels. hooks package bridges Claude Code and Codex hooks; concepts map 1:1 (system prompt, tools, subagent, skill, plan mode, todo tool). Skill package is a directory loader akin to Claude Code Skills. Capability groups reveal positioning: sandbox (bwrap, Landlock, Seatbelt — cross-platform Linux/macOS), workflow (with workflow and ralph tools), session-query (SQLite full-text search), subagent (experimental Agent Teams). Plugin ecosystem aggregates via GitHub dsh-plugin topic.

Author's judgment: not competing with LangChain; provides an open reference implementation for coding-agent products. Teams building their own coding agent can treat its architecture docs as a ready-made design reference, avoiding many detours.

8. Cold Water: Don't Bet Production on It Yet

All caveats from official docs:

Developer preview : 0.1.2-alpha.1, breaking changes coming, no security audit, not production-ready.

Sandbox ≠ security boundary : sandbox, approval, permissions reduce risk but don't block all damage. Run in throwaway VM/container, least privilege, backup important files.

Privacy telemetry on by default : anonymous user-id, user-agent, plugin package list sent to DeepSeek endpoint. Enabling dsh_session_log expands upload to working directory, system prompt snapshot, user/assistant content, tool args/results (API keys excluded).

Session format volatile : SESSION_FORMAT_VERSION still 0; backend may reject old data at any time.

Bottom line: read source, use as reference, run experiments — all fine; hand over critical environments — wait.

Summary

DeepSeek Harness is an open-source agent harness: the model's exoskeleton, offloading everything the model can't do (sessions, tools, shell, sandbox, approval, persistence). Architecture pushes pluginization to the extreme — even the agent loop is a plugin. Implementation keeps the core loop at ~1,500 lines, recoverability backed by invariants not luck. Strategically, the wire-protocol extensions reveal the model vendor's motive: closing the data loop back to the model side.

Worth attention? Depends. Building your own coding agent or seriously studying agent architecture — this repo deserves close reading; its architecture docs are clearer than most commercial products'. Using it in production today — risk outweighs reward.