Inside DeepSeek Harness: How a Modular Agent Architecture Enables Plug‑in‑Based AI Agents

DeepSeek Harness builds its runtime on the open‑source Cordis framework, a meta‑framework for modern JavaScript applications that provides dependency injection, scoped services, and lifecycle cleanup.

Why Cordis

Cordis predates DeepSeek Harness and is used by the Koishi chatbot framework, which demonstrates a plugin‑centric model similar to agents. DeepSeek vendors Cordis as @deepseek-ai/cordis and makes every internal package a peer dependency, constructing the entire product on Cordis.

Three common plugin forms are compared:

Traditional DI containers suffer from unmanaged unbinding, inability to hot‑replace dependencies, and static configuration read only at startup.

Lightweight hook systems lack dependency injection and proper unload hooks.

Cordis solves these gaps with a cordis.yml file where each line defines a plugin instance; editing the file triggers hot‑module replacement (HMR).

Pi’s Extension model lacks dependency injection, dependency management, and unload hooks, making Cordis’s reversible side‑effects a distinct advantage.

Fiber and Effect: Foundations of Reversible Side Effects

In Cordis a plugin is one of three types:

type Plugin<T> = Plugin.Function<T> | Plugin.Constructor<T> | Plugin.Object<T>

Plugins are mounted via ctx.plugin(plugin, config), which creates or reuses a Runtime record and spawns a Fiber. Fibers have six states (PENDING, LOADING, ACTIVE, FAILED, DISPOSED, UNLOADING). Declared dependencies (e.g., inject: ['tools', 'shell']) keep the fiber in PENDING until the services become available, then transition to ACTIVE.

Side effects are registered through ctx.effect(() => { …; return () => { /* undo */ } }). The callback runs immediately; the returned disposer is pushed onto a disposables stack. On unload, disposers are executed in reverse order, guaranteeing LIFO cleanup.

Example plugin (session logger) registers an event listener and a timer, with a disposer that clears the timer and unsubscribes the listener:

export const name = 'session-logger'
export function apply(ctx) {
  ctx.effect(() => {
    const off = ctx.on('tool/result', event => appendToLog(event))
    const timer = setInterval(flushBuffer, 1000)
    return () => {
      clearInterval(timer)
      off()
    }
  })
}

When the plugin is mounted, the effect callback executes immediately, and the disposer is stored. Unloading the plugin runs

disposables.splice(0).reverse().forEach(dispose => dispose())

, first clearing the timer then removing the listener.

Constraints and System Boundaries

All framework capabilities ( ctx.on, ctx.provide, ctx.plugin, ctx.use) funnel through ctx and internally wrap ctx.effect. ctx is a Proxy, intercepting all ctx.foo = x assignments for tracking.

Each fiber’s state machine rejects effect creation on an inactive fiber, throwing CordisError INACTIVE_EFFECT.

Transactional HMR backs up module state; on import failure the whole reload rolls back, preventing partial states.

Operations outside the tracked boundary (global variables, public files, etc.) are considered outside and are not reversible.

Service Resolution via Proxy and Fiber Chain

Accessing ctx.tools, ctx.llm, or similar triggers the Proxy’s get trap, which walks up the fiber chain until it finds a service implementation or throws an error. Services are registered via self.ctx.reflect.provide(name, self, check), which also uses ctx.effect for automatic cleanup.

DeepSeek defines an llm service interface and provides two implementations ( dsh-llm-deepseek and dsh-llm-pi-ai) that can be swapped without changing the agent loop code, illustrating the “design verification twin” concept.

Agent Loop Design Details

Turns can end via a concludesTurn: true flag from a tool, not just model output.

Max‑token termination is sticky; once a turn ends due to token limits, later steps cannot overwrite that reason.

An agent/turn-stopping event lets plugins inject additional messages before the turn truly ends.

Tool execution mode is determined per call; concurrency‑safe tools run in parallel, others enforce exclusive execution.

Pre‑execute, post‑execute, and protection stages are separate, registerable events, allowing new approval or safety policies without touching core code.

Two‑Layer Preset Scope

Presets allow a configuration directory ( agent.cordis.yml) to be mounted once and reused across many sessions. The first layer creates a real Fiber via ctx.plugin(scope); the second layer records a logical parent relationship in a WeakMap, avoiding new Fiber nodes. This enables fast reuse of a standard preset instance for writing, coding, or research sessions.

Preset selection scans the event log for the latest agent-preset/selected event, falling back to the session header default.

Code Mode Isolation

Model‑generated code is executed in a Node worker_threads environment rather than a vm sandbox, providing a truly isolated V8 heap and the ability to terminate the worker on timeout or resource limits ( resourceLimits.maxOldGenerationSizeMb). The code is first stripped of TypeScript types, preserving line numbers, then wrapped in an async function with injected bindings for tools, error classes, and a console shim.

Communication between the worker and host uses a simple message protocol ( {type:'call',…} / {type:'reply',…}), and tool calls from the worker go through the same pre‑execute / protection / dispatch / post‑execute pipeline as normal tool calls.

Tool Registration Masking Algorithm

Each scope maintains a ToolLayer map. Visibility is computed by loading the global layer, then overlaying ancestors (nearest first), applying any restriction rules, and finally the current scope’s own registrations, which always win. Registration itself is an effect, so uninstalling a plugin automatically removes its tools.

The name run_code is reserved and cannot be overridden, preventing conflicts with the Code Mode transport.

Comparisons with Codex

The core loop in DeepSeek Harness is a replaceable factory ( ReactLoopAgent), whereas Codex’s loop is fixed.

Sandbox implementation: DeepSeek uses a worker thread plugin, Codex uses a separate V8 isolate.

Module granularity: DeepSeek splits into >200 TypeScript packages, Codex into ~100 Rust crates, but DeepSeek’s modules are all replaceable.

Tool exposure: Codex marks visibility statically; DeepSeek computes it dynamically per scope, allowing the same tool to be visible in some presets and hidden in others.

Practical Implications

The reversible effect system turns “unload” from a manual cleanup task into a framework guarantee, enabling hot‑module replacement, zero‑downtime production updates, self‑evolving agents that can roll back faulty modifications, and atomic failure handling without residual state.

Presets solve the problem of reusing the same plugin tree across different use‑cases, while Code Mode reduces round‑trip latency for multi‑step tasks by letting the model orchestrate tool calls directly in code.

“Future harnesses will generate and deploy modifications to their own components while serving requests continuously. Without a reversible side‑effect model, a faulty self‑modification could destroy the only recoverable process.”

Images illustrating the architecture, plugin lifecycle, session logger example, and full process flow are included below.