---
title: "Cordis Framework"
description: "Microkernel plugin and dependency-injection framework powering DeepSeek Harness: lifecycle management, service containers, typed event buses, reversible side-effects."
section: "concepts"
type: "concept"
created: "2026-08-24"
updated: "2026-08-24"
confidence: "high"
tags: ["agents", "workflow", "principle"]
canonical: "https://pyweb.dev/wiki/cordis-framework"
---
# Cordis Framework

**Cordis** is a microkernel plugin and dependency-injection framework used as the underlying infrastructure kernel in [DeepSeek Harness](/wiki/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](/wiki/deepseek-harness)
- [agent harness engineering](/wiki/agent-harness-engineering)
- [agent native infrastructure](/wiki/agent-native-infrastructure)
- [deepseek](/wiki/deepseek)

---

## Agent Navigation

cluster: person (170 pages) | betweenness: 20.3

### References (outbound)
- [DeepSeek Harness](https://pyweb.dev/wiki/deepseek-harness.md)
- [Agent Harness Engineering](https://pyweb.dev/wiki/agent-harness-engineering.md)
- [Agent-Native Infrastructure](https://pyweb.dev/wiki/agent-native-infrastructure.md)
- [DeepSeek](https://pyweb.dev/wiki/deepseek.md)

### Referenced by (inbound)
- [Agent Harness Engineering](https://pyweb.dev/wiki/agent-harness-engineering.md)
- [Clean Architecture](https://pyweb.dev/wiki/clean-architecture.md)
- [DeepSeek Harness](https://pyweb.dev/wiki/deepseek-harness.md)
- [DeepSeek](https://pyweb.dev/wiki/deepseek.md)

### Evidence (verified primary sources)
- [deepseek-harness-cordis-primer-2026](https://pyweb.dev/wiki/raw/articles/deepseek-harness-cordis-primer-2026.md) | origin: https://deepseek-harness.github.io/deepseek-harness/reference/cordis-primer | ingested: 2026-08-24 | sha256: e76a43328989f6f8a87a4299f0cbcf80120d985097a95863eba7cec2cf74fc1c

### Machine endpoints
- Knowledge graph: https://pyweb.dev/api/graph.json
- Graph analysis: https://pyweb.dev/api/graph-analysis.json
- Context index: https://pyweb.dev/llms.txt