Files
deepseek-harness/packages/session
Yichen Jiang 691ebd7b6c refactor(worktrees): move archive cleanup into the worktree service
The worktree service now records each checkout it creates as a
`plugin:worktree/created` record, folds them in its own `worktree`
projection with fork-aware ownership, and reclaims a clean, unreferenced
checkout when the Session that created it is archived. The Forge panel
reads the service's record and forwards its cleanup state; it no longer
writes a `created` record, owns a retention projection, or gates every
Session's directory access.

Admission registers the attempt inside the Workspace write queue and
returns; inspection runs afterwards, reading cold Sessions through the
projection cache when mounted and from their log otherwise, with subagent
children of an archived ancestor counted as archived. Only a path being
removed holds `working-directory/access`, whose request now carries the
access's `signal`, and listeners withdraw before the drain. Ignored files
no longer retain a checkout, matching Git's non-force removal; processes
and terminals are not consulted.

The Forge bundle mounts one `worktree` service: the `forge-worktree` row
and the `optional-forge-panel` group that isolated a second service are
gone, and `forge-panel` is a top-level row. `canRemove`, `remove`, the
`forgeWorktreeRetention` projection, and `ForgeWorktreeCleanup` are
removed; `WorktreeService.cleanupOf`, `WorktreeCleanup`, and the
`worktree/cleanup` Host event replace them. The upgrade guide moves to
the current version directory and covers the id removals.
2026-11-05 12:28:50 +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 keeps conversations durable, restores released log formats, and makes committed history available after restart. Its storage and checkpoint packages protect requests, tool side effects, and completed steps; projection packages derive client-ready values; title packages name sessions; telemetry packages report activity. Start with the shipped JSONL storage, then add checkpointing and only the projections, title policy, or telemetry your deployment needs. Each package README owns its guarantees and configuration, while a sibling query group provides independent read and tool access.

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
message-quotes/ Quotation controls and Markdown blockquote rendering —
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-v2-to-v3/ Frozen V2 decoder and system-prompt, envelope, and PTC migration into V3 library — no ctx key
session-format-v3-to-v4/ V3 identity migration and V4 codec with generation-aware delivery validation 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
working-directory/ Owns each Session's effective execution directory and user-context changes ctx.workingDirectory
tool-working-directory/ Reads or changes the active directory through one tool working_directory
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 bounded execution for provider-owned title strategies library — no ctx key
session-title-first-prompt-llm/ Titles a session from its first eligible human message 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.


See session-title-all-prompts-llm for the experimental optional capability.

Dev Note

None.