DeepSeek Harness Open‑Source: A Fully Pluggable AI Agent Framework Backed by a Formal Paper

Core Design: Everything Is a Plugin

Model, tools, UI, storage, security policies, context management, and even the Agent Loop are all pluggable. Harness runs as a Cordis Context; packages register services, events, capabilities, assembled via configuration into a runnable agent.

The repository contains over 230 workspace members across packages/, apps/, examples/, python/, native/. Each capability (filesystem, shell, subprocess, terminal, language server, web access, skills, sub‑agents, workflow) lives in its own package.

Four Preset Modes

Web UI offers four modes built from the same host:

Standard : full‑featured coding agent with file editing, shell, search, sub‑agents, workflow.

PTC : retains standard abilities and adds Code Mode, allowing the model to write TypeScript that performs multiple steps in a single run_code call, reducing round‑trip latency.

Minimal : only persistent Bash and str_replace_editor tools, suited for straightforward coding tasks.

Creative : agents can inspect the current plugin tree and dynamically mount or unmount temporary plugins, akin to swapping a car engine on the highway.

Security Policy

Default workspace‑write mode confines command execution and file modifications to the current workspace, with an ask‑approval policy for privilege escalation. It follows a “fail‑closed” rule: if isolation cannot be verified, execution is rejected.

Multiple Entrypoints and Three‑Layer Architecture

Besides the Web UI, Harness provides a TUI, headless script/CI mode, and ACP/JSON‑RPC/Python SDK. All share the same core capability model and session event semantics, assembled into different product shapes via bundles.

The project splits typical capabilities into three layers: interface, implementation, consumer. For example, the Bash interface defines “execute command”; the local implementation creates the process; the model‑oriented tool package translates the capability into a schema the model can understand. Replacing the local shell with a remote container or cloud sandbox only requires swapping the implementation layer.

This design decouples the framework from any specific runtime environment; models, tool implementations, UI, and even the Agent Loop can be exchanged.

Quick Start

With Node.js installed, run a single command: npx @deepseek-ai/dsh web The Web UI defaults to http://127.0.0.1:3080. Building from source:

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

The preview release may introduce breaking changes; the team promises rapid iteration.

The Cordis Paper: A Programming Paradigm for Spatiotemporal Composability

The accompanying paper formalizes Harness’s design. It first builds a theory of reversible effects (temporal composability) and reactive coeffects (spatial composability), then assembles an operational calculus with proofs, and finally maps the theory to engineering implementation.

Problem: Lack of Mathematical Foundations for Dynamic Composition

Two orthogonal dimensions are identified:

Temporal composability : after a component is unloaded, every modification it made to the shared environment must be fully reversible.

Spatial composability : components must be able to declare, discover, and validate dependencies, reacting to changes in the dependency topology.

Static scenarios map to lexical scope and module import resolution, but dynamic runtime composition requires handling long‑lived stateful effects and runtime‑only dependencies.

The paper uses VSCode extensions as an empirical case: 87 % of 100 popular extensions contain executable code, yet hot‑unloading is unsupported and dependency declarations are scarce, illustrating the need for a more robust model.

Theoretical Core: Reversible Effects and Reactive Coeffects

Reversible effects turn any impure function into a pure representation by expressing side‑effects as state transformations with a left‑inverse. A “witnessed effect function” returns the new state together with an on‑the‑spot inverse, enabling precise rollback even when effects are interleaved.

Independence of effects is proved: if a set of effects are pairwise independent (their transformations commute), any order of rollback restores the initial state, supporting arbitrary component interleaving.

Reactive coeffects model dependencies as keyed partial‑function tables. Components declare required keys; the runtime monitors key changes to activate or deactivate components. Isolation and interception mechanisms allow per‑realm bindings and metadata‑driven constraints without modifying component code.

Dynamic Composition Calculus

Components are modeled as triples (dependency spec, provision set, witnessed effect function). Fibers represent instantiated components with lifecycle state. The active‑fiber set forms the coeffect context.

The calculus defines five primitive operations: insert, retire, remove, load, unload, assuming atomic, instantaneous, failure‑free transitions. Subsequent sections relax these assumptions to address real‑world concerns:

Evacuation : split deactivation into marking and waiting for dependents before applying the accumulator.

Iteration : effect functions become iterators that can be paused, matching async generators.

Asynchrony : introduce a Future abstraction with inertia—once started, it must complete, though the target may change.

Failure : errors trigger the unload path, rolling back applied effects while allowing sibling fibers to continue.

Meta‑theorems

Preservation : all ten rules maintain registry well‑formedness.

Temporal Composability : independent effects can be precisely reversed even after other fibers have mutated state.

Spatial Composability : dependents must activate after providers; bindings remain stable during a dependent’s episode; each transition iterates over a single resolution.

Progress : without circular dependencies the system cannot deadlock and eventually reaches a quiescent state.

Confluence (key result): regardless of insertion/removal order or runtime scheduling, the final state is isomorphic to the state obtained by a single static assembly with no unloads.

Confluence guarantees that a system continuously adding, removing, and replacing components converges to the same configuration as if the final configuration were written from scratch, freeing developers from reasoning about intermediate scheduling.

Implementation in Cordis

The paper maps mathematical symbols to concrete APIs such as ctx.effect, ctx.get/set, fiber.state, fiber.dispose. All context mutations go through ctx.effect, which drives an execute engine that folds inverses into an accumulator.

Co‑effects use a two‑level lookup (realm then binding). Notification traverses fibers to check key matches; isolation and interception create derived contexts that are discarded wholesale on disposal.

Component lifecycle is driven by three mutually recursive functions: refresh (detects target changes), reload (commits view, executes effects, verifies target), and unload (waits for dependents to become inactive then runs the accumulator). These correspond to the three ordering guarantees proved in the theory.

The loader’s declarative configuration (id, url, isolate, intercept, config, disabled) leverages the meta‑theorems: Confluence ensures final state depends only on configuration, Progress guarantees convergence, Terminal Recovery guarantees clean removal, and Ordering removes the need for manual load ordering.

Hot Module Replacement follows a three‑stage algorithm: mark accepted/declined sub‑graph, traverse entry dependency trees, and perform transactional reload with backup and rollback, all without developer‑specified acceptance boundaries because fibers already define complete effect and coeffect scopes.

The paper validates the model with Koishi, a four‑year‑old chatbot framework with 4000+ community plugins, demonstrating cross‑runtime applicability (server and web console) and automatic dependency handling.