ChatGPTClaudeGrok / X / CursorGemini

DSH plugin deriveMessages: Surface, end reasons, and replay

Plugin DevelopmentPublished 2026-11-12Author: DeepSeek Plugin Market
DSH pluginDeepSeek HarnessderiveMessagesSurfaceTurnEndReason
Events look complete but message order is wrong. Covers which events produce messages, surfaceOp, deriveMessages rules, and TurnEndReason.

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)

  1. A Session is an append-only log of typed SessionEvents recording the full interaction history;
  2. Model history is derived from that log and never stored separately;
  3. 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:

ts
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)

  1. user/message — one user message carrying the exact content; an optional envelope stays as log-only display metadata.
  2. 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.
  3. 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.
  4. tool/result — one first-class tool-role message with result content and call identity.
  5. Injected user/message — non-user-source context becomes a user-role message in time order, content verbatim, with a typed source naming the producer.
  6. Everything else — turn/*, step/*, assistant/attempt, and plugin-owned llm/retry are 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)

ReasonMeaning
completedNormal completion
abortedA cancellation interrupted the live turn, carrying a TurnEndCancelCause
blockedBlocked
errorFailure; error is always a structured LlmFailure
max-tokensAt least one step reached the output ceiling
interruptedA crash-orphaned turn closed after the fact
forkedFork-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)

  1. Append turn/start, user/message, and step/start; assert exactly one user message.
  2. Append assistant/message with a stream and usage; assert one more message whose usage comes from the top level.
  3. Append an empty assistant/message; assert the message count is unchanged while the event count grows.
  4. Insert a log-only event between turn/end and the next turn/start; assert it produces no message and only consumes a seq.
  5. End a step at max-tokens and assert the whole turn ends max-tokens, not completed.
  6. 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.

ChatGPTClaudeGrok / X / CursorGemini

FAQ

Where is message history stored in DSH plugin?

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.

Why does DSH plugin log an empty assistant message?

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.

Can a DSH plugin turn end reason be inferred from one step?

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.

Does DSH plugin emit the interrupted reason live?

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