DSH plugin deriveMessages: Surface, end reasons, and replay
When the log has every event but the message list is short or out of order, suspect the derivation rules, not missing writes. DSH plugin stores only SessionEvent; the messages the model sees are a projection. Reading the projection as storage leads to endless doubt about the log.
The log is the source; messages are a projection
The append-only event log is the only source of truth; Message[] is one way to read it.(source)
- A
Sessionis an append-only log of typedSessionEvents recording the full interaction history; - Model history is derived from that log and never stored separately;
- Replay re-derives from the same events rather than reading another snapshot.
That changes your debugging order: inspect the event sequence first, and only then the derivation cache. A cache can amplify an error, but it cannot invent events.
Surface decides which events become messages
Only the SurfaceEventType subset produces messages; everything else is structural.(source)
The five members are system/message, developer/message, user/message, assistant/message, and tool/result.
Every message-producing event must declare a surfaceOp, which is how it joins the ordered derived surface:
type SurfaceOp = 'append' | { op: 'replace'; startSeq: SessionSeq; endSeq: SessionSeq }
append is the ordinary tail path. A replace carries exactly op, startSeq, and endSeq with no aliases or extra keys; it shadows the inclusive range between those two current surface event seqs and inserts the new event in place. Equal endpoints replace exactly one entry.
One counterintuitive constraint: endpoints must precede the replacing event, but their relative order follows surface order rather than numeric seq order. That is how compaction replacements shadow early nodes without relying on seq comparison.
Non-surface events are denied this metadata at compile time. Passing surfaceOp to a log-only event is a type-layer mistake, not a runtime one.
Six projection rules that explain duplicates
Match the six rules one by one before blaming the cache.(source)
user/message— one user message carrying the exactcontent; an optional envelope stays as log-only display metadata.assistant/message— one assistant message with its producing provider and model plus optional adapter replay state. The embedded compact stream is evidence, not a second message.- Empty
assistant/message— skipped. A max-tokens truncated step still records an event to keep stream, usage, provider, and model, but an empty turn never enters the provider transcript. tool/result— one first-class tool-role message with result content and call identity.- Injected
user/message— non-user-source context becomes a user-role message in time order, content verbatim, with a typedsourcenaming the producer. - Everything else —
turn/*,step/*,assistant/attempt, and plugin-ownedllm/retryare structural and project to no message.
Rules 2 and 3 explain a frequent surprise: an assistant/message exists in the log but not in the derived list. Check for empty content first, then for interrupted: true. A cancelled turn finalizes its delivered prefix as such an event and marks it interrupted; undispatched tool calls are absent.
Token accounting follows the same path: it expands the embedded stream per event, but a top-level usage on the committed message remains authoritative. That lets a failed attempt keep provider usage without fabricating a message.
Cached and frozen: why editing history fails to compile
Caching solves cost; freezing makes mutation unrepresentable.(source)
The cache rule is: each surface node projects once on first appearance, and a surface rewrite rebuilds. Ordinary appends project only new nodes, while a replace recomputes affected parts. If derivation suddenly slows down, check for plugins doing frequent replacements.
The freeze rule is: every call returns a new array of shared deep-frozen messages. Editing recorded history through the projection is not a runtime error; it is something the type system prevents you from writing.
deriveEventMessage(event) is the pure per-node function the fold applies. It is public so external rebuilders project log prefixes with exactly the same rules and never diverge from the cache. Build offline tooling on it instead of copying the rules.
Live reads have a third entry point: Session.surface returns a stable SessionSurface view with nodes, replaceGeneration, and contentGeneration. replaceGeneration counts positional replacements; contentGeneration also counts plugin-owned message changes.
TurnEndReason changes how you read a message
The same assistant message means different things under different end reasons.(source)
| Reason | Meaning |
|---|---|
completed | Normal completion |
aborted | A cancellation interrupted the live turn, carrying a TurnEndCancelCause |
blocked | Blocked |
error | Failure; error is always a structured LlmFailure |
max-tokens | At least one step reached the output ceiling |
interrupted | A crash-orphaned turn closed after the fact |
forked | Fork-seed construction closed a source turn still open at the boundary |
Three details matter. aborted may carry { kind: 'legacy' } when an imported coarse record did not preserve the caller; it does not mean nobody cancelled. Non-LLM errors are flattened to { message, code }, using TOOL_ACTIVATION_FAILED for failed tool conditions and UNKNOWN otherwise. And max-tokens is a whole-turn judgment that wins even if execution continues.
interrupted and forked are never emitted live: the former comes from crash recovery or cold reads, the latter only from fork seeds. Seeing either, look at recovery or fork paths instead of searching the loop.
Validation with a fixed event sequence
A fixed sequence beats random replay because every assertion maps to a rule.(source)
- Append
turn/start,user/message, andstep/start; assert exactly one user message. - Append
assistant/messagewith a stream and usage; assert one more message whose usage comes from the top level. - Append an empty
assistant/message; assert the message count is unchanged while the event count grows. - Insert a log-only event between
turn/endand the nextturn/start; assert it produces no message and only consumes a seq. - End a step at max-tokens and assert the whole turn ends
max-tokens, notcompleted. - Rebuild the same prefix node by node with
deriveEventMessage()and assert identical results.
If step 6 diverges, you probably reimplemented surfaceOp replacement yourself. Let foldSurface and deriveEventMessage() work together.
For the complete event vocabulary and persistence details, see session log and session query API.
One line to close: only surface events produce messages, deriveMessages() is a projection, empty and structural events stay out, and end reasons are read per turn.
FAQ
There is no separate table. DSH plugin derives model history from the session log: it persists typed SessionEvents, and deriveMessages plus deriveEventMessage project them into Message arrays.
Because it preserves stream, usage, and route evidence while staying out of the provider transcript. DSH plugin skips it during projection so empty turns cannot pollute model history.
No, DSH plugin decides per turn. If any step ends at max-tokens, the whole turn ends max-tokens rather than completed, even when a plugin continues afterward.
No. DSH plugin's loop never emits interrupted live; crash recovery appends it afterward, or session-query synthesizes it on cold reads, leaving pre-crash events intact.
Related Terms
- SurfaceEventType
- SurfaceEventType is the message-producing event subset: system/message, developer/message, user/message, assistant/message, and tool/result.— packages/core/session/src/types.ts
- surfaceOp
- surfaceOp declares how an event enters the ordered derived surface; it is append or a replace that shadows an inclusive seq range.— packages/core/session/src/types.ts
- deriveEventMessage
- deriveEventMessage is the pure per-node function used by the surface fold, exposed so external rebuilders project log prefixes with identical rules.— packages/core/session/src/types.ts
- TurnEndReasonMap
- TurnEndReasonMap is the merge-extensible end-reason union covering completed, aborted, blocked, error, max-tokens, interrupted, and forked.— packages/core/session/src/types.ts
Sources
- DeepSeek Harness reference - Sessions· deepseek-ai
- packages/core/session/src/types.ts· deepseek-ai