deepseek-harness/packages/core/session

dsh-session

English | 中文

Event-sourced session log and in-memory store. A Session is the append-only source of truth for an agent's whole interaction history — the LLM message history is derived from it. A surface layer (an ordered projection of message-producing events) is maintained on top of the raw log for efficient derivation and compaction.

The optional @deepseek-ai/dsh-session/invariant companion registers this package's relational trace checks with ctx.invariants: monotonic sequence numbers, turn/step enclosure, and same-step tool call/result pairing. It replays existing sessions when loaded or reloaded; storage validation, snapshotting, freezing, provenance, and surface acceptance remain always-on responsibilities of the root session package.

Service: SessionStore (ctx key: sessions)

Creates and holds event-sourced Session instances. Persistence is intentionally not implemented here — plugins subscribe to session/event, flush on session/flush, and may mirror the paired session/created/session/disposed lifecycle.

Public API

• ctx.sessions.create(id?, { seed?, meta? }?) validates and detaches durable seed/header data, fills the version and id, defaults createdAt to now, publishes the session, and binds it to the calling fiber. Persisted reconstruction supplies its original createdAt, seedLength, origin, and delegationDepth.
• ctx.sessions.flush(session) dispatches the awaited parallel durability checkpoint through the session's captured scope. Every listener starts and the call waits for all to settle before reporting failure; it returns true when at least one listener participated and false for an empty snapshot, while unpublished, detached, and stale objects reject. A caller that requires durable storage rejects false at its own policy boundary.
• findLastMessageTurnEnd(events) pairs message-triggered starts with their ends and returns the latest matched turn/end. Outcome consumers use this fold instead of the raw latest log event because between-turn records and non-message turns have no prompt outcome.
• ctx.sessions.fork(source, boundary?, childSessionId?): Session — Resolve a live session object or id, select a seed through the inclusive boundary event seq (default: current last event), require that prefix to end outside an open turn, and create a live child session with lineage metadata.
• ctx.sessions.get(id: SessionId): Session | undefined
• ctx.sessions.list(): Session[]

Advanced: ordered-teardown lifecycle primitives

Use the split lifecycle only when teardown must be ordered with another resource:

• prepare(id?, options?) validates and constructs without publication.
• enter(session) performs the collision check, publishes without announcing, and returns an entry-bound idempotent detach. Concurrent same-id preparations are allowed, but only one entry succeeds; a stale detach cannot remove its replacement.
• announce(session) emits the single creation edge and rejects repeat or reentrant announcements. Detach during that dispatch is deferred and later emits the paired disposal edge; an unannounced entry emits neither lifecycle edge.

dsh-agent-loop uses this split so final loop flush precedes session detach; see the ownership Agent Note.

Live service events

The store pairs announced creation with disposal, publishes post-commit append notifications with per-listener containment, and provides an awaited durability checkpoint. Exact signatures and scope behavior live in the generated event catalog; payloads live in the persistence catalog.

Class: Session

Plain class (not a Cordis Service). Create live sessions through ctx.sessions.create() and detached replay or inspection sessions through Session.create(); the detached factory does not publish lifecycle events or bind the session to a fiber.

• session.append(type, data, opts?) snapshots and freezes durable data and surface metadata, validates marker shape, provenance, complete replacement coverage, and content-only single-result tool/result rewrites, commits synchronously, then notifies observers with independent failure containment. Reentrant attached-session appends reject, and runtime checks cover widened unions and loaded logs.
• session.deriveMessages() incrementally projects each new surface entry once and returns a fresh array over the complete identified, frozen messages stored by those entries. Assistant messages preserve provider/model provenance and adapter-private replay state in their model source. A surface rewrite rebuilds the projection; there is no raw-log fallback.
• session.deriveEventMessage(event) is the canonical per-event projection used by reconstruction and request checks.
• session.surface exposes the readonly SessionSurface view owned by the session's single incremental surface manager; replaceGeneration changes on every committed rewrite.
• session.events is a cached frozen snapshot invalidated by append; accepted events remain deeply frozen.
• session.seq, session.id — current sequence and readonly typed identity.
• session.header: SessionHeader — detached, deep-frozen creation metadata (version, id, createdAt, optional cwd/parentSession/seedLength/origin/delegationDepth). origin: 'subagent' is a coarse product classification, not a continuation capability. Construction validates the durable record and requires its id to match session.id.

Lossless JSON utilities

Durable values need one accepted representation, not a check followed by a second read. isJsonValue(value) is the boolean predicate; snapshotJsonValue(value) iteratively validates and copies a plain value in one pass, returning undefined for invalid input and propagating a throwing getter. The snapshot helper accepts finite JSON numbers except -0 (JSON rewrites it to 0), dense ordinary arrays, and plain or null-prototype objects; it rejects cycles, unsupported scalars, and exotic prototypes before normalization without imposing a call-stack depth limit.

