DeepSeek Harness Redefines Agent Framework with OS‑Level Architecture (6 K★ Overnight)

DeepSeek Harness Overview

DeepSeek Harness (code‑named dsh) is an open‑source MIT‑licensed agent runtime framework built on the Cordis meta‑framework. Its core claim is that every component must be replaceable without affecting others, eliminating a privileged kernel.

Architecture and Replaceability

The configuration tree can be inspected with: dsh --profile web --dump-config Any entry in the printed tree can be overridden via a patch file, allowing component swaps without source changes.

Layered Design (OS Analogy)

dsh‑base : model adapters, tool registry, persistence, sandbox, approval policies, settings, credentials, telemetry.

dsh‑web‑app (browser UI) or dsh‑headless (CLI runner).

Profiles are named plugin compositions. Configuration is applied in four non‑conflicting layers: official baseline → company standard → project customization → personal preference. Upgrading the baseline never touches custom layers.

Package Landscape

core/session : append‑only session event log.

core/system-prompt : prompt and tool‑schema assembly.

core/tools : scoped tool registry and execution pipeline.

core/agent : agent interface and registry.

core/agent-loop : default agent driver implementation.

llm/llm : message/stream vocab and adapter interface.

Runtime Modes

Standard : full tool set for everyday use.

PTC (Programmatic Tool Calling): model generates code that composes multi‑round tool calls.

Minimal : only a shell tool and a file‑edit tool for bare‑metal model benchmarking.

Creative : inspect the current runtime, experiment with Cordis plugins in memory, and create new modes.

Cordis Core Concepts

Plugin as Service : a function or class with optional inject and apply(ctx) fields.

Context as Service Container : services live in a stable ctx (e.g., ctx.tools, ctx.llm).

Inject for Dependency Declaration : a plugin declares required services; the runtime waits for them before starting.

Typed Events for Communication : services register event names via TypeScript and emit, waterfall, parallel, or serial dispatch.

Registration as Reversible Side‑Effect : prompts, tool schemas, adapters, listeners are installed via ctx.effect() or ctx.on() and are automatically torn down on unload.

Event Dispatch Modes

emit : non‑awaited, listeners observe in registration order, no return value.

waterfall : non‑awaited, listeners observe in registration order, returns a value; implements middleware where a listener receives (...args, next) and must call next() to continue.

parallel : awaited, all listeners run in parallel, no return value.

serial : awaited, listeners observe in registration order, returns a value.

Mathematical Guarantees (Five Theorems)

Preservation : each transformation preserves system invariants (e.g., no leftover timers after unload).

Exact Recovery : after a component is removed, the environment returns precisely to its pre‑component state.

Ordering & Resolution Consistency : dependencies activate before dependents; once a component starts loading, its implementation never silently swaps.

Progress : an acyclic dependency graph guarantees no deadlock; each component has a bounded number of transformation steps, ensuring eventual quiescence.

Confluence : independent operations converge to the same final state, enabling hot‑updates and zero‑downtime upgrades.

Four‑Year Production Validation

Koishi, a cross‑platform chatbot framework with >4,000 plugins, runs on Cordis v3. DeepSeek Harness uses Cordis v4 with a simpler composition rule and a redesigned loader. In Koishi, disabling a plugin automatically removes its scheduled tasks, demonstrating reversible side‑effects.

Seam Concept (Ability‑Level Plug‑Points)

More than twenty seams (e.g., filesystem, process execution, sandbox, approval, credentials, storage, search, sub‑agent) each consist of:

Service Definition : declares the interface.

Service Provider : implements the interface.

Consumer : typically a model‑oriented tool that uses the service.

Two concrete swaps:

Local ↔ Cloud : replacing filesystem and process execution providers with an E2B cloud sandbox moves Bash, PTY, and LSP to the cloud without changing any tool code.

Storage & Retrieval : session persistence can switch between JSONL and SQLite; storage can be JSON or SQLite; telemetry can be OpenTelemetry; search can toggle among Exa, Perplexity, DeepSeek. Application code remains unchanged.

Session Log as Truth

The append‑only session log records every observable event (system prompts, reasoning chains, tool calls, sub‑agent scheduling, context injections). The runtime enforces the invariant:

Model‑visible means logged.

If any information reaches the model without a corresponding log entry, an alarm is raised. Derived capabilities include: fork: branch a new session from any historical node.

Restore: exact replay of any session state.

Search: query across historical sessions.

Replay: re‑execute any point in time.

Transcription: export a full textual record.

Telemetry: cost, latency, token usage are fully measurable.

Event System Domains

Session Events : persistent, append‑only facts that survive reloads.

