Feature Request: Config toggle for session persistence timing

[hjasond]

Feature Request: Config toggle for session persistence timing

Problem

PR #1184 (shipped in v0.50.230) intentionally deferred the first session save() until /api/chat/start fires — i.e. until the first user message arrives and streaming begins. This solved #1171 (orphan "Untitled" JSON files accumulating under ~/.hermes/webui/sessions/).

However, the deferred-save behavior introduces a reliability/visibility gap that several follow-up issues (#1327, #1298, #1361) have only partially addressed:

• The session is in-memory only during the first turn.
• The user message sits in pending_user_message but has not yet been merged into s.messages or written to disk.
• If the user refreshes the page mid-stream, switches to another session, or the process crashes, the new session vanishes from the sidebar or loses the user's prompt entirely.
• For users who frequently context-switch between sessions (e.g. Cmd/Ctrl+K to spawn a new chat, pop a quick question, then switch back), the new conversation is invisible in the sidebar until the assistant finishes its first token — which, on slow providers, can take many seconds.

In short: the UX is optimized for disk hygiene, but at the cost of immediate session confidence.

Proposed Solution

Add a user-configurable toggle that lets operators choose the trade-off they prefer.

Option A — config.yaml setting

webui:
  session_save_mode: eager  # "eager" | "deferred" (default)

Mode	Behavior
deferred (default)	Current behavior: s.save() fires at first message/stream start (#1184).
eager	Legacy behavior: s.save() fires at new_session() time, and the user message is checkpointed to disk immediately on /api/chat/start before the agent thread is launched.

Option B — Per-session / per-profile UI toggle

A checkbox in Settings → Session Behavior (or the profile-level settings panel requested in #749):

✅ Persist new sessions immediately
Write session JSON to disk as soon as the conversation is created. Disable to avoid empty Untitled files.

Why this matters

• Multi-session workflows: Users juggling several concurrent conversations need the sidebar to be a trustworthy source of truth the instant they hit Send.
• Crash resilience: A server restart (or Docker container recycle) during a long first turn should not erase a carefully-typed user prompt.
• Backwards compatibility: Users who liked the pre-v0.50.230 behavior have no escape hatch other than staying on an old version.

Related issues

• New Conversation always creates empty session even when current session is empty #1171 — Original motivation for deferred save (orphan files).
• fix(models): defer first save() until session has real state (#1171 follow-up) #1184 — The PR that introduced deferred save.
• Active streaming session disappears from sidebar when user navigates away (regression from #1184) #1327 — Streaming session vanished from sidebar because Untitled + 0-messages filter hid it.
• Bug: Activity panel collapses during streaming and latest user message disappears after Stop #1298 — Stop/Cancel deleted the user message before it was merged to s.messages.
• bug(streaming): Stop/Cancel discards AI's already-streamed reasoning + tool output (and possibly user prompt) — paid tokens lost #1361 — Stop/Cancel discarded reasoning + user prompt.
• Fix/chat history WAL recovery #1353 — WAL recovery mitigates crash data loss but does not address the gap between "user hits Send" and "first assistant token lands".

Suggested implementation

1. Thread the toggle through api/config.py → api/models.py.
2. In new_session() (or api/routes.py:2806), branch:

   if config.webui_session_save_mode == "eager":
       s.save()  # pre-flight checkpoint

3. In /api/chat/start, eagerly checkpoint the user message turn to disk before launching run_conversation() when in eager mode, so the prompt is safe even if the LLM takes minutes.
4. Keep the all_sessions() / sidebar filter unchanged; the user message will bump message count to ≥1, so the new session renders immediately.

Environment

• hermes-webui version: v0.50.253
• hermes-agent version: v0.12

[nesquena-hermes]

Thanks for the careful write-up — and especially for tying it to the prior PR/issue chain. The trade-off is real and the proposed solution is the right shape.

A few notes:

On Option A vs Option B — start with Option A (config.yaml setting) only. The Settings panel is already crowded with toggles whose behavior most users never need to think about, and "when does my session get written to disk?" is squarely operator-level. If demand for the UI toggle materializes, we can promote it later — but the config knob is essential and the UI version is convenience.

Default: agree with deferred staying default. The orphan-Untitled problem (#1171) was a real source of cognitive load and rolling back the default would re-introduce it.

On suggested implementation step 3 — the eager checkpoint at /api/chat/start should write only the user message turn, not the empty session that triggered #1171. The threshold is "do we have ≥1 user message?", not "did new_session() get called?". Otherwise eager mode reintroduces empty Untitled files for sessions where the user opens a new chat, types nothing, and switches away.

So the sequence in eager mode is:

1. new_session() → in-memory only, no disk write
2. /api/chat/start with the user message → merge into s.messages, then s.save() before launching the agent thread
3. Streaming continues; periodic saves happen as today

That gets you crash-resilience for the user's prompt without recreating the orphan-file class.

WAL recovery (#1353) interaction: worth confirming that eager mode + WAL doesn't cause double-recovery. In eager mode the session is on disk, so WAL replay should be a no-op on conflict. In deferred mode WAL is the only safety net, which is exactly what was designed.

I'll add this to the ICEBOX for now — it's a small, well-scoped feature and a good first PR for a contributor who wants to wade into the session lifecycle code. If you (or anyone reading) want to take it, comment here.