mirror of
https://github.com/deepseek-ai/deepseek-harness
synced 2026-08-15 21:04:50 +00:00
8c2970e70e
Review found five real defects in the configuration-source work, all confirmed against the code rather than argued: 1. The note claimed --config outranks settings.yaml. It does not: the settings seam registers a plugin's cordis entry config as the `base` layer and the user section layers over it, and the seam cannot tell a shipped value from a --config one. The note now states shipped reality and names --config-replace as the lever for a deployment that must win. Separately, a literal `apiKey` in settings outranked both the environment and .credentials.yaml — the field is removed, so configuration carries a reference and nothing else. 2. DEEPSEEK_SEARCH_BASE_URL was functionally deleted: the shipped inline went away without the provider learning to read it. It now resolves from the environment snapshot, as the README always claimed. 3. The bootstrap deny list missed the interpreter start-up hooks. BASH_ENV is the sharpest: `bash -c` sources it on every bash tool call, so a project .env could run a file of its choosing before every command. The list now covers BASH_ENV and its per-language siblings, the Git hook commands, and the remaining preload and CA variables, organised by what a variable does rather than which runtime owns it. 4. YAML parse errors quoted the offending source line — which in a credentials document is the secret — into boot stderr and the watcher's logger. Only the error code and position are reported now, in credentials-local and settings-local alike, pinned by a test that asserts the secret is absent. 5. 0600 governed only files the harness wrote. A hand-created 0644 document was read normally. POSIX now checks the mode before reading contents, at boot and on every reload; Windows has no mode to inspect and is skipped rather than faked. The project a session is launched in is trusted by default, with no prompt and no stored trust record: it may supply its own endpoint, ordinary variables, and a key ranked below the managed store. Trust stops at the harness itself — a discovered file still cannot set DSH_PERMISSION_MODE, PATH, BASH_ENV, or the rest, because those take effect with no user action, before any turn, outside the permission policy and the sandbox.
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 |
typert/ |
Type graph generation, artifact loading, and runtime registry | 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-tree 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/ |
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/ |
Cordis runtime integration: self-inspection/model-written temporary Plugins and restricted repository Plugin loading | Product — stable surface |
hooks/ |
Hook bridges + the shared Claude Code / Codex wire-protocol library | Product — stable surface |
session-persistence/ |
Persistence seam + JSONL/SQLite backends | Product — stable surface |
session-projection/ |
Projection seam: domain fold units serve whole values | 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 and opt-in LLM providers | Product — stable surface |
settings/ |
User-settings seam + file-backed provider | Product — stable surface |
credentials/ |
Credential-reference seam + env-over-.env provider |
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/ |
TUI and JSON-RPC integrations, approval/interaction seams, ask-user tool | Product — stable surface |
host/ |
Web-GUI host half: API gateway + HTTP route server | Product — stable surface |
client/ |
Web-GUI browser half: shell, wire, object services, slots, ui-* plugins |
Product — stable surface |
experimental/ |
Prototypes and internal plugins | Unreleased |
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 |
New packages join existing groups; new groups update their 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.