Study DeepSeek Harness architecture for ideas worth adapting

[cbusillo]

Objective

Examine the newly released official DeepSeek Harness at the source level and determine which architectural patterns, if any, are worth adapting into Codex Lab.

This is comparative architecture research, not a proposal to port DeepSeek Harness, adopt Cordis wholesale, or replace the current upstream-first Codex substrate.

Context

DeepSeek has released deepseek-ai/deepseek-harness as a developer-preview open-source agent harness. Its central design is “everything is a plugin”, implemented on top of the Cordis plugin framework.

The architecture documentation exposes several ideas that are directly relevant to current Codex Lab work:

• A shared service context (ctx.*) instead of consumers importing concrete implementations.
• Explicit service dependencies that control plugin activation.
• Typed event contracts with distinct observer, middleware, parallel, and ordered dispatch semantics.
• Reversible effects: prompt sections, tools, adapters, providers, and event listeners register with lifecycle-aware disposers so unload/reload unwinds behavior predictably.
• Profiles, bundles, and layered patch configuration rather than one privileged core configuration.
• An append-only typed session event log as the single source of truth, with LLM history derived from it rather than maintained separately.
• A strong reconstructability invariant: model-visible state, rendered system prompts, and tool schemas are recorded such that requests can be reconstructed from durable session state.
• Explicit capability seams separating service definition, provider implementation, and consumers for areas such as filesystem, subprocess, shell, sandbox, approvals, credentials, telemetry, persistence, LLM adapters, subagents, and background jobs.
• Per-agent scoped registrations and agent presets for changing one agent/session's capabilities without globally mutating the harness.
• A guarded tool-execution pipeline and live interception points around agent requests, tool execution, and turn stopping.

Useful starting points:

• Repository: https://github.com/deepseek-ai/deepseek-harness
• Architecture: https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md
• Cordis primer: https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/cordis-primer.md
• Session model: https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/subsystems/session.md
• Capability graph: https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/capability-seams.md

DeepSeek explicitly labels the project a developer preview with compatibility-breaking changes expected, so documentation alone should not be treated as a stable contract.

Research Questions

1. Plugin lifecycle and reversible registration

   • Compare Cordis effects/disposal with Codex Lab's existing plugin/hook lifecycle and Plugin lifecycle hooks for workspace preparation and quality providers #149.
   • Would first-class reversible registration reduce cleanup leaks, stale registrations, or feature-specific core wiring?
   • Which lifecycle concepts translate cleanly to Rust without recreating Cordis as a framework project?

2. Service/capability seams

   • Compare DeepSeek's service-definition/provider/consumer split with current Codex Lab boundaries for tools, filesystem, subprocess/shell, sandbox, approvals, telemetry, LLM providers, agents, and hooks.
   • Identify places where Codex Lab currently requires concrete knowledge that could instead depend on a narrower capability contract.
   • Also identify cases where Codex Lab's existing traits/services are already cleaner and no change is warranted.

3. Typed middleware/event contracts

   • Inspect the actual emit / waterfall / parallel / serial event machinery and representative consumers.
   • Compare it with current Codex Lab events, hooks, tool middleware, app-server notifications, and agent lifecycle surfaces.
   • Determine whether any missing interception point is causing duplicated product-specific wiring today.

4. Durable session state and reconstructability

   • Study the append-only SessionEvent model and the rule that model-visible state must be logged/reconstructable.
   • Compare this with Codex Lab's rollout/thread/session state, prompt assembly, tool state, Background Review, Validation, external-agent provenance, and resume/fork behavior.
   • Identify whether Codex Lab has state that influences later model requests but cannot currently be reconstructed or audited from durable state.
   • Do not assume event sourcing is inherently better; explicitly account for storage, migration, compaction, concurrency, and compatibility costs.

5. Per-agent composition

   • Examine scoped registrations, presets, subagent providers, and session-specific capability composition.
   • Compare with Codex Lab's native/Every Code agent split, exact/minimal prompt-profile work (Add exact/minimal prompt profiles for non-code agents #93), and routing work (Teach the root agent when to use native versus Every Code subagents #633).
   • Determine whether capability composition can simplify per-agent tools/prompts/providers without making configuration opaque.

