DeepSeek Harness: An Architecture Dissection

One codebase has to ship as several different things: a web version, a one-shot command-line task, a background service for editors, an SDK other programs call. The usual answer is a pile of if branches, or a handful of entry files, and after a while nobody can say what any given form actually has loaded.

A complete AI coding assistant is a 165-line YAML manifest — which plugins to load, and how each one is configured. At startup the system first empties the root config down to an empty list, then stacks layers on in order:

base bundle → form bundle (web/CLI) → the user's personal config → machine-level config → command-line overrides

Every layer is a patch: find a line by id, replace its config, or insert a new line. No layer is "the main config file" — they all rank the same.

The classic plugin-system headache is startup order: A needs B, B needs C, who initializes first? A hand-ordered list breaks the moment someone cuts in line.

A plugin only declares which services it needs. The framework computes a readiness state for each one — all dependencies present, it activates; any one of them disappears, it unloads itself. Load order isn't choreographed. It falls out of the dependency declarations.

And further: that readiness state records not just whether a dependency is there, but which instance provides it. So when you swap a service for a different implementation, the plugins depending on it restart once, automatically, even though the service name never changed.

Unloading is where plugins break: event listeners left attached, files left open, timers left running. And the unload can arrive while initialization is still mid-flight.

The framework's rule: anything that changes the world has to go through one registration interface, and it hands back a return ticket. Unloading a plugin = redeeming all of its tickets in reverse order.

Nesting is handled too: register inside another registration, and the child ticket is automatically moved off the plugin's top-level list and hung under the parent ticket — so nested cleanup unwinds along the nesting. Every step of async initialization checks whether the state has changed first, so an unload can interrupt an initialization in progress.

The same tool registry gets read twice, for different purposes: step ② reads it to write the tools' documentation into the prompt (telling the model which tools are available), and step ⑥ reads it to actually run them.

This isn't redundancy. It's an important constraint: both reads must see the same list. Every visibility question in the project — what the prompt lists, what can be executed, what shows up in the generated SDK — goes through the same resolution function. Otherwise you get "the model was told this tool exists, and calling it says it doesn't," the kind of thing that makes a model give up on correcting itself entirely.

The plugins in the right column aren't just "being notified." Take step ③: the main loop hands over "these messages I'm about to send to the model," and each listening plugin can choose to pass it to the next one, rewrite it and pass it on, or veto the step outright. This is where the compaction policy notices the context is about to fill up and goes off to summarize first.

In web frameworks this pattern is called middleware (the onion model); the project kept the name its own framework ships with, waterfall — it didn't invent the concept.

Registration doesn't have to be global. Every live agent has its own registration scope, and a plugin can register into just one agent's scope. So things with the same name get "shadowed by the nearest one" — one session's bash tool can be a restricted version while every other session still sees the original.

That's how "a different capability set per session" is implemented: a preset config is mounted once, and each session joins it through the parent-child relationship between scopes, rather than every session mounting its own copy.

If the conversation history lives in an array, then "replay a session", "fork a session", "recover from a crash" and "render the UI" each need their own logic — and sooner or later they drift apart. What the model saw stops matching what you see on screen, and that kind of bug is brutal to track down.

There is only one ledger. When it's time to send a request, you fold the ledger from the top and compute the message list. UI, replay, fork, persistence — all of them are different folds over the same ledger.

The rule fits in one line: "model-visible ⟺ logged". Anything that reaches a model request — workspace instructions, time information, the system prompt itself — has to become an entry in the ledger first. Want a new kind of model-visible input? Define a new log event first.

Once a conversation gets long it has to be compacted, or it won't fit in the model's context window. But the usual approach replaces old messages with a summary — so conversation the user already read vanishes from the screen.

Don't tear pages out. Compaction appends a special entry: "for entries 12 through 47, this summary is what counts".

Then the same ledger has two readings. The model-facing one honors that masking entry and sees the summary; the human-facing one reads only the entries that "were appended in the first place" and ignores the mask entirely.

After an upgrade, what should an old build do when it reads a log written by a new one? "Skip what you don't recognize" is the most common answer, and the most dangerous — it silently restores a hollowed-out session, and the user has no idea.

The default is the opposite: an unrecognized entry type means refusing to rebuild the whole session, unless the author explicitly marked that entry as "ignorable".

Before a tool runs, it has to clear a series of safety checks (permissions, sandbox, user policy). The classic way to write this is a middleware chain, where each link can allow, deny, or pass to the next.

But middleware chains have a hidden trap: order changes the verdict. A plugin that inserts itself at the front of the line can allow something before anyone else gets a chance to deny it. Bugs like this throw nothing, make no noise, and are usually security bugs.

The project splits safety checks into two things that live side by side:

• Middleware chains — kept, for the things that genuinely need to wrap a call: timeouts, retries, instrumentation.
• Guards — the new thing. Their type only lets them return a denial reason or "no objection." There is no "allow" option at all.

So composing guards is just "one no means no" over an unordered set. Whatever the registration order, whoever cuts the line, the verdict is identical.

Defaults like "if no timeout was passed, use 60 seconds" usually sit scattered inside the implementation (timeout ?? 60000). The result is that nobody can say what parameters a call actually ran with, and debugging means reading the source.

Filling in defaults is promoted into a public, named conversion step: from a request (most fields optional) to a spec (every field required). The execution function's type only accepts a spec, so a half-filled request can't get in at all.

That same defaulting step also clamps the upper bounds — ask for a 10-hour timeout and it's quietly pulled down to the maximum the deployment allows, rather than throwing or being let through.

The backend forwards some internal events to the browser. Which ones may cross and which may not is usually an array plus a comment — and then the forwarding code and the frontend subscription code each keep their own copy, and the two slowly drift.

