docs/module-graph.md

<!-- Generated by scripts/gen-module-graph.ts — do not edit by hand.
     Run `pnpm run gen-module-graph` to regenerate. -->

# Module dependency graph

Inter-package dependencies among the `@deepseek-ai/dsh-*` harness packages, derived from each package's `peerDependencies` (the canonical runtime-dependency signal). An edge `a --> b` means package `a` depends on package `b`. Names have the `@deepseek-ai/dsh-` prefix stripped.

```mermaid
graph TD
  bash --> brand
  llm --> brand
  bash-local --> bash
  fs --> brand
  fs --> llm
  llm-deepseek --> llm
  llm-pi-ai --> llm
  session --> brand
  session --> llm
  system-prompt --> llm
  web --> llm
  agent --> brand
  agent --> llm
  agent --> session
  compact --> llm
  compact --> session
  fs-local --> fs
  fs-policy --> fs
  hook-protocol --> bash
  hook-protocol --> session
  llm-replay --> llm
  llm-replay --> session
  session-persistence --> session
  web-fetch-local --> web
  web-search-deepseek --> web
  web-search-exa --> web
  web-search-perplexity --> web
  compact-basic --> agent
  compact-basic --> compact
  compact-basic --> llm
  compact-basic --> session
  invariants --> agent
  invariants --> llm
  invariants --> session
  session-persistence-jsonl --> session
  session-persistence-jsonl --> session-persistence
  session-persistence-sqlite --> session
  session-persistence-sqlite --> session-persistence
  tools --> agent
  tools --> llm
  tools --> system-prompt
  acp --> agent
  acp --> llm
  acp --> session
  acp --> session-persistence
  acp --> tools
  agent-loop --> agent
  agent-loop --> llm
  agent-loop --> session
  agent-loop --> session-persistence
  agent-loop --> system-prompt
  agent-loop --> tools
  hooks-codex --> agent
  hooks-codex --> hook-protocol
  hooks-codex --> llm
  hooks-codex --> session
  hooks-codex --> tools
  subagent --> agent
  subagent --> llm
  subagent --> tools
  tool-bash --> agent
  tool-bash --> bash
  tool-bash --> llm
  tool-bash --> tools
  tool-fs --> fs
  tool-fs --> llm
  tool-fs --> session
  tool-fs --> system-prompt
  tool-fs --> tools
  tool-todo --> agent
  tool-todo --> session
  tool-todo --> tools
  tool-web --> llm
  tool-web --> system-prompt
  tool-web --> tools
  tool-web --> web
  agent-core --> agent
  agent-core --> agent-loop
  agent-core --> invariants
  agent-core --> llm
  agent-core --> session
  agent-core --> system-prompt
  agent-core --> tool-bash
  agent-core --> tools
  hooks-claude --> agent
  hooks-claude --> hook-protocol
  hooks-claude --> llm
  hooks-claude --> session
  hooks-claude --> subagent
  hooks-claude --> tools
  subagent-acp --> agent
  subagent-acp --> llm
  subagent-acp --> subagent
  subagent-inprocess --> agent
  subagent-inprocess --> llm
  subagent-inprocess --> session
  subagent-inprocess --> subagent
  subagent-mock --> agent
  subagent-mock --> llm
  subagent-mock --> subagent
  tool-subagent --> agent
  tool-subagent --> llm
  tool-subagent --> subagent
  tool-subagent --> tools
  acp-agent --> acp
  acp-agent --> agent-core
  acp-agent --> session-persistence-jsonl
  stdio-agent --> agent
  stdio-agent --> agent-core
  stdio-agent --> llm
  stdio-agent --> session
  stdio-agent --> session-persistence-jsonl
  subagent-fork --> agent
  subagent-fork --> session
  subagent-fork --> subagent
  subagent-fork --> subagent-inprocess
  subagent-spawn --> subagent
  subagent-spawn --> subagent-inprocess
```