Session-event import separates ownership from message validation. snapshotSessionEvent(event) clones a borrowed event before validating and freezing its identified message. adoptSessionEvent(event) performs the same message work in place and returns the original event; callers may use it only when they transfer an exclusively owned object graph with no mutable child shared with another event.

Chunk-row storage codec (chunk-rows.ts)

Providers stream token-sized deltas, so a raw log stores hundreds of assistant/chunk lines whose JSON envelopes dwarf their payloads. packChunkRuns(events) packs each run of ≥3 consecutive same-block delta chunks into one storage row — text-chunks, reasoning-chunks, or tool-call-chunks (bare slash-less tags: storage vocabulary, not SessionEventMap members) — and decodeStorageRecord(value) expands a parsed line back into its exact events (seq0/time0 + per-member dt gaps reconstruct every seq/time). The encoder whitelists exact shapes and stores anything unrecognized verbatim; the decoder validates row-tagged values and throws on malformation. Owned here so the JSONL backend and the fixture readers (dsh-llm-replay, dsh-acp-snapshot) share one codec; the backend's default-enabled packChunks config controls writes only.

Surface types

• SurfaceOp — how an event entered the ordered surface: 'append' (normal tail append) or { op: 'replace', start, end } (replace entries from start through end inclusive — both must be valid surface seqs; start === end replaces one entry). Used by compaction to shadow old events without deleting them.
• SurfaceIntent — { surfaceOp: SurfaceOp; sourceEventSeqs?: number[] }, the required third parameter to session.append() for surface-eligible types.
• SessionSurface — the readonly live nodes and replaceGeneration projection exposed by session.surface; candidate validation remains private to Session.
• foldSurface(events) — replay the canonical surface contract into detached current event sequences and actual replacement ranges. The same pass rejects non-contiguous seqs, misplaced or malformed metadata, empty or duplicate provenance, non-earlier sources, invalid positional ranges, replacements that fail to cite every shadowed surface entry, and a tool/result replacement that changes anything except one current result's content; SurfaceManager shares the atomic transition while retaining only its incremental sequence cache. Its optional baseSeq folds a contiguous loaded window with absolute event sequences and no synthetic prefix; replacements must remain inside that window.
• isSurfaceEvent(event) / isSurfaceEligibleType(type) — the first narrows a SessionEvent to a fully formed surface event; the second detects a surface-eligible event missing its marker when validating a seed or loaded log.
• isAppendSurfaceEvent(event) / isReplacementSurfaceEvent(event) — split a formed surface event by marker variant. Append-origin events are the durable source for a human transcript, which is not the model-visible surface: a landed replacement shadows the range it summarizes, so projecting a transcript from session.surface erases conversation the reader already saw. Consumers that must send exactly what the model sees keep reading session.surface.

Request-header reconstruction (request-header.ts)

request/header records a full canonical snapshot of the non-history request envelope with reason initial, resume, or change. Its optional adapterDefaults map marks effective reasoningEffort or maxTokens values materialized by exact-model resolution, allowing the next request proposal to distinguish them from explicit conversation settings. foldRequestHeader() selects the latest snapshot; legacy delta events and the removed fallback reason are rejected. See the reconstructable-requests Agent Note.

request/context records registration-bound metadata for the route a request resolved to, appended inside its step beside request/header and only when the provider, model, or capacity differs from the previous record. session.requestContext() folds the latest one incrementally, mirroring requestHeader(). Capacity stays OUT of EpochHeader on purpose: it is adapter metadata describing a route, not an input the request was built from, so it must not enter request reconstruction or header equality — a capacity change is not a header change. A route whose adapter advertises no capacity is still recorded with contextWindow absent, clearing any older known capacity.

A user/message stores the complete UserMessage directly, including the identity created before routing or prompt admission. It renders its content verbatim whether it is a direct human prompt, a synthetic injection, or an admitted goal round; its typed source is the only channel that tells them apart and carries any domain-specific durable facts. assistant/message, tool/result, and steering/message likewise store complete message values. Turn execution remains enclosed by turn/start and turn/end, while an idle injection may append and flush a user/message between turns without running the model.

tool/result persists one identified user-role tool-result message, optional internal failure identity, and optional presentation metadata. A tool's successful canonical value and human-readable canonical failure message remain execution-local; rendered error content is the replay-authoritative message.

Session event vocabulary (types.ts)

The append-only log's event types, enumerated member by member — payloads, surface badges, provenance — in the generated persistence log event catalog. Token accounting reads per-step assistant/chunk { type: 'usage' } records and treats assistant/message.usage as the committed-step fallback when no usage chunk exists; failed model-request attempts have no assistant message. Provider/model/replay provenance rides on assistant/message; an operational error's step is on turn/end.reason for kind: 'error', with structured provider facts for a final model-request failure.

