DeepSeek Harness · 6 of 6
Design assessment lab
DeepSeek’s architecture buys explicit composition, policy placement, and replay. The price is a larger contract surface: plugin lifecycle, scope, event ordering, provider selection, and durable projection all matter.
§1
Strengths and corresponding costs
| Design choice | Benefit | Cost / risk | Evidence |
|---|---|---|---|
| Cordis plugin tree | Replace or omit model, tool, persistence, UI, and policy providers through composition. | Resolved behavior depends on layer order, scope, and lifecycle. | SOURCE Architecture and config tree. |
| Typed event domains | Durable replay facts stay distinct from live interception and capability policy. | Extension authors must choose the correct domain and dispatch semantics. | SOURCE Event map and lifecycle. |
| Append-only session + surface | Model history is reconstructable; compaction can be audited as replacement events. | Projection and persistence invariants are substantial and versioned. | SOURCE Session subsystem. |
| Staged tool pipeline | Policy, approval, confinement, dispatch, and final outcome are independently observable. | Ordering and transformation rules are part of the security model. | SOURCE Tool pipeline. |
| Capability providers | A provider swap can move related consumers into one execution world. | Seam interfaces must be complete enough to prevent reach-around. | SOURCE Capability graph. |
| Many extension modes | Instructions, children, tools, plugins, dynamic code, and workflows fit different needs. | Operational and cognitive surface is wide; least-powerful-seam discipline matters. | INTERPRETATION Based on pinned source map. |
§2
The four-owner control ledger
User/operator: selects profile, patches composition, supplies approvals and credentials. Harness: resolves the plugin tree, owns event/state invariants, runs waterfalls and tool policy. Model: proposes messages, calls, code, or delegation. Environment/providers: execute model calls, filesystem/process operations, persistence, and external child transports. Source · composition
Documented seams make ownership easier to locate. When several plugins wrap the same waterfall, the resolved composition may be the only place that shows the effective order.
§3
Lab 1 · add a denying guard on paper
- Open
packages/core/tools/src/index.ts, lines 676–711. - Write a guard invariant for one tool family, such as “the resolved path must remain inside the agent workspace.”
- Identify the data the guard needs and whether that data is already in the call context.
- Explain why the guard may deny or abstain but must not grant.
- Name the durable result the model should see after denial.
Success is a complete contract, not a code patch: owner, input, decision, error representation, and ordering guarantee.
§4
Lab 2 · follow one fact through the session
- Choose
assistant/chunk,assistant/message, ortool/result. - Find where the loop appends it in the lifecycle sequence.
- Decide whether it is a surface event.
- Trace how
deriveMessages()treats it. - State what JSONL/SQLite persistence must retain and what a UI can replay.
§5
Lab 3 · swap a capability provider
Use the capability graph. Pick filesystem, subprocess, spill, persistence, compaction, or subagent. Identify service definition, current provider, every consumer, selection/configuration point, and failure semantics. Claim record
Then name one reach-around that would defeat the swap—for example, a consumer touching the host filesystem directly instead of using ctx.fs.
§6
Lab 4 · compare spawn and fork without hand-waving
Read the provider contract and fork seeding description. Produce a two-column ledger for conversation seed, session ID, flat scope, tool registrations, service providers, authority, cancellation, result, and continuation. Mark any field not established by the source as unknown. Source · spawn/fork
Fork inherits a balanced conversation prefix. It does not automatically inherit every parent capability or permission.
§7
A scoped judgment
At this commit, DeepSeek Harness is a strong reference for making harness seams explicit: event-sourced model history, waterfall interception, monotonic policy, provider composition, and child transports all have named contracts. It is also a demanding system to hold in one head. The same modularity that avoids a privileged loop produces many interacting lifecycle surfaces.
The developer-preview warning matters most at the edges: an integrator should expect API and composition movement, pin revisions, and use the repository’s generated architecture catalogs as navigation while verifying behavior in source. Source · version boundary