| Package | Depends on |
| --- | --- |
| `brand` | — |
| `bash` | `brand` |
| `llm` | `brand` |
| `bash-local` | `bash` |
| `fs` | `brand`, `llm` |
| `llm-deepseek` | `llm` |
| `llm-pi-ai` | `llm` |
| `session` | `brand`, `llm` |
| `system-prompt` | `llm` |
| `web` | `llm` |
| `agent` | `brand`, `llm`, `session` |
| `compact` | `llm`, `session` |
| `fs-local` | `fs` |
| `fs-policy` | `fs` |
| `hook-protocol` | `bash`, `session` |
| `llm-replay` | `llm`, `session` |
| `session-persistence` | `session` |
| `web-fetch-local` | `web` |
| `web-search-deepseek` | `web` |
| `web-search-exa` | `web` |
| `web-search-perplexity` | `web` |
| `compact-basic` | `agent`, `compact`, `llm`, `session` |
| `invariants` | `agent`, `llm`, `session` |
| `session-persistence-jsonl` | `session`, `session-persistence` |
| `session-persistence-sqlite` | `session`, `session-persistence` |
| `tools` | `agent`, `llm`, `system-prompt` |
| `acp` | `agent`, `llm`, `session`, `session-persistence`, `tools` |
| `agent-loop` | `agent`, `llm`, `session`, `session-persistence`, `system-prompt`, `tools` |
| `hooks-codex` | `agent`, `hook-protocol`, `llm`, `session`, `tools` |
| `subagent` | `agent`, `llm`, `tools` |
| `tool-bash` | `agent`, `bash`, `llm`, `tools` |
| `tool-fs` | `fs`, `llm`, `session`, `system-prompt`, `tools` |
| `tool-todo` | `agent`, `session`, `tools` |
| `tool-web` | `llm`, `system-prompt`, `tools`, `web` |
| `agent-core` | `agent`, `agent-loop`, `invariants`, `llm`, `session`, `system-prompt`, `tool-bash`, `tools` |
| `hooks-claude` | `agent`, `hook-protocol`, `llm`, `session`, `subagent`, `tools` |
| `subagent-acp` | `agent`, `llm`, `subagent` |
| `subagent-inprocess` | `agent`, `llm`, `session`, `subagent` |
| `subagent-mock` | `agent`, `llm`, `subagent` |
| `tool-subagent` | `agent`, `llm`, `subagent`, `tools` |
| `acp-agent` | `acp`, `agent-core`, `session-persistence-jsonl` |
| `stdio-agent` | `agent`, `agent-core`, `llm`, `session`, `session-persistence-jsonl` |
| `subagent-fork` | `agent`, `session`, `subagent`, `subagent-inprocess` |
| `subagent-spawn` | `subagent`, `subagent-inprocess` |
feat: generate module dependency graph with freshness gate 2026-06-16 21:00:24 +08:00			`<!-- Generated by scripts/gen-module-graph.ts — do not edit by hand.`
			Run `pnpm run gen-module-graph` to regenerate. -->

			`# Module dependency graph`