The allowlist is one constant array, constrained by the type system (every entry must be an event that really exists, and must meet the requirements for being forwardable). The runtime forwarding loop and the set of legal subscription keys on the frontend are both derived from that one array.

The project got burned by this for real: one plugin file had an extra line, a default export. The loader's rule is "if there's a default export, take only the default export," so this plugin's dependency declaration was thrown out with everything else. The plugin started up in an environment with no services at all, and the service crashed the moment it hit a real editor.

At the time this package had 178 green unit tests and 100% line coverage. So why didn't they catch it? Because every test hand-built the plugin object, and the "take the default export" logic only runs in the real loader.

Two lines of defense went in after the incident. First: a check script parses every package with the TypeScript parser and forces each one to satisfy a list of structural requirements — including "no default exports." All 219 packages comply.

Second, written into the testing policy: every externally visible plugin must have a test that goes through the real loading path. Tests on hand-built objects don't count.

Process isolation differs a lot across operating systems. Assuming "I called the sandbox, so I'm safe now" turns into a dangerous illusion on some platforms.

The sandbox interface has exactly one method: hand over the command string you're about to run, get back a replacement command string plus three facts:

• Containment level: full or partial. "Partial" is a state that really occurs — on Windows, hard links let one file be reached from several paths, so it's statically classified as partial; the Linux kernel-level backend probes for itself, based on the kernel version it actually negotiated.
• That backend's own denial wording. Different sandboxes print different error text when they refuse, so the caller matches only the wording returned by the backend actually in use this time — taking the union across all backends would claim denials some backends can't even produce.
• How to tell "the sandbox itself broke" from "the command was denied".

When you wrap a complex protocol — the Language Server Protocol, say — the path of least effort is "expose a few common operations, plus one generic raw-call interface just in case".

The language-service seam exposes four operations: go to definition, find references, go to implementation, hover info. The result types are a closed set of two. No raw protocol calls, no process control, no document management. Want a fifth operation? You change the interface, every implementation, and every consumer at once, and the compiler watches you until you're done.

The model may ask for five tool calls at once. Running them serially is too slow; running them in parallel scrambles the order of the results — and the model reads those results in the order it listed them.

Dispatch can overlap, but commits are strictly ordered: the scheduler only advances along the run of calls that have finished contiguously. If the third one finishes first, it still waits on the first two.

Two extra touches: before each next call is started, re-decide whether it may run concurrently — so a tool registry that changes mid-run forms a barrier against calls not yet started; and on interruption, write a synthetic error result for the calls that never got to run, so that stretch of log still replays complete (every call has a matching result).

Every tool call costs the model a round trip: it emits the call request → the system executes it → the result is stuffed back into the context → ask the model again. Ten things means ten round trips, and both the token cost and the latency add up.

Change the presentation: the tool list handed to the model holds exactly one tool, called "run code", while the system prompt carries the TypeScript (or Python) interface declarations for every tool. The model writes a program and gets all ten things done in one run.

The key is that each tool call inside that program still flows back through the same safety pipeline — permissions, sandbox, approvals, none of them dropped, and every sub-call is logged. But only the final output, curated by the model itself, enters the conversation history.

A run can need to abort for three reasons: the user hit stop, this plugin got unloaded, the whole system is shutting down. Handle them separately and you miss the combinations, especially "unloaded halfway through initialization".

The three sources fuse into a single cancellation signal, registered before any resource is created, paired with a reverse-order teardown (which runs exactly once even under concurrent calls).

A command can be "timed out" and "exit code 0" at the same time — because it caught the termination signal and then exited normally. Nest the "timed out" flag inside the "failed" branch and the caller reads a run that was cut in half as a clean success.

Timed out or not, which signal arrived, exit code — each gets its own field, and none of them is nested inside another's branch.

Docs generated from code — API catalogs, dependency graphs, config listings — always go stale. So you write a checker to verify they are current, and then the checker itself slowly drifts from the generator, and you get "the check passes but the file is wrong."

Don't write a second program. Checking = the same generator with one extra flag, regenerating in memory and comparing byte for byte against the file in the repo.

A check like "every public function needs a doc comment" has to walk every form an export can take in the code. The language ships an upgrade, a new syntax appears, the checker doesn't recognize it and falls into the default branch — and waves it through. From that moment it has degraded into sampling, and nobody finds out.

Hit a construct you don't recognize and throw, with an error that says: I don't know what this is, come extend me.

Testing an AI agent is expensive: every run calls the real model, slow and nondeterministic. So you want record-and-replay — which usually means inventing a recording format.

Don't invent a format. The session log itself is the replay material. Recording = run it for real once and keep the log file.

Three lessons come with it. When something can't be derived from the log, fail loudly and name the fix — no quiet degradation. At the end of a test, assert that the recording was fully consumed (a test that makes fewer model calls still passes every output comparison; the transcript just gets shorter). And for big, frequently-changing content like the system prompt, compare it verbatim in exactly one scenario and compare reconstructions everywhere else — otherwise one prompt edit churns hundreds of expectation files, and review turns into a rubber stamp.

"Why was it designed this way" is the first knowledge to evaporate. Design docs either never get written, or go stale the moment they're finished and start misleading people.

Every non-trivial change ships a decision record in the same PR. The taxonomy is encoded in the file path (status/category/date-title), and both dimensions are closed in code — want a new category, you edit the code.

Three hard rules: "alternatives considered" is a required section; a central index file is explicitly forbidden (that kind of file is guaranteed to go stale); finished records move into a cryptographically sealed archive that every doc check skips, with a stated rule that an archived record is never authority for current behavior.