DeepSeek Harness source analysis: when “everything is a plugin” is pushed until there is no kernel

1.1 Answer “why” first

When a model company open-sources an agent framework, the motive is not the same as an application company’s. An application company wants a product. A model company wants a carrier that can fully release the model’s capability, and that carrier has to be reshapeable by outsiders into any form.

DeepSeek Harness’s README is only 55 lines, but the first sentence already states the architectural stance (README.md:7):

It uses an architecture where everything is a plugin, and is powered by Cordis, whose design is described in A Programming Paradigm for Spatiotemporal Composability.

Three points of extremely high information density:

1. Everything is a plugin — not “plugins are supported,” but “only plugins.”
2. The substrate is Cordis, an independent plugin framework with a paper, vendored into the repository.
3. The paper title’s spatiotemporal composability — in engineering terms: spatially, services are replaceable by key; temporally, registrations unwind in reverse order.

1.2 The concrete pain it is solving

Of the 20-plus agent projects this series has analyzed, the overwhelming majority have this shape: one main loop, plus a pile of features that grew around the main loop. That shape has a shared disease:

Every new requirement comes back and patches the main loop.

Permission confirmation inserts itself before tool execution, context compaction inserts itself into the while, swapping model vendors edits the adapter function, supporting a second frontend copies a loop. Three months later the main loop is a thousand-line mud ball, and no external contributor can extend it without changing it.

dsh’s insight: first build a runtime with no privileged kernel, then make the loop itself a plugin.

The sentence at docs/architecture.md:13 is the spine of the entire architecture document:

There is no privileged core to patch: you extend dsh by mounting a plugin beside the others, and registrations are effects that unwind when their plugin unloads.

“There is no privileged kernel to patch” — you extend dsh by mounting a new plugin beside the others, not by stuffing code into the center.

1.3 Three verifiable engineering claims

1.4 Relation to earlier work in this series

mindmap
  root((Agent 架构的三种形态))
    循环型
      Claude Code
      Codex
      Cline
      特征：主循环是中心
功能围着它长
    宿主型
      Open Design
      特征：不写循环
把别人的 CLI 当引擎
    harness 型
      DeepSeek Harness
      特征：没有中心
循环也是插件
      Reasonix 部分接近
但仍是单循环

The same company’s two open-source agents happen to take two roads: Reasonix is “one static binary + cache-first + a transport-agnostic controller,” chasing cost and portability; Harness is “a 241-package monorepo + everything is a plugin,” chasing replaceability and extensibility. That contrast itself is interesting — Chapter 31 will expand it.

2.1 Evidence table

2.2 A rare rule: refuse over-defense

Most engineering norms teach you to “validate more.” dsh does the opposite (AGENTS.md):

Trust TypeScript at typed same-process boundaries. Do not add runtime validation, fallback behavior, or hostile-input tests solely for values the static interface requires; validate at parser/config, queued, model/tool JSON, durable/file, worker, process, and wire boundaries.

It lists seven boundaries that must be validated (parser/config, queue, model and tool JSON, durable/file, worker, process, wire) and explicitly says: do not add validation elsewhere.

The reason is a chain reaction of per-file 100% coverage: if you add a defensive branch that cannot fire, you have to write an impossible test for it, or write an exemption comment. So “over-defense” has a direct cost under this constitution.

This is a rule I have not seen a second house write down in this series. It shows that this repository’s norms are not a copied best-practice checklist; they grew out of its own gate system.

2.3 “Pre-release stance”: writing the technical-debt policy into the constitution

AGENTS.md has a section titled "Pre-release stance: foundation over blast radius". The first sentence is:

Remove this section at the first tagged release. With no external consumers, prefer the correct foundation over compatibility shims: rename or repackage freely and update every reference together. Backends reject old on-disk formats.

It even wrote its own deletion condition — delete this section at the first official tag.

This style of “temporary rule with a self-destruct instruction” is far more effective than the verbal promise “we will refactor later.” Accompanying it: SESSION_FORMAT_VERSION stays at 0 and explicitly makes no compatibility promise.

3.1 Top-level shape

deepseek-harness/
├── vendor/          # 9 包 · 6 584 行 —— pinned 的 Cordis 源码副本（manifest 带上游 SHA）
├── packages/        # 219 包 —— @deepseek-ai/dsh-<name>，按 group/pkg 两级组织
│   ├── core/        #   8 包 · 40 854 行 —— session · system-prompt · tools · agent · agent-loop · scope
│   ├── client/      #  39 包 · 138 163 行 —— Web 客户端模块（全仓最大组）
│   ├── subagent/    #  11 包 · 24 555 行 —— 子智能体缝 + 多种 provider
│   ├── host/        #   8 包 · 22 513 行 —— 宿主能力
│   ├── session/     #  13 包 · 21 520 行 —— 日志持久化/投影/标题/遥测
│   ├── llm/         #   5 包 · 20 502 行 —— 模型缝 + DeepSeek providers
│   ├── extensions/  #   4 包 · 20 305 行
│   ├── typert/      #  11 包 · 15 404 行 —— 类型图生成器/加载器/运行时注册表
│   ├── test-support/#   6 包 · 13 391 行 —— 测试基础设施（自成一等公民）
│   ├── fs/ shell/ sandbox/ terminal/ lsp/ … 执行世界 40 包 · 62 000+ 行
│   └── goal/ plan/ todo/ schedule/ jobs/ guard/ … 治理 39 包
├── apps/            #   2 包 · 23 928 行 —— cli（拥有 dsh bin）+ web
├── native/          #   4 包 · 343 行 —— Landlock 原生启动器（按平台分包）
├── python/          #   4 286 行 —— Python SDK + bundled runtime
├── examples/        # 可运行的 cordis.yml 叶子
├── docs/            # 40+ 子系统文档，全部双语，其中 8 177 行是生成的
├── scripts/         # 124 个 .ts —— 生成器 + 28 个 verify-* 门禁
├── .agents/         # 686 篇 Agent Notes + 11 个 skill
└── AGENTS.md        # 架构宪法（CLAUDE.md 是它的符号链接）

3.2 Micro stack: the layers one request actually walks

After the macro, the micro. The technical layers a model request actually walks:

flowchart TB
    subgraph L1["① 装配层（启动期，YAML → 插件树）"]
        A1["profile（web/headless）"] --> A2["bundle 有序叠层"]
        A2 --> A3["cordis.patch.yml × 3 级 + --patch"]
        A3 --> A4["Loader：!!js 表达式插值"]
    end
    subgraph L2["② 框架层（Cordis）"]
        B1["Context：服务仓库"] --> B2["inject：不动点解析加载顺序"]
        B2 --> B3["Typed Events：emit/waterfall/parallel/serial"]
        B3 --> B4["effect：可逆注册 + 逆序拆卸"]
    end
    subgraph L3["③ 主轴层（core 8 包）"]
        C1["ctx.sessions：append-only 日志"]
        C2["ctx.systemPrompt：有序段 + 工具 schema"]
        C3["ctx.tools：注册表 + 五段流水线"]
        C4["ctx.agents / ctx.agentLoop：驱动"]
        C5["ctx.scope：逐 agent 注册隔离"]
    end
    subgraph L4["④ 能力层（seam × N，每个三角色）"]
        D1["ctx.llm"] & D2["ctx.fs / subprocess"] & D3["ctx.shell / terminals / lsp"]
        D4["ctx.sandbox"] & D5["ctx.subagents"] & D6["ctx.compaction / spillStore"]
    end
    subgraph L5["⑤ 前端层（一套行为四种壳）"]
        E1["apps/cli"] & E2["apps/web + client 39 包"] & E3["ACP 自动化"] & E4["JSON-RPC SDK（TS/Python）"]
    end
    L1 --> L2 --> L3 --> L4
    L3 --> L5
    L4 -.被 L3 注入.-> L3

The five-layer division of labor is very clean: the assembly layer decides what exists, the framework layer decides how it is wired, the spine layer decides how it runs, the capability layer decides what it can do, the frontend layer decides who is watching.

3.3 In-degree: where the real center of gravity is

I ran a full census of the 241 packages (script in Chapter 33), counting inter-package dependencies in package.json and inject declarations. Packages with the highest in-degree:

dsh-invariants at 218 in-degree is the single most informative number in this analysis. It means “runtime invariants” are not an optional practice of some team; they are part of a package’s birth certificate. Chapter 27 will cover how this constitution operates.

Service-side in-degree (inject declarations):

tools 31 times, systemPrompt 20 times means these two are the largest confluence points — half the repository is contributing into the tool table and the prompt. That is exactly why they must be registries, not constants.

3.4 The stack in one breath

• Language: TypeScript (ESM everywhere, strict: true + noImplicitAny; every residual any must explain why it cannot be narrowed)
• Package management: pnpm 11.7 workspaces, node ^22.19 || >=24
• Framework: vendored Cordis (plugins / services / events / effects)
• Build: tsc emits lib/types + tsdown builds the runtime bundle; source face and artifact face are strictly unmixed
• Tests: vitest × 6 layers (unit / per-file 100% coverage / real-API e2e / keyless snapshot / browser snapshot / gate collection)
• Frontend: apps/web + client 39 packages (138 163 lines, including UI slots / primitives / locale / connection layering)
• Native: the Landlock launcher is a C11 static executable (native/landlock-run/packages/entry/src/main.c), not an N-API addon; the npm name carrying node-addon is historical naming only. On Linux, sandbox-local tries bwrap first then falls back to Landlock; darwin uses Seatbelt/sandbox-exec; win32 uses a windows-acl restricted token (PLATFORM_CHAINS in sandbox-local/src/index.ts)
• Protocol surface: ACP (Agent Client Protocol), JSON-RPC SDK (TS + Python), Typert RPC gateway

5.1 Five sentences

docs/cordis-primer.md:9-13 defines the entire framework in five sentences:

Item 3 is the turning point of the whole architecture. “Load order is expressed through service requirements, not manual boot sequencing” — that one sentence kills the nastiest class of complexity in agent frameworks: the boot-order table.

5.2 How a service key is declared: declaration merging

// packages/shell/shell/src/index.ts:40-44
declare module '@deepseek-ai/cordis' {
  interface Context {
    shell: ShellExecutor
  }
}

This move gets two things that are usually mutually exclusive:

• Globally visible types: writing ctx.shell.run(...) in any package has full type hints
• Runtime-injected implementation: no import of any concrete implementation

The glossary has a strict constraint on Service Definition (docs/glossary.md:9): it must be a Cordis Service (an abstract class such as ShellExecutor, or a concrete registry such as WebRuntime), “never a TypeScript interface”.

