mirror of
https://github.com/deepseek-ai/deepseek-harness
synced 2026-08-15 21:04:50 +00:00
bfb034830f
vitest coverage (v8 provider) with per-file 100% thresholds for statements, branches, functions, and lines. Scope: our runtime source only — types-only files, vendor/ (upstream code), and examples/ (exercised by the demo smoke test) are excluded. yarn test:coverage runs the gate. 59 tests added to close every gap: llm generate-waterfall and adapter disposal; assembler edge protocol (duplicate block-start, stragglers after block-end, id fallback, usage omission, invariant violation); the whole Inbox surface incl. the wakeup-overwrite race; LoopAgent disposed-state throws and double-stop idempotence; config-driven agent creation; loop backstop catches (throwing turn-start/turn-end listeners, non-Error throws, non-JSON tool arguments); system-prompt dynamic sections and disposer paths; tools errorMessage fallbacks and the full schema-DSL emission matrix. Genuinely unreachable defensive guards carry /* v8 ignore */ comments with stated reasons rather than deletion (132 tests total).
Packages
Harness packages, all under the @deepseek-ai/dsh-* scope. Each package is a
Cordis service (microkernel plugin-style): it exports a default Service class
that gets registered via ctx.plugin(), declares its ctx key and events through
declaration merging, and exposes extension points through ctx.effect(),
ctx.on(), and ctx.waterfall().
Dependency graph
dsh-llm (no harness deps — pure vocabulary)
dsh-session ← dsh-llm
dsh-system-prompt ← dsh-llm
dsh-agent ← dsh-llm, dsh-session
dsh-tools ← dsh-llm, dsh-system-prompt, dsh-agent
dsh-agent-loop ← dsh-llm, dsh-session, dsh-system-prompt, dsh-tools, dsh-agent
The rule: 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.
What goes where
| Package | Role | ctx key |
|---|---|---|
llm/ |
Abstract LLM service + content-block vocabulary + chunk assembler | ctx.llm |
session/ |
Event-sourced session log + in-memory store | ctx.sessions |
system-prompt/ |
Prompt-section + tool-schema assembly registry | ctx.systemPrompt |
tools/ |
Tool registry + tools/execute waterfall |
ctx.tools |
agent/ |
Agent interface, registry, agent/* event vocabulary |
ctx.agents |
agent-loop/ |
THE concrete plugin: LoopAgent + the loop driver |
ctx.agentLoop |
Each package has its own README.md with purpose, service API, events,
extension points, and deliberate non-goals (TODOs).
Conventions (applied across all harness packages)
- Registrations are effects: every contribution (adapter, tool, section,
agent, event listener) goes through
ctx.effect()/ctx.on(), so disposal and HMR clean up automatically. Everyregister()returns the disposer. - Declaration merging for events and ctx: services declare their events in
declare module 'cordis' { interface Events { ... } }and their ctx key ininterface Context. - Waterfall semantics:
ctx.waterfalllisteners receive(...args, next)and MUST callnext()to delegate; returning without it short-circuits (the veto mechanism). - Extensible unions:
ContentBlockMap,MessageSourceMap,FinishReasonMap,TurnTriggerMap,TurnEndReasonMap, andSessionEventMapuse the merge-extensible-map pattern so plugins can add variants via declaration merging. - ESM everywhere; imports use package names across package boundaries,
.tsextensions within a package. - Tests: vitest, colocated under
packages/<name>/tests/*.spec.ts. Every registry needs an HMR-safety test. Err on the side of more tests.