Tianyi Cui
1103b0277b
A successful verifier message was treated as terminal even though the Worker Thread was still alive. The parent immediately terminated the worker and detached cancellation, so an error, nonzero exit, or caller cancellation after that message could be ignored and verification could resolve successfully. Keep the first successful response pending until an observed natural exit with code 0. A missing response or nonzero exit rejects after the worker has already exited. Error and abort callbacks retain the existing terminate-and-join path, including its first-error and AggregateError behavior. The scheduler stays unchanged: its permit remains held until the verification promise settles, now after successful worker quiescence. The worker already closes its parent port in finally, so success needs neither a forced stop nor another protocol message. Replace success-termination expectations with deterministic message/exit barriers and cover post-response errors, nonzero exit, cancellation, and permit handoff. Remove the obsolete hand-written termination thenable and its retired unknown-assertion baseline entry. Add real source workers for plain and Zstandard input, and require the built plain-Node migration smoke to complete with zero termination calls. Document the settlement condition. Native Windows CI recorded process access violation 0xC0000005 while a migration fixture was active. Removing unnecessary successful-worker termination is consistent with that evidence, but this commit does not claim that the native faulting module or mechanism has been established. The deterministic regressions prove the lifecycle defect independently; the next native CI run must assess whether the observed crash recurs. Validation: - Original source failed all new message-to-exit regression scenarios; the updated focused lifecycle file passes 19 tests with 100% coverage. - Node 24 owning package: 19 files, 741 passed, 1 skipped; every included package source file reaches 100% statements/branches/functions/lines. - Real source workers passed for none/zstd; built plain-Node smoke passed with zero terminate calls and no timeout or process signal. - Exact Node 22.19 source-mode none/zstd workers naturally exited 0 with zero terminate calls, exercising the async Module.register fallback. - Host TypeScript build, focused lint, no-new-unknown-assertion gate, README translation pairing, and all 42 doc-sync gates passed. Related to #4387 and #4394.
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 |
|---|---|---|
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 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.
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.
Dev Note
None.