When Conversation Becomes State: Replay, Persistence, and Compaction

DeepSeek Harness treats conversation as state only after it has an explicit record of what the model could see. This chapter follows that record from an append-only Session log through durable storage, restart repair, projections, token measurement, and compaction. The aim is to distinguish four things that are easy to confuse: raw history versus the current model surface, physical storage repair versus semantic recovery, a cache of derived state versus the authoritative log, and reduced context versus exact token accounting.

An agent that only streams text can appear complete while leaving little that another process can reconstruct. An agent that writes every internal callback into the transcript can make the model history noisy and difficult to control. DeepSeek Harness chooses a middle path: durable events are the source of truth, model messages are a derived surface, live frames are transient, and specialized consumers derive their own views without replacing the log.

The Session log is more than a transcript

A Session is an append-only sequence of typed events. It includes user messages, assistant settlements, tool calls and results, system-prompt changes, request metadata, turn and step boundaries, and events contributed by optional capabilities. Each accepted event receives a sequence position and a frozen, lossless-JSON payload. Once committed, the event is not rewritten.

The log is more than a transcript because it records both surface facts and structural facts. A user message or tool result can become part of the model’s next request. A turn boundary explains whether work completed, was cancelled, failed, or was interrupted. A request header records the non-history envelope and visible tool schemas needed to reconstruct a later call. An assistant attempt can preserve a failed or cancelled provider stream without inventing an assistant message that the model should treat as successful conversation.

The project’s key invariant is simple to state: model-visible means logged. If content reaches a provider request, the system must be able to reconstruct it from the Session log. This is why the rendered system prompt is represented as a system-message surface event rather than hidden in an in-memory request object. It is also why assistant settlements carry a compact timed representation of the provider stream. The log retains enough information to explain both the visible message and the attempt that produced it.

deriveMessages() projects the model history from the current ordered surface. System messages, user messages, assistant messages, and tool results produce the message sequence. Turn boundaries, retry records, assistant attempts without a surface message, and other structural events remain in the log but do not become messages. A live assistant-stream frame may already have appeared in a browser, yet it contributes to future model history only when the relevant durable settlement is recorded.

This separation protects the meaning of replay. Replaying a Session does not rerun every observer, UI animation, or transient chunk. It walks the committed surface events and reconstructs the history that a new request should see. Other consumers can inspect the full log for audit or diagnostics without forcing all those facts into the model context.

Append-only history and the current surface are different

Ordinary conversation grows by appending surface events. A new user message follows earlier messages; a successful assistant message follows the request that produced it; a tool result follows its recorded call. This preserves the earlier prefix and makes the model’s next context easy to derive.

Some operations need to change what the model sees without deleting the evidence of what happened. DeepSeek Harness represents that operation as a surface replacement. A replacement records the surface range it shadows and, when its event type requires it, cites the earlier nodes it replaces before occupying their position in the current ordered surface. The original events remain in the raw log. The replacement can be a compacted summary, a shortened tool result, or another producer-defined surface update.

This distinction gives the Session two useful properties at once.