Merge-extensible via SessionEventMap — a plugin declaration-merges its own types (the compaction seam's compact/*, bounded recovery's non-surface llm/retry, the hook bridges' hook/*); merged members appear in the same catalog. A plugin owns the relational invariant for its merged events, including whether a log-only event may appear between turns. A producer that requires durability appends through Session and then awaits ctx.sessions.flush(session) without fabricating an execution turn.

Also defines TurnTriggerMap and TurnEndReasonMap (merge-extensible sum types for typed turn boundaries — kind-tagged instead of strings). A final model-request error retains one structured LlmFailure; other turn errors retain message/code, and both identify the failed step.

An interrupted live turn ends with the coarse { kind: 'aborted' } outcome. Caller identity belongs to the Agent's runtime cancellation signal rather than the durable transcript; disposal remains the separate { kind: 'disposed' } terminal state.

Every SessionEvent carries two optional top-level fields (structural metadata):

• sourceEventSeqs?: number[] — seq numbers of provenance sources (e.g., the assistant/chunk seqs behind an assistant/message, or the shadowed entries behind a compaction replacement entry). On assistant/message, a present [] records a known empty provider stream, while omission means legacy or otherwise unrecorded provenance; other surface events require a non-empty list when this field is present.
• surfaceOp?: SurfaceOp — how this event entered the surface. Absent for non-surface events (boundaries, chunks, usage, errors).

Metadata types (types.ts)

• SessionHeader — session metadata written once when published as Session.header, where detachment and deep-freezing enforce immutability at runtime: { version, id, createdAt, cwd?, parentSession?, seedLength?, origin?, delegationDepth? }. Persistence loaders may return mutable detached copies of the same data type. Owned here (beside SessionId) because Session.header is typed by it; persistence backends re-export it rather than own it (which would force a package cycle).

Extension points

• Persistence plugins: subscribe to session/event (write-behind) and drain on session/flush (awaited) and fiber dispose. A durable backend reads the log and reloads it into a live session; the metadata seam (SessionHeader, session.header) is what such a backend stores beside the log.
• Replay/fork: create(id, { seed }) validates and freezes a contiguous current-format log and rebuilds its surface; request headers require provider/model, assistant messages require provider/model provenance, and a coarse aborted outcome must contain only { kind: 'aborted' } (legacy reason-bearing records are rejected). fork(source, boundary?, childSessionId?) selects a completed-turn prefix and records lineage.
• Compaction: dsh-compact-basic appends a user/message replacement for summary checkpoints, while dsh-compact-tool-result-prune appends a content-only tool/result replacement. Tool-pairing boundary policy and its cache belong to the dsh-compact seam, while this package owns ordered surface membership, replacement validation, and replaceGeneration.

Model Experience

Derived message history

What the model sees

The model receives the complete messages from user/message, assistant/message, tool/result, and steering/message surface entries verbatim. Their identities, roles, sources, and content blocks are the same values established at creation; projections do not mint identities. A prompt envelope changes only human presentation; its prefix context and request delimiter are already present in the event content. Tool calls live inside assistant messages. Chunks, boundaries, usage, hook records, todo records, and other log-only events add no message.

Token effect

Appended surface entries are resent on later steps. A replace surface operation removes the shadowed entries from future inputs without deleting their raw log records.

KV Cache effect

Appended surface entries preserve reusable prefixes. A replace operation invalidates reuse from the first shadowed message even though the underlying event log stays append-only.

Crash-repair result

What the model sees

If recovery finds an assistant tool request with no durable tool/call, its synthetic TOOL_NOT_STARTED result says The tool call was interrupted before the Harness recorded it as started. Retry it if it is still needed. If a durable tool/call has no result, its TOOL_OUTCOME_UNKNOWN result says The tool call was interrupted after it was recorded, but no result was durably recorded. Its outcome is unknown. Decide whether to retry from the tool semantics: retry only if the operation is read-only or idempotent; if it may have side effects, first verify external state or ask the user. Do not retry blindly.

Token effect

Zero tokens in an intact session. Each repaired call adds its retained risk-specific error text on resume.

KV Cache effect

Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.

Logged request header

What the model sees

The session reconstructs the system prompt, tool schemas, call config, and session prefix that the loop actually sent. Header events do not add a second copy to message history; the prefix is prepended outside deriveMessages().

Token effect

Zero duplicate tokens from logging. The reconstructed prefix, system text, and schemas still incur their normal per-request cost.

KV Cache effect

Logging causes no invalidation, and exact reconstruction preserves request-prefix identity. A later header with changed prefix, prompt, or schemas may invalidate reuse from its first difference.

Known Limitations and Deferred Work

• Session branching/tree (pi-style entry tree) — deferred unless needed beyond boundary-based fork().
• fork() cuts only at stable boundaries of live sessions — the selected prefix must end outside an open turn and the source must be in the store; forking a persisted-but-unloaded session is excluded from the fork API.
• SESSION_FORMAT_VERSION stays pinned at 0 — pre-release, no broad compatibility implied: Session accepts only current seed shapes and a backend rejects any other version. Narrow storage import upgrades belong to the persistence boundary (policy, pre-identity message recovery).
• TurnEndReasonMap omits the ACP-named refusal / max_turn_requests variants — producer-gated: they land when an adapter or the loop first emits them.