Yichen Jiang
aaf58eb5bf
Second review round on the contained-group composition:
- Ownership scanned only `insert` rows, so an external bundle could set a
built-in row's id as a child through `{ id: own, config: [...] }` and the
Loader re-parented that row under the bundle while `originOf` still named
the built-in layer. The rows an id-targeted patch sets as a group's config
now count as the layer's own: an external bundle that sets an id another
layer owns is left out whole, a built-in layer that takes another layer's
id fails loud, and a layer restating its own child is not a repeat.
- `recompose` read the committed profile before awaiting the update, so a
watcher firing while a bundle was being enabled composed the tree before
the enable and applied it after; the plugin vanished while `layers` kept
listing it. Recompositions now queue, each reading what the previous one
committed, and a rejection stays its own caller's outcome.
- A patch that replaced a built-in target's config removed the wrapper the
bundle had put there, yet later inserts still targeted the detached
wrapper and vanished. The composition forgets the wrapper on such an
override and creates a new one under the same id.
- Generated wrapper ids bypassed the duplicate check, so a bundle declaring
a row spelled like a wrapper produced two nodes with one id. Declared and
generated ids now go through one registration.
- Failure records outlived their rows when a bundle update dropped a failed
row without unmounting the group, or when a pending row sat in a plain
nested group whose id the record named. A contained group now drops the
records of rows its configuration no longer names after each update, and
the audit records every row under the contained group that isolates it.
- `applyEntryPatches` assigned override values by reference, so applying a
patch list carried a later insert's rows back into the patch object; the
vendored include now clones object-valued overrides as it does inserts.
description, kind
| description | kind |
|---|---|
| The DeepSeek Harness package workspace: how the npm packages under packages/ are grouped, what each group owns, and the conventions that bind them. | package-group |
Packages
English | 中文
Summary
The harness is assembled from npm packages under packages/, grouped by capability family: sessions and the agent loop, model-facing tools, shell and filesystem execution, web access, subagents, and the rest. Use this page as the top-level map: find the owning group, then open its README for the package list. Every package is scoped @deepseek-ai/dsh-* and lives in exactly one group; each group README is the authoritative package map for its family.
Table of Contents
Package groups
Every package lives in exactly one group; new packages join existing groups, and a new group updates its own README and this table.
| Group | Role |
|---|---|
core/ |
Product API spine: sessions, prompts, tools, agent services, and the concrete loop |
api/ |
Remote BFF assembly and Typert RPC gateway |
typert/ |
Type graph generation, artifact loading, and runtime registry |
goal/ |
Same-session goal persistence and lifecycle |
schedule/ |
Session-local scheduled follow-ups |
feedback/ |
Human feedback capture and command |
identity/ |
Shared anonymous identity |
llm/ |
LLM capability family: abstract service + provider adapters |
e2b/ |
E2B remote-runtime providers |
subprocess/ |
Subprocess capability family: Service Definition + local process-tree provider |
shell/ |
Bash capability family: executor seam, local impl, model-facing tools |
terminal/ |
Persistent PTY capability family: owner-scoped sessions, local implementation, model-facing tools |
code-runtime/ |
Code-execution capability family: Service Definition + worker-thread provider + PTC mode Consumer |
sandbox/ |
Process-confinement seam; bwrap/Landlock/Seatbelt backends |
fs/ |
Filesystem capability family: seam, local impl, model-facing file tools, discovery tools |
lsp/ |
LSP capability family: seam, generic stdio provider, and the lsp tool |
skill/ |
Skill capability family: provider registry, local provider, model-facing catalog/loader |
compaction/ |
Compaction capability family: Service Definition + basic provider + command Consumer |
context/ |
Model-visible request context: workspace instructions, time context, references |
subagent/ |
Subagent capability family: provider-registry contract and model-facing delegation tools |
jobs/ |
Generic background-job runtime and model-facing job control tools |
experimental/ |
Private prototypes and internal-only plugins |
workflow/ |
Workflow seam, worker-thread engine, and model-facing workflow/ralph tools |
webhook/ |
Verified external events, trusted rules, and fire-and-forget Workspace Sessions |
web/ |
Web capability family: seam, search/fetch providers, model-facing web tools |
attachment/ |
Durable attachment identity, validation, local content-addressed storage |
spill/ |
Spill capability family: storage seam, local impl, tool-result spill policy |
todo/ |
The model-facing todo_write tool |
plan/ |
Plan collaboration state with a direct entry command and reviewed exit |
preset/ |
Per-session agent composition from preset cordis.yml files |
guard/ |
Loop-hygiene guards: advisory repeat-call reminders + the tools/execute deadline enforcer |
bundle/ |
Installable dsh --profile patch layers |
extensions/ |
Agent runtime self-modification: live plugin/service inspection and model-written mount/unmount |
hooks/ |
Hook bridges + the shared Claude Code / Codex wire-protocol library |
session/ |
Durable session data plane: persistence seam + backends, projection seam, log-backed titles, session reporting |
session-query/ |
Session retrieval family: logical corpus, bounded reads, lineage, semantic filtering, SQLite full-text search |
settings/ |
User-settings seam + file-backed provider |
credentials/ |
Credential-reference and credential-record seam + env-over-.env provider + authorization flows that ask a human |
storage/ |
Non-session storage hub + backends + domain form |
workspace/ |
Workspace entity |
sdk/ |
Out-of-process SDK: JSON-RPC protocol and TypeScript client/server |
acp/ |
Automation-only Agent Client Protocol server |
interaction/ |
Human-collaboration plane: approval/interaction seams, permission preset, commands, ask-user tool |
boot/ |
Shared app-bin boot glue |
host/ |
Web-GUI host half: API gateway + HTTP route server |
client/ |
Web-GUI browser half: shell, wire, object services, slots, ui-* plugins |
test-support/ |
Support infrastructure (testkits, invariants, replay, Loader smokes) |
runtime-diagnostics/ |
Runtime diagnostics: package-owned invariant checks and reports |
util/ |
Low-level zero-dependency utilities shared across groups (Branded<B>, home/path helpers, timeout, retention) |
Release expectations
Most groups are product — stable API. The exceptions: e2b/ is a POC, experimental/ is unreleased, and test-support/, runtime-diagnostics/, and util/ are support with lower compatibility expectations.
Dependencies
The dependency graph is generated: docs/module-graph.md (pnpm run gen-module-graph, freshness-gated in CI).
Extension plugins depend on Service Definitions, never concrete providers. dsh-agent-loop is swappable; UI, hook, and tool plugins use dsh-agent. Composition bundles may depend on spine plugins. Capabilities separate Service Definition / Service Provider / Consumer roles when they evolve independently; see capability seams.
Package README contracts
Every package README covers purpose, configuration, extension points, and Model Experience unless the model-agnostic omission allowlist exempts it. It also carries ## Known Limitations and Deferred Work or uses its allowlist. Package conventions — exports, service access, invariants, tests — live in packages/AGENTS.md.
Dev Note
Working context for maintainers — click to expand
None.