Dudu-0223
590f520949
Translate ctx.bash.run() REJECTIONS into the SEARCH_* taxonomy. The seam
contract has run() reject for infrastructure failures (a pre-aborted
signal, an unusable/deleted session workdir, a missing shell); the bare
await let those escape as plain Errors, so the tool registry produced
isError results without the structured SearchError { name, code } the
package documents. A pre-aborted spec.signal now maps to SEARCH_ABORTED
and any other start failure to SEARCH_FAILED, original error chained as
cause. Covered by fake-executor tests for both branches plus real-executor
integration tests pinning the exact pre-aborted-signal and deleted-cwd
paths.
Packages
Harness packages live under the @deepseek-ai/dsh-* scope. Each is a Cordis plugin: it exports a Service subclass or functional plugin, declares ctx keys/events through declaration merging, and extends through ctx.effect(), ctx.on(), and ctx.waterfall(). Authoring conventions: AGENTS.md and root AGENTS.md § Conventions.
Hierarchy
Packages are grouped by role at packages/<group>/<pkg>/. The group directory is a pure container; package names stay @deepseek-ai/dsh-<pkg>. Group READMEs are the canonical maps for package roles, ctx keys, and product-vs-support split.
| 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 |
fs/ |
Filesystem capability family: the abstract seam, a local impl, the model-facing file tools, and the bash-backed discovery tools | 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 |
web/ |
Web capability family: the abstract seam, search/fetch provider impls, and the model-facing web tools | Product — stable surface |
spill/ |
Spill capability family: the storage seam, a local impl, and the tool-result spill policy | Product — stable surface |
todo/ |
Todo/planning family: the model-facing todo_write tool |
Product — stable surface |
timeout/ |
Tool-call timeout policy: the tools/execute deadline enforcer |
Product — stable surface |
guard/ |
Loop-hygiene guards: advisory repeat-call reminders | 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 |
ui/ |
Editor/client integration surfaces (the ACP bridge) + the app packages | Product — stable surface |
support/ |
Dev/test/example infrastructure (invariants, replay adapter, subagent mock) | Support — lower compatibility expectations |
util/ |
Low-level zero-dependency primitives shared across groups (branding, timeout, retention) | Support — small, stable, harness-dep-free |
The split marks product API versus support/test/example infrastructure, so release and removal decisions do not treat every package as equally public. New packages join an existing group; a new top-level group updates the group READMEs and this table.
Dependencies
The dependency graph is generated: docs/module-graph.md (pnpm run gen-module-graph, freshness-gated in CI).
The rule it must obey: extension plugins depend on interfaces, never on the concrete loop. dsh-agent-loop is swappable, so UI/hook/tool plugins keep working against dsh-agent if the loop changes. The exception is a composition bundle like dsh-agent-core: it depends on dsh-agent-loop because it assembles the concrete spine. Swappable capabilities split into interface / implementation / consumer packages (the bash trio is the template — see capability seams).
Each package has its own README.md with purpose, service API, events, extension points, and deliberate non-goals (TODOs).