deepseek-harness/packages/AGENTS.md

# 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()`, and
  `register()` 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 in
  `interface Events`. Merge-extensible maps (`ContentBlockMap`,
  `MessageSourceMap`, `FinishReasonMap`, `TurnTriggerMap`, `TurnEndReasonMap`,
  `SessionEventMap`) are how plugins add new variants.
- **Waterfall semantics**: `ctx.waterfall` listeners receive `(...args, next)`;
  call `next()` to delegate, or return without it to short-circuit (veto). Never
  call `next()` 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.ts` export the service default + all public types
- `src/types.ts` contain only types — no runtime code
- Tests live at package level under `tests/`, not `src/__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.