c06e6bea0b
Master unifies every live agent with its exact SessionId and moves declarative startup failures to agent-loop/config-start-failed. Keeping the branch’s AgentId label binding would let the TUI target the wrong lifecycle after reload and would miss asynchronous resume failures. Resolve that contract migration by giving the selected terminal front door the same generated or resumed SessionId as agent-core, mounting the front door first, and entering fullscreen only after the matching root appears. Refresh the source-derived catalogs and keyless terminal goldens so Code Mode, workflow, Cordis-tool, and transient UI scenarios all exercise the merged identity model.
Packages
Packages use the @deepseek-ai/dsh-* scope. Each is a Cordis Service subclass or function plugin; contributions use ctx.effect(), ctx.on(), or ctx.waterfall(). Authoring rules: package and root.
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, the model-facing file tools, and the bash-backed discovery 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 |
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/ |
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 |
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 |
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: logical corpus, bounded reads, lineage, and event relationships | Product — stable surface |
sdk/ |
Project SDK tooling | Product — stable surface |
ui/ |
Editor/client integration surfaces: ACP bridge, JSON-RPC SDK server, user-approval/user-interaction seams, ask-user tool | Product — stable surface |
examples/ |
Demo bundles (agent-spine + stdio/ACP/JSON-RPC bins) the leaves load | Support — example infra |
support/ |
Support infrastructure (testkits, invariants, replay, Loader smokes, subagent mock) | 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 |
Groups distinguish product API from support infrastructure. New packages join an existing group; a new group updates its README 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 — UI/hook/tool plugins keep working against the dsh-agent vocabulary if the loop is replaced. The sanctioned exception is a composition/bundle package like dsh-agent-spine-demo, whose whole job is to assemble the concrete spine: it depends on dsh-agent-loop (and the other concrete spine plugins) on purpose. The rule constrains plugins that EXTEND the system, not the bundle that COMPOSES it. A swappable capability splits into interface / implementation / consumer packages (the bash trio is the template — 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.