imccyu
eb1713f856
* fix(session-projection): keep released units in checkpoints Since the Cordis rc.11 teardown order unloads the Web layer before the base layer, Session Controller and harness-dev-context release their projection units before their live Sessions detach. The projection cache is still alive at that point and wrote a checkpoint holding only the units that were still registered, replacing the complete record. A blank Session then lost sessionListMetadata and listed as an untitled conversation after every graceful restart. A released unit now stays in the registry as a predecessor: it leaves event drives, snapshots, restores, and change notifications, while checkpoint() keeps each Session's last cell of it without advancing it. Registering the same key again replaces the predecessor and refolds the log. The projection cache keeps replacing whole records. * test(session-projection): assert frozen released units across unload tests Update the remaining unload tests that still expected a released unit to vanish from checkpoint(): user-approval, agent-loop inbox and scope lifecycle, time-context, and the agent registry now assert that the same Session keeps its pre-unload row, that a later event does not advance it, and that a Session created after the unload has no row. The token-meter and goal unload tests also append an event after the unload. Document that a retained handle read still advances a released cell that checkpoint() serves, and that restore() folds only live units, so its refreshed rows omit released units. * docs(session-projection): sync the ProjectionHandle type-equiv block * docs(session-projection): record frozen released units and their upgrade Add the upgrade guide for checkpoint() keeping a released unit's last row, update the registration-handles Agent Note with the frozen-cell decision and the retained predecessor, list both consequences under the registry README's known limitations, note in the projection cache README that a stored row can be frozen at its unit's release, and say that restoreFloor() ignores released predecessors. Update the agent-loop resource-lifecycle unload test, which read checkpoints through an alias, to the frozen-row semantics. * docs(upgrade-guide): mark the released-checkpoint snippet ignore-check * docs(session-projection): state the retained-handle path and narrow a rejected alternative * docs(upgrade-guide): re-record the released-checkpoint guide pairing
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.
Related documentation
- Session persistence subsystem — backend-neutral service semantics, the flush checkpoint, and crash recovery.
- Working directory subsystem — effective directory and recovery.
- Session projections subsystem — the projection unit contract and drive semantics.
- Session titles subsystem — title eligibility, fallback, and provider flow.
- Session telemetry subsystem — capture, redaction, and delivery modes.
- Session subsystem — the live event log every package in this group persists or derives from.
See session-title-all-prompts-llm for the experimental optional capability.
Dev Note
None.