How Cordis Enables DeepSeek Harness’s Plugin Architecture – A Deep Dive

DeepSeek Harness (dsh) is an open‑source AI agent harness that declares “everything is a plugin” as its core architectural tenet. The framework’s runtime is built on the Cordis micro‑kernel – a TypeScript‑only core of roughly 2,000 lines that provides only the primitives for loading, unloading, and managing plugin dependencies.

1. Scale of the Core

The dsh product consists of 54 npm package groups (about 219 modules) that are all published under the @deepseek-ai/dsh-* namespace. All of these packages are hosted by the Cordis framework, which is vendored into the repository as @deepseek-ai/cordis. The ratio of core code to product size is striking: a 2,000‑line kernel supports 7,404 files and 2,319 TypeScript source files.

2. Micro‑kernel Strategy: Vendor vs Dependency

2.1 Vendor Directory – The Framework Family

cordis/

– Core framework providing Context, Service, Fiber, and typed events. cosmokit/ – Shared utilities used by the framework and Schemastery. schemastery/ – Schema validation for each plugin’s configuration. loader/ – Plugin loading, parsing, and cache handling. include/ – Configuration inclusion and patch layering. group/ – Plugin group lifecycle management. timer/ – Timer plugin. hmr/ – Hot‑module replacement and configuration watching. logger-console/ – Console logging plugin.

All of these facilities, which would normally belong to the framework layer, are themselves plugins in Cordis, confirming the micro‑kernel’s design that the kernel only supplies runtime primitives while everything else is plug‑in‑able.

2.2 Deep Embedding Instead of Simple Dependency

DeepSeek vendors the Cordis source code (placing it under vendor) and rescopes it into its own namespace rather than importing it as a regular npm dependency. The source index records 18 local modifications. This decision serves three purposes:

Deep customization: Any semantic adjustment (e.g., scope chain, lifecycle ordering) propagates to all 54 package groups. Vendoring lets DeepSeek treat the kernel as its own code and enforce consistency with scripts such as rescope and verify-runtime-closure.

Version pinning and supply‑chain control: A pinned source combined with pnpm-workspace.yaml overrides/patches and verification scripts ( verify-cordis-config.ts) guarantee that kernel invariants are checked on every build.

Ecosystem foundation: The nine vendored packages form a complete “framework family” – Schemastery supplies schema validation, loader/include provide declarative assembly, and HMR offers hot updates. DeepSeek does not reinvent wheels; it welds them into its own chassis.

3. The Five Plugin Primitives in Cordis

3.1 Plugin & Plugin Registry

Cordis’s Plugin Registry tracks metadata and dependency graphs for all installed plugins. In dsh this becomes a directory structure packages/<group>/<pkg>/. Documentation under docs/ (e.g., config-catalog.md, tool-catalog.md, module-graph.md) is a readable projection of the registry. Capability families such as core, api, llm, sandbox, fs, shell, subagent, web, and session are each a plugin group managed by the registry.

3.2 Context – The Plugin Workbench

Each plugin receives an isolated Context through which it accesses services and registers resources. dsh extends the core Context with a “dsh‑scope” that adds tags and a parent‑child scope chain, turning the plugin boundary into an Agent isolation boundary. Evidence includes: dsh-agent – Provides a process‑local initiator scope for each Agent. dsh-subagent-spawn-in-process / dsh-subagent-fork-in-process – Create new child scopes or inherit parent history.

Terminal, sub‑agent, and persistent shell resources are declared with exact Agent ownership via ctx.terminals.

This abstraction upgrades Cordis’s Context to a multi‑tenant model for Agents.

3.3 Service – Capability Seam

Every capability family follows a three‑layer structure:

Service Definition (interface contract)

Service Provider (implementation)

Model‑facing Tool (schema exposed to the LLM)

Examples include the file system ( dsh-fs → dsh-fs-local / dsh-fs-sandbox → dsh-tool-fs), subprocess handling, shell execution, sandboxing, code runtime, LSP, terminal handling, and LLM adapters.

3.4 Typed Events – System Vocabulary

