deepseek-harness/packages/README.md

Packages

English | 中文

Packages use the @deepseek-ai/dsh-* scope. Cordis Service subclasses and function plugins contribute through ctx.effect(), ctx.on(), or ctx.waterfall(). Authoring rules: package and root.

Hierarchy

packages/<group>/<pkg>/ contains @deepseek-ai/dsh-<pkg> packages. Each group README is the canonical package/ctx-key map.

Group	Role	Release expectation
core/	Product API spine: sessions, prompts, tools, agent services, and the concrete loop	Product — stable surface
api/	Remote BFF assembly and TypeRT RPC gateway	Product — stable surface
typert/	Type graph generation, artifact loading, and runtime registry	Product — stable surface
goal/	Same-session goal persistence and lifecycle	Product — stable surface
feedback/	Human feedback	Product — stable surface
llm/	LLM capability family: the abstract service + provider adapters	Product — stable surface
subprocess/	Subprocess capability family: spawn seam + local process-tree implementation	Product — stable surface
bash/	Bash capability family: executor seam, local impl, model-facing tool	Product — stable surface
pty/	Persistent PTY capability family: owner-scoped sessions, local impl, model-facing tools	Product — stable surface
code-runtime/	Code-execution capability family: runtime seam for model-written programs + worker-thread backend	Product — stable surface
sandbox/	Process-confinement seam; bwrap/Landlock/Seatbelt backends	Product — stable surface
fs/	Filesystem capability family: seam, local impl, model-facing file tools, bash-backed discovery tools	Product — stable surface
lsp/	LSP capability family: seam, generic stdio provider, and the lsp tool	Product — stable surface
skill/	Skill capability family: the provider registry, local provider, and model-facing catalog/loader	Product — stable surface
compact/	Compaction capability family: the abstract seam + a basic backend (tool deferred)	Product — stable surface
context/	Model-visible request context, including workspace instructions and time context	Product — stable surface
subagent/	Subagent capability family: the provider-registry seam and the model-facing delegation tool	Product — stable surface
tasks/	Generic background-task runtime and model-facing task_* control tools	Product — stable surface
workflow/	Script seam, worker-thread engine, and model-facing workflow/ralph tools	Product — stable surface
web/	Web capability family: seam, search/fetch provider impls, and the model-facing web tools	Product — stable surface
attachment/	Attachments	Product — stable surface
spill/	Spill capability family: storage seam, local impl, tool-result spill policy	Product — stable surface
todo/	The model-facing todo_write tool	Product — stable surface
plan/	Plan collaboration state with a direct entry command and reviewed exit	Product — stable surface
timeout/	Tool-call tools/execute deadline enforcement	Product — stable surface
guard/	Loop-hygiene advisory repeat-call reminders	Product — stable surface
bundle/	Installable dsh --profile patch layers	Product — stable surface
cordis/	Cordis runtime integration: self-inspection, temporary Plugins, restricted repository Plugin loading	Product — stable surface
hooks/	Hook bridges + the shared Claude Code / Codex wire-protocol library	Product — stable surface
session-persistence/	Persistence seam + JSONL/SQLite backends	Product — stable surface
session-projection/	Projection seam: domain fold units serve whole values	Product — stable surface
session-query/	Session retrieval family: logical corpus, bounded reads, lineage, event relationships, semantic filtering, and SQLite full-text search	Product — stable surface
session-title/	Log-backed session titles: fallback service and opt-in LLM providers	Product — stable surface
settings/	User-settings seam + file-backed provider	Product — stable surface
credentials/	Credential-reference seam + env-over-.env provider	Product — stable surface
telemetry/	Session reporting: capture/redact seam, OTel backend	Product — stable surface
storage/	Non-session storage hub + backends + domain form	Product — stable surface
workspace/	Workspace entity	Product — stable surface
sdk/	Project SDK tooling	Product — stable surface
acp/	Automation-only Agent Client Protocol server	Product — stable surface
ui/	JSON-RPC integration, approval/interaction seams, ask-user tool	Product — stable surface
host/	Web-GUI host half: API gateway + HTTP route server	Product — stable surface
client/	Web-GUI browser half: shell, wire, object services, slots, ui-* plugins	Product — stable surface
experimental/	Prototypes and internal plugins	Unreleased
examples/	Demo bundles (agent-spine + CLI/ACP/JSON-RPC bins) leaves load	Support — example infra
support/	Support infrastructure (testkits, invariants, replay, Loader smokes)	Support — lower compatibility expectations
util/	Low-level zero-dependency utilities shared across groups (Branded<B>, Harness home/path helpers, timeout, retention)	Support — small, stable, harness-dep-free

New packages join existing groups; new groups update their README and this table.

Dependencies

The dependency graph is generated: docs/module-graph.md (pnpm run gen-module-graph, freshness-gated in CI).

Extension plugins depend on interfaces, never the concrete loop. dsh-agent-loop is swappable; UI, hook, and tool plugins use dsh-agent. Composition bundles, including dsh-agent-spine-demo, may depend on spine plugins. Capabilities split into interface / implementation / consumer packages; see capability seams.

Package READMEs cover purpose, APIs, extension points, and Model Experience unless on the model-agnostic omission allowlist. They also carry ## Known Limitations and Deferred Work or use its allowlist.