docs: document module-graph gate; unwrap generated prose 2026-06-16 21:21:21 +08:00			Inter-package dependencies among the `@deepseek-ai/dsh-*` harness packages, derived from each package's `peerDependencies` (the canonical runtime-dependency signal). An edge `a --> b` means package `a` depends on package `b`. Names have the `@deepseek-ai/dsh-` prefix stripped.
feat: generate module dependency graph with freshness gate 2026-06-16 21:00:24 +08:00
			```mermaid
			`graph TD`
feat(types): brand bash ids + stop brand erosion; extract Branded to dsh-brand 2026-06-21 07:17:25 +08:00			`bash --> brand`
			`llm --> brand`
refactor: order module-graph table topologically (low→high level) 2026-06-16 21:11:09 +08:00			`bash-local --> bash`
refactor(fs): split filesystem seam into provider ctx.fs + policy ctx.fileContext 2026-06-26 17:23:18 +08:00			`fs --> brand`
Add filesystem capability seam and tools 2026-06-22 10:48:41 +08:00			`fs --> llm`
refactor: order module-graph table topologically (low→high level) 2026-06-16 21:11:09 +08:00			`llm-deepseek --> llm`
			`llm-pi-ai --> llm`
feat(types): brand bash ids + stop brand erosion; extract Branded to dsh-brand 2026-06-21 07:17:25 +08:00			`session --> brand`
refactor: order module-graph table topologically (low→high level) 2026-06-16 21:11:09 +08:00			`session --> llm`
			`system-prompt --> llm`
chore: adapt web seam to master's tsconfig + regenerate catalogs 2026-06-26 19:18:46 +08:00			`web --> llm`
feat(types): brand bash ids + stop brand erosion; extract Branded to dsh-brand 2026-06-21 07:17:25 +08:00			`agent --> brand`
feat: generate module dependency graph with freshness gate 2026-06-16 21:00:24 +08:00			`agent --> llm`
			`agent --> session`
feat(compact): compaction capability seam — abstract CompactService interface 2026-06-22 14:52:30 +08:00			`compact --> llm`
			`compact --> session`
Add filesystem capability seam and tools 2026-06-22 10:48:41 +08:00			`fs-local --> fs`
fix(fs): address review — rename to dsh-fs-policy, fs/*-intent events, RFC currency, ENOTDIR 2026-07-02 03:12:38 +08:00			`fs-policy --> fs`
feat(hooks): dsh-hook-protocol — shared Claude Code / Codex hook wire-protocol core 2026-07-01 00:38:06 +08:00			`hook-protocol --> bash`
			`hook-protocol --> session`
refactor(examples): extract reusable logic into tested packages 2026-06-19 12:42:28 +08:00			`llm-replay --> llm`
			`llm-replay --> session`
Merge remote-tracking branch 'origin/master' into split/session-persistence 2026-06-16 23:16:59 +08:00			`session-persistence --> session`
chore: adapt web seam to master's tsconfig + regenerate catalogs 2026-06-26 19:18:46 +08:00			`web-fetch-local --> web`
feat(web): add DeepSeek-backed web search provider 2026-06-29 15:21:12 +08:00			`web-search-deepseek --> web`
chore: adapt web seam to master's tsconfig + regenerate catalogs 2026-06-26 19:18:46 +08:00			`web-search-exa --> web`
			`web-search-perplexity --> web`
feat(compact-basic): baseline compaction backend (squashed from compact-basic) 2026-06-25 17:30:42 +08:00			`compact-basic --> agent`
			`compact-basic --> compact`
			`compact-basic --> llm`
			`compact-basic --> session`
refactor: order module-graph table topologically (low→high level) 2026-06-16 21:11:09 +08:00			`invariants --> agent`
			`invariants --> llm`
			`invariants --> session`
Merge remote-tracking branch 'origin/master' into split/session-persistence 2026-06-16 23:16:59 +08:00			`session-persistence-jsonl --> session`
			`session-persistence-jsonl --> session-persistence`
Merge remote-tracking branch 'origin/split/agent-factory' into split/session-persistence-sqlite 2026-06-16 23:19:45 +08:00			`session-persistence-sqlite --> session`
			`session-persistence-sqlite --> session-persistence`
refactor: order module-graph table topologically (low→high level) 2026-06-16 21:11:09 +08:00			`tools --> agent`
			`tools --> llm`
			`tools --> system-prompt`
feat(acp): tool-owned tool-call UI presentation (title/command/output) 2026-06-18 09:01:36 +08:00			`acp --> agent`
			`acp --> llm`
			`acp --> session`
			`acp --> session-persistence`
			`acp --> tools`
feat: generate module dependency graph with freshness gate 2026-06-16 21:00:24 +08:00			`agent-loop --> agent`
			`agent-loop --> llm`
			`agent-loop --> session`
Merge remote-tracking branch 'origin/split/session-persistence' into split/agent-factory 2026-06-16 23:18:31 +08:00			`agent-loop --> session-persistence`
feat: generate module dependency graph with freshness gate 2026-06-16 21:00:24 +08:00			`agent-loop --> system-prompt`
			`agent-loop --> tools`
feat(hooks): dsh-hooks-claude + dsh-hooks-codex bridges (hooks stack PR-F) 2026-07-01 04:22:00 +08:00			`hooks-codex --> agent`
			`hooks-codex --> hook-protocol`
			`hooks-codex --> llm`
			`hooks-codex --> session`
			`hooks-codex --> tools`
Add subagent capability seam: interface, mock backend, model-facing tool 2026-06-21 22:31:56 +08:00			`subagent --> agent`
			`subagent --> llm`
			`subagent --> tools`
feat: generate module dependency graph with freshness gate 2026-06-16 21:00:24 +08:00			`tool-bash --> agent`
			`tool-bash --> bash`
			`tool-bash --> llm`
			`tool-bash --> tools`
Add filesystem capability seam and tools 2026-06-22 10:48:41 +08:00			`tool-fs --> fs`
			`tool-fs --> llm`
feat(tool-fs): result-time applied-hunk diffs for write/edit 2026-07-03 17:12:00 +08:00			`tool-fs --> session`
Add filesystem capability seam and tools 2026-06-22 10:48:41 +08:00			`tool-fs --> system-prompt`
			`tool-fs --> tools`
feat(tool-todo): add the model-facing todo_write tool 2026-06-29 10:30:52 +08:00			`tool-todo --> agent`
			`tool-todo --> session`
			`tool-todo --> tools`
chore: adapt web seam to master's tsconfig + regenerate catalogs 2026-06-26 19:18:46 +08:00			`tool-web --> llm`
			`tool-web --> system-prompt`
			`tool-web --> tools`
			`tool-web --> web`
refactor(examples): extract the app spine into dsh-agent-core + app packages 2026-06-21 12:03:44 +08:00			`agent-core --> agent`
			`agent-core --> agent-loop`
			`agent-core --> invariants`
			`agent-core --> llm`
			`agent-core --> session`
			`agent-core --> system-prompt`
			`agent-core --> tool-bash`
			`agent-core --> tools`
feat(hooks): dsh-hooks-claude + dsh-hooks-codex bridges (hooks stack PR-F) 2026-07-01 04:22:00 +08:00			`hooks-claude --> agent`
			`hooks-claude --> hook-protocol`
			`hooks-claude --> llm`
			`hooks-claude --> session`
			`hooks-claude --> subagent`
			`hooks-claude --> tools`
Add the ACP subagent backend: out-of-process delegation (PR3) 2026-06-22 10:47:02 +08:00			`subagent-acp --> agent`
			`subagent-acp --> llm`
			`subagent-acp --> subagent`
Extract the shared in-process driver into dsh-subagent-inprocess (review feedback) 2026-06-22 14:27:38 +08:00			`subagent-inprocess --> agent`
			`subagent-inprocess --> llm`
			`subagent-inprocess --> session`
			`subagent-inprocess --> subagent`
Add subagent capability seam: interface, mock backend, model-facing tool 2026-06-21 22:31:56 +08:00			`subagent-mock --> agent`
			`subagent-mock --> llm`
			`subagent-mock --> subagent`
			`tool-subagent --> agent`
			`tool-subagent --> llm`
			`tool-subagent --> subagent`
			`tool-subagent --> tools`
refactor(examples): extract the app spine into dsh-agent-core + app packages 2026-06-21 12:03:44 +08:00			`acp-agent --> acp`
			`acp-agent --> agent-core`
			`acp-agent --> session-persistence-jsonl`
			`stdio-agent --> agent`
			`stdio-agent --> agent-core`
docs: regenerate the module graph and dependency row for the dsh-llm edge 2026-07-04 17:17:36 +08:00			`stdio-agent --> llm`
refactor(examples): extract the app spine into dsh-agent-core + app packages 2026-06-21 12:03:44 +08:00			`stdio-agent --> session`
			`stdio-agent --> session-persistence-jsonl`
Add in-process subagent backends: spawn (fresh) and fork (seeded) 2026-06-22 05:58:40 +08:00			`subagent-fork --> agent`
			`subagent-fork --> session`
			`subagent-fork --> subagent`
Extract the shared in-process driver into dsh-subagent-inprocess (review feedback) 2026-06-22 14:27:38 +08:00			`subagent-fork --> subagent-inprocess`
			`subagent-spawn --> subagent`
			`subagent-spawn --> subagent-inprocess`
feat: generate module dependency graph with freshness gate 2026-06-16 21:00:24 +08:00			```

			`\| Package \| Depends on \|`
			`\| --- \| --- \|`
