Cordis Framework

Cordis is a microkernel plugin and dependency-injection framework used as the underlying infrastructure kernel in DeepSeek Harness. It provides modular lifecycle management, service containers, typed event buses, and reversible side-effects for agent runtimes.

The 5 Core Concepts

Cordis structures agent harnesses around 5 foundational mechanics:

1. Plugins as Service Providers: A plugin is either an object implementing apply(ctx) with optional inject declarations, or a Service subclass whose lifecycle is bound to the current context.
2. Context as Service Container: Services occupy stable keys on the context object (e.g., ctx.tools, ctx.llm, ctx.sessions, ctx.agents). Consumer plugins access capabilities via context keys rather than importing concrete module implementations.
3. Declarative Inversion of Control via inject: Plugins declare required services via inject. Cordis delays plugin activation until all dependent services are mounted and ready, eliminating manual startup sequencing.
4. Typed Event Dispatch: Services communicate through typed event buses with 4 distinct dispatch modes:
   • emit: Asynchronous observation in registration order (no return value, no await).
   • waterfall: Middleware pipeline in registration order; listeners can modify data, delegate via next(), or short-circuit return values.
   • parallel: Parallel asynchronous execution across all listeners (await, no return value).
   • serial: Sequential execution in registration order (await, returns value).
5. Reversible Side Effects & Teardowns: Registrations (prompt fragments, tool schemas, middleware, event listeners) are mounted via ctx.effect() or ctx.on(). Reloads and teardowns automatically invoke associated disposers to cleanly undo side-effects.

Waterfall Middleware Semantics

The waterfall pattern functions as an onion-style interceptor:

• Listeners accept (...args, next).
• Calling next() delegates to downstream handlers and yields their return value back up the stack.
• Returning directly without calling next() short-circuits execution, allowing policy plugins to preemptively veto or handle actions.
• Collaborative listeners modify shared request/decision payloads before delegating.

Loader & Configuration Engine

Dynamic configuration uses @deepseek-ai/cordis-plugin-include:

• Parses expressions like !!js into dynamic AST nodes.
• Evaluates config and disabled predicates reactively against service context (ctx.serviceName).
• Environment-specific overrides and overlays allow dynamic feature flags without modifying harness code.

Related Concepts

• deepseek harness
• agent harness engineering
• agent native infrastructure
• deepseek