DSH plugin conversation: targets, windows, and updates
"Content duplicated after replay" and "I only see half of it" are usually different update paths, not render bugs: replace rebuilds, prepend is incremental, and append touches only matched contexts. DSH plugin's conversation assembly spells out all three, and picking wrong yields two different results.
The window belongs to the Session Controller
The assembler consumes entries directly and opens no second history stream.(source)
The Session Controller owns the contiguous loaded logical event window. Each SessionEventLikeEntry is either { type: 'event', event } for a persistent event or { type: 'transient', event } for client-only assistant or live-chunk presentation; both inner events expose type, seq, time, and data.
ui-conversation hands these entries straight to the assembler without opening another history stream. Each Session has one ConversationNodeAssembler that applies every registered definition and publishes an independent source per registered view target.
Six concepts and their owner
Only the mechanism is shared; State and final payloads belong to each target.(source)
- Event Definition — a business package matches one persistent or transient event at a time, associates input by a stable
(kind, id), folds deterministic State, and optionally materializes a target node. - Context — the ordered matches and current State the engine owns for one
(kind, id); persistent and transient events can both serve as start; the earliest start initializes State and later matches update it; evidence with only updates stays pending until its start loads. - Location — a Session, Turn, or Step coordinate derived from persistent boundary events; definitions may publish typed data onto a Turn or Step.
- View Definition — a target package creates one incremental builder per Session and owns that target's final snapshot type.
- Group Definition — a business package derives root references and group snapshots from materialized nodes, owning membership, segmentation, summaries, and incremental caches.
- View — a slot entry such as Chat or Trajectory reads only its own target snapshot and renders target-owned nodes.
Chat and Trajectory may recognize the same persistent event family while keeping separate definition State and final node payloads. Shared target-neutral machinery covers only identity routing, ordered replay, Location data, predecessor dependency, and publication cadence.
Target activation: reading does not activate
The assembler receives only a resolved target id and never picks a default.(source)
Each Session keeps a monotonically growing active target set. Creating or reading a target source does not activate it. The shell explicitly activates a persisted or newly chosen View, while other consumers activate a target through the target source's first subscription.
First activation creates that target's builder and calls replace() once against the contexts currently indexed by target. Later flushes call apply() for each active target, and unsubscribing never removes a target.
The shell owns View selection and, on binding creation, being chosen as current, or a roster change, resolves the registered preferred View or the Chat fallback before rendering. The assembler takes only the resolved target id and never chooses Chat or any other default itself. Third-party Views use the same selection and activation operations.
Three window update paths
Only replace rebuilds; prepend and append are both incremental.(source)
History may be requested page by page from the tail backwards. The Session journal first validates non-overlapping logical seq ranges, and the assembler then sorts accepted inputs by each input's first seq before entering State replay.
| Path | Engine behavior |
|---|---|
replace (open, resync, gap repair) | Rebuilds the loaded window: each standard event or packed run matches once per definition, then every existing start's Context replays — start first, then updates in ascending logical seq; update-only pending contexts still have no State |
prepend of an earlier page | Matches only the newly added earlier input, merges it into contexts by (kind, id), keeps existing keyed nodes, and replays only affected contexts and dependencies |
append of one live event | Calls match once per definition, looks up the matched Context by key, updates only it, and scans no existing contexts |
| Failed incremental flush | Replays the full loaded window into fresh contexts, replaces each active view, then throws ConversationUpdateError with rebuilt: true; if rebuilding also fails it throws with false and retries on the next flush |
Write the complexity constraint into your definition: with D definitions registered, one new scalar event or packed run performs D matches over the current input only, and the subsequent Context key lookup is constant time. The normal append hot path must not walk the full event window, all contexts, context.matches, or the rendered node set. Put accumulated facts in State, same-Turn or same-Step information in Location data, and indexed prior dependencies in reader.previous().
Claiming deserves its own note: when a match result carries exclusive: true, that definition claims the event on its target. The assembler computes all matches for the event before accepting them one by one, so results are independent of registration order; claiming the same target twice, or claiming from a definition without a target, throws during dispatch.
Predecessor reads and re-runs
Predecessor dependencies are recorded and re-run when earlier information changes.(source)
Some definitions need the nearest State of another business kind before the current position. start receives a ConversationContextReader: call reader.previous<State>(kind) there rather than accepting context collections or scanning events. The reader returns read-only data from the nearest started Context before the current start seq.
The assembler records that dependency. If a later older prepend brings a nearer predecessor, fills a previously unknown window gap, or the predecessor State is revised, the engine re-runs the dependent Context from start and replays its updates in ascending seq.
The queried definition still owns writing useful information into its own State; the reader offers no business-specific query methods and grants no permission to modify other contexts.
Group definitions and publication cadence
A group combines references and data and never owns node content.(source)
The optional ctx.uiConversation.groups.register(definition) follows the same effect lifetime as event and view registration. It requires an existing view target, rejects duplicate target registrations, and constructs no builder. Each Session creates its own group contexts only when the target activates; a registration replacement discards old contexts and clears their observed groups.
A builder registering groups must provide groupInput(), and a missing input method fails on first activation. Before installing, the complete submission is validated: root group references match records one to one, referenced nodes all exist, each (NodeKey, groupPart) occupies at most one slot across root and member positions, a whole node cannot coexist with any part of itself, and duplicate upserts, duplicate deletes, or upserting and deleting one group together all throw.
Data-only upserts keep root and member arrays, read no nodes, and notify only changed groups' sources; full replacement revalidates every reference. Renderers switch on the two reference kinds, and the owning View selects components rather than a renderer field inside group data.
Publication cadence follows content change: immediate for structural or terminal changes, animation-frame for high-frequency visible deltas, and none when State only accumulates for later publication. The engine applies each scalar update in log order and applies a packed run as one batch update — an option that merges view publication frequency without changing replay results.
Verification: switch targets and replay
Prove that all three paths converge on the same result.(source)
- Run replace over a complete window and assert final State, Location data, node payloads, and
anchorSeq. - Supply only tail updates and assert the Context stays pending; after prepending its start, assert the result matches a full replace.
- Append live events after the initial history and assert the result matches the merged full window.
- Prepend an earlier page and assert only earlier rows are added while unchanged existing keyed node values are not replaced.
- Repeat a visible delta and assert
context.keyis unchanged with at most one publication per frame. - Make a definition throw during an incremental flush and assert every active target shows the full rebuild and later events keep updating it.
If step 2's pending Context renders partial results, you forced State before start loaded — the reference requires a terminal or checkpoint event to carry the complete fallback rather than scanning unrelated events.
For the full node matching and registration flow, see conversation nodes; for client layering, see web client architecture.
One line to close: the Controller owns the window, reading never activates, replace rebuilds while prepend and append are incremental, predecessors re-run, groups hold references only, and cadence changes frequency without changing results.
FAQ
No. DSH plugin states creating or reading a target source does not activate it. DSH plugin performs one full replace only on explicit View selection or the target source's first subscription.
No. DSH plugin matches only the newly added earlier input. DSH plugin keeps existing keyed nodes and replays only affected contexts and dependencies.
No. DSH plugin's reader returns read-only data. DSH plugin offers no business-specific query methods and grants no permission to modify other contexts.
DSH plugin replays the full loaded window and replaces each active view. DSH plugin throws ConversationUpdateError with rebuilt true, or false if rebuilding also fails and the next flush retries.
Related Terms
- SessionEventLikeEntry
- SessionEventLikeEntry is one entry of the loaded window, either a persistent event or a client-only transient assistant or live chunk.— DeepSeek Harness reference - Conversation assembly
- Context
- Context is the ordered matches and current State the engine owns for one (kind, id), initialized by the earliest start.— DeepSeek Harness reference - Conversation assembly
- Location
- Location is the Session, Turn, or Step coordinate the engine derives from persistent boundary events, optionally carrying typed data.— DeepSeek Harness reference - Conversation assembly
- ConversationContextReader
- ConversationContextReader supplies reader.previous(kind) during start, returning read-only data from the nearest started Context before it.— DeepSeek Harness reference - Conversation assembly
Sources
- DeepSeek Harness reference - Conversation assembly· deepseek-ai
- packages/client/ui-conversation/src/client/index.ts· deepseek-ai