kandev/docs/specs/context-compaction-count/spec.md

status, created, owner

status	created	owner
approved	2026-08-02	kandev

Context Compaction Count

Why

Users can see how much of an agent session's context window is currently occupied, but they cannot tell how often the conversation has already been compacted. That history helps them understand when an old session has repeatedly shed context and when starting a fresh session may be preferable.

What

• The context-window hover shows a non-negative compaction count for the active agent session.
• Kandev infers an automatic compaction when a valid context-window sample reports fewer used tokens than the previous persisted sample for the same session.
• The first valid sample establishes a comparison baseline and does not increment the count.
• Equal or increasing usage does not increment the count.
• A successful explicit context reset or model change clears the usage comparison baseline without incrementing or erasing the session's lifetime count.
• The hover includes an info control explaining that Kandev derives the count from observed usage drops rather than an ACP compaction event, so missing samples and provider-side resets can make it approximate.
• The count and its explanatory control are available through the existing desktop hover and mobile tap-pinned context-window surface.

Data model

task_sessions.metadata owns both the current sample and the lifetime count:

• context_window: existing nullable object containing size, used, remaining, efficiency, and source; its used value is the comparison baseline.
• context_compaction_count: non-negative integer. Absence is equivalent to 0 for sessions created before this feature.

The count belongs to one task_sessions row. It is not shared across sessions for the same task and is not reset when context_window is cleared.

API surface

No new HTTP route or ACP extension is introduced. Existing session metadata and session.state_changed payloads expose context_compaction_count alongside context_window. Context-window frontend state represents the count as compactionCount for the active session hover.

Failure modes

• If a context-window update cannot be persisted, neither its baseline nor a derived increment becomes visible; Kandev logs the failure and a later valid sample compares against the last successfully persisted sample.
• ACP does not identify compaction events. A provider-side usage reset that appears as a decrease can be counted as a compaction, and compactions between missing usage samples can be missed. The UI disclosure states that the value is approximate.
• Invalid or unusable context-window reports remain hidden under the existing reliability rules and do not create user-visible count-only UI.

Persistence guarantees

• context_compaction_count survives backend restarts, agent execution recovery, page refreshes, and explicit context resets for as long as the owning task session exists.
• Restart recovery uses the persisted context_window.used value as the next comparison baseline when it is present.
• Legacy sessions without context_compaction_count begin at zero without a schema backfill.
• Deleting the owning task session deletes its count with the session metadata.

Scenarios

• GIVEN a session has no persisted context-window sample, WHEN its first valid sample arrives, THEN Kandev stores the sample and shows 0 compactions without incrementing the count.
• GIVEN a session's persisted usage is 120,000 tokens with zero compactions, WHEN a valid sample reports 80,000 used tokens, THEN Kandev persists and shows a count of 1.
• GIVEN a session already has a compaction count, WHEN equal or increasing usage samples arrive, THEN the count remains unchanged.
• GIVEN a session has a persisted baseline and count, WHEN the backend restarts and the next valid sample reports lower usage, THEN the persisted count increments exactly once.
• GIVEN the same decreased-usage update is delivered more than once, WHEN Kandev persists each delivery, THEN the count increments only for the first delivery because subsequent deliveries equal the persisted baseline.
• GIVEN a session has a non-zero count, WHEN the user successfully resets context or changes models, THEN the current context-window sample is cleared and the lifetime count remains unchanged.
• GIVEN a counted session has a reliable current context-window sample, WHEN the user opens its context hover with a pointer or touch, THEN the hover shows the count and an accessible explanation that Kandev infers it from usage drops and that it may be approximate.

Out of scope

• Adding a compaction event to ACP or agent adapters.
• Distinguishing an automatic compaction from every provider-side reset when both produce the same observed usage decrease.
• Counting explicit user context resets or model changes as compactions.
• Aggregating compactions across sessions, tasks, agents, or workspaces.
• Showing a count outside the existing context-window hover.