Agent Events (agent/*) : carry live agent references for observation or interception.

Ability Events : allow attaching strategies or adapters to a seam without entering the loop.

Waterfall events require an explicit next() to continue; serial events have no next, encoding who may interrupt the flow.

Runtime Self‑Evolution

Plugins can be installed, updated, rolled back, or removed while the process is running:

define → run → update → rollback → undefine

Versioning is asset‑level: each plugin ID maps to immutable package IDs (read‑only snapshots). Licensing can be scoped to a single version or all future versions. Failed updates never silently corrupt the previous version; manual rollback is always possible. New host‑side code runs in an isolated VM sandbox; the browser UI accesses the same services via a remote namespace.

Reversible Side‑Effect Discipline

Every registration (service, event, tool, timer, UI, theme) lives on its own fiber. Unloading a plugin automatically disposes all its side‑effects, preventing “hot‑update leaves half‑dead state” problems.

Enterprise Deployment Handbook

Compositional Configuration : configuration is a stack of layers—official baseline, company standard, project customization, personal preference—applied in order without conflict. The dsh --profile web --dump-config command reveals the effective tree; any entry can be overridden with a custom patch.

Dual Runtime Plane : shared infrastructure (persistence, sandbox, approval stack, model routing, sub‑agent registry) lives in the Host composition ; per‑session contributions (tools, personas, prompts) live in an agent preset isolated from other sessions, enabling distinct capabilities for different customers without separate codebases.

Parametric Security Governance : sandbox modes (read‑only, workspace‑write, full‑access), configurable approval policies, one‑click permission presets that toggle sandbox and approval together, and credential seams that separate references from actual secrets, allowing seamless key rotation.

Hard Engineering Details (Selected Organs)

Spill Overflow : oversized tool output automatically overflows to storage, providing a pointer for the model instead of truncating.

Model‑Free Tool Result Trimming : before context compression, a replayable node replaces overly long tool results, saving token budget.

Cold‑Read Ladder : session lists are read via checkpoint + tail replay, keeping even ten‑thousand‑session lists responsive.

Typert Type‑Safe RPC : Zod runtime type registration + API gateway bind generated remote descriptors to live services, ensuring end‑to‑end type safety.

Long‑Session Cost Governance : token accounting, pressure‑triggered auto‑compression, goal‑driven multi‑round continuation, and resumable execution keep long‑running tasks affordable.

Parallel Orchestration Engine : workflow scripts run in independent threads, fanning out tasks to dozens of sub‑agents and aggregating results.

Frontend as Plugin Tree : the browser UI itself is a plugin graph supporting hot updates without recompiling the whole product.

Interoperability Era

Six backend types (spawn, fork, ACP, Codex CLI, Claude Code, DSH SDK) can be invoked mid‑session and seamlessly reintegrated into the log, preserving an uninterrupted audit trail. The Agent Client Protocol (ACP) provides a bidirectional transport layer, exposing DSH agents to any programmatic client and allowing external agents to act as “employees”. Model adapters support DeepSeek by default and any OpenAI‑compatible endpoint, with immediate effect upon configuration change.

Installation & Getting Started

Prerequisites: Node.js (latest LTS) and optionally pnpm for source builds. npx@deepseek-ai/dsh web Default server runs at http://127.0.0.1:3080.

Source installation:

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

Inspect or modify the configuration tree:

# Print the full plugin tree
 dsh --profile web --dump-config
# Apply a custom patch
 dsh --profile web --patch ./my-patch.yaml

Writing Your First Plugin

import { Context } from 'cordis'

export function myPlugin(ctx: Context) {
  ctx.effect(() => {
    // Effect: register a timer
    const timer = setInterval(() => {
      console.log('tick')
    }, 1000)
    // Inverse operation executed on unload
    return () => {
      clearInterval(timer)
    }
  })
}

Practical Rules (From Official Docs)

Encapsulate behavior as plugins: tools belong to ctx.tools, streaming LLM output to ctx.llm, real‑time agent coordination to ctx.agents.

Prefer events for interception and strategy; use direct service methods for capability calls.

Every registration must have a disposer—either returned from ctx.effect() or handled by Cordis helpers.

If teardown order matters, place related work in the same effect to guarantee correct release sequencing.

Pitfalls

Developer preview: the project is marked as a fast‑moving preview; breaking changes are expected.

MIT license permits commercial use, but future API changes may require adaptation.

Ecosystem maturity: third‑party plugins exist (e.g., scheduled tasks, self‑evolution), but the ecosystem is still nascent.

References

https://github.com/deepseek-ai/deepseek-harness

https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.zh.md

https://deepseek-harness.github.io/deepseek-harness/reference/cordis-primer

https://github.com/cordiverse/cordis

https://github.com/cordiverse/paper