How DeepSeek Harness Turns an Agent Runtime into a Plugin System

Why the Runtime Matters

Most agent frameworks follow the same loop—model output → tool call → execution → feed result back—so the core logic is becoming indistinguishable. DeepSeek Harness shifts the focus to the runtime: how plugins are mounted, how services are isolated, how tools can be swapped without stopping the service, and how side effects are safely rolled back.

Everything is a plugin is the keyword used by Harness. Model integration, tool execution, session recording, the Agent Loop and even the Web UI are all treated as plugins. The goal is not merely to create another tool‑calling agent but to build a runtime that can continuously assemble, hot‑update, and replace components.

Why Harness Chooses Cordis

Cordis is a modern JavaScript plugin framework originally created for chat‑bot platforms like Koishi. It provides dependency injection, scoped services, lifecycle cleanup and dynamic composition. Traditional DI containers can bind services but struggle with elegant hot replacement and complete cleanup—who unbinds a service when a LLM provider changes? Lightweight hook systems are simpler but often leave resources uncleared on unload.

Cordis treats each plugin as a component with declared dependencies, a lifecycle, and reversible side effects, solving the classic problem of adding, replacing, or removing components while a runtime continues serving requests.

Fiber and Effect: Reversible Side Effects

When a plugin is mounted, Cordis creates a Fiber that acts as a state machine with states PENDING, LOADING, ACTIVE, FAILED, DISPOSED and UNLOADING. A plugin declares its dependencies, e.g. inject: ['tools', 'shell'], causing the Fiber to stay in PENDING until those services appear. Only then does the plugin code execute.

The crucial mechanism is ctx.effect(). Inside an effect you register listeners, start timers, provide services, etc., and return a disposer that undoes those actions. On unload, disposers run in reverse order, similar to React’s useEffect but applied to the entire plugin tree. This guarantees structural safety for hot updates, plugin removal and failure rollback.

Framework Guarantees vs. Author Responsibility

The framework can guarantee that every ctx.effect() call is tracked, but it cannot verify that the disposer correctly restores state. Authors must write correct cleanup logic; the runtime only ensures the disposer is invoked.

Key layers (summarized from the original table) include:

API entry : all framework capabilities go through ctx, automatically entering the effect system.

Context Proxy : property reads/writes are proxied; if a property isn’t on the root context, the system walks up the Fiber chain to find the service.

Fiber state machine : after disposal, a Fiber cannot create new effects; attempts throw errors.

HMR transaction : import failures roll back to the previous version, preventing a half‑loaded state.

Author obligation : the disposer must be written by the plugin author; the runtime does not validate its semantics.

Agent Loop Design Choices

The Harness Agent Loop follows the classic read‑context → model request → tool detection → tool execution → result injection pattern, but adds several engineering improvements:

Tool results can end a turn early by returning concludesTurn: true, avoiding an extra model turn.

The max‑tokens limit is sticky: once a step is truncated, later steps won’t overwrite the flag, preserving diagnostic information.

Before a turn stops, the runtime broadcasts agent/turn‑stopping, allowing plugins to inject additional messages via agent.steer(...). The end of a turn is thus extensible.

Concurrency safety is decided per execution: each tool’s isConcurrencySafe method is consulted, allowing some calls to run in parallel while others remain exclusive.

Tool execution is split into tools/pre‑execute, the main body, and tools/post‑execute stages, so approval policies, safety checks and post‑processing can be added as plugins without touching the core loop.

Preset Double Scope

Presets solve the problem of reusing the same Agent configuration across many sessions without re‑parsing or re‑mounting. A preset is defined by an agent.cordis.yml file and loaded via the PresetTree plugin. Two scopes exist:

Global → preset: a single plugin tree is instantiated and shared.

Preset → session: a WeakMap records a logical parent‑child relationship, so each session inherits the preset without triggering another load.

This design lets multiple sessions share the same preset instance, and child agents inherit the parent’s preset simply by lookup, not by re‑executing the mount process.

Code Mode and Worker Threads

When the model generates code, Harness runs it in a node:worker_threads sandbox rather than an in‑process vm2 eval. The generated TypeScript is first stripped of type annotations with stripTypeScriptTypes, then wrapped in a dynamically constructed async function and executed inside a worker thread. Communication uses explicit message objects (e.g., {type: 'call', id, global: 'tools', name, args}) that are validated and sent between the worker and host.

