From df2edee86eec2a8deb0ad57b5d20552199c12b65 Mon Sep 17 00:00:00 2001 From: T Date: Mon, 25 May 2026 13:24:02 -0700 Subject: phase 1 done --- docs/phase-4.md | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) (limited to 'docs/phase-4.md') diff --git a/docs/phase-4.md b/docs/phase-4.md index af68cca..6c4f9b9 100644 --- a/docs/phase-4.md +++ b/docs/phase-4.md @@ -32,7 +32,31 @@ A session persistence system where pantograph saves and resumes conversations. A - Custom entry types (for extensions — future phase) - Labels, bookmarks, session naming - Session export or format migration beyond version 1 -- In-memory-only sessions (every session is persisted) +- In-memory-only sessions from the CLI (every CLI session is persisted; libpanto embedders can opt out by passing a no-op store) + +--- + +## Library / CLI Boundary + +The storage interface lives in libpanto. The default `fs_jsonl` implementation also lives in libpanto. The CLI decides _where_ a session is stored and constructs the store with that path. + +### libpanto owns + +- The `SessionStore` interface (vtable: append entry, load entries, etc.). +- An `fs_jsonl` implementation that takes a base directory at construction time and writes the JSONL format defined below. +- The agent loop's interaction with the store: which events get appended, at what points in a turn. + +### CLI owns + +- Selecting the base directory: XDG resolution (`$XDG_DATA_HOME` or `~/.local/share`), the `panto/sessions/` subpath, and the per-project `/` grouping. +- Selecting the session file: new-file-per-invocation by default; `--resume` / `--resume ` to pick an existing file. +- Constructing `fs_jsonl` with the resolved directory and passing it to libpanto. + +Other embedders (a TUI, a daemon, a Lua host, a test harness) bring their own directory policy or their own `SessionStore` implementation. A no-op store is a valid choice for embedders that don't want persistence. + +### Mid-turn writes + +The in-memory `Conversation` is the source of truth during a turn. The store is written between discrete events — never as an inline dependency of streaming. A crash mid-turn loses the in-flight assistant message but never corrupts prior state. (Phase 4 writes per-message; finer-grained streaming-event entries are out of scope.) --- -- cgit v1.3