feat(types): brand bash ids + stop brand erosion; extract Branded to dsh-brand 2026-06-21 07:17:25 +08:00			\| `brand` \| — \|
			\| `bash` \| `brand` \|
			\| `llm` \| `brand` \|
refactor: order module-graph table topologically (low→high level) 2026-06-16 21:11:09 +08:00			\| `bash-local` \| `bash` \|
refactor(fs): split filesystem seam into provider ctx.fs + policy ctx.fileContext 2026-06-26 17:23:18 +08:00			\| `fs` \| `brand`, `llm` \|
feat: generate module dependency graph with freshness gate 2026-06-16 21:00:24 +08:00			\| `llm-deepseek` \| `llm` \|
			\| `llm-pi-ai` \| `llm` \|
feat(types): brand bash ids + stop brand erosion; extract Branded to dsh-brand 2026-06-21 07:17:25 +08:00			\| `session` \| `brand`, `llm` \|
feat: generate module dependency graph with freshness gate 2026-06-16 21:00:24 +08:00			\| `system-prompt` \| `llm` \|
chore: adapt web seam to master's tsconfig + regenerate catalogs 2026-06-26 19:18:46 +08:00			\| `web` \| `llm` \|
feat(types): brand bash ids + stop brand erosion; extract Branded to dsh-brand 2026-06-21 07:17:25 +08:00			\| `agent` \| `brand`, `llm`, `session` \|
feat(compact): compaction capability seam — abstract CompactService interface 2026-06-22 14:52:30 +08:00			\| `compact` \| `llm`, `session` \|
Add filesystem capability seam and tools 2026-06-22 10:48:41 +08:00			\| `fs-local` \| `fs` \|
fix(fs): address review — rename to dsh-fs-policy, fs/*-intent events, RFC currency, ENOTDIR 2026-07-02 03:12:38 +08:00			\| `fs-policy` \| `fs` \|
feat(hooks): dsh-hook-protocol — shared Claude Code / Codex hook wire-protocol core 2026-07-01 00:38:06 +08:00			\| `hook-protocol` \| `bash`, `session` \|
refactor(examples): extract reusable logic into tested packages 2026-06-19 12:42:28 +08:00			\| `llm-replay` \| `llm`, `session` \|
Merge remote-tracking branch 'origin/master' into split/session-persistence 2026-06-16 23:16:59 +08:00			\| `session-persistence` \| `session` \|
chore: adapt web seam to master's tsconfig + regenerate catalogs 2026-06-26 19:18:46 +08:00			\| `web-fetch-local` \| `web` \|
feat(web): add DeepSeek-backed web search provider 2026-06-29 15:21:12 +08:00			\| `web-search-deepseek` \| `web` \|
chore: adapt web seam to master's tsconfig + regenerate catalogs 2026-06-26 19:18:46 +08:00			\| `web-search-exa` \| `web` \|
			\| `web-search-perplexity` \| `web` \|
feat(compact-basic): baseline compaction backend (squashed from compact-basic) 2026-06-25 17:30:42 +08:00			\| `compact-basic` \| `agent`, `compact`, `llm`, `session` \|
refactor: order module-graph table topologically (low→high level) 2026-06-16 21:11:09 +08:00			\| `invariants` \| `agent`, `llm`, `session` \|
Merge remote-tracking branch 'origin/master' into split/session-persistence 2026-06-16 23:16:59 +08:00			\| `session-persistence-jsonl` \| `session`, `session-persistence` \|
Merge remote-tracking branch 'origin/split/agent-factory' into split/session-persistence-sqlite 2026-06-16 23:19:45 +08:00			\| `session-persistence-sqlite` \| `session`, `session-persistence` \|
feat: generate module dependency graph with freshness gate 2026-06-16 21:00:24 +08:00			\| `tools` \| `agent`, `llm`, `system-prompt` \|
feat(acp): tool-owned tool-call UI presentation (title/command/output) 2026-06-18 09:01:36 +08:00			\| `acp` \| `agent`, `llm`, `session`, `session-persistence`, `tools` \|
Merge remote-tracking branch 'origin/split/session-persistence' into split/agent-factory 2026-06-16 23:18:31 +08:00			\| `agent-loop` \| `agent`, `llm`, `session`, `session-persistence`, `system-prompt`, `tools` \|
feat(hooks): dsh-hooks-claude + dsh-hooks-codex bridges (hooks stack PR-F) 2026-07-01 04:22:00 +08:00			\| `hooks-codex` \| `agent`, `hook-protocol`, `llm`, `session`, `tools` \|
Add subagent capability seam: interface, mock backend, model-facing tool 2026-06-21 22:31:56 +08:00			\| `subagent` \| `agent`, `llm`, `tools` \|
refactor: order module-graph table topologically (low→high level) 2026-06-16 21:11:09 +08:00			\| `tool-bash` \| `agent`, `bash`, `llm`, `tools` \|
feat(tool-fs): result-time applied-hunk diffs for write/edit 2026-07-03 17:12:00 +08:00			\| `tool-fs` \| `fs`, `llm`, `session`, `system-prompt`, `tools` \|
feat(tool-todo): add the model-facing todo_write tool 2026-06-29 10:30:52 +08:00			\| `tool-todo` \| `agent`, `session`, `tools` \|
chore: adapt web seam to master's tsconfig + regenerate catalogs 2026-06-26 19:18:46 +08:00			\| `tool-web` \| `llm`, `system-prompt`, `tools`, `web` \|
refactor(examples): extract the app spine into dsh-agent-core + app packages 2026-06-21 12:03:44 +08:00			\| `agent-core` \| `agent`, `agent-loop`, `invariants`, `llm`, `session`, `system-prompt`, `tool-bash`, `tools` \|
feat(hooks): dsh-hooks-claude + dsh-hooks-codex bridges (hooks stack PR-F) 2026-07-01 04:22:00 +08:00			\| `hooks-claude` \| `agent`, `hook-protocol`, `llm`, `session`, `subagent`, `tools` \|
Add the ACP subagent backend: out-of-process delegation (PR3) 2026-06-22 10:47:02 +08:00			\| `subagent-acp` \| `agent`, `llm`, `subagent` \|
Extract the shared in-process driver into dsh-subagent-inprocess (review feedback) 2026-06-22 14:27:38 +08:00			\| `subagent-inprocess` \| `agent`, `llm`, `session`, `subagent` \|
Add subagent capability seam: interface, mock backend, model-facing tool 2026-06-21 22:31:56 +08:00			\| `subagent-mock` \| `agent`, `llm`, `subagent` \|
			\| `tool-subagent` \| `agent`, `llm`, `subagent`, `tools` \|
refactor(examples): extract the app spine into dsh-agent-core + app packages 2026-06-21 12:03:44 +08:00			\| `acp-agent` \| `acp`, `agent-core`, `session-persistence-jsonl` \|
docs: regenerate the module graph and dependency row for the dsh-llm edge 2026-07-04 17:17:36 +08:00			\| `stdio-agent` \| `agent`, `agent-core`, `llm`, `session`, `session-persistence-jsonl` \|
Extract the shared in-process driver into dsh-subagent-inprocess (review feedback) 2026-06-22 14:27:38 +08:00			\| `subagent-fork` \| `agent`, `session`, `subagent`, `subagent-inprocess` \|
			\| `subagent-spawn` \| `subagent`, `subagent-inprocess` \|