Why not an interface? Because an interface is type-only with no runtime existence, and a seam needs a runtime entity that can be provided onto ctx, can hold a lifecycle, and can be torn down by HMR.

5.3 Duplicate service names: fail loud

The comment at packages/shell/shell/src/index.ts:16-20 explains why the shell settings namespace belongs to the Definition and not to any executor:

a host composes exactly one provider of ctx.shell (the win32 layer swaps the POSIX rows for the pwsh ones, and mounting both fails loud on a duplicate service registration), so the providers share one namespace without ever registering it twice, and a settings document carried between platforms keeps resolving on both.

Three payoffs in one: the Windows layer switches to PowerShell by replacing config rows rather than adding a branch; mounting two providers at once explodes immediately rather than silently picking one; a settings document carried across platforms still resolves on both sides.

5.4 Four dispatch modes and waterfall semantics

See Chapter 7.

5.5 Cost

Item 4 is worth noting: dsh vendors Cordis into the repository rather than taking it as an npm dependency. The vendoring policy in AGENTS.md requires: a pinned source copy, a manifest carrying the upstream SHA, updates through the sync procedure, local patches must be re-applied or retired, and test && build must be re-run after sync.

This is a pragmatic choice: framework and product are on the same evolution cadence; they are not yet at a stage where a version can be locked.

6.1 Motive and constraint

Motive: let a capability such as “execute bash” be replaceable as a whole (host / sandbox / remote / PowerShell), while the tool contract the model sees stays unchanged.

Constraint: once the schema the model sees changes, the prompt cache dies, model behavior drifts, snapshot tests all go red. So replacement must happen on a layer the model cannot see.

6.2 Rejected alternatives

6.3 Choice: three roles

docs/architecture.md:100:

A seam is a swappable capability with three roles: a Service Definition declaring the interface, a Service Provider implementing it, and a Consumer using it, commonly a model-facing tool. A package may combine roles, but one role alone is not a seam; adding a capability means designing all three.

AGENTS.md upgrades this to a hard rule:

A capability seam comprises Service Definition / Service Provider / Consumer roles. It is complete, never one role; split only when roles evolve independently.

shell is the officially designated template (docs/glossary.md:9):

