Not a source paraphrase
We explain why the design exists before tracing events, boundaries, and trade-offs.
28 chapters · 6 layers · upstream@47f9438
Read an agent harness
as a transferable architecture skill
Start with why this is more than a while loop, then travel through Cordis composition, turns and steps, event truth, guarded tools, compaction, projections, subagents, workflows, and finally your own safe extensions.
Plain intuitionReal event flowAuditable sources
Research baselinedeepseek-harness@47f94382026-08-13 · developer preview
Not a floating snapshot
Every claim is calibrated to upstream 47f9438: 49 package families and 324 docs.
Not passive reading
Every chapter has an interactive mechanism, invariants, failure modes, a check, and an explicit bridge.
ARCHITECTURE ATLAS
See the system before the files
Forty-nine package families are not forty-nine islands. Six planes put complexity into understandable drawers.
Six-plane architecture atlas SOURCE ALIGNED
Profile · Bundle · Patch · Cordis
Composition plane
Decides which plugins exist, how they layer, and how they unwind.
bootbundlepresetextensionsGUIDED CURRICULUM
One conceptual step per chapter, without staying shallow
01
Explain the boundary between model, agent, and harness
4 chaptersBuild the mental model
Understand the problem before studying how complexity is divided.
What is a harness, really?
Why can the same model feel like a different system inside another agent product?
Why everything is a plugin
If sessions, tools, and even the agent loop are plugins, what remains as the core?
The six-plane system map
Across thousands of source files, how do you decide where new behavior belongs?
How to read the source city
In a large agent repository, do you search functions first or find contracts first?
02
Read why a real plugin tree can mount, replace, and unwind
5 chaptersLearn the composition grammar
Read the system through Cordis contexts, effects, services, events, scopes, and config trees.
Context: the plugin collaboration surface
Is Context a convenient global variable, or the system's boundary object?
Effects and fibers: make disposal finish
Why does AbortController.abort() not mean a plugin has finished unloading?
Services and events: separate capability from cooperation
When should you call ctx.fs, and when should you listen to fs/write-intent?
Scope, realm, and rescope
How can two agents see different tools, personas, and working directories in one process?
Profiles, bundles, patches, and the boot tree
How do you replace models, sandboxing, or tools without forking upstream?
03
Explain a complete model request event by event
6 chaptersTrace the agent spine
From agent creation through SessionEvent, turns, steps, prompts, LLMs, and tools.
Agent creation, ownership, and cancellation
Who may destroy an agent, and how does a half-failed creation roll back?
SessionEvent: the single source of truth
Why persist raw assistant chunks instead of only the final message?
Inbox, turns, and steps
Why does one user message not imply one model request?
A prompt is not one string
How can plugins add model-visible context without everyone editing one systemPrompt?
LLM adapters and the streaming vocabulary
Why can DeepSeek, replay, and other providers stream into the same agent loop?
Tool execution is not a function call
Why can a later plugin not re-allow a dangerous call already denied upstream?
04
Judge whether the system stays trustworthy under denial, crashes, cancellation, and long context
5 chaptersUnderstand safety and durability
Approval, sandboxing, filesystem policy, compaction, persistence, projections, and invariants.
Approval, policy, and permission presets
Why does danger-full-access plus never-ask still not mean every tool can execute?
Sandbox, FS, shell, and one execution world
Why does replacing the subprocess provider move Bash, PTY, LSP, and external subagents together?
Compaction, token metering, and spill
How do you shorten context without breaking tool call/result pairing or deleting original facts?
Persistence, projections, and queries
Why should a session list not load the complete event log for every row?
Cancellation, timeouts, and defensive invariants
Why can a timeout not simply Promise.race and forget the still-running work?
05
Separate state, delegation, orchestration, and long-running work
4 chaptersScale beyond one agent
Goals, plans, todos, subagents, jobs, workflows, schedules, and capability discovery.
Goals, plan mode, and todos
Why can all todos be complete while the goal is not?
Subagents, continuations, and jobs
After starting a subagent, who owns it, who may continue it, and who must stop it?
Workflow engine and durable schedules
Why can workflow, job, and schedule not collapse into one background-task concept?
Skills, MCP, LSP, and Web capabilities
Skills and plugins both extend agents—why are they not the same?
06
Ship a capability without patching the agent loop
4 chaptersBuild and ship extensions
Turn understanding into tools, adapters, client surfaces, profiles, and bundles.
Lab: add a tool
Beyond name, description, and execute, what makes a production-grade tool definition?
Lab: design a capability seam and provider
When should you add a provider, and when should you design a new seam?
Lab: Web, CLI, ACP, SDK, and Host
How does a Web UI button become agent behavior without making the browser own business state?
Lab: from plugins to a shippable product
What boundaries separate a locally working plugin from a shippable product?
FROM READER TO BUILDER
Trace one run, explain every boundary, then build your own composition.
Chapter one takes twelve minutes and starts by separating a harness from an agent loop.
Start deep dive