Tianyi Cui
ab19fed77c
The first real LlmAdapter implementations, shipped as a deliberate pair:
same models and wire protocol, completely different internals, so the
StreamChunk protocol is verified across independent implementations.
- dsh-llm-deepseek: hand-rolled fetch + SSE parser + chunk-translation
state machine against the official chat-completions format (thinking
mode via top-level thinking/reasoning_effort; the empty-string
reasoning_content first chunk; usage attached to the finish chunk or
trailing; reasoning_content passback on tool-call turns; disjoint
cache-token accounting).
- dsh-llm-pi-ai: the same endpoint through @earendil-works/pi-ai,
mapping its event vocabulary (parsed tool arguments, in-stream error
events, folded reasoning tokens) onto the same chunks.
The agent loop now honors the in-band error path: an adapter that ends
its stream with finish {kind:error|aborted} (the only option for
adapters that can't throw mid-stream, like pi-ai) is translated into a
step error, so the turn ends error/aborted with a logged error event
instead of a normal completed assistant message. This makes the
StreamChunk error contract real for both adapters; docs/architecture.md
and the StreamChunk doc are updated accordingly.
New yarn test:e2e (vitest.e2e.config.ts, *.e2e.ts) runs key-gated
real-API matrices for both adapters across V4 Flash/Pro and all
thinking/effort levels; it self-skips without DEEPSEEK_API_KEY. Unit
suites run against local node:http mock SSE servers at 100% per-file
coverage.
1.7 KiB
1.7 KiB
AGENTS.md — Harness Packages
This directory contains all @deepseek-ai/dsh-* harness packages. When editing
code here, follow these conventions:
- Effect-based registrations: every contribution (tool, section, adapter,
agent, event listener) goes through
ctx.effect()/ctx.on(), andregister()methods return disposers. Never use bare arrays or manual cleanup. - Declaration merging: services declare their ctx key in
declare module 'cordis' { interface Context { } }and their events ininterface Events. Merge-extensible maps (ContentBlockMap,MessageSourceMap,FinishReasonMap,TurnTriggerMap,TurnEndReasonMap,SessionEventMap) are how plugins add new variants. - Waterfall semantics:
ctx.waterfalllisteners receive(...args, next); callnext()to delegate, or return without it to short-circuit (veto). Never callnext()after returning. - Tests: vitest in
packages/<name>/tests/*.spec.ts. Every registry needs an HMR-safety test (register a plugin, dispose its fiber, assert cleanup). Err on the side of more tests — edge cases, error paths, event ordering, races.
Naming notes:
- Files
src/index.tsexport the service default + all public types src/types.tscontain only types — no runtime code- Tests live at package level under
tests/, notsrc/__tests__/ - A package's README and module/JSDoc comments are part of the change: when you alter behavior (config keys, defaults, error codes, wire fields), update them in the same commit. CI has no doc-sync gate, so stale docs are on the author.
Read the per-package README.md for package-specific details: service API, events, extension points, TODOs.