mirror of
https://github.com/deepseek-ai/deepseek-harness.git
synced 2026-08-29 04:26:38 +00:00
Tianyi Cui
3672cd25b4
Review direction (tianyicui, PR #660): in a stacked PR, change all other process-running places to use the new service. - lsp-local: LspConnection spawns through ctx.subprocess (piped protocol streams + a no-spill collected stderr tail); its private process-tree helpers (POSIX group signalling, Windows taskkill, liveness polling) are deleted in favor of the seam's handle verbs, and its buildChildEnv now rides scrubbedParentEnv (LSP children also stop inheriting stale DSH_*). The plugin injects 'subprocess'; compositions/tests mount dsh-subprocess-local. - subagent-acp: the ACP child spawns through the seam (piped ndjson streams, inherited stderr); spawn failure surfaces through done-rejection into the same startup race; disposal is handle.dispose with the plugin's configured graces. dsh-subagent-subprocess is DELETED — its dispose ladder and scrub are the seam's, and the isolated-config-dir helper had no consumer. - mcp-client, pty-local, sdk-helper: adopt scrubbedParentEnv as the one scrub definition (their spawns stay put by ownership: the MCP SDK and node-pty own those calls; the SDK wizard runs outside any composition). - Coverage: per-file 100% over every touched src file, with each v8 ignore carrying a platform or contract reason; new suites cover stdio dispositions, the dispose ladder tiers, injected-win32 tree semantics, waitForExit, settled-kill/terminate no-ops, and spawn-failure disposal. - Docs: consumer-migration Agent Note (en; zh follows in this PR), seam note updated in place, subprocess.md rewritten for the reshaped vocabulary (type-equiv re-registered), READMEs and SERVICE_ROLES updated, taskkill added to knip ignoreBinaries.
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: 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 |
subprocess/ |
Subprocess capability family: spawn seam + local process-group 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 implementation, and model-facing tools | Product — stable surface |
code-runtime/ |
Code-execution capability family: the 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: 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/ |
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, event relationships, semantic filtering, and 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 |
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/ |
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).
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.