Skip to content
Merged
Show file tree
Hide file tree
Changes from 4 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion docs/design/live-journal-truncation-recovery.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,14 @@ The daemon keeps a bounded in-memory live journal for an unfinished turn. Consec

The marker previously had no prompt ownership, the SDK rendered a generic message, and WebUI either hid the marker behind history pagination or left the retained tail permanently visible. This design keeps the existing resource limits and eviction policy while making the loss precise and repairing the visible tail without another model request.

Web Shell renders the parent transcript in summary mode and discards nested subagent updates, but those updates previously still consumed the parent live-journal limits. A long-running subagent could therefore evict the visible root Agent status and leave the summary UI with only the truncation marker.

## Protocol and SDK

The compaction engine maintains independently bounded `full` and `summary` live journals. Both share the completed-turn compaction and event high-water mark. The full journal retains every update. The summary journal excludes `session_update` frames carrying a non-empty `_meta.parentToolCallId`, while retaining root updates and all non-session events. Two exceptions mirror the main-transcript projection. First, nested `agent_message_chunk` frames whose `_meta.usage` carries a numeric `inputTokens` or `outputTokens` are retained: the main transcript consumes exactly those frames for subagent token accounting, so dropping them would silently lose nested usage from the restored conversation's totals. Second, a frame whose `_meta.parentToolCallId` equals its own `toolCallId` is treated as root, matching the UI normalizer's self-reference guard (`normalizeToolUpdate` drops a self-parent), so both projections agree such a frame is a root tool block. The two journals share one pair of caps (entry count and byte size), so a single in-flight turn can retain up to twice the cap of journal heap; operators sizing daemon memory from `maxJournalBytes x live sessions` must double the journal term, including any adaptively grown cap.

`session/load` accepts optional `liveReplayMode: 'full' | 'summary'`. Omission means `full`, preserving SDK, `/acp`, and other daemon consumers. WebUI requests `summary` only when its existing `subagentTranscriptMode` is summary; Web Shell already selects that mode for the main transcript. Persisted transcript pagination remains complete and unchanged. Concurrent restores of the same session only coalesce on identical shapes; the single exception is that a `summary` request may share an in-flight `full` restore — the summary journal is a strict subset, and once the restore settles the daemon recomputes the waiter's replay fields for its own mode from the registered session, so the waiter never inherits the owner's unprojected full journal or its truncation marker. A `full` request never shares an in-flight `summary` restore (that projection would lack the nested detail the full client expects), so that direction stays fenced with `restore_in_progress`.

For a live-journal marker returned by `session/load`, the bridge copies the session's authoritative `activePromptId` to the marker envelope as optional `promptId`. The persisted event and event schema version do not change. An older daemon without this field is repairable only when the retained live events have exactly one prompt ID.

`DaemonHistoryTruncatedData` exposes the existing optional `scope` and `maxEvents` fields. Validation rejects malformed optional values. Normalized status data retains the complete daemon payload. The text distinguishes replay-history truncation from live-turn truncation, states that the newest events were retained and older replay events were discarded, and promises post-terminal recovery only when `fullTranscriptAvailable` is true.
Expand Down Expand Up @@ -37,7 +43,9 @@ The checkpoint inherits the current transcript store's effective `maxBlocks`, wh
- New clients accept old payloads and safely decline ambiguous automatic repair.
- Default `reloadSession` behavior remains configured replay; only the internal repair path requests memory replay.
- Daemon persistence, transcript APIs, journal limits, and oldest-first eviction are unchanged.
- Existing load callers and `/acp` continue to receive full live replay by default.
- Summary and full journals track truncation independently, so full-journal pressure does not create a summary marker.

## Verification

Unit coverage exercises marker ownership, post-terminal compaction, payload validation, precise status text, prompt matching, replay validation, atomic suffix replacement, duplicate-side-effect suppression, history preservation, failure fallback, and reload-source propagation. Daemon integration tests use a deterministic mock ACP agent and a three-event journal to observe the live marker from a second client, verify the complete compacted turn after terminal, and mount the real WebUI provider to prove that recovery adds one load and no model request.
Unit coverage exercises marker ownership, post-terminal compaction, independent full/summary limits, default-full compatibility, request validation and propagation, precise status text, prompt matching, replay validation, atomic suffix replacement, duplicate-side-effect suppression, history preservation, failure fallback, and reload-source propagation. Daemon integration tests use a deterministic mock ACP agent and a three-event journal to observe the live marker from a second client, verify the complete compacted turn after terminal, and mount the real WebUI provider to prove that recovery adds one load and no model request.
Loading
Loading