Files
deepseek-harness/packages/session
Tianyi Cui e04cfc4c87 feat(session-format): migrate V2 prompts into V3 system surfaces
Stream an empty protected head after the first step and replace it before changed or cleared request headers, without moving source events. Remap only audited local sequence references, derive inherited cuts after upstream cardinality changes, and preserve generation-qualified captures and message identities.

Refuse pre-step surfaces and out-of-step prompt changes rather than invent lifecycle events. Reject unclassified migration payloads and detect deterministic generated-ID collisions in either source order. Native V3 accepts empty and in-history system messages, protects only the head, and reuses frozen relationships through a private nonescaping projection; historical repair IDs remain opaque.

Keep released codecs untouched and distinguish migration admission from native extension admission. V3 structural payload preflight cannot disappear behind recoverable row corruption. Validation: 35 focused tests, host TypeScript build, focused Oxlint, documentation quick gates and paired README recording. Parent owns installed-core/catalog/persistence integration and lockfile propagation.
2026-09-06 20:45:00 +08:00
..

description, kind
description kind
Package map for the durable session data plane: the persistence seam and its backends, checkpoint policy, projections, log-backed titles, and outbound session telemetry. package-group

session/ — durable session data plane

English | 中文

Summary

The session group makes an agent's conversation durable and reusable outside the live loop: the static format chain restores released generations, the persistence seam stores the event log and restores it on resume, the checkpoint policy keeps requests, tool side effects, and completed steps durable before the next action, projections serve whole log-derived values to client carriers, titles name each session from its content, and telemetry reports session activity outbound. Mount the shipped JSONL persistence provider first, then add the checkpoint policy and any projection, title, or telemetry packages the deployment needs. This page maps the group; every package README owns its contract, and session-query/ is a sibling group whose read/tool surface consumes persistence independently.

Table of Contents


Packages

The group splits into four families: durable storage (persistence seam, backends, checkpoint policy), projections, titles, and telemetry. Each package README owns its contract and configuration.

Persistence

Package Role ctx key
session-format/ Pure adjacent-format chain and artifact validation library library — no ctx key
session-format-v0-to-v1/ Frozen released-v0 decoder and identity migration into released v1 library — no ctx key
session-format-v1-to-v2/ Frozen released-v1 decoder and cardinality-changing Assistant-stream migration into released v2 library — no ctx key
session-format-catalog/ Generated static catalog of shipped adjacent migrations library — no ctx key
session-persistence/ Defines the durable session-storage service and the shared write coordination every backend composes ctx.sessionPersistence
session-persistence-jsonl/ Shipped backend: immutable canonical generation filenames per Session with exclusive successor publication, optionally Zstandard-compressed registers on ctx.sessionPersistence
session-checkpoint-policy/ Makes model requests, top-level tool side effects, and completed steps durable before the next action wraps ctx.llm and ctx.tools
session-log-deepseek/ Uploads the incremental canonical log as optional official DeepSeek request metadata contributes dsh_session_log

Projection

Package Role ctx key
session-projection/ Defines and drives projection units that fold committed events into whole current values ctx.sessionProjections
session-projection-cache/ Persists projection checkpoints so cold reads skip full log loads ctx.sessionProjectionCache
session-stats/ Serves whole-log conversation counts and wall times through the sessionStats unit registers on ctx.sessionProjections
session-turn-outline/ Serves the whole-log turn outline (turn, turn/start seq, prompt preview) through the turnOutline unit registers on ctx.sessionProjections

Titles

Package Role ctx key
session-title/ Log-backed session titles with a deterministic fallback and one optional provider ctx.sessionTitle
session-title-llm/ Shared model-backed title-generation policy for the provider packages library — no ctx key
session-title-first-prompt-llm/ Titles a session from its first eligible human message registers on ctx.sessionTitle
session-title-all-prompts-llm/ Titles a session from all eligible human messages registers on ctx.sessionTitle

Telemetry

Package Role ctx key
session-telemetry/ Captures session activity and hands records to a configured reporting backend ctx.sessionTelemetry
session-telemetry-otel/ Delivers telemetry through OpenTelemetry logs in FEEDBACK_ONLY or DISABLED mode registers on ctx.sessionTelemetry

Only one title provider may register at a time; without one, the title service keeps its deterministic fallback. The subsystem pages below are the backend-neutral references for each family.


Dev Note

None.