description	kind
Whole-log turn outline for clients and maintainers composing or debugging the turnOutline projection unit behind full-session turn navigation.	package-reference

@deepseek-ai/dsh-session-turn-outline

English | 中文

Summary

This package gives history clients a whole-session outline of every started turn, including bounded prompt and settled-response previews. Clients can navigate turns that are not yet loaded and page backward from the exact event sequence needed to load a selected turn. It fits assemblies that provide session projections; elsewhere, clients continue using loaded-window navigation. Previews exclude injected context and tool results, and a response appears only after its turn settles.

Use this package
Understand the implementation
Further Exploration
Model Experience
Known Limitations and Deferred Work
Dev Note

Use this package

Mount the plugin beside the session store and the projection registry when clients should navigate every turn of a session without holding its complete event log. The unit registers only when the registry is present.

Composition

- name: '@deepseek-ai/dsh-session'
- name: '@deepseek-ai/dsh-session-projection'
- name: '@deepseek-ai/dsh-session-turn-outline'

What an entry means

Field	Meaning
`turn`	Host-assigned turn number from the `turn/start` payload
`seq`	The turn's `turn/start` event seq — paging a window back through this seq loads the whole turn
`prompt`	Preview of the turn's first human prompt (space-joined text blocks, collapsed whitespace, 50-character cap with a trailing ellipsis when clipped — one rail-card line); `''` until an eligible prompt lands
`response`	Preview of the turn's final text-bearing assistant message (same normalization, 120-character cap — up to three rail-card lines); `''` until the turn ends with assistant text

The wire value is the complete entry array, strictly increasing by turn (whole-value rule): consumers replace, never merge. Prompts fill only from user/message events with the human user source, so injected context and tool results never leak into navigation; a turn whose prompt is images-only keeps '' and consumers label it by number. The response buffers as a draft while its turn streams and commits at turn/end; the change feed's raw-view identity gate keeps draft-only changes quiet, so the outline pushes at most three times per turn — boundary, prompt, settled response. Preview budgets match the chat rail's loaded-turn previews, so a turn shows the same words before and after its events load.

Failures and recovery

The unit is inert without the projection registry: inject keeps the fiber pending and nothing registers, so other assemblies lack the turnOutline key. Unmounting the plugin removes the key, because registrations are effects on the mounting fiber. Persisted-cache rows are schema-validated on restore — including the strictly-increasing turn order — so a corrupt row is discarded instead of seeding a broken fold.

Understand the implementation

Implementation internals — click to expand

This section explains the fold behind the outline; the observable behavior is fully covered in Use this package.

Design concept

The unit is a pure fold over committed session events. turn/start — not the prompt user/message — anchors each entry because its seq is the load-through target for a jump: the agent loop logs turn/start before the turn's prompt and steps, so a window paged back through that seq contains the whole turn. The prompt fills from the first human user/message, and only while the newest entry is still empty — later human messages in the same turn (steering) keep the first preview. The response cannot fill the same way (turn/end carries no text), so each text-bearing assistant/message overwrites a state draft and turn/end commits the survivor — the newest text, which is the loaded rail's findLast semantic.

Source map

File	Role
`src/index.ts`	Plugin entry: `inject`, unit registration on the mounting fiber
`src/projection.ts`	The fold: entry append, preview fill, wire view
`src/types.ts`	One home of the `turnOutline` projection-key declaration and entry types
—	No runtime invariant companion is published: the package owns one pure projection fold, `session-projection` schema-validates its served values, and re-folding the same log would duplicate the implementation instead of comparing independently maintained observations; session and agent-loop own turn-boundary ordering.

Fold rules

Uninteresting events return the same state reference, and draft-only changes keep the turns array's identity; the registry's two Object.is gates then hold the feed to at most three pushes per turn.
A turn/start that does not advance the turn number is skipped, keeping the outline sorted; a retried boundary's previews then land on the standing entry.
The wire view projects state.turns; the persisted-cache state schema wraps the wire schema with the draft field.

Further Exploration

Read these pages when the unit's contract is not enough. They move from the registry that drives units to adjacent session packages.

Session projection subsystem — the registry that drives units and serves snapshot and change-feed values.
Session projection registry package — the registry contract units register against.
Session package map — adjacent persistence, projection, title, and telemetry packages.

Model Experience

None, as the turnOutline unit folds already-logged turn boundaries into a client-facing read model and registers nothing model-facing.

KV Cache effect

None; the package never assembles or sends provider requests.

Known Limitations and Deferred Work

These limits define what the outline describes and when the unit is absent. They are current package constraints.

The wire value grows with the session — every push carries the complete outline (whole-value rule), up to ~600 bytes per turn at full CJK budgets and typically far less; splitting previews into an on-demand read is deferred until sessions with many thousands of turns need it.
The response previews only settled turns — it commits at turn/end, so an open turn (or one whose end never logged) shows a prompt-only preview until the boundary lands.
A turn without eligible text keeps '' — images-only and command-only turns are navigable but labeled by number, and a turn whose steps emit no text gets no response preview.
Mounted only where the projection registry is composed — other assemblies serve no turnOutline key, and their consumers fall back to loaded-window navigation.

Dev Note

Working context for maintainers — click to expand

None.

README.md