Compared with Codex, which uses V8 isolates, Harness treats the worker as an untrusted component that can be swapped out via a plugin, offering more flexibility in isolation strategy.

Tool Masking and Visibility

Each scope maintains its own ToolLayer. To compute visible tools, the system starts with the global layer, then overlays each ancestor scope in order; the nearest definition wins. Registration itself goes through ctx.effect(), ensuring proper cleanup. The special tool name run_code (used by Code Mode) is reserved and cannot be overridden.

This algorithm allows the same tool name to be hidden in one preset, exposed in another, or replaced with an approved version in a corporate preset, providing fine‑grained control over tool availability.

Architectural Differences with Codex

Both Harness and Codex address AI‑programming runtimes, but their approaches differ:

Codex has a fixed core loop with configurable tool, approval and sandbox policies; Harness makes the loop itself a replaceable plugin.

Codex embeds sandboxing (bwrap/Landlock, Seatbelt) directly in the execution path; Harness exposes sandboxing as a capability plugin, allowing alternative isolation mechanisms.

Codex’s code mode uses V8 isolates; Harness uses worker_threads.

Codex’s codebase is split into many Rust crates serving a single core loop; Harness’s TypeScript code is split into hundreds of packages, even the loop is modular.

Neither is universally better; the choice depends on whether you need a highly stable core (Codex) or maximal composability and dynamic extensibility (Harness).

Full Execution Chain

At process start, a profile selects which plugin packages to load. Cordis loads each as a Fiber, preparing model adapters, credential managers, sandbox services and web servers. When a session begins, an Agent instance is created under the global‑preset‑session scope chain, inheriting the appropriate tools and prompts.

The Agent Loop then reads the session context, queries the model, detects tool calls, routes them through the unified tool pipeline (pre‑execute → main → post‑execute), and writes results back. Every step appends to an immutable session log, which serves as both persistence and the source for the next turn’s context.

Value for Developers and Enterprises

For individual AI product developers, Harness compresses the distance from idea to prototype by turning UI, tools, sessions and loops into interchangeable plugins. For enterprises, the ability to mount, isolate, mask and roll back tools per business line reduces risk and speeds experimentation.

Currently the system is developer‑focused—requiring Node, configuration files and command‑line operations—so a production‑ready product would still need a desktop launcher, one‑click plugin installer, permission UI and better error diagnostics.

Integration with AI Coding Tools

The bridge between AI coding assistants (Claude Code, Codex, Cursor) and Harness lies in the tool layer. As tasks become more complex, models need fine‑grained capabilities such as querying business systems, running diagnostics, triggering approvals, accessing knowledge bases, invoking test suites and updating tickets. Harness provides a composable, reversible container for these capabilities.

For Chinese developers wanting to connect to overseas models, Harness can be paired with Code80 to simplify API keys, payment and endpoint configuration.

Frequently Asked Questions

What is the core architectural feature of DeepSeek Harness?

It decomposes the Agent runtime into a plugin system where models, tools, sessions, loops, UI and sandboxing are all mountable components, with lifecycle management and reversible side effects at its core.

What problem does Cordis’s effect solve?

It binds side effects (event listeners, service registration, sub‑plugin mounting, timers) with a cleanup function, ensuring that unloading a plugin runs its disposers in reverse order and prevents resource leaks during hot updates.

How does Harness differ from Codex?

Codex keeps a fixed core loop with configurable tools and sandbox policies; Harness makes the loop, tools, sandbox and UI all replaceable plugins. Codex’s code mode uses V8 isolates, while Harness runs generated code in worker_threads.

Why compute tool visibility via the scope chain?

Different sessions, presets or enterprise contexts need distinct tool sets. Dynamic scope‑based visibility lets the same tool name be overridden, hidden or replaced locally without affecting other agents.

What benefit does this bring to ordinary developers?

For simple scripts the impact is minimal, but for long‑running Agent products the ability to hot‑swap capabilities, isolate permissions, mask tools and roll back failures becomes essential, reducing risk to the plugin boundary.

How can Chinese users more easily access models like Claude, GPT or Gemini?

By using Harness together with Code80, which abstracts away overseas payment, network and endpoint hurdles, allowing seamless integration of multiple model APIs into existing CLI, script or Agent workflows.