6. Profiles, bundles, and layered patches

   • Determine whether DeepSeek's profile/bundle composition solves a real Codex Lab packaging or configuration problem.
   • Pay particular attention to whether it offers anything better than the current upstream-first overlay/owned-contract approach rather than simply adding another configuration language.

7. Background work and observable lifecycle

   • Inspect DeepSeek's jobs, goals, agent lifecycle, and durable session events for ideas relevant to Background Review and generic activity/state reporting.
   • Compare with Rework durable Background Review around upstream review primitives #231 and Expose a generic Work Pulse activity stream #298 without folding either issue into this research task.

8. Costs and failure modes

   • Look for runtime indirection, ordering hazards, plugin dependency complexity, debugging difficulty, type-system escape hatches, performance overhead, reload edge cases, and configuration ambiguity.
   • Review representative tests and implementation code, not only architecture prose.
   • Distinguish genuinely useful architecture from patterns that mainly fit DeepSeek's TypeScript/Cordis ecosystem.

Deliverables

Produce a concise architecture comparison with:

• A subsystem-by-subsystem matrix of DeepSeek Harness versus current Codex Lab behavior.
• Concrete source references from both repositories.
• A short list of the most promising ideas, each classified as Adopt, Adapt, Already Have, Reject, or Needs Measurement.
• For every Adopt/Adapt candidate, identify the specific Codex Lab pain point it addresses and the smallest independently testable implementation shape.
• For every rejected idea, record why the added abstraction or migration cost is not justified.
• Separate architecture lessons from model-specific DeepSeek behavior.
• Create follow-up implementation issues only for findings with a concrete Codex Lab benefit; do not turn the research issue itself into a broad refactor.

Acceptance Criteria

• Pin the exact DeepSeek Harness commit reviewed so conclusions remain reproducible while the developer preview changes rapidly.
• Inspect the architecture and Cordis documentation plus the implementation of representative plugin loading/unloading, agent loop, session log, tool pipeline, capability/provider registration, approval/sandbox path, and subagent/background-job path.
• Trace at least one model-request/turn lifecycle and one tool-execution lifecycle end to end from source rather than relying on diagrams alone.
• Trace at least one plugin registration and teardown path to verify the claimed reversible-effect behavior.
• Map findings to current Codex Lab source and existing issues instead of proposing abstractions in isolation.
• Explicitly evaluate Plugin lifecycle hooks for workspace preparation and quality providers #149 plugin lifecycle overlap and whether DeepSeek provides a simpler or stronger lifecycle contract.
• Explicitly evaluate session reconstructability/event-sourcing ideas against Codex Lab resume, provenance, and model-visible context behavior.
• Identify at least three meaningful patterns worth serious consideration or record a justified no-action result if the current Codex architecture already covers them better.
• For any proposed experiment, keep the prototype bounded, measurable, and independently revertible; no whole-harness rewrite or Cordis port.
• Record developer-preview/API-instability and licensing considerations before suggesting any code reuse.

Relationships

• Related plugin/lifecycle work: Plugin lifecycle hooks for workspace preparation and quality providers #149.
• Related Background Review architecture thinning: Rework durable Background Review around upstream review primitives #231.
• Related generic lifecycle/activity stream: Expose a generic Work Pulse activity stream #298.
• Related exact/minimal per-agent prompt composition: Add exact/minimal prompt profiles for non-code agents #93.
• Related native-versus-Every Code agent routing: Teach the root agent when to use native versus Every Code subagents #633.
• This issue is architecture research and should not block current release or upstream-sync work.

Decisions

• Treat DeepSeek Harness as a source of design evidence, not a target architecture.
• Prefer small transferable principles over importing a framework-shaped abstraction.
• Preserve Codex Lab's upstream-first ownership model unless a measured problem demonstrates a better boundary.
• Source-level behavior and tests outrank README claims.
• A well-supported “nothing to adopt” conclusion is a valid outcome.