8e9d5467b0
Review findings on the CPython backend: a child that never reads fd 3 leaves
the reply pipe full forever, so the drain loop waits on 'drain' while every
call frame it keeps sending resolves a binding and queues another reply —
the backlog (and the binding results it pins) would grow until the wall
clock. sendReply now caps the pending backlog at MAX_PENDING_REPLIES and
settles the run as worker-exit past it, mirroring the frame cap; a child
flooding calls against a binding that never settles would otherwise bypass
that cap (pendingReplies grows only after the await), so the dispatcher
counts in-flight binding calls before dispatch and releases the slot in the
async body's finally, capping outstanding closures at the same bound. The
drain also compacts its consumed prefix (replyQueue.splice(0, head)) once
head reaches the bound, so a drain that stays alive without emptying cannot
grow the backing store linearly with cumulative throughput.
The completion-value meter counted lone surrogates with
_SURROGATE.findall(folded), materializing one single-character string per
surrogate: a surrogate-dense value near the budget (millions of surrogates,
each serializing to six bytes) allocated millions of objects before the meter
returned, defeating the meter's counting-without-building contract. The count
is now the length difference between folded and the without string the meter
already computes; a standalone equivalence check confirms it matches findall
across lone-high, lone-low, paired, astral, and mixed cases.
validateBindings read namespace.global/errorClass.name/memberNameProperty
several times and retained the original errorClass object for the boot
frame, whose JSON.stringify re-read it after validation: a stateful getter
could throw or change between the two stages, turning the seam-misuse
rejection into a worker-exit or injecting an unvalidated name. Each field is
now read once into a plain value and the bindings map stores a plain
{ name, memberNameProperty } copy, so validation and the boot frame see
identical values.
Regression tests: a hostile child floods 5000 sequential valid calls without
reading fd 3 and the run settles worker-exit with the reply-queue message
before maxWallMs; a 3,000,000-surrogate completion succeeds at an
18,000,002-byte budget and reports output-limit one byte under; a 5000-call
flood against a never-settling binding settles worker-exit with the
call-backlog message; getter-backed namespace metadata that throws or
changes on a second read boots and runs with each field read exactly once; a
two-wave flood whose replies exceed the writable high-water mark drives the
drain past the compaction bound mid-delivery and verifies all 1524 replies
arrive. README Known Limitations gains the reply-backlog and call-backlog
bounds (en/zh, pairing re-recorded); a new Agent Note registers the findings.
|
||
|---|---|---|
| .. | ||
| acp | ||
| api | ||
| attachment | ||
| boot | ||
| bundle | ||
| client | ||
| code-runtime | ||
| compaction | ||
| context | ||
| core | ||
| credentials | ||
| e2b | ||
| experimental | ||
| extensions | ||
| feedback | ||
| fs | ||
| goal | ||
| guard | ||
| hooks | ||
| host | ||
| identity | ||
| interaction | ||
| jobs | ||
| llm | ||
| lsp | ||
| mcp | ||
| plan | ||
| preset | ||
| runtime-diagnostics | ||
| sandbox | ||
| schedule | ||
| sdk | ||
| session | ||
| session-query | ||
| settings | ||
| shell | ||
| skill | ||
| spill | ||
| storage | ||
| subagent | ||
| subprocess | ||
| terminal | ||
| test-support | ||
| todo | ||
| typert | ||
| util | ||
| web | ||
| webhook | ||
| workflow | ||
| workspace | ||
| AGENTS.md | ||
| CLAUDE.md | ||
| README.i18n.yaml | ||
| README.md | ||
| README.zh.md | ||
| 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.