deepseek-harness/packages/README.md

Packages

Harness packages use the @deepseek-ai/dsh-* scope. Each is a Cordis service or functional plugin contributing through the framework's effect/event seams. Authoring conventions: AGENTS.md and root AGENTS.md.

Hierarchy

Packages live at packages/<group>/<pkg>/; groups are containers, while names remain @deepseek-ai/dsh-<pkg>. Each group README is the canonical package/ctx-key map.

Group	Role	Release expectation
core/	Product API spine: session, system-prompt, tools, agent, and the concrete loop	Product — stable surface
llm/	LLM capability family: the abstract service + provider adapters	Product — stable surface
bash/	Bash capability family: the executor seam, a local impl, and the model-facing tool	Product — stable surface
code-runtime/	Code-execution capability family: the abstract runtime seam for model-written programs + a worker-thread backend	Product — stable surface
sandbox/	Process-confinement seam; bwrap/Landlock/Seatbelt backends	Product — stable surface
fs/	Filesystem capability family: the abstract seam, a local impl, and the model-facing file tools	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
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/	Workflow capability family: the script-engine seam, the worker-thread engine, and the model-facing workflow tool	Product — stable surface
web/	Web capability family: the abstract seam, search/fetch provider impls, and the model-facing web tools	Product — stable surface
timeout/	Tool-call timeout policy: the tools/execute deadline enforcer	Product — stable surface
todo/	Todo/planning family: the model-facing todo_write tool	Product — stable surface
guard/	Loop-hygiene guards: advisory repeat-call reminders	Product — stable surface
cordis/	Self-referential runtime toolset: inspect the live runtime's plugins and services, mount/unmount model-written plugins (design)	Product — stable surface
hooks/	Hook bridges + the shared Claude Code / Codex wire-protocol library	Product — stable surface
session-persistence/	Persistence capability family: the seam + JSONL/SQLite backends	Product — stable surface
session-query/	Session retrieval family: logical corpus, surface records, and bounded exact reads	Product — stable surface
ui/	Editor/client integration surfaces: ACP bridge, JSON-RPC SDK server, app packages, user-approval and user-interaction seams, ask-user tool	Product — stable surface
support/	Dev/test/example infrastructure (invariants, replay adapter, subagent mock)	Support — lower compatibility expectations
util/	Low-level zero-dependency utilities shared across groups (the Branded<B> primitive)	Support — small, stable, harness-dep-free

Groups distinguish product API from support infrastructure. New packages join an existing group; a new group updates its README and this table.

Dependencies

The inter-package 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. Composition bundles such as dsh-agent-core intentionally assemble that loop. Swappable capabilities split into interface, implementation, and 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.