diff --git a/.agents/skills/dsh-session-projection/SKILL.md b/.agents/skills/dsh-session-projection/SKILL.md new file mode 100644 index 0000000000..a28c66005d --- /dev/null +++ b/.agents/skills/dsh-session-projection/SKILL.md @@ -0,0 +1,17 @@ +--- +name: dsh-session-projection +description: Use when creating, extending, or reviewing a DeepSeek Harness session projection, or migrating a fold helper to one. +--- + +# DeepSeek Harness Session Projections + +Follow the [projection API](../../../packages/session/session-projection/README.md) for registration and lifecycle details. + +1. Decide whether to extend an existing projection or create one; check whether an existing owner already maintains the needed state. +2. Keep projection definitions and handles private to the owning service's implementation. Expose domain methods to consumers, not projection definitions. +3. A service that stores its data in projections should normally require `sessionProjections` in its Cordis dependencies. +4. Evaluate retained state size as the session grows. Do not accumulate state proportional to session length, including collections of event sequence numbers. Growth is acceptable only when slow enough to remain negligible. When the data would keep growing, consider incremental loading instead of retaining the complete state. +5. `apply` is synchronous and cannot read arbitrary historical events asynchronously. When later reads need event payloads, consider storing sequence numbers and letting state consumers resolve them asynchronously. +6. When migrating from `foldXXX`, remove the superseded fold helper. +7. Do not add calls to deprecated readers such as `snapshotEvents` or `eventAt`. Assume the full event log is not resident in memory and random reads may require asynchronous disk access. +8. Consider performance, but do not complicate the design without a concrete need. diff --git a/AGENTS.md b/AGENTS.md index 5ee465f84d..cc01553104 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -135,6 +135,7 @@ Real-API tests/demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`, and - **Switch on discriminant tags.** Closed unions end in `assertNever`; merge-extensible unions fall through a documented default. - **Waterfall listeners MUST call `next()`** to delegate; returning without it short-circuits the chain ([semantics](docs/cordis-primer.md#cordis-waterfall-semantics)). - **Model-visible ⟺ logged**: anything that reaches a model request must be reconstructable from the session log; a new model-visible input requires a session event. +- **Session projections:** follow [dsh-session-projection](.agents/skills/dsh-session-projection/SKILL.md) when creating, extending, reviewing, or migrating one. - **Plugins, not loop changes**: new behavior goes on documented extension points; changing `agent-loop` requires updating docs/architecture.md. - **A capability seam comprises Service Definition / Service Provider / Consumer roles.** It is complete, never one role; split only when roles evolve independently ([glossary](docs/glossary.md#capability-seam)). - **Prefer maintained dependencies over hand-rolling** when they genuinely delete owned code and tests ([policy](.agents/notes/implemented/process/2026-07-26-dependencies-over-hand-rolling.md)).