Typed events enable loosely‑coupled communication between plugins. dsh elevates this to a system‑level contract, where each core plugin declares a set of events: dsh-agent – agent/* events. dsh-tools – pre / execute / post‑execute events. dsh-fs – Filesystem strategy events. dsh-compaction – Compaction events. dsh-llm-retry – Agent request‑error waterfall for provider‑level retry.

Scripts such as scripts/gen-scoped-events.ts generate docs/event-producer-consumer.md, turning the event vocabulary into compile‑time checkable, documented contracts.

3.5 Effects & Fiber – Lifecycle State Machine and Zero‑Garbage Unload

Cordis’s Fiber tracks plugin instance states ( PENDING → LOADING → ACTIVE → DISPOSED). Effect objects represent reversible side‑effects that are automatically cleaned up on unload. Evidence of this mechanism in dsh includes:

Hot updates via cordis-plugin-hmr and dsh-client-hmr – only reversible effects allow safe hot reload.

Ordered shutdown via apps/cli/process-shutdown.ts handling SIGINT and SIGTERM.

Deterministic cleanup in dsh-terminal (awaited cleanup) and dsh-session-persistence (write coordination).

This guarantees that runtime plugin mounting/unmounting leaves no resource leaks.

4. Concrete Engineering Manifestations in Harness

4.1 Service Definition & Provider Separation → Replaceability

In the sandbox capability family, dsh-sandbox-local provides four back‑ends (Linux bwrap/Landlock, macOS Seatbelt, Windows ACL, and a native C11 Landlock plugin of ~300 lines). Even native code is treated as a plugin, illustrating the deepest level of the “everything is a plugin” claim.

4.2 Declarative Composition Language

dsh assembles its system via a layered, snapshot‑able configuration pipeline: cordis.yml – Declarative manifest.

Schemastery – Schema validation.

Loader – Parsing and caching.

Include – Layered patching.

Profile / Preset – Scenario‑specific composition.

Each runnable leaf (e.g., examples/acp-agent, examples/web-cordis) carries its own cordis.yml. The CLI supports --profile, --patch, and --dump-config to parse, overlay, and materialize the final plugin tree.

4.3 Dual‑Side Plugin Model – Crossing Process Boundaries

The Web GUI demonstrates cross‑environment plugin reuse:

Host side ( packages/host/) – Plugins such as dsh-host-apiproxy, dsh-host-webserver, and directory pickers run in Node.

Browser side ( packages/client/) – Plugins like dsh-client-web, dsh-client-modules, and UI components run in the browser, all built on the same Cordis primitives.

Typed RPC – The typert family generates cross‑side service descriptors, ensuring type‑safe calls between host ctx.typertGateway and browser ctx.remote.

This unifies UI development and backend development under a single mental model.

4.4 Runtime Self‑Modification

Extensions in packages/extensions/ implement a dynamic plugin chain: dsh-cordis-host-runner – Defines a registry, a Node vm sandbox, and a request‑run round‑trip ( ctx.dynamicCordisRunner) to evaluate and mount plugins at runtime. dsh-cordis-client-runner – Browser counterpart that evaluates definitions into real browser plugins. dsh-tool-cordis – Exposes runtime inspection and dynamic package tools to the model.

Example: examples/web-cordis/ is described as “self‑referential demo: Agent checks and mounts its own Cordis plugins”. The combination of plugin‑based architecture, Fiber lifecycle, and Effects enables safe self‑extension.

4.5 Observability & Invariants – Plugin Structure as Engineering Structure

dsh-invariants

– Each package publishes an ./invariant module; the runtime registers them under ctx.invariants.

~150 verification scripts (e.g., verify-package-invariants.ts, verify-runtime-closure.ts) run in CI to enforce the integrity of the plugin world.

Generation scripts ( gen-cordis-catalog.ts, gen-cordis-api.ts, gen-module-graph.ts) produce documentation directly from source, ensuring docs never drift from the plugin structure.

4.6 Tests & Demonstrations as Plugins

Testing facilities follow the same plugin paradigm: replay and mock servers for LLMs, testkits for agents, and jsdom‑based runtimes for the client. Even the Python SDK bundles a Cordis configuration ( deepseek-harness-runtime-bin) that mirrors the TypeScript side, proving cross‑language, cross‑runtime consistency.

5. Benefit Analysis – Architectural Promises Realized

Modularity: 54 package groups organized by capability, with a generated module‑graph.

Replaceability: Service Definition / Provider separation allows swapping LLMs, sandboxes, persistence back‑ends, and search providers without changing contracts.

Hot‑plugability: HMR plugins, config‑only HMR, and Fiber+Effects guarantee safe hot reloads.

Extensibility: Cookbook docs provide a standard path for adding new packages, tools, or LLM adapters.

Testability: Replay, mock, and testkit plugins enable deterministic testing.

Self‑evolution: Runtime VM runners let agents mount user‑written plugins on the fly.

Auditability: Generated documentation, event matrices, invariant checks, and 505 Agent Notes record decisions.

6. Costs & Challenges

Vendor maintenance: 18 local modifications plus rescope scripts mean each upstream Cordis upgrade requires a migration effort.

Compatibility risk: The developer‑preview version (0.1.0‑rc.5) may introduce breaking changes that affect all 54 packages.

Complexity shift: The micro‑kernel pushes complexity to the composition layer, requiring tooling such as composition.md, runtime closure verification, and dead‑code analysis.

Cognitive barrier: Extensive tutorials (e.g., cordis‑primer.md, 7‑chapter tutorial) are needed to teach the plugin mindset.

7. Conclusion

The ratio question – how a 2,000‑line kernel supports 54 package groups – is answered by Cordis providing a “relationship syntax”: Context & Fiber define boundaries and lifecycles; Plugin Registry manages components; Service & inject define interface/implementation/dependency syntax; Typed Events define notification syntax; Effects provide reversibility. DeepSeek Harness does not invent these primitives; it disciplines the entire product – from LLM adapters to filesystem, sandbox, UI, and testing – into this unified grammar, enabling runtime self‑inspection, self‑modification, and safe unloading. Cordis is therefore not just a software bus for dsh but an “evolutionary base” that makes the Agent system both robustly composable and openly self‑bootstrappable.