2026-08-25 23:47:20 +08:00
---
description: "The DeepSeek Harness package workspace: how the npm packages under packages/ are grouped, what each group owns, and the conventions that bind them."
kind: "package-group"
---
Document the codebase thoroughly and tighten type safety
Docs: per-folder README.md for packages/ (family overview + one per
package: service, events, API, extension points, TODOs), examples/,
and examples/echo-agent/; folder-level AGENTS.md (+ CLAUDE.md
symlinks) for packages/ and vendor/; module-level doc comments in
every packages/*/src file; richer JSDoc on all exported API
(event side effects, disposal contracts, error behavior). Root
AGENTS.md gains a "Type Safety and Documentation" policy section:
the codebase aims to be very type-safe and well documented; type
gymnastics are acceptable in core packages when they improve
plugin-author DX; verbose docs are fine as long as they stay strictly
in sync with the code.
Type safety: removed the upstream-inherited "noImplicitAny": false
from tsconfig.base.json — packages/* now compile under full strict
mode; vendor/loader and vendor/include set it locally (vendor/cordis
already did). Eliminated every `: any` / `as any` from packages and
examples (catch clauses use unknown + a CodedError narrowing type;
event data access uses discriminated-union narrowing).
Typed tool schemas: new @deepseek-ai/dsh-tools schema DSL —
SchemaSpec with per-property `required: true` booleans, type-level
InferArgs<S>, a runtime SchemaSpec → JSON Schema converter, and
defineTool() so first-party tools get typed execute(args) with zero
casts (raw JSON Schema still accepted for MCP interop; chosen over
schemastery because it targets JSON Schema generation directly).
echo-tool and all test tools migrated; +7 tests.
2026-06-11 12:39:27 +08:00
# Packages
2026-07-26 05:03:53 +08:00
English | [中文 ](README.zh.md )
2026-08-25 23:47:20 +08:00
## 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 ](#package-groups )
- [Release expectations ](#release-expectations )
- [Dependencies ](#dependencies )
- [Package README contracts ](#package-readme-contracts )
- [Dev Note ](#dev-note )
-----
< a id = "package-groups" > < / a >
## 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/` ](core/README.md ) | Product API spine: sessions, prompts, tools, agent services, and the concrete loop |
| [`api/` ](api/README.md ) | Remote BFF assembly and Typert RPC gateway |
| [`typert/` ](typert/README.md ) | Type graph generation, artifact loading, and runtime registry |
| [`goal/` ](goal/README.md ) | Same-session goal persistence and lifecycle |
| [`schedule/` ](schedule/README.md ) | Session-local scheduled follow-ups |
| [`feedback/` ](feedback/README.md ) | Human feedback capture and command |
| [`identity/` ](identity/README.md ) | Shared anonymous identity |
| [`llm/` ](llm/README.md ) | LLM capability family: abstract service + provider adapters |
| [`e2b/` ](e2b/README.md ) | E2B remote-runtime providers |
| [`subprocess/` ](subprocess/README.md ) | Subprocess capability family: Service Definition + local process-tree provider |
| [`shell/` ](shell/README.md ) | Bash capability family: executor seam, local impl, model-facing tools |
| [`terminal/` ](terminal/README.md ) | Persistent PTY capability family: owner-scoped sessions, local implementation, model-facing tools |
2026-08-26 01:22:51 +08:00
| [`code-runtime/` ](code-runtime/README.md ) | Code-execution capability family: Service Definition + worker-thread provider + PTC mode Consumer |
2026-08-25 23:47:20 +08:00
| [`sandbox/` ](sandbox/README.md ) | Process-confinement seam; bwrap/Landlock/Seatbelt backends |
| [`fs/` ](fs/README.md ) | Filesystem capability family: seam, local impl, model-facing file tools, discovery tools |
| [`lsp/` ](lsp/README.md ) | LSP capability family: seam, generic stdio provider, and the `lsp` tool |
| [`skill/` ](skill/README.md ) | Skill capability family: provider registry, local provider, model-facing catalog/loader |
| [`compaction/` ](compaction/README.md ) | Compaction capability family: Service Definition + basic provider + command Consumer |
| [`context/` ](context/README.md ) | Model-visible request context: workspace instructions, time context, references |
| [`subagent/` ](subagent/README.md ) | Subagent capability family: provider-registry contract and model-facing delegation tools |
| [`jobs/` ](jobs/README.md ) | Generic background-job runtime and model-facing job control tools |
| [`experimental/` ](experimental/README.md ) | Private prototypes and internal-only plugins |
| [`workflow/` ](workflow/README.md ) | Workflow seam, worker-thread engine, and model-facing `workflow` /`ralph` tools |
| [`webhook/` ](webhook/README.md ) | Verified external events, trusted rules, and fire-and-forget Workspace Sessions |
| [`web/` ](web/README.md ) | Web capability family: seam, search/fetch providers, model-facing web tools |
| [`attachment/` ](attachment/README.md ) | Durable attachment identity, validation, local content-addressed storage |
| [`spill/` ](spill/README.md ) | Spill capability family: storage seam, local impl, tool-result spill policy |
| [`todo/` ](todo/README.md ) | The model-facing `todo_write` tool |
| [`plan/` ](plan/README.md ) | Plan collaboration state with a direct entry command and reviewed exit |
| [`preset/` ](preset/README.md ) | Per-session agent composition from preset `cordis.yml` files |
| [`guard/` ](guard/README.md ) | Loop-hygiene guards: advisory repeat-call reminders + the `tools/execute` deadline enforcer |
| [`bundle/` ](bundle/README.md ) | Installable `dsh --profile` patch layers |
| [`extensions/` ](extensions/README.md ) | Agent runtime self-modification: live plugin/service inspection and model-written mount/unmount |
| [`hooks/` ](hooks/README.md ) | Hook bridges + the shared Claude Code / Codex wire-protocol library |
| [`session/` ](session/README.md ) | Durable session data plane: persistence seam + backends, projection seam, log-backed titles, session reporting |
| [`session-query/` ](session-query/README.md ) | Session retrieval family: logical corpus, bounded reads, lineage, semantic filtering, SQLite full-text search |
| [`settings/` ](settings/README.md ) | User-settings seam + file-backed provider |
| [`credentials/` ](credentials/README.md ) | Credential-reference and credential-record seam + env-over-`.env` provider + authorization flows that ask a human |
| [`storage/` ](storage/README.md ) | Non-session storage hub + backends + domain form |
| [`workspace/` ](workspace/README.md ) | Workspace entity |
| [`sdk/` ](sdk/README.md ) | Out-of-process SDK: JSON-RPC protocol and TypeScript client/server |
| [`acp/` ](acp/README.md ) | Automation-only Agent Client Protocol server |
| [`interaction/` ](interaction/README.md ) | Human-collaboration plane: approval/interaction seams, permission preset, commands, ask-user tool |
| [`boot/` ](boot/README.md ) | Shared app-bin boot glue |
| [`host/` ](host/README.md ) | Web-GUI host half: API gateway + HTTP route server |
| [`client/` ](client/README.md ) | Web-GUI browser half: shell, wire, object services, slots, `ui-*` plugins |
| [`test-support/` ](test-support/README.md ) | Support infrastructure (testkits, invariants, replay, Loader smokes) |
| [`runtime-diagnostics/` ](runtime-diagnostics/README.md ) | Runtime diagnostics: package-owned invariant checks and reports |
| [`util/` ](util/README.md ) | Low-level zero-dependency utilities shared across groups (`Branded<B>` , home/path helpers, timeout, retention) |
-----
< a id = "release-expectations" > < / a >
## Release expectations
refactor(examples): extract reusable logic into tested packages
Logic that lived under examples/ was outside the per-file 100% coverage
gate (examples/ are not workspaces) and, in the stdio-UI case, duplicated
across two examples. Move it into packages/ so it is gated and de-duped.
- packages/ui-stdio (new): unify the two diverged stdio-chat.ts copies into
one @deepseek-ai/dsh-ui-stdio plugin (welcome/agent Config). A test-only
I/O seam (createStdioChat(ctx, config, runtime)) keeps process streams out
of the serializable config and makes every render/EOF/disposal branch
unit-testable. Per-file 100%. echo/coding cordis.yml now load the package;
both src/stdio-chat.ts deleted.
- packages/llm-replay (new): move examples/acp-agent/src/llm-replay.ts (+ its
spec) here so its derive/parse/replay branches fall under the coverage gate.
cordis.snapshot.yml + README rewired to the package name; added apply/env
/assertNever/abort tests to reach per-file 100%.
- examples/{echo,coding}-agent: keyless Loader-path e2e smokes that boot the
real cordis.yml (no key) — the guard a hand-mounted unit test cannot be for
the unwrapExports/export-shape class (postmortem 0001). examples/AGENTS.md
codifies the keyless+with-key smoke convention (keyless-by-nature exception
for echo-agent).
- AGENTS.md: a scoped, removal-triggered pre-release stance (foundation over
blast radius). packages/README.md: new rows + a FIXME to later regroup ALL
packages into a hierarchy. Wiring: tsconfig paths/refs, publint, knip,
module-graph.
Verified: typecheck, lint, test:coverage (887 tests, 100%), build, hygiene,
doc-sync, test:snapshot (10), test:e2e (6 keyless pass, with-key self-skip).
2026-06-19 12:42:28 +08:00
2026-08-26 14:12:26 +08:00
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.
2026-08-25 23:47:20 +08:00
-----
< a id = "dependencies" > < / a >
docs(AGENTS): rewrite the root standing orders to the 1,500-word budget
Applies the documentation standard to its biggest offender. Every rule
survives as one to three lines plus a link to its durable home; the
stories, duplicate statements, and re-narrations go:
- Situational clusters evict to new homes: docs/testing.md (tiers,
with-key policy, real-over-mock, world-verification, real-entry-path
guards), docs/defensive-patterns.md (the bug-class rules), and
docs/cookbook/responding-to-pr-review-on-a-stack.md (the stacked-PR
review procedure).
- Doc-authoring rules consolidate into docs/AGENTS.md § Writing rules
(current-state-never-history, md-wrap, ts-block compilation, @mode,
catalog same-change, pair same-change).
- packages/README.md drops to the group table + the extension-vs-bundle
dependency rule; the hand ASCII graph yields to the generated
module-graph.md; group READMEs are the canonical per-package map.
- packages/AGENTS.md keeps only its packages-specific rules (export
shape, ctx.get, real-Loader coverage); examples/AGENTS.md repoints
its with-key-policy link; rfc/README.md loses a narrated-history
aside; dsh-code-review / dsh-find-simplifications / verify-md-wrap
references follow the moved content.
- Budget manifest ratchets: AGENTS.md 8200 -> 1500 (now 1,495 words),
packages/README.md 1900 -> 600, packages/AGENTS.md 600 -> 450; the
two new eviction docs join the budget set (testing 800, defensive
550); docs/AGENTS.md raises 1000 -> 1250 for the absorbed writing
rules (the one justified increase). The doc-tiers RFC's deferred list
prunes the two items this change ships.
2026-07-04 14:22:47 +08:00
## Dependencies
Document the codebase thoroughly and tighten type safety
Docs: per-folder README.md for packages/ (family overview + one per
package: service, events, API, extension points, TODOs), examples/,
and examples/echo-agent/; folder-level AGENTS.md (+ CLAUDE.md
symlinks) for packages/ and vendor/; module-level doc comments in
every packages/*/src file; richer JSDoc on all exported API
(event side effects, disposal contracts, error behavior). Root
AGENTS.md gains a "Type Safety and Documentation" policy section:
the codebase aims to be very type-safe and well documented; type
gymnastics are acceptable in core packages when they improve
plugin-author DX; verbose docs are fine as long as they stay strictly
in sync with the code.
Type safety: removed the upstream-inherited "noImplicitAny": false
from tsconfig.base.json — packages/* now compile under full strict
mode; vendor/loader and vendor/include set it locally (vendor/cordis
already did). Eliminated every `: any` / `as any` from packages and
examples (catch clauses use unknown + a CodedError narrowing type;
event data access uses discriminated-union narrowing).
Typed tool schemas: new @deepseek-ai/dsh-tools schema DSL —
SchemaSpec with per-property `required: true` booleans, type-level
InferArgs<S>, a runtime SchemaSpec → JSON Schema converter, and
defineTool() so first-party tools get typed execute(args) with zero
casts (raw JSON Schema still accepted for MCP interop; chosen over
schemastery because it targets JSON Schema generation directly).
echo-tool and all test tools migrated; +7 tests.
2026-06-11 12:39:27 +08:00
2026-07-09 13:01:14 +08:00
The dependency graph is generated: [docs/module-graph.md ](../docs/module-graph.md ) (`pnpm run gen-module-graph` , freshness-gated in CI).
Document the codebase thoroughly and tighten type safety
Docs: per-folder README.md for packages/ (family overview + one per
package: service, events, API, extension points, TODOs), examples/,
and examples/echo-agent/; folder-level AGENTS.md (+ CLAUDE.md
symlinks) for packages/ and vendor/; module-level doc comments in
every packages/*/src file; richer JSDoc on all exported API
(event side effects, disposal contracts, error behavior). Root
AGENTS.md gains a "Type Safety and Documentation" policy section:
the codebase aims to be very type-safe and well documented; type
gymnastics are acceptable in core packages when they improve
plugin-author DX; verbose docs are fine as long as they stay strictly
in sync with the code.
Type safety: removed the upstream-inherited "noImplicitAny": false
from tsconfig.base.json — packages/* now compile under full strict
mode; vendor/loader and vendor/include set it locally (vendor/cordis
already did). Eliminated every `: any` / `as any` from packages and
examples (catch clauses use unknown + a CodedError narrowing type;
event data access uses discriminated-union narrowing).
Typed tool schemas: new @deepseek-ai/dsh-tools schema DSL —
SchemaSpec with per-property `required: true` booleans, type-level
InferArgs<S>, a runtime SchemaSpec → JSON Schema converter, and
defineTool() so first-party tools get typed execute(args) with zero
casts (raw JSON Schema still accepted for MCP interop; chosen over
schemastery because it targets JSON Schema generation directly).
echo-tool and all test tools migrated; +7 tests.
2026-06-11 12:39:27 +08:00
2026-08-26 14:12:26 +08:00
**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 ](../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md ).
Document the codebase thoroughly and tighten type safety
Docs: per-folder README.md for packages/ (family overview + one per
package: service, events, API, extension points, TODOs), examples/,
and examples/echo-agent/; folder-level AGENTS.md (+ CLAUDE.md
symlinks) for packages/ and vendor/; module-level doc comments in
every packages/*/src file; richer JSDoc on all exported API
(event side effects, disposal contracts, error behavior). Root
AGENTS.md gains a "Type Safety and Documentation" policy section:
the codebase aims to be very type-safe and well documented; type
gymnastics are acceptable in core packages when they improve
plugin-author DX; verbose docs are fine as long as they stay strictly
in sync with the code.
Type safety: removed the upstream-inherited "noImplicitAny": false
from tsconfig.base.json — packages/* now compile under full strict
mode; vendor/loader and vendor/include set it locally (vendor/cordis
already did). Eliminated every `: any` / `as any` from packages and
examples (catch clauses use unknown + a CodedError narrowing type;
event data access uses discriminated-union narrowing).
Typed tool schemas: new @deepseek-ai/dsh-tools schema DSL —
SchemaSpec with per-property `required: true` booleans, type-level
InferArgs<S>, a runtime SchemaSpec → JSON Schema converter, and
defineTool() so first-party tools get typed execute(args) with zero
casts (raw JSON Schema still accepted for MCP interop; chosen over
schemastery because it targets JSON Schema generation directly).
echo-tool and all test tools migrated; +7 tests.
2026-06-11 12:39:27 +08:00
2026-08-25 23:47:20 +08:00
-----
< a id = "package-readme-contracts" > < / a >
## Package README contracts
Every package README covers purpose, configuration, extension points, and [Model Experience ](../docs/cookbook/adding-a-package.md#4-write-the-package-readme ) unless the model-agnostic [omission allowlist ](../scripts/verify-package-readme-model-experience.ts ) exempts it. It also carries `## Known Limitations and Deferred Work` or uses its [allowlist ](../scripts/verify-package-readme-limitations.ts ). Package conventions — exports, service access, invariants, tests — live in [packages/AGENTS.md ](AGENTS.md ).
-----
< a id = "dev-note" > < / a >
## Dev Note
< details >
< summary > Working context for maintainers — click to expand< / summary >
None.
< / details >
