refactor(session): fold the session family into packages/session/
git mv the 12 packages from session-persistence/, session-projection/,
session-title/, and telemetry/ into one session/ group per the
regrouping RFC; merge the four group READMEs into one bilingual
triplet; rewrite the group segment in tsconfig references (intra-group
references shorten to ../<pkg>), tsconfig.base.json paths/globs,
knip.json keys, vitest include, gate scripts, and authored doc/note
citations; regenerate module graph, doc graphs, catalogs, and the
lockfile importer keys. No npm names change.
Full unit suite: 8779 passed; the 18 reported failures reproduce as
env flakes (ambient-proxy IPv6 tunneling, watched-dir inotify
timeouts under parallel load) — each passes in isolation with
NO_PROXY set, matching their known pre-existing behavior on master.
2026-07-30 01:52:06 +08:00
# session/ — durable session data plane
English | [中文 ](README.zh.md )
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/` ](session-persistence/README.md ) | Defines the persistence service and shared write coordination | `ctx.sessionPersistence` |
| [`session-checkpoint-policy/` ](session-checkpoint-policy/README.md ) | Applies semantic durability checkpoints | wraps `ctx.llm` and `ctx.tools` |
| [`session-persistence-jsonl/` ](session-persistence-jsonl/README.md ) | Persists sessions in JSONL files | registers on `ctx.sessionPersistence` |
2026-08-18 15:56:54 +08:00
| [`session-persistence-sqlite/` ](session-persistence-sqlite/README.md ) | Opt-in SQLite backend with packed physical chunk rows | registers on `ctx.sessionPersistence` |
refactor(session): fold the session family into packages/session/
git mv the 12 packages from session-persistence/, session-projection/,
session-title/, and telemetry/ into one session/ group per the
regrouping RFC; merge the four group READMEs into one bilingual
triplet; rewrite the group segment in tsconfig references (intra-group
references shorten to ../<pkg>), tsconfig.base.json paths/globs,
knip.json keys, vitest include, gate scripts, and authored doc/note
citations; regenerate module graph, doc graphs, catalogs, and the
lockfile importer keys. No npm names change.
Full unit suite: 8779 passed; the 18 reported failures reproduce as
env flakes (ambient-proxy IPv6 tunneling, watched-dir inotify
timeouts under parallel load) — each passes in isolation with
NO_PROXY set, matching their known pre-existing behavior on master.
2026-07-30 01:52:06 +08:00
The [session-persistence decision ](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md ) records the persistence design.
## Projection
Serves current, log-derived per-session state to client carriers.
| Package | Role | ctx key |
|---|---|---|
| [`session-projection/` ](session-projection/README.md ) | Defines and drives session projection units | `ctx.sessionProjections` |
| [`session-projection-cache/` ](session-projection-cache/README.md ) | Persists and restores projection checkpoints | `ctx.sessionProjectionCache` |
2026-08-12 20:26:47 +08:00
| [`session-stats/` ](session-stats/README.md ) | Serves whole-log conversation counts and wall times (`sessionStats` unit) | registers on `ctx.sessionProjections` |
refactor(session): fold the session family into packages/session/
git mv the 12 packages from session-persistence/, session-projection/,
session-title/, and telemetry/ into one session/ group per the
regrouping RFC; merge the four group READMEs into one bilingual
triplet; rewrite the group segment in tsconfig references (intra-group
references shorten to ../<pkg>), tsconfig.base.json paths/globs,
knip.json keys, vitest include, gate scripts, and authored doc/note
citations; regenerate module graph, doc graphs, catalogs, and the
lockfile importer keys. No npm names change.
Full unit suite: 8779 passed; the 18 reported failures reproduce as
env flakes (ambient-proxy IPv6 tunneling, watched-dir inotify
timeouts under parallel load) — each passes in isolation with
NO_PROXY set, matching their known pre-existing behavior on master.
2026-07-30 01:52:06 +08:00
## Titles
Derives durable session titles from the session log, with an optional model-backed provider.
| Package | Role | ctx key |
|---|---|---|
| [`session-title/` ](session-title/README.md ) | Owns title state, fallback behavior, provider registration, and refresh | `ctx.sessionTitle` |
| [`session-title-llm/` ](session-title-llm/README.md ) | Provides shared model-backed title generation | — |
2026-08-13 00:36:22 +08:00
| [`session-title-first-prompt-llm/` ](session-title-first-prompt-llm/README.md ) | Titles a session from its first eligible human message | registers on `ctx.sessionTitle` |
| [`session-title-all-prompts-llm/` ](session-title-all-prompts-llm/README.md ) | Titles a session from all eligible human messages | registers on `ctx.sessionTitle` |
refactor(session): fold the session family into packages/session/
git mv the 12 packages from session-persistence/, session-projection/,
session-title/, and telemetry/ into one session/ group per the
regrouping RFC; merge the four group READMEs into one bilingual
triplet; rewrite the group segment in tsconfig references (intra-group
references shorten to ../<pkg>), tsconfig.base.json paths/globs,
knip.json keys, vitest include, gate scripts, and authored doc/note
citations; regenerate module graph, doc graphs, catalogs, and the
lockfile importer keys. No npm names change.
Full unit suite: 8779 passed; the 18 reported failures reproduce as
env flakes (ambient-proxy IPv6 tunneling, watched-dir inotify
timeouts under parallel load) — each passes in isolation with
NO_PROXY set, matching their known pre-existing behavior on master.
2026-07-30 01:52:06 +08:00
Deployments may register one model-backed provider; the service retains a deterministic fallback when none is present.
2026-08-13 00:36:22 +08:00
## SessionTelemetryBackend
refactor(session): fold the session family into packages/session/
git mv the 12 packages from session-persistence/, session-projection/,
session-title/, and telemetry/ into one session/ group per the
regrouping RFC; merge the four group READMEs into one bilingual
triplet; rewrite the group segment in tsconfig references (intra-group
references shorten to ../<pkg>), tsconfig.base.json paths/globs,
knip.json keys, vitest include, gate scripts, and authored doc/note
citations; regenerate module graph, doc graphs, catalogs, and the
lockfile importer keys. No npm names change.
Full unit suite: 8779 passed; the 18 reported failures reproduce as
env flakes (ambient-proxy IPv6 tunneling, watched-dir inotify
timeouts under parallel load) — each passes in isolation with
NO_PROXY set, matching their known pre-existing behavior on master.
2026-07-30 01:52:06 +08:00
Projects session activity into outbound telemetry and delegates delivery to a configured reporting backend. The [telemetry decision ](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md ) records the reporting boundary; the [mode decision ](../../.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md ) records immediate, feedback-gated, and disabled delivery.
| Package | Role |
|---|---|
| [`session-telemetry/` ](session-telemetry/README.md ) | Defines capture, redaction, projection, and live or on-demand backend delivery. |
| [`session-telemetry-otel/` ](session-telemetry-otel/README.md ) | Delivers telemetry through OpenTelemetry logs in `FULL` , `FEEDBACK_ONLY` , or `DISABLED` mode. |
docs: anchor each subsystem page to its package group; make group READMEs thin tables
core.md read as a type grab-bag: LLM wire vocabulary up front, the agent/loop story buried, and no correspondence to packages/core. It now opens on the packages/core control spine — the package-by-package loop map with a Page column into session/system-prompt/tools/scope — and keeps only what the spine group declares plus the repo-wide patterns: the Agent handle with its delivery/cancellation/interception contracts, the SessionEvent envelope, branded ids, the …Map pattern. The conversation vocabulary (Message/ContentBlock, the model request, adapters — 17 type-equiv blocks) moves to llm-streaming.md, which now declares packages/llm end-to-end; the duplicate ContentBlockMap paste near its seam section folds into the moved section, and the manifest, LINK_MAP, README table rows, website label (Core data structures → Core), and inbound anchors follow.
Every packages/<group>/README pair is now a thin front door in one shape: a why-first intro (bash's seam-pattern-first paragraph rewritten as 'shell execution for the agent'), the package table, and a closing pointer to the owning docs/subsystems page — the bash-style table stays the load-bearing middle. Load-bearing trailing paragraphs relocate rather than vanish: the fs no-timeout rationale becomes a filesystem.md section (both languages), session's four sectioned tables merge into one 12-row table, examples' legacy-bin H2 collapses to a pointer at jsonrpc-demo's README, and design rationale that already lives in an Agent Note or subsystem page is now linked instead of restated. All 40 pair records re-recorded.
2026-08-02 05:54:15 +08:00
2026-08-13 00:36:22 +08:00
The subsystem references: [persistence.md ](../../docs/subsystems/persistence.md ), [session-projection.md ](../../docs/subsystems/session-projection.md ), [session-title.md ](../../docs/subsystems/session-title.md ), and [session-telemetry.md ](../../docs/subsystems/session-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.
