Skip to main content
Session Continuity (Phase 4) manages the lifecycle of long-running conversations by condensing the active working set (compaction) and creating restorable state snapshots (checkpoints). These operations prevent context window overflow and allow for non-destructive branching.

​
Two-Stage Compaction Pipeline

The compaction pipeline follows a Preview → Apply pattern. This ensures that the operator can review what information will be summarized or discarded before the session’s durable record is modified.

​
1. Compaction Preview

The system analyzes the session transcript to identify “review candidates”—specific items like tool outputs or assistant turns that are eligible for summarization.

​
2. Compaction Apply

Once reviewed, the compaction is committed to the database.

​
Compaction Flow Data Path

The following diagram illustrates the flow from the user command to the backend and back to the UI state machine. Title: Compaction Execution Flow Sources: apps/web/src/chat/chatPhase4Actions.ts#33-120, apps/web/src/chat/ChatConsolePanel.tsx#17-22, apps/web/src/chat/chatShared.tsx#145-151

​
Checkpoint Creation & Restore

Checkpoints are immutable snapshots of a session’s state, including its transcript, workspace documents, and compaction history.

​
Creation

Checkpoints are created via api.createSessionCheckpoint apps/web/src/console/sections/SessionsSection.tsx#142-146. They capture the branch_state and can be tagged for easier discovery apps/web/src/chat/chatConsoleUtils.ts#81-100.

​
Restore

Restoring a checkpoint is a branching operation. It does not overwrite the current session; instead, it creates a new session based on the checkpoint’s state.

​
Checkpoint and Compaction Entity Relationship

Title: Continuity Entity Mapping Sources: apps/web/src/chat/chatConsoleUtils.ts#50-100, apps/web/src/console/sections/SessionsSection.tsx#44-46, apps/web/src/chat/ChatInspectorColumn.tsx#3-15

​
The Detail Panel State Machine

The DetailPanelState is the central mechanism for inspecting Phase 4 artifacts without cluttering the main chat transcript.

​
Implementation

The state is managed in ChatConsolePanel.tsx apps/web/src/chat/ChatConsolePanel.tsx#113 and passed to the ChatInspectorColumn apps/web/src/chat/ChatInspectorColumn.tsx#93.

​
Key Transformation Functions

The chatConsoleUtils.ts file provides “builders” that map raw API records to the DetailPanelState interface:

​
Action Integration

The DetailPanelState includes an actions array apps/web/src/chat/ChatInspectorColumn.tsx#50-55. This allows the UI to render context-specific buttons (e.g., “Restore Checkpoint”, “Accept Candidates”) directly within the inspection view.
Source RecordBuilder FunctionKey Actions
ChatCompactionPreviewbuildCompactionPreviewDetailAccept All, Reject All
ChatCompactionArtifactRecordbuildDetailFromCompactionArtifactView Source Records
ChatCheckpointRecordbuildDetailFromCheckpointRecordRestore Checkpoint
ChatBackgroundTaskRecordbuildDetailFromBackgroundTaskPause, Resume, Retry, Cancel
Sources: apps/web/src/chat/chatConsoleUtils.ts#11-146, apps/web/src/chat/chatPhase4Actions.ts#64-113, apps/web/src/chat/ChatInspectorColumn.tsx#44-56

​
Token Delta Calculation

The system provides real-time feedback on context usage through the useChatContextBudget hook and Phase 4 status entries.
  • Baseline vs. Draft: The budget differentiates between baseline_tokens (persisted history) and draft_tokens (unsent text in composer) apps/web/src/chat/chatShared.tsx#54-65.
  • Compaction Savings: When a compaction preview is generated, the token_delta represents the difference between the current baseline and the projected summarized baseline apps/web/src/chat/chatPhase4Actions.ts#117.
  • Visual Indicators: The ContextBudgetSummary assigns a tone (“default”, “warning”, “danger”) based on thresholds like CONTEXT_BUDGET_SOFT_LIMIT (12,000 tokens) apps/web/src/chat/chatShared.tsx#22-23.
Sources: apps/web/src/chat/chatShared.tsx#54-65, apps/web/src/chat/chatPhase4Actions.ts#117, apps/web/src/chat/chatShared.test.ts#41-62