flowchart LR
    subgraph D["① Definition · dsh-shell（476 行）"]
        DD["abstract class ShellExecutor
declare ctx.shell
词汇：ExecRequest / ExecSpec / Process / RunResult
+ SHELL_SETTINGS_NAMESPACE"]
    end
    subgraph P["② Providers（四个）"]
        P1["bash-local"]; P2["bash-sandbox"]; P3["pwsh-local"]; P4["pwsh-sandbox"]
    end
    subgraph C["③ Consumers（三个模型可见工具）"]
        C1["tool-bash → bash"]; C2["tool-pwsh → pwsh"]; C3["tool-bash-persistent → bash（PTY）"]
    end
    DD -.实现.- P
    DD -.注入.- C
    C --> M["模型只看到工具名 + JSON Schema"]
    P --> W["ctx.subprocess / ctx.terminals"]

6.4 A refined detail: the request/spec split

AGENTS.md designates shell as the template for “explicit over implicit”:

Explicit > implicit at package boundaries: defaulting is an explicit resolve(request): Spec step in the owning implementation, never a hidden ?? default inside run()（the dsh-shell request/spec split is the template）.

ShellExecRequest (optional fields) and ShellExecSpec (complete fields) are two types. Default resolution is an explicit step that can be logged and asserted, not a ?? hidden inside run().

The cost of not doing this is concrete: the caller does not know the actual timeout, it cannot be found in the log, it silently changes after a provider swap, tests cannot assert it.

6.5 The Definition’s sense of boundary

The module JSDoc at packages/shell/shell/src/index.ts:1-5:

Service Definition for the ctx.shell capability seam, covering foreground commands and background process handles. Job ids, ownership, polling, and notices belong to @deepseek-ai/dsh-jobs, keeping executors independent of sessions.

“Keep executors independent of sessions” — background-job ids, ownership, polling, and notices all belong to ctx.jobs. So the same executor can serve chat, an automation protocol, and a sub-agent at once.

This sense of “push out what is not mine” appears repeatedly in the module JSDoc of 241 packages. It is why this architecture can grow this large without collapsing.

6.6 Cost

• A capability is at least three packages. The repository’s package count therefore inflates to 241.
• Navigation cost: to change “bash timeout” you first have to decide whether to change the Definition (contract), the Provider (implementation), or the Consumer (schema).
• Risk of over-splitting: the constitution writes “split only when roles evolve independently,” and allows one package to hold multiple roles (dsh-llm is both Definition and Consumer).

7.1 Three event domains

docs/architecture.md:55 is blunt: "Events are the extension points, and picking the right domain is the first decision in most changes."

The complete producer/consumer table for the three domains is in docs/event-producer-consumer.md (generated).

7.2 Four dispatch modes

docs/cordis-primer.md:19-24:

The key sentence (:26):

The dispatch mode is part of the event's public contract. New harness events document it with an @mode tag so the generated catalog can check declarations against dispatch sites.

The dispatch mode is a public contract, written in JSDoc with an @mode tag, and the generated catalog checks that declarations match actual dispatch sites.

7.3 Technical highlight: separating “may mutate” from “may only watch” with types

Look at the tool registry’s four events (packages/core/tools/src/index.ts:150,161,173,195):

/** @mode waterfall */ 'tools/pre-execute'(exec, next): Promise<PreToolDecision>
/** @mode waterfall */ 'tools/execute'(exec, next): Promise<…>
/** @mode waterfall */ 'tools/post-execute'(exec, result, next): Promise<PostToolDecision>
/** @mode emit      */ 'tools/result'(exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): undefined

The first three are waterfall (may rewrite); the last is emit + both parameters Readonly<> (may only observe).

And it does not rest on types alone — there is also a runtime invariant (packages/core/tools/src/invariant.ts:23-25):

if (!Object.isFrozen(exec)) fail('tools/result execution must be frozen before publication')
if (…) fail('tools/result outcome and content must be frozen before publication')

Once a result is finalized it is frozen; no observer can mutate it; a violation is caught at runtime.

This is the most meticulous treatment of an “event system” I have seen in this series. In most projects’ EventEmitters, “some listener secretly mutated a finalized result” is a class of extremely hard-to-debug bugs; dsh uses dispatch mode + Readonly + Object.freeze + a runtime assertion as four layers of defense to make it impossible.

7.4 waterfall is around-middleware

docs/cordis-primer.md:30:

ctx.waterfall is around-middleware. A listener receives (...args, next). Call next() to delegate the possibly wrapped result to the next service; return without next() to short-circuit.

Paired with the capitalized rule in AGENTS.md:

Waterfall listeners MUST call next() to delegate; returning without it short-circuits the chain.

Short-circuit is part of the design (:34):

For single-decision events, short-circuiting is the design. A policy listener can return without next() when it owns the decision, while a listener that only annotates or observes must delegate.

The danger of this rule is that violating it does not error: a listener that only wanted to log forgets next(), every downstream policy silently dies, and the logs look fine. That is why it is lifted into AGENTS.md with a capitalized MUST.

8.1 Definitions

docs/architecture.md:65:

A step is one model request plus the tools it calls. A turn is zero or more steps: it opens before its first input is claimed and closes once nothing is owed.

Two deliberate phrasings:

• "zero or more steps" — a zero-step turn is legal (see 8.4)
• "once nothing is owed" — the close condition is “nothing is owed,” not “the model finished speaking”

8.2 The full pipeline

The architecture document gives a stretch of pseudocode (:67-82). I mapped it against the source into a sequence diagram:

sequenceDiagram
    participant IN as inbox
    participant D as ReactLoopAgent
    participant SP as ctx.systemPrompt
    participant L as 会话日志
    participant M as ctx.llm
    participant T as ctx.tools

    D->>L: turn/start
    loop 每个 step
        D->>IN: claim(target, turn)
        D->>SP: assemble(assembleContextFor(agent, signal))
        D->>D: agent/pre-step ⟨waterfall⟩ → reject | enter(messages)
        Note over D: reject 或首个 enter 被改空
→ 关掉零 step 的 turn（日志留痕）
        D->>L: step/start
        D->>L: user/message ×N
        D->>L: deriveMessages()
        D->>D: agent/request ⟨waterfall⟩ → provider/model/参数
        D->>M: prepareCall → stream(request)
        M-->>L: assistant/chunk ×N（每片记 seq）
        D->>L: assistant/message（sourceEventSeqs 回指 chunk）
        alt finish = error/aborted
            D->>D: agent/request-error ⟨waterfall⟩ → retry?
        else max-tokens
            D->>D: 返回 max-tokens（sticky）
        else 无 tool-call
            D->>D: completed
        else 有 tool-call
            D->>T: executeToolCalls（三道 waterfall）
            T-->>IN: 附加上下文 → next-step 队列
        end
        D->>L: step/end
        D->>D: agent/turn-stopping ⟨serial⟩
        Note over D,IN: 再查 inbox.nextStep：非空则继续
    end
    D->>L: turn/end（结构化 reason）

Source locations: the outer while (await this.turn()) {} is at packages/core/agent-loop/src/agent.ts:212, turn() at :246, step() at :332, buildRequest() at :407.

8.3 Four technical highlights

① max-tokens is sticky (agent.ts:285-290):

max-tokens is sticky: once any step hits the ceiling, later steps that complete normally must not downgrade the turn outcome.

If step 3 of a turn hits the output ceiling and step 4 finishes normally — the turn’s conclusion must still be “hit the ceiling.” Downstream (UI hints, retry policy, eval) uses that to judge whether the result is trustworthy. Downgrading it is lying.

② Every chunk enters the log, and the message points back at its sources (agent.ts:349,381-390):

chunkSeqs.push(this.session.append('assistant/chunk', { turn, step, chunk }).seq)
// …
this.session.append('assistant/message', { turn, step, message, usage },
  { surfaceOp: 'append', sourceEventSeqs: chunkSeqs })

sourceEventSeqs lets any final message be traced back to the raw streaming slices that composed it. When you are debugging “why was this answer truncated,” this is life-saving.

③ Request errors are a retryable waterfall, not try/catch (agent.ts:354-371):

const action = await this.dispatch.waterfall('agent/request-error',
  { turn, step, provider, failure, retryPolicy, signal }, () => Promise.resolve(undefined))
if (action?.kind !== 'retry') throw new LlmError(…)
continue    // 重试整个请求（包括重新 buildRequest）

Retry policy is a plugin, not a constant in the loop. And a retry re-walks buildRequest — so a retry can swap provider/model.

④ Failure is structured (agent.ts:307-314):

turnEnds = { kind: 'error', error: error instanceof LlmError
  ? error.failure                                     // LlmError 保留它的事实
  : { message: errorChain(error), code: 'UNKNOWN' } }  // 其它一切 flatten

turn/end is always emitted in finally (:316-322). Never let a half-turn appear in the log — otherwise replay logic has to handle incomplete state, and that is a bottomless pit.

8.4 Why a zero-step turn must exist

// agent.ts:271-277
if (turnEnds && decision.messages.length === 0) break
// A removed waking message or an enter decision rewritten to empty
// still owns the initial turn boundary, but it spends no model call.
if (phase.step === 0 && decision.messages.length === 0) {
  turnEnds = { kind: 'completed' }
  return false
}

The user pressed send, but some plugin emptied the message. A turn is still opened and closed normally. architecture.md explains (:88):

a rejected or empty first claim still closes a durable turn that spent no step, so the log records the attempt.

The consequence of not doing this: the UI shows “I clearly sent a message but nothing happened,” and the log has no trace. “The user initiated an attempt” is itself a fact that needs to be recorded.

8.5 A constitutional fingerprint: /* v8 ignore next */

agent.ts:333:

/* v8 ignore next -- private callers establish the running phase before executing a step */
if (this.phase.kind !== 'running') throw new Error(`agent "${this.id}": step outside running phase`)

This is a fingerprint left by the per-file 100% coverage gate: an unreachable defensive branch must be explicitly exempted and the reason written down. And scripts/coverage-exempt.ts + coverage-exempt.spec.ts in turn guard the exemptions themselves. See Chapter 26.

9.1 One inbox, two delivery slots

docs/architecture.md:86:

Input reaches the driver through one inbox. Some messages wake it immediately; injected context waits in the inbox until another message does.

Four input sources, two wake semantics (packages/core/agent-loop/src/agent.ts:122-132):

inject and steer enter the same next-step queue; the difference is only wake. Injection does not open a turn on its own: when idle it only enters the inbox; when running it is eaten only at a step boundary after the already-claimed batch. Otherwise every injected “the current branch is main” would idle-open a round.

The inbox is not a pure in-memory queue. First session.append('agent/inbox/spliced', …), then mutate the live projection (packages/core/agent/src/inbox.ts:157-193). cancel / resume / fork can all reconstruct pending work from the log.

target switching inside the loop (agent.ts:261,300):

let target: InboxTarget = 'next-turn'   // turn 的第一个 step 领 turn 队列
// …一个 step 结束后…
target = 'next-step'                    // 后续 step 领 step 队列

9.2 How tools stuff things into the inbox

agent.ts:395-398:

const { concluded } = await executeToolCalls(
  this.loopCtx, turn, step, toolCalls, signal,
  context => this.inbox.splice('next-step', this.inbox.nextStep.length, 0, [context]),
)
return concluded ? { kind: 'completed' } : null

Two details:

• The sixth argument is a delivery callback — this is where the tools/post-execute “add context” decision lands. The pipeline document describes it as “Active-batch additionalContexts FIFO → injected user/message after recorded tool results”.
• concluded ? completed : null — “whether another request is still owed” is reported by the tool batch itself, not guessed by the loop.

9.3 Technical highlight: the “announce–object” pattern of agent/turn-stopping

The two checks before the loop wants to stop (agent.ts:295-299):

if (turnEnds && this.inbox.nextStep.length === 0) {
  await this.dispatch.serial('agent/turn-stopping', { turn, signal })   // 发公告
  signal.throwIfAborted()
}
if (turnEnds && this.inbox.nextStep.length === 0) break                 // 再查一次

After the serial event is sent, check the inbox again. Because a listener is fully allowed to stuff something new into the inbox at that moment.

This is the textbook answer to “keep the loop going without changing the loop”: give the loop an announcement moment of “I am about to stop,” and any plugin can object at that moment.

agent/turn-stopping is serial and has no next() (architecture.md:84) — every listener is awaited in turn; no one can short-circuit someone else’s right to object. The standard objection from a listener is steer (stuff a message into next-step and wake), then the second inbox check is non-empty, and the turn continues. This is the answer to “keep the loop going without changing the loop” inside the same turn.

Goal continuation in the same session is not this hook. goal-round-driver listens for agent/status entering idle with the goal still armed, then agent.followup opens the next turn (see Chapter 14). Writing goal continuation into turn-stopping is wrong: that would mash “this round still owes a step” and “the goal is not finished, open another round” into one thing.

9.4 Wake latch: teardown waits on no model turn

wakeDriver at agent.ts:164-193:

if (this.phase.kind !== 'idle') {
  // Maintenance and aborted drivers cannot deliver the wake: latch it for
  // replay at convergence. Live drivers claim queued work themselves;
  // disposal never latches, so teardown waits on no model turn.
  const reason = this.phase.abort.signal.reason as AgentCancelCause | undefined
  if (reason?.kind !== 'disposed' && (this.phase.kind === 'maintenance' || wakeAfterAbort)) {
    this.phase.wakeRequested = true
  }
  return
}

Phase is three states: idle / maintenance / running (agent.ts:38-46). The maintenance phase is a design rarely seen elsewhere — while the driver is doing maintenance work (compaction, title generation) it does not accept wake delivery; it latches and waits for convergence.

And disposal never latches: so teardown waits on no model turn. This class of detail — “teardown must not be held hostage by business logic” — is the watershed between a harness that has run in production for a long time and a demo.

10.1 Motive

In the step-0 scheme of const messages = [...], the model’s input lives in memory. Then reconnect after disconnect, session fork, auditing “what did the model actually see,” UI replay of the streaming process, eval reproduction — none of it can be done.

10.2 Choice: the log is the truth, messages are a projection

docs/architecture.md:94:

The session log is the source of the context the model sees. deriveMessages() projects model history from it, and raw assistant/chunk events preserve replay and UI fidelity. Fork, resume, transcripts, telemetry, and persistence all derive from this stream.

The direction is crucial: not “the message array happens to be logged,” but “the log is the truth, the message array is a projection.”

The module JSDoc of packages/core/session:

Event-sourced session service: append-only session log, in-memory store, and the derived LLM message history. Persistence is a plugin concern (subscribe to session/event, drain on session/flush).

Persistence is a plugin concern — the session service itself never touches disk. That is why the session group has 13 packages: log core + JSONL/zstd persistence + projection + title generation + telemetry + reference resolution…

10.3 Technical highlight: institutionalizing invariants

docs/architecture.md:96 and AGENTS.md:

Model-visible means logged. Anything that reaches a model request must be reconstructable from the log, and a runtime invariant asserts it. This is why a new model-visible input requires a new session event: extend SessionEventMap and render from the log.

The concrete assertion hangs on the llm/stream entry (packages/core/agent-loop/src/invariant.ts:21-52): for requests emitted by agent-loop, freeze GenerateOptions, then require JSON equality between session.deriveMessages() and options.messages, otherwise fail (log-reconstruction desync). The agent/request waterfall cannot change messages; to change history you can only append a session event. Without this: a plugin can silently mutate the outgoing array, live and replay fork, and there is no assertion.

Invariants are not a global assert function; they are a per-package ownership registration service (docs/subsystems/invariants.md):

// packages/runtime-diagnostics/invariants/src/index.ts:94
register(packageName: string, installer: InvariantInstaller): () => void

Constitutional points:

The most meticulous part is what it specifies a check may assert (AGENTS.md):

Runtime invariants assert owned relationships. Check authoritative event streams or mutable data, not service or method presence, plugin metadata or effects, or fixed pure examples. Without a plausible relationship, an explained empty companion is correct.

You may not write an assertion that pretends to check such as “does ctx.shell exist.” When there is no real relationship to assert, the correct move is to export an empty installer and explain why in a comment that starts with No runtime invariant:.

And this too is machine-guarded: pnpm run verify-package-invariants rejects “generated placeholder markers,” “unexplained empty installers,” “non-empty installers that ignore the reporter,” “wrong registration names,” “incomplete export/publish/dependency/bundle wiring.”

This is why dsh-invariants is depended on by 218 packages. None of the 21 projects in this series does this.

10.4 A refined design in the session-log versioning mechanism

AGENTS.md:

A SessionEventMap member is required-on-read by default — builds that do not know its type refuse the log unless the event carries the envelope's ignorable: true; only structural format changes bump SESSION_FORMAT_VERSION.

Strict by default: an old-version program that reads an unrecognized event type refuses the entire log, rather than skipping it and continuing. Because skipping means “a piece of model-visible history is missing,” and that produces silently wrong replay.

To let an event be ignorable by old versions, you must explicitly mark ignorable: true on the envelope. Safe by default, exceptions explicit.

10.5 Cost

• Any “add some context for the model” requirement must first extend SessionEventMap + add rendering, much more work than pushing a message
• Log volume is large (every chunk is recorded) — hence JSONL + zstd persistence and a packed-row layout
• 218 packages’ invariant companions are a real maintenance burden (even though most are empty installers with an explanation)

11.1 Motive

Tool execution is the place in an agent that most needs plug-and-play: permission, approval, sandbox, timeout, retry, metrics, result rewriting, UI rendering, filesystem read/write policy, hook bridging… stuffing all of that into runTool() is a thousand-line mud ball.

The first sentence of docs/tool-execution-pipeline.md states the design goal:

This graph shows where policy, hooks, sandboxing, filesystem guards, result rewriting, final-outcome observation, and UI rendering run without changing the loop.

11.2 The full pipeline

The module JSDoc of packages/core/tools summarizes it as five stages:

Tool registry, model presentation modes, and pre/guard/around/post/result execution pipeline.

flowchart TD
    A["assistant 消息含 tool-call"] --> B["session: tool/call
（执行前先记）"]
    B --> C["UI: presentCall(args)
待处理卡片"]
    B --> D["tools/pre-execute ⟨waterfall⟩
hooks · permission · sandbox"]
    D -->|allow| E["注册的单调守卫
deny 或弃权 · 身份受保护"]
    D -->|deny| X["跳过工具体"]
    D -->|ask| F["ctx.approval 一次性询问
缺失或无法回答 = deny"]
    F -->|allowed-once| E
    F -->|拒绝/取消/不可用| X
    E -->|allow| G["tools/execute ⟨waterfall · around⟩
timeout · retry · metrics"]
    E -->|deny| X
    G --> H["ToolDefinition.execute() 本体"]
    H --> I["fs/write-intent · fs/edit-intent 门
（仅 tool-fs 变更）"]
    H --> J["工具自有 session 事件
todo/write · fs/observed · hook/* · tool/code-dispatch"]
    H --> G
    G --> K["tools/post-execute ⟨waterfall⟩
accept · block · replace · add context"]
    X --> K
    K --> L["注册表外层规范化
流水线/快照抛出 → isError"]
    L --> M["finalizeContent
最后的 content-only 不变量"]
    M --> N["tools/result ⟨emit · 冻结⟩
权威结果，只能观察"]
    N --> O["session: tool/result
单一模型可见结果"]
    O --> P["additionalContexts FIFO
→ inbox.next-step"]

11.3 Technical highlight one: monotonic guards

There is a design in the pipeline that looks redundant: given the tools/pre-execute waterfall, why an extra guard layer?

Because waterfall has a fatal flexibility: a later-registered listener can override earlier decisions.

// 一个能通过 code review 的"善意"插件
ctx.on('tools/pre-execute', async (exec, next) => {
  const d = await next()
  if (d.kind === 'deny' && isProbablySafe(exec)) return { kind: 'allow' }  // 提权了
  return d
})

So dsh runs a guard layer after the extensible waterfall. The pipeline document’s description:

Registered monotonic guards — deny or abstain; identity protected

Only two options: deny, or abstain. There is no “allow” return value, so it is mathematically impossible to relax anything. Source JSDoc (packages/core/tools/src/index.ts:704,1101):

A monotonic execution guard evaluated after every tools/pre-execute … Register a monotonic guard after the extensible tools/pre-execute …

The phrasing “after the extensible” is precise: the extensible part runs first, the non-relaxable part runs after. Order itself is the safety design.

11.4 Technical highlight two: pipeline order itself is a runtime contract

packages/core/tools/src/invariant.ts:94-115:

if (eventName === 'tools/pre-execute') {
  if (stages.has(exec)) fail('tools/pre-execute repeated for one execution')
}
if (…) { if (stages.get(exec) !== 'pre') fail('tools/execute must follow tools/pre-execute') }
if (eventName === 'tools/post-execute') {
  if (…) fail('tools/post-execute must follow tools/pre-execute or tools/execute')
}

Stage order is not implied by code structure; it is explicitly asserted by a runtime invariant. A miswritten plugin that bypasses stage order explodes immediately and is attributed to its package name.

11.5 Technical highlight three: UI render intent is part of the design

AGENTS.md:

A tool's UI render intent is part of its design, decided up front (generic/terminal/diff, locations); presentation methods are pure functions of args.

When a tool is defined it must already say “I should be rendered as an ordinary card, terminal output, or a diff.” And the render function must be a pure function of args — so a pending card can be drawn before execution (presentCall(args) in the pipeline diagram is before tools/pre-execute).

11.6 The catalog of 47 tools is booted, not statically scraped

The file-header comment of docs/tool-catalog.md (1 873 lines):

Unlike the cordis catalog (a pure source-AST pass), this generator BOOTS each tool plugin on a real context and reads ctx.tools.schemas(), because a tool schema is not statically knowable (runtime-spread enums, concatenated descriptions, config-driven names, raw-JSON-Schema MCP tools). A completeness guard globs packages/*/tool-* and fails if any package is missing from the generator's boot manifest, so a new tool cannot be silently undocumented.

A tool schema is not statically knowable (runtime-spread enums, concatenated descriptions, config-driven names, raw JSON-Schema from MCP), so the generator actually boots each tool plugin to read the schema. And there is a completeness guard: a new tool cannot be silently omitted from the docs.

The 47 model-visible tools (from my census):

ask_user_question · bash · pwsh · console · edit · read · read_image · write · str_replace_editor
glob · grep · lsp · web_fetch · web_search · skill · todo_write · ralph · workflow
create_goal · get_goal · update_goal · schedule_create · schedule_delete · schedule_list
job_kill · job_list · job_output · terminal_open/read/send/close/list/signal
subagent · subagent_fork · send_message · interrupt_agent · list_agents · report
session_search · session_trace · session_event_read/search/trace
cordis_define/undefine/run/stop/inspect_list/inspect_query/inspect_self

That last line is the protagonist of Chapter 29: the agent can define, run, and inspect its own Cordis plugins.

12.1 systemPrompt is a registry, not a template

The module JSDoc of packages/core/system-prompt (1 582 lines):

Registry for ordered system sections, dynamic context, tool schemas, and prompt variables.

Four kinds of contribution. Depended on by 30 packages, inject in-degree 20 — half the repository has to stuff things into the prompt, which is exactly why it must be a registry.

Assembly happens on every step (agent.ts:230):

const assembly = await this.loopCtx.systemPrompt.assemble(assembleContextFor(this, signal))

Not once per turn. Because the tool set can change mid-turn: a sub-agent came up, plan mode exited, cordis_run mounted a new tool (Chapter 29).

assembleContextFor(this, signal) passes in both “which agent is asking” and the cancel signal — assembly is per-agent.

12.2 scope: two levels, flat, no inheritance

The module JSDoc of packages/core/scope (1 215 lines):

Scoped-context primitive: mint a Cordis context that tags registrations with an opaque identity and build routing-only event carriers for that identity.

The glossary’s definition is stricter (docs/glossary.md:13):

scope — the unit of per-agent registration: a contribution (tool, prompt section, variable, restriction, listener) is either global (visible to every agent) or scoped (owned by exactly one scope key). Two levels, flat: scoped registrations do not inherit down to subagents; subtree behavior is expressed with lineage data, never scope structure.

Three deliberate restrictions:

1. Only two levels (global / a single scope), no multi-level nesting
2. No downward inheritance — a sub-agent does not automatically receive the parent agent’s scoped registrations
3. When subtree behavior is needed, express it with lineage data, never with scope structure

Why this restraint? Because “scope inheritance” is the easiest place for a permission system to go wrong. Once inheritance is allowed, you have to answer “can a child override the parent’s restriction,” “what about a grandchild,” “what after a fork.” Two-level flatness kills all of those questions.

An instance (dsh-tool-subagent-report in docs/tool-catalog.md):

Registered per continuable in-process child rather than globally, so this schema is visible only inside such a child and survives its global toolFilter.

The report tool is visible only inside a continuable in-process child, and can pass through the global tool filter — because it is the only channel a child has to report to the parent, and it must not be filtered out.

13.1 Problem decomposition

A project that only does the first (compress history) will blow the window on the second case. A project that only does the second (truncate output) will never let the model see the truncated part.

13.2 spill: persist + locator + retrieval guidance

The Definition JSDoc of packages/spill (original wording captured by the census):

Service Definition for the spill storage capability seam (ctx.spillStore): an abstract service defining WHAT a spill backend does — persist a tool's oversized text and return a model-facing locator plus retrieval guidance.

Three words are the key: persist + locator (model-facing) + retrieval guidance.

Not simple truncation: the full content is stored, and the model is given a message of “I stored the complete result here; you can read it this way.”

Real usage (dsh-tool-fs-search in docs/tool-catalog.md):

Capped results save the complete formatted list through the optional ctx.spillStore backend; returned locators are follow-up-readable/searchable when the backend exposes local paths in co-located deployments.

Spilled content is not a grave — what the locator points at can still be processed by read and grep.

13.3 Compaction’s hard part is not the summary; it is “does this count as model-visible”

By Chapter 10’s constitution: a compaction result does count as model-visible, so it must be a session event, not a variable in memory.

That brings three payoffs: compaction is auditable (you can see which range was compacted and what the summary is), replayable (replaying the log yields the same model input), unwindable (delete that event and the original is restored).

The cost is that compaction cannot “mutate the array in place”; implementation complexity is higher.

13.4 ctx.spillStore is optional

Note the phrase above, “the optional ctx.spillStore backend.” Tools still work without a spill backend (they just truncate); with a backend they automatically upgrade to “truncate + locator.”

This is a secondary payoff of seam design: absence of a capability is a legal deployment shape, not a boot failure. Contrast ctx.lsp’s handling (docs/tool-catalog.md):

Requires a registered provider (e.g. @deepseek-ai/dsh-lsp-stdio) at runtime; without one, a query returns the structured LSP_UNAVAILABLE error rather than changing the schema.

Without a provider, return a structured error, do not change the schema. Because changing the schema kills the prompt cache and drifts model behavior. The contract the model sees must be decoupled from deployment details.

14.1 goal: event-sourced + CAS + human root authority + bounded

The module JSDoc of packages/goal (4 packages · 5 786 lines · ctx.goals):

Same-session goal domain: event-sourced state, compare-and-set mutations, and process-local continuation activation.

The deployment note in the tool catalog (dsh-tool-goal in docs/tool-catalog.md) is extremely dense:

create_goal, get_goal, update_goal … create, edit, pause, and resume require direct-human root authority; complete and blocked also accept the exact current goal round. The default blocked lower bound is three admitted rounds.

Three designs, unpacked one by one:

① Create / edit / pause / resume require “direct-human root authority.” The model cannot assign itself a goal, nor quietly change a goal. Otherwise “make the tests green” gets rewritten to “comment the tests out.”

② complete / blocked must carry the exact current round. This is compare-and-set: the model says “I completed the goal of round 5”; if it is actually round 6, the claim is invalid. This guards against stale claims.

③ blocked has a lower bound: at least 3 admitted rounds. The model cannot say “I am stuck” on round one; it must actually have tried three rounds.

Continuation does not go through agent/turn-stopping. goal-round-driver (packages/goal/goal-round-driver/src/index.ts:137-205) renders <goal_round> and agent.followup when the agent is idle, the goal is active and armed, and the inbox has no competing work. After resume the durable phase is still there, but activation is process-local state, disarmed by default, to avoid auto-continuation on a cold start. Not one line of loop code is changed: the driver only consumes the public agents / goals / sessions.

14.2 plan: making plan mode logged state

In AGENTS.md’s repository layout, plan is described as "plan mode as logged state".

Compared with Claude Code’s plan mode (a session-level boolean switch + prompt change), dsh’s approach is a ctx.planMode service + log events. The tool catalog’s note on dsh-plan-mode:

exit_plan_mode stays in the model-facing schema while planning is inactive so transitions add no tool-catalog churn on top of the plan-policy change. Its execute path rejects calls outside plan mode; in plan mode it presents the plan over the user-questions seam (approve / keep planning with feedback), and approval logs plan mode inactive at the step boundary.

Three points of care:

• The tool stays in the schema even outside plan mode — because entering and leaving plan mode should not change the tool table the model sees (cache-friendly + snapshot-stable)
• The execute path rejects calls outside the mode — schema stability is not behavioral relaxation
• After approval, “plan mode inactive” is logged at the step boundary — the state change has a definite log moment

14.3 schedule: a versioned timing capability

dsh-schedule in docs/tool-catalog.md:

Registered only inside live root Agent scopes created after the opt-in Schedule plugin loads. Version 1 accepts after_seconds, explicit absolute at, and bounded fixed-rate every_seconds, and discloses session-local delivery; management reads and mutations require the shared Session persistence barrier.

The phrasing “Version 1” is worth noticing — it treats “this tool’s capability set” as a versioned contract, not an arbitrarily growing parameter table. every_seconds is bounded (you cannot set it to once per millisecond). And it explicitly discloses that delivery is session-local (not cross-session).

14.4 jobs: a kind-agnostic background-job controller

dsh-tool-jobs in docs/tool-catalog.md:

The kind-agnostic background-job controller: background bash commands, PTY sends, and subagents are read, listed, and killed through the same three tools. Loading the plugin attaches the controller that arms producers' ctx.jobs.start().

Three tools (job_list / job_output / job_kill) cover every kind of background work. Background bash, PTY sends, sub-agents all go through the same set.

This solves a real model-experience problem: if every kind of background work has its own management tools, the model has to remember 9 tool names instead of 3, and frequently picks the wrong one.

And ctx.jobs’s design decouples executors from sessions (look back at the shell Definition JSDoc in §6.5) — job ids, ownership, polling, notices belong to jobs; the executor only executes.

14.5 todo: allowParallelInProgress is required with no default

dsh-tool-todo in docs/tool-catalog.md:

todo_write is session-owned state; UIs render the latest todo/write event as a checklist. allowParallelInProgress is required with no default, so the catalog states its choice: true, whose description invites several in_progress items. A deployment choosing false receives the same tool with a description asking for exactly one active task.

Required with no default is deliberate. Because “can several in-progress tasks exist at once” is a product-semantics choice, and should not have an implicit default. And that choice changes the tool description text — the same tool, two ways of teaching the model.

This is the landing of AGENTS.md’s “No hardcoded tunables in plugins”:

deployment-varying choices are validated Config fields changeable from cordis.yml; a DEFAULT_* constant or test hook is not configurability.

14.6 guard: loop hygiene

packages/guard has only two sub-packages, no unified entry package: repeat-tool-reminder (injects a reminder when the same tool+canonical args are hammered consecutively, never vetoes) and timeout-policy (wraps a deadline on tools/execute; when a tool declared timeoutMs but does not honor the signal, it yields a structured TOOL_TIMEOUT). AGENTS.md writes “loop-hygiene + tool-timeout plugins”. max-steps / token budget are not in this group.

15.1 How wide the provider range is

docs/architecture.md:102:

Subagent providers vary just as widely behind one interface, from a fresh child agent to a delegated turn in another product.

Behind one interface, from “start a new child agent” to “delegate to one round of conversation in another product.” The census shows package names such as subagent-codex and subagent-claude-code — it treats Codex and Claude Code as subagent providers.

This is a third shape of the same idea as this series’ Open Design (treat someone else’s CLI as the engine) and DeepTutor (treat a coding CLI as a consultable knowledge base): dsh treats them as providers of the subagent seam, so they automatically receive the entire infrastructure of jobs management, session recording, and the tool pipeline.

15.2 Three-layer tool design

The tool catalog has four subagent-related packages, with a clear division of labor:

The deployment note on tool-subagent particularly embodies “configuration is architecture”:

The shipped compositions load this package once per subagent backend, so the model additionally sees subagent_fork bound to the fork backend. Each instance's description, run_in_background parameter, and system-prompt policy follow its own backgroundMode and enableRunInBackground, so the two shipped schemas are not identical: subagent is continuable and defaults omitted calls to background with automatic settlement delivery, while subagent_fork stays one-shot and defaults them to foreground.

The same package loaded twice produces two tools with different semantics (one continuable + default background, one one-shot + default foreground). This is something only a pluginized architecture can do — in a main()-shaped architecture you would have to write two tool classes.

15.3 ralph: an interesting workflow tool

dsh-tool-ralph in docs/tool-catalog.md:

A fixed foreground workflow starts one fresh structured child per round; the model selects only the immutable objective and an optional round cap.

Each round starts a brand-new structured child; the model can only choose the “immutable objective” and a round cap. The model cannot change the objective, nor the flow — another instance of “sink the deterministic skeleton into the tool” (compare the same class of design in DeepTutor Chapter 14).

16.1 hooks: bridging Claude Code and Codex hook protocols

In AGENTS.md’s repository layout:

hooks/ Claude Code/Codex hook bridges + wire-protocol library

packages/hooks (3 packages · 4 933 lines) implements other products’ hook wire protocols. That means a hook script written for Claude Code can run inside dsh.

This is a decision with strategic meaning: lower migration cost. The user’s existing hook investment is not wasted. And it is made into an independent wire-protocol library, not hardcoded into the tool pipeline.

In the pipeline diagram, hooks hang on tools/pre-execute (“hooks · permission · sandbox”) and produce their own session events (hook/invoked / hook/result) — hook invocation and results are also log-visible.

16.2 skill: registry + local implementation + catalog/loader tools

packages/skill (4 packages · 6 242 lines): provider registry + local implementation + catalog/loader tools.

One line in the tool catalog for dsh-tool-skill is worth noticing:

skill | ctx.tools, ctx.agents, ctx.skills | tool/call, tool/result, user/message replacement catalogs via agent.inject()

The skill catalog is updated by replacing the user/message catalog via agent.inject() — looking back at Chapter 9, inject does not wake the loop, so refreshing the skill catalog does not trigger an extra model call; it waits for the next real message and goes in together. This is a clean application of the inbox’s dual semantics.

16.3 mcp: one package, 3 322 lines

packages/mcp has only 1 package. MCP tools’ schemas are raw JSON-Schema (see the generator explanation in tool-catalog.md), so they cannot be statically analyzed and must be read after boot.

17.1 The architecture’s strongest selling point

docs/architecture.md:102:

Seams are why one provider swap changes the whole product. Filesystem and subprocess providers share one execution world, so pointing them at a remote sandbox moves Bash, PTY, and LSP with them, with no provider forks.

flowchart TB
    subgraph prim["两个原语 seam"]
        FS["ctx.fs"]:::p
        SP["ctx.subprocess"]:::p
    end
    subgraph built["建在原语之上（26 包 · 42 885 行）"]
        SH["ctx.shell → bash / pwsh"]
        TM["ctx.terminals → 持久 PTY"]
        LSP["ctx.lsp → 语言服务"]
        SEARCH["glob / grep → 打包的 ripgrep"]
        CR["ctx.codeRuntime → 代码模式"]
    end
    FS --> built
    SP --> built
    subgraph swap["换 provider = 换整个世界"]
        L["本机：node:fs + child_process"]
        E["远程：dsh-e2b（沙箱 FS/subprocess 适配器）"]
    end
    L -.任选其一.-> prim
    E -.任选其一.-> prim
    classDef p fill:#e8f0fe,stroke:#4285f4

17.2 Code evidence for the claim

The key is the direction of dependence: no upper-layer capability directly imports node:child_process. I verified this in the census — subprocess is injected by 8 packages.

The search tools make the point most clearly (dsh-tool-fs-search in docs/tool-catalog.md):

glob and grep are unconditional discovery tools that spawn the packaged ripgrep binary (@vscode/ripgrep) through ctx.subprocess as ordinary foreground calls (never background jobs) — no host rg install and no shell layer.

“no shell layer”: search does not go through the shell. So search capability does not depend on “whether the machine has bash”; it works consistently in a remote sandbox, on Windows, and in a stripped container.

17.3 e2b is the empirical proof of this claim

packages/e2b (3 packages · 6 630 lines), positioned in AGENTS.md:

e2b/ E2B POC: sandbox + FS/subprocess adapters

A POC uses 6 630 lines to prove the architectural promise: swap two providers, five capabilities move with them.

Sizes of the execution-world groups (census data):

17.4 code-runtime: Code Mode

The run_code entry in docs/tool-catalog.md is the longest deployment note in the whole lecture; it is worth understanding in full:

Owned by the tool registry as a reserved transport outside filterable capability layers under mode: code / mode: both. Under code it is the registry's only wire contribution; the other visible capabilities are declared in a generated SDK section in the loaded runtime's language, and a program calls them through bindings scheduled under the native concurrency contract (submission-ordered starts and policy; concurrency-safe bodies overlap up to maxParallelSubCalls) that re-enter the complete guarded tool pipeline and link each nested execution to this outer result.

Unpacked:

1. Under Code Mode, run_code is the registry’s only wire contribution — the model sees only one tool
2. Other capabilities appear as a generated SDK section (in the runtime’s language, e.g. Python/JS)
3. The program calls them through bindings, re-entering the complete guarded tool pipeline
4. Each nested execution is linked to the outer result
5. Concurrency has a native contract: submission-ordered starts; concurrency-safe bodies overlap up to maxParallelSubCalls

This is a morphological jump from “tool call” to “write a program that calls tools”, and it does not bypass any safety check — nested calls re-walk the guard pipeline. In this series Claude Code’s code execution and Reasonix’s use_capability have explored similar ground; dsh’s version is the most thorough on “nested execution is also constrained by the complete pipeline.”

18.1 The sandbox does not execute; it only wraps argv

The extension-point table in docs/architecture.md:

Confine spawned processes | use a ctx.sandbox backend; consumers wrap argv before spawning

This design lets the sandbox compose with any provider: host bash, remote subprocess, LSP child process — anyone can wrap a layer before spawn. If the sandbox itself were responsible for execution, it would fight the executor for the same duty.

18.2 The platform chain is not “Landlock only”

PLATFORM_CHAINS of sandbox-local (packages/sandbox/sandbox-local/src/index.ts:159-165):

The Landlock launcher is in native/landlock-run: the body is C11 main.c (self-restrict-then-exec, the rule set inherited through execve; on failure exit 125, do not exec the target). The npm package name carries node-addon, but it is not an N-API addon; it is a prebuilt static binary + a TS wrapper (grantArgs → --ro/--rw). macOS/Windows have no Landlock port.

pnpm-workspace.yaml:

The Landlock launcher is developed with its harness consumers but keeps its native build and publication scripts under native/landlock-run.

18.3 Two independent service keys

In the census, sandbox and sandboxPolicy are two service keys. “Capability” and “policy” are separated — so policy can be swapped per deployment without swapping the sandbox implementation.

On the tool side you can see traces of policy (packages/shell/tool-bash/src/index.ts:23-25):

import { ESCALATION_TARGETS, approveEscalation, canonicalPath, validateEscalationArgs } from '@deepseek-ai/dsh-sandbox'
import type { SandboxPolicyService } from '@deepseek-ai/dsh-sandbox-policy'

ESCALATION_TARGETS / approveEscalation / validateEscalationArgs — there is a controlled privilege-escalation path, not “all forbidden or all open.”

18.4 A postmortem every sandbox author should read

docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.md

The title is the entire lesson: Landlock’s “partial enforcement” notice once misclassified a child process’s own failures.

When the sandbox can only partially enforce (an old kernel does not support some rule), if the “partial enforcement” hint you emit also counts the child process’s own failure, the user will think it is a sandbox problem and turn the sandbox off — a classification error in a diagnostic message causes the user to voluntarily lower the security level.

dsh has only 4 postmortems in total, and one of them is given to sandbox misclassification. That choice itself shows what they think is worth writing down.

19.1 What it is

AGENTS.md:

typert/ type graph generator, loader, and runtime registry api/ Remote BFF assembly and Typert RPC gateway

packages/typert has 11 packages · 15 404 lines — larger than goal, plan, todo, schedule, jobs, and guard combined. This is not a helper tool; this is a piece of infrastructure.

19.2 What problem it solves

The Web frontend (client 39 packages · 138 163 lines) needs to call backend services. The traditional approach: hand-write REST/RPC interfaces + hand-write type definitions + keep them in sync by hand.

typert’s approach: generate a type graph from TypeScript types; the loader and runtime registry then provide end-to-end type-safe RPC.

Companion docs: docs/api-gateway.md and docs/subsystems/typert.md. The census shows dsh-api-remotes depended on by 23 packages — frontend modules access the backend through it.

19.3 Why this counts as “ambition”

Because it means dsh does not intend to be only a CLI. api/’s positioning is “Remote BFF assembly” (Backend For Frontend) — this is an architecture aimed at multiple clients and multiple deployment shapes.

There is a related sentence in AGENTS.md’s compiler-face rules:

Keep compiler faces explicit. Each package uses one aggregate except api/remotes; repo-wide programs seed a face config, never the root solution.

api/remotes is the only package in the warehouse allowed to have multiple compiler aggregates — because it has to face both the host face and the client face. The exception is recorded explicitly, not silently present.

20.1 Four shells

AGENTS.md specifically marks ACP as "automation-only" — it is not an interactive UI for humans; it is an automation interface for programs.

20.2 Web Client extension points

One row in the extension-point table of docs/architecture.md:

Add a Web Client Chat node | register a ConversationNodeDefinition + keyed renderer

The frontend is pluginized too. Every kind of node in a conversation (message, tool card, diff, terminal output) is a ConversationNodeDefinition + a corresponding keyed renderer.

Layering of the client group’s 39 packages (in-degree in the census): dsh-client-ui-slots 35 times, dsh-client-runtime 34, dsh-client-ui-primitives 29, dsh-client-locale 27, dsh-client-connection 19. UI slots are the frontend’s largest confluence point, corresponding to the backend’s ctx.tools.

20.3 How one behavior is guaranteed

By a snapshot-test matrix (docs/testing.md):

• ACP scenarios: examples/<name>/tests/snapshots/, boot a real automation-server example, replay a recorded session, diff normalized JSON-RPC plus the re-persisted log
• headless backend scenarios: examples/headless-agent owns internal standard-event JSONL snapshots
• CLI interactive journeys: apps/cli/tests/snapshots/, JSONL-driven
• Web browser journeys: apps/web/tests/snapshots/, Chromium replay (a required Linux PR gate)

And there is a very careful rule:

One ACP scenario (text-turn) pins full system-prompt/tool-schema content; other fixtures tokenize it so an edit churns one line.

Only one scenario pins the full system-prompt and tool-schema content; other scenarios tokenize it — so changing one prompt sentence only turns one snapshot into one changed line, not dozens of snapshots all red.

This is the key trick for scaling snapshot tests; it is worth copying on its own.

21.1 How this roster was produced

I wrote a census script (scripts/dsh-plugin-census.py) that extracts, for each of the 241 packages:

The last column is the most valuable part of this roster: it is not my summary; it is the one-sentence duty the package author wrote. 227 of 241 packages have such a JSDoc (the missing 14 are fixtures, platform binary packages, and vendored Cordis plugins).

This also side-proves the effect of the verify-export-jsdoc gate — this repository’s module-level documentation coverage is high enough to be used as a roster directly.

21.2 Role distribution

60 Service Definitions own 73 service keys (a few packages own multiple keys, e.g. agent-loop owns both agentLoop and configuredAgentIdentities).

21.3 Six functional domains

52 package groups rearranged by function into six domains; the next three chapters expand domain by domain:

flowchart TB
    subgraph D1["域一 · 主轴（30 包 · 95 200 行）"]
        core["core 8"]; llm["llm 5"]; sess["session 13"]; sq["session-query 4"]
    end
    subgraph D2["域二 · 上下文经济（11 包 · 19 828 行）"]
        ctxg["context 4"]; comp["compaction 4"]; spill["spill 3"]
    end
    subgraph D3["域三 · 执行世界（40 包 · 64 743 行）"]
        fs["fs 7"]; sh["shell 9"]; sub["subprocess 2"]; term["terminal 3"]
        cr["code-runtime 2"]; lsp["lsp 3"]; sb["sandbox 4"]; e2b["e2b 3"]; web["web 6"]; mcp["mcp 1"]
    end
    subgraph D4["域四 · 任务治理（39 包 · 65 646 行）"]
        skill["skill 4"]; sa["subagent 11"]; wf["workflow 4"]; goal["goal 4"]
        plan["plan 1"]; todo["todo 1"]; sch["schedule 1"]; jobs["jobs 3"]
        guard["guard 2"]; inter["interaction 5"]; hooks["hooks 3"]
    end
    subgraph D5["域五 · 装配与宿主（51 包 · 71 000 行）"]
        preset["preset 2"]; bundle["bundle 3"]; boot["boot 2"]; host["host 8"]
        api["api 2"]; typert["typert 11"]; sdk["sdk 3"]; acp["acp 1"]
        misc["settings/credentials/identity/storage/
workspace/attachment/feedback/
runtime-diagnostics/extensions 19"]
    end
    subgraph D6["域六 · 前端与支撑（70 包 · 187 500 行）"]
        client["client 39"]; apps["apps 2"]; ex["examples 3"]
        ts["test-support 6"]; util["util 7"]; vendor["vendor 9"]; native["native 4"]
    end
    D2 & D3 & D4 -.注入/被注入.-> D1
    D5 -.装配.-> D1
    D6 -.消费.-> D5

22.1 Domain I guide: five keys hold up the whole product

The 30 spine packages provide only seven core service keys: sessions systemPrompt tools agents agentLoop llm + scope (a library, no key). But they are the mount surface for every other plugin:

flowchart LR
    AL["agentLoop
驱动"] -->|注入| A["agents"]
    AL -->|注入| S["sessions"]
    AL -->|注入| SP["systemPrompt"]
    AL -->|注入| T["tools"]
    AL -->|注入| L["llm"]
    T -->|注入| SP
    S -.session/event.-> P["session 组 12 包
持久化/投影/标题/遥测"]
    S -.日志.-> SQ["session-query 4 包
5 个只读检索工具"]
    L -.adapter seam.-> PR["llm providers"]

agent-loop injects five services (agents llm sessions systemPrompt tools, census data) — those five are the complete dependency of “run one round of conversation.” And it itself is mounted by configuration, replaceable.

Three observations on Domain I:

1. core/tools at 13 743 lines is the second-largest single package — tool registry + five-stage pipeline + presentation modes; complexity concentrates here
2. The session group of 13 packages splits “the log” into core + persistence + projection + title + telemetry + reference resolution, because their evolution cadences differ
3. session-query 4 packages, 12 283 lines provide 5 read-only tools so the model can retrieve its own history — the agent can query its own session log, a capability rarely seen elsewhere

core · product-API spine (8 packages · 40,854 lines)

llm · model-access seam (5 packages · 20,502 lines)

session · durable session log (13 packages · 21,520 lines)

session-query · log retrieval (4 packages · 12,323 lines)

22.2 Domain II guide: four keys manage context

See Chapter 13. This domain is only 11 packages and 19 828 lines, but it decides whether a long session can survive.

The context group (4 packages · 10 251 lines) is “request-context plugins” — they decide what enters a request, in what order. The division of labor with systemPrompt is: systemPrompt owns system-prompt sections, context owns runtime-context projections (look back at runtimeContext.project() in Chapter 8).

context · request-context assembly (4 packages · 10,280 lines)

compaction · context compaction (4 packages · 8,063 lines)

spill · oversized-output spill (3 packages · 1,485 lines)

23.1 Domain III guide: two primitives + eight capabilities

See Chapter 17. The most important way to read this domain is the direction of dependence: fs and subprocess are primitives; shell / terminal / lsp / code-runtime / search tools are built on them; sandbox is cross-cutting (wraps argv); e2b is the remote empirical proof.

The web group (6 packages · 5 985 lines) is another independent seam: behind ctx.web are swappable search/fetch providers; the model sees only two stable tools, web_search / web_fetch.

fs · filesystem seam and policy (7 packages · 13,088 lines)

shell · bash/pwsh execution seam (9 packages · 10,453 lines)

subprocess · process trees (2 packages · 4,272 lines)

terminal · persistent PTY (3 packages · 5,741 lines)

code-runtime · code-mode runtime (2 packages · 3,982 lines)

lsp · language services (3 packages · 5,528 lines)

sandbox · sandbox and policy (4 packages · 9,089 lines)

e2b · remote-sandbox POC (3 packages · 6,646 lines)

web · search and fetch (6 packages · 6,010 lines)

mcp · MCP bridge (1 package · 3,333 lines)

23.2 Domain IV guide: the shared pattern of governance plugins

The 39 governance packages share a pattern I summarize as “sink determinism into the tool, leave judgment to the model”:

This division of labor is a different implementation of the same idea as this series’ MiMo Code (independent Goal referee), grok-build (Goal Mode five-piece set), Reasonix (Delivery Profile evidence sign-off), DeepTutor (mastery gates sunk into tools). dsh’s distinctive feature is that each of these is an independent plugin; the loop knows nothing about them.

skill · skills (4 packages · 6,255 lines)

subagent · sub-agent seam (11 packages · 24,555 lines)

workflow · workflow engine (4 packages · 7,734 lines)

goal · same-session goals (4 packages · 5,812 lines)

plan · plan mode (1 package · 2,036 lines)

todo · todos (1 package · 1,012 lines)

schedule · timing (1 package · 4,314 lines)

jobs · background jobs (3 packages · 3,712 lines)

guard · loop hygiene (2 packages · 1,027 lines)

interaction · approval / permission / commands / ask-the-human (5 packages · 4,225 lines)

hooks · external hook-protocol bridges (3 packages · 4,968 lines)

24.1 Domain V guide: from YAML to a running tree

The assembly chain (drawn in tutorial step 19):

flowchart LR
    PJ["package.json 的 dsh 字段
dsh.profile / dsh.bundle"] --> B["bundle 有序叠层"]
    B --> P1["profile 的 cordis.patch.yml"]
    P1 --> P2["home 级 cordis.patch.yml"]
    P2 --> P3["--patch CLI 覆盖层"]
    P3 --> LD["Loader：!!js 表达式插值
config（注入激活后）+ disabled（每次 mount）"]
    LD --> TREE["插件树"]
    TREE --> PRESET["preset：逐会话重装配
service 行需要 isolate realm"]

Three observations:

1. dsh-base is a 117-line package with no runtime API — its entire substance is a cordis.patch.yml. The JSDoc’s own words: “this module carries no runtime API.” Configuration-is-architecture, literally.
2. typert 11 packages, 15 404 lines is the largest investment in this domain; see Chapter 19.
3. The host group, 8 packages, 22 412 lines provides host capabilities (keys such as dshHomePath launchEnvironment cmdlineArgs directoryPicker appExit) — the “process/machine” layer is also made into services.

preset · per-session capability assembly (2 packages · 3,814 lines)

bundle · distribution layer (3 packages · 1,424 lines)

boot · boot glue (2 packages · 4,094 lines)

host · host capabilities (8 packages · 22,513 lines)

api · remote BFF and RPC gateway (2 packages · 4,431 lines)

typert · type-graph runtime (11 packages · 15,404 lines)

sdk · JSON-RPC protocol and clients (3 packages · 4,492 lines)

acp · Agent Client Protocol (1 package · 1,669 lines)

settings · user settings (2 packages · 3,913 lines)

credentials · credential references (2 packages · 1,831 lines)

identity · anonymous identity (1 package · 252 lines)

storage · storage domains (4 packages · 3,428 lines)

workspace · workspace registry (1 package · 2,155 lines)

attachment · attachments (2 packages · 921 lines)

feedback · message feedback (2 packages · 2,167 lines)

runtime-diagnostics · runtime invariants (1 package · 543 lines)

extensions · extension assembly (4 packages · 20,305 lines)

24.2 Domain VI guide: 39 frontend packages and “test infrastructure is a first-class citizen”

client 39 packages · 138 163 lines is the largest group in the warehouse, a quarter of the TS/TSX total. It is itself layered: ui-slots (in-degree 35) → ui-primitives (29) → runtime (34) → connection (19) → locale (27).

test-support 6 packages · 13 344 lines deserves a separate mention: test infrastructure is made into publish-grade workspace packages (e.g. dsh-acp-snapshot is a “suite factory”). Most projects’ test tools are scripts scattered in tests/helpers/; dsh treats them as product.

vendor 9 packages are pinned Cordis source (including cordis-plugin-loader / -hmr / -include / -group); native 4 packages are the Landlock launcher split by platform.

client · Web client modules (39 packages · 138,163 lines)

apps · product assembly (CLI / Web) (2 packages · 23,928 lines)

examples · runnable example assemblies (3 packages · 2,876 lines)

test-support · test infrastructure (6 packages · 13,391 lines)

util · zero-dependency utility libraries (7 packages · 2,225 lines)

vendor · vendored Cordis (9 packages · 6,584 lines)

native · Landlock native launcher (4 packages · 343 lines)

25.1 In-degree layering

The dependency layers drawn from census data (arrow = is depended on):

flowchart BT
    INV["dsh-invariants ← 218 包
（制度层：每包必有 invariant 伴生）"]
    SCH["schemastery ← 110 包
（配置校验）"]
    BR["dsh-brand ← 30 包
（branded id）"]
    TO["dsh-timeout ← 23 包"]
    SESS["dsh-session ← 84 包"]
    LLM["dsh-llm ← 82 包"]
    AG["dsh-agent ← 61 包"]
    TOOLS["dsh-tools ← 47 包"]
    SP["dsh-system-prompt ← 30 包"]
    CLIENT["dsh-client-ui-slots ← 35 包
dsh-client-runtime ← 34"]
    API["dsh-api-remotes ← 23 包"]

    INV --- SCH --- BR --- TO
    SESS --> AG --> TOOLS
    LLM --> AG
    TOOLS --> SP
    API --> CLIENT

The three-layer structure is very clear:

• Constitution layer (invariants / schemastery / brand / timeout): cross-cuts every package, independent of business
• Spine layer (session → agent → tools → system-prompt, llm cross-cutting): the business core
• Frontend layer (api-remotes → client-*): an independent dependency community

25.2 Plugin participation table for one turn

This is the most direct answer to “how they cooperate” — in the same turn, at which moment each plugin joins:

This table is the value proof of a pluginized architecture: 19 moments, each with an independent plugin joining, and of agent.ts’s 496 lines not one is written for “approval,” “sandbox,” “spill,” “goal,” or “title.”

25.3 Three typical assembly chains

Chain one: the complete dependency closure of the bash tool

tool-bash（Consumer）
  → ctx.tools（core/tools）        注册与流水线
  → ctx.shell（shell Definition）  接口
     → bash-local | bash-sandbox（Provider）
        → ctx.subprocess           起进程
        → ctx.sandbox              包 argv（sandbox 组）
        → ctx.sandboxPolicy        策略
  → ctx.systemPrompt               贡献工具 schema + 用法段
  → ctx.shellEnv                   托管 DSH_* 环境
  → ctx.jobs（call time）          run_in_background
  → ctx.approval（间接）           写操作审批

One tool, seven service keys, three provider layers. And its source is only 2 081 lines, because it does not need to care about any of those layers.

Chain two: a legal path for “add context for the model”

某插件 → agent.inject(message)
  → inbox（不唤醒）
  → 下次有唤醒消息时一起 claim
  → append user/message（session 事件）
  → deriveMessages() 投影进模型历史
  → invariant 断言：模型可见 ⟺ 已记录 ✓

Chain three: switch to a remote execution world

patch 掉两行配置：
  fs-local     → e2b-fs
  subprocess-local → e2b-subprocess
自动跟着搬家：bash / pwsh / 持久 PTY / lsp / glob / grep / code-runtime
零 provider fork

26.1 Six test layers

docs/testing.md (49 lines, all substance):

26.2 Technical highlight: the correct reading of coverage

docs/testing.md:10:

An uncovered line is often dead code the gate is correctly flagging for deletion, not a missing test to bolt on. Line coverage is necessary, never sufficient — it proves lines ran, not that the feature works as shipped.

“An uncovered line is often dead code; the gate is correctly hinting that you should delete it” — treat coverage as a code-deletion tool, not a write-tests KPI.

This explains the /* v8 ignore next -- … */ seen in Chapter 8: an unreachable defensive branch must be explicitly exempted + the reason written down, and scripts/coverage-exempt.ts + coverage-exempt.spec.ts guard the exemptions themselves.

It also explains the “do not over-defend” rule in §2.2 — under a 100% coverage constitution, every surplus defensive branch has a direct cost.

26.3 An honest exception

docs/testing.md:10:

Per-file 100% on packages/shell/pwsh-local/src needs a real pwsh: without one its executor suites self-skip and vitest.config.ts exempts the file so pwsh-less hosts stay green, while CI runners ship pwsh and enforce the full bar.

On a machine without PowerShell the file is exempted so the host stays green; CI ships pwsh and enforces full marks. The exception is written into the docs with a reason, not a silent lowering of the standard.

26.4 Three test rules I think most worth copying

① Verify the world, not the self-report (:29):

An e2e assertion re-runs the command or re-reads the file externally; a keyword probe on the agent's own output lets a cheating agent pass. Assert untouched files are byte-identical.

“A keyword probe on the agent’s own output lets a cheating agent pass” — that sentence should be carved at the top of every agent project’s test file.

② A guard must be proven to work (:34):

A guard only guards if the regression actually fails it. … add an explicit assertion, and prove it: introduce the regression, watch red, revert.

First introduce the regression, watch it go red, then revert — this is the highest testing standard I have seen in this series.

③ Test the real entry path (:35):

"Real entry path" means the published artifact: a package bin runs built lib/bin.js under plain node, exposing failures tsx masks (settle races, module resolution, swallowed load failures).

Running source under tsx will mask three classes of real failure. The critical path must be tested with the published artifact.

26.5 The with-key policy: a sentence that carries company identity

docs/testing.md:19:

The with-key policy: inference is cheap here — We are DeepSeek — do not ration real-API tests. A no-key test proves plumbing; only a with-key run proves the agent works against a real model. … Self-skip keeps secretless CI and keyless contributors unblocked; it is not a cost signal.

“We are DeepSeek; do not ration real-API tests” — this is the most personality-bearing sentence in the warehouse. And it explicitly says: self-skip is so that keyless contributors are not blocked; it is not a cost signal.

Accompanying it is the judgment that “highest value is a smoke test”:

Highest-value are smoke tests that boot the real example, send one prompt, and check the world — they catch the "green unit tests, broken product" class that mocks cannot（postmortem 0001）.

27.1 Constitutional requirement

AGENTS.md:

Wire mechanically checkable invariants into an executed top-level gate and prove each changed acceptance path rejects an invalid case. Use narrow, justified exceptions instead of disabling a rule globally.

Two requirements: a mechanically checkable invariant must be wired into a top-level gate that will actually execute; and you must prove that every changed acceptance path rejects illegal input.

27.2 Gate list

124 .ts files under scripts/, of which 28 are verify-*:

Also pnpm run hygiene (knip dead code + publint publish norms + workspace constraints + NodeNext consumer checks) and pnpm run duplication (jscpd cross-file TypeScript clone detection).

27.3 Three this series has not seen a second house do

① verify-package-readme-limitations: forces every package README to state limitations. This guards against “over-advertising” — if a package’s docs only say what it can do, not what it cannot, users will use it in the wrong scene.

② verify-package-readme-model-experience: forces a statement of model experience. It requires the author to describe their package from the model’s point of view: what the model will see, how it will misuse it, what behavior the schema wording will cause. This is the institutionalization of “write docs for the model.”

③ verify-type-equiv: type code blocks in docs must be equivalent to source types. So those ts type-equiv fenced blocks in docs/subsystems/*.md are not hand-copied; they are machine-checked against source.

27.4 The gates themselves are guarded

Under scripts/ you see files appearing in pairs: coverage-exempt.ts + coverage-exempt.spec.ts, run-gates.ts + run-gates.spec.ts, gen-doc-graphs.ts + gen-doc-graphs.spec.ts, translation-pairing.ts + .spec.ts…

Guards must be guarded. A broken gate is more dangerous than no gate, because it gives a false sense of safety.

27.5 8 177 lines of generated documentation

These in docs/ are generated (produced by scripts/gen-*.ts, freshness verified by doc-sync):

Plus the “Cordis API” blocks on every subsystem page (generated by gen-cordis-catalog.ts, byte-identical on both language sides).

Conclusion: this repository’s documentation is not “written”; it is generated from source + machine-checked for freshness. That is also why I could extract accurate duties for 241 packages with one census script — because JSDoc in source is forced by a gate.

28.1 Numbers

English primary files under .agents/notes/ (each also has a .zh.md + .i18n.yaml three-piece set):

28.2 What it is

.agents/notes/README.md:

An Agent Note records a decision or proposal that affects this codebase — the why and what we gave up, the parts code and docs can't carry.

“Why” and “what we gave up” — this is exactly what this series’ analysis methodology (motive → constraint → rejected alternatives → choice → cost) tries to reverse-engineer from code. dsh writes it down at the source.

28.3 Dual-axis path encoding

{lifecycle}/{class}/yyyy-mm-dd-topic-title.md

• lifecycle (top-level directory) = state; notes move between directories as state changes
• class (nested directory) = the kind of decision, from a closed set (defined by scripts/agent-note-tree.ts; the classification gate rejects other folders):

refactor is deliberately absent; the README gives the reason:

(refactor is deliberately absent — it overlaps simplification, whose discriminator, "does observable behavior change?", already covers it.)

Use one discriminator (does observable behavior change?) to kill a fuzzy category. This is good taxonomic taste.

28.4 Four careful rules

① implemented must stay in sync with what actually shipped:

is kept current with what actually shipped: when the code later moves a file, renames a package, or changes a key/default, the Agent Note is updated in the same change to match (facts only — paths, names, structure — not the decision itself).

Only facts are updated (paths, names, structure), not the decision itself. So when you read a 2026-06 note, the paths in it are current, but the decision is of that time.

② archived is frozen:

Archived notes are frozen: never edit or treat them as current authority.

When archiving, the only allowed operations: move the three-piece set, keep Status: implemented, insert the same Archived: YYYY-MM-DD line below the status (in both languages), re-record the sidecar, fix or delete inbound links. This is the only allowed content change.

③ Cross-references must be relative markdown links:

Cross-references between Agent Notes use relative markdown links … — never bare prose or numbers — so they are mechanically checkable and survive moves between folders.

You may not write “see that note about X”; you must write a link. Then verify-doc-refs can check, and after a note moves between lifecycle directories the link can still be repaired.

④ Do not add a centralized index:

Do not add a centralized INDEX.md; the [no-index Agent Note] owns the rationale.

Even the decision “do not add an index” itself has an Agent Note. This is the extreme of constitutional self-reference.

28.5 Cooperation with AGENTS.md

AGENTS.md:

Non-trivial changes MUST include an Agent Note in the same PR; only mechanical/local edits are exempt.

And verify-agent-note-classification / verify-agent-note-format / verify-archived-agent-notes three gates guard this constitution.

28.6 11 skills for AI collaborators

.agents/skills/:

28.7 A rare prose discipline

The “Type safety and documentation” section of AGENTS.md:

Comments and docs state complete contracts and context, not reasoning transcripts. Use direct, concrete terms. Do not use metaphors. Before writing contract, boundary, or shape, ask whether a more exact term names the subject: write response fields, JSON validation, or ESM exports instead of response shape, validation boundary, or module shape.

“Do not use metaphors” + “before writing contract/boundary/shape, ask whether a more exact term names the subject” — it even gives three pairs of replacement examples, and stipulates that contract is reserved for obligations a caller actually depends on: preconditions, postconditions, invariants, compatibility promises.

Also:

Do not narrate control flow or tests, preserve review history, or restate code. Keep behavior, failure, timing, ownership, and safe-use facts; link the rationale.

Do not narrate control flow, do not preserve review history, do not restate code. Keep five classes of fact — behavior, failure, timing, ownership, safe use — and link the rationale.

This prose discipline plus verify-doc-budgets (word-count budgets) explains why this repository’s 40-plus subsystem documents read at extremely high density without being verbose.

29.1 What it is

AGENTS.md’s repository layout still writes self-modification/. The repository has no such directory. vitest.config.ts’s coverage exclude still lists packages/self-modification/*/src/**. The actual code is in packages/extensions/:

Corresponding tools (the census captured 7):

cordis_define · cordis_undefine · cordis_run · cordis_stop
cordis_inspect_list · cordis_inspect_query · cordis_inspect_self

There is a demo script in package.json: pnpm run demo:cordis — "the agent modifies its own runtime".

29.2 Safety boundary

The deployment note for dsh-tool-cordis in docs/tool-catalog.md is cautious:

Not in any shipped tree (a deliberate opt-in — dynamic package code reaches the real runtime, see .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). The toolset injects ctx.dynamicCordisRunner from @deepseek-ai/dsh-cordis-host-runner, which owns the definition registry and the vm sandbox; a composition missing it never activates the tools. A running package may register ADDITIONAL model-visible tools until it is stopped, undefined, or DSH restarts; a full changed request header logs those tool-set changes.

Five safety designs:

1. Not in any shipped tree — a deliberate opt-in, because dynamic package code reaches the real runtime
2. Needs ctx.dynamicCordisRunner (from an independent host-runner package), which holds the definition registry and the vm sandbox
3. If the composition is missing this service, the tools never activate
4. A running package may register additional model-visible tools — until it is stopped / undefined / DSH restarts
5. Tool-set changes are recorded in the log as a full changed request header — back to Chapter 10’s constitution: the tool table is model-visible, so its changes must already be logged

29.3 Why this is the logical endpoint of “everything is a plugin”

If everything is a plugin, and the agent can write code, then the agent can write plugins. And if registration is a reversible effect, then a plugin the agent mounts can also be cleanly unloaded.

This capability is not bolted on; it is derived from the architecture. It is also a stress test of the architecture: if dynamically mounting a plugin would break something, that something should not be privileged state.

The closest in this series are DeepTutor’s subagent (treat a coding CLI as a KB) and Open Design (treat a CLI as the engine), but those two are “call an external agent.” This one in dsh is the agent modifying its own runtime assembly — a different order of magnitude.

31.1 Comparison with the main projects in this series

31.2 Two roads from the same company

Reasonix: one static binary, cache-first, a transport-agnostic control.Controller, three-stage compression soft→snip→summary. The goal is save money + portable.

Harness: 241-package monorepo, everything is a plugin, 73 service keys, six test layers. The goal is replaceable + extensible + long-term maintainable.

This is not a contradiction; it is two different product hypotheses: Reasonix assumes “the user wants a terminal agent that can be stuffed into any environment”; Harness assumes “the ecosystem wants a skeleton that can be reshaped into any form.”

31.3 Applicability bounds of the harness shape

The harness shape wins at: one behavior across multiple frontends, third-party extension, whole-capability replacement (host↔remote), long-term maintainability, welding discipline into gates.

The loop shape wins at: fast onboarding, intuitive debugging (you can see the whole process in the stack), low cost of a small change, no assembly layer to maintain.

A concrete criterion: does your product need to support “the user replaces the execution environment”? If yes (remote sandbox, enterprise intranet, custom runtime), the seam investment of the harness shape will pay back. If not, the 241 packages of indirection are a pure tax.

31.4 Three combinations nobody else has

1. dsh-invariants is depended on by 218/241 packages — runtime invariants are part of a package’s birth certificate, and it specifies “you may not write an assertion that pretends to check.”
2. Monotonic guards — using the type (no allow return value) to guarantee that a safety policy cannot be mathematically relaxed by a later plugin.
3. 686 dual-axis-classified Agent Notes + 3 gates — institutionalizing “why we designed it this way, what we gave up” to the point of having a lifecycle, a closed classification, archive-freeze rules, and even “do not add an index” having a note.

33.1 🔍 Source pointer table

33.2 Local reproduction (read-only analysis)

cd 参考项目/deepseek-harness
git rev-parse --short HEAD          # 期望 47f9438
git log -1 --format='%s'            # Merge pull request #2519 …

# 复核本文的关键数字
find packages -name package.json -not -path '*/node_modules/*' -not -path '*/lib/*' | wc -l   # 219
find . -name '*.ts' -not -path '*/node_modules/*' -not -path './.git/*' | wc -l               # 2319
ls scripts/verify-*.ts | wc -l                                                                # 28
for s in proposed implemented archived rejected; do
  printf "%s: " "$s"; find ".agents/notes/$s" -name '*.md' -not -name '*.zh.md' | wc -l
done                                                                                          # 25/507/143/11

Reproduce this lecture’s 241-package roster (scripts in this repository):

cd "claude code源码分析"
python3 scripts/dsh-plugin-census.py     # → scripts/dsh-plugin-census.json（241 包）
python3 scripts/dsh-roster-gen.py        # → scripts/dsh-roster.md（分组名册）

If you actually want to run it (not required for analysis; needs DEEPSEEK_API_KEY):

pnpm install                             # node ^22.19 || >=24
pnpm run build
pnpm dsh web                             # http://127.0.0.1:3080
pnpm dsh --profile web --dump-config     # 看实际装配的整棵树
pnpm dsh --profile headless "一句任务"
pnpm run demo:cordis                     # agent 修改自己的运行时

33.3 Handoff to other documents in this series

• Want to build one by hand → Build a pluginized agent harness from scratch (20 steps · minidsh)
• The same company’s other road → DeepSeek-Reasonix source analysis (single binary + cache-first)
• The extreme of not writing a loop → Open Design source analysis (treat someone else’s CLI as the engine)
• The classic of the loop shape → How Claude Code works (deep dive)
• Sandbox and permission contrast → openai-codex source analysis (three-platform OS fences)
• Three-layer plugins and the education axis → DeepTutor source analysis
• Engineering-technique cross-cut → Catalog of agent engineering patterns