6adb14b56d
A cursor-less adoption (process restart + resume, fork, seam-module reload) replayed the session's full log from seq 0, re-exporting history that already left the process — a resume re-billed its entire stored log on every restart, and a fork re-shipped the parent's prefix under the child's id, doubling query-time counts on OTLP backends with no native ingest dedupe. dsh-session now exposes the fact the constructor already validated but discarded: Session.firstLiveSeq, the constructor-seed length — the first seq appended in this process. header.seedLength cannot serve here: it is the durable fork-lineage boundary, and a resumed session's constructor seed is its full stored log while the header keeps the original fork value (llm-replay and session-query-sqlite depend on that meaning). Constructor seeds also never publish on the session/event firehose, so adoption replaying them was inconsistent with the system's own publication semantics. Adoption's cursor-less fallback starts at firstLiveSeq; seed events still feed the chunk projection, so mid-step continuations re-drop after a resume. Fork streams are no longer self-contained: records now carry session.seed_length (with the existing session.parent_id) so receivers stitch the child's stream onto the parent's. Accepted cost, consistent with at-most-once delivery and recorded in the revival Agent Note: a resume no longer backfills records a previous process failed to deliver — a deployment with that requirement needs the deferred outbox, not replay. Pinned red-first: seeded adoption exports nothing (assertion reversed from the prior seed-readback test, obsolete behavior changed with its test), resume-shaped seed rebuilds the projection without exporting, and fork records carry the stitch attributes.
Packages
English | 中文
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: sessions, prompts, tools, agent services, and the concrete loop | Product — stable surface |
goal/ |
Persisted same-session goal state and lifecycle | Product — stable surface |
llm/ |
LLM capability family: the abstract service + provider adapters | 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: abstract seam + 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, worker-thread engine, and model-facing workflow and fresh-agent ralph tools |
Product — stable surface |
web/ |
Web capability family: seam, search/fetch provider impls, and the model-facing web tools | Product — stable surface |
spill/ |
Spill capability family: storage seam, local impl, tool-result spill policy | Product — stable surface |
todo/ |
Todo/planning family: 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 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 family: logical corpus, bounded reads, lineage, relationships, semantic filtering, SQLite full-text search | Product — stable surface |
session-title/ |
Log-backed session titles: fallback service, shared LLM policy, and opt-in providers | 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/ |
Human/client integrations: TUI and JSON-RPC, approval/interaction seams, ask-user tool | Product — stable surface |
examples/ |
Demo bundles (agent-spine + TUI/CLI/ACP/JSON-RPC bins) leaves load | Support — example infra |
support/ |
Support infrastructure (testkits, invariants, replay, Loader smokes) | Support — lower compatibility expectations |
util/ |
Zero-dependency utilities shared across groups (Branded<B>, 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).
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.