e58cc13de4
SessionPersistence.readRaw previously used undefined for two unrelated states: a supported backend could not find the requested session, or the backend had no per-session artifact concept at all. The export endpoint consequently reported an existing SQLite-backed session as HTTP 404, which falsely diagnosed storage capability as session absence. Make raw-artifact support an explicit backend capability. Unsupported backends now fail their inherited readRaw path loudly and the host answers 501 before reading, while undefined retains the single meaning of an absent artifact on a supporting backend. First-party backends, test providers, generated API catalogs, bilingual persistence docs, and export error contracts now state that distinction; focused tests cover both the 501 and the inherited rejection.
session/ — durable session data plane
English | 中文
The durable family around core/session's live in-memory service: the persistence seam with its storage backends and checkpoint policy, the projection seam that serves whole log-derived values, log-backed titles, and outbound session telemetry. All product packages. session-query/ remains a sibling group: the read/tool surface is consumed independently of persistence internals.
Persistence
Durable session persistence, semantic checkpoint policy, and the shipped storage backends.
| Package | Role | ctx key |
|---|---|---|
session-persistence/ |
Defines the persistence service and shared write coordination | ctx.sessionPersistence |
session-checkpoint-policy/ |
Applies semantic durability checkpoints | wraps ctx.llm and ctx.tools |
session-persistence-jsonl/ |
Persists sessions in JSONL files | registers on ctx.sessionPersistence |
session-persistence-sqlite/ |
Persists sessions in SQLite | registers on ctx.sessionPersistence |
The session-persistence decision records the persistence design.
Projection
Serves current, log-derived per-session state to client carriers.
| Package | Role | ctx key |
|---|---|---|
session-projection/ |
Defines and drives session projection units | ctx.sessionProjections |
session-projection-cache/ |
Persists and restores projection checkpoints | ctx.sessionProjectionCache |
Titles
Derives durable session titles from the session log, with an optional model-backed provider.
| Package | Role | ctx key |
|---|---|---|
session-title/ |
Owns title state, fallback behavior, provider registration, and refresh | ctx.sessionTitle |
session-title-llm/ |
Provides shared model-backed title generation | — |
session-title-first-message-llm/ |
Titles a session from its first eligible human message | registers on ctx.sessionTitle |
session-title-all-messages-llm/ |
Titles a session from all eligible human messages | registers on ctx.sessionTitle |
Deployments may register one model-backed provider; the service retains a deterministic fallback when none is present.
Telemetry
Projects session activity into outbound telemetry and delegates delivery to a configured reporting backend. The telemetry decision records the reporting boundary; the mode decision records immediate, feedback-gated, and disabled delivery.
| Package | Role |
|---|---|
session-telemetry/ |
Defines capture, redaction, projection, and live or on-demand backend delivery. |
session-telemetry-otel/ |
Delivers telemetry through OpenTelemetry logs in FULL, FEEDBACK_ONLY, or DISABLED mode. |
The subsystem references: persistence.md, session-projection.md, session-title.md, and telemetry.md. Only one title provider may register at a time; the demo spine mounts the fallback service and leaves both model providers out of default composition.