feat(context): use provider usage for compaction

[omarluq]

Summary

• use successful provider usage to improve context estimates
• ignore stale usage after compaction boundaries
• add split-turn compaction summary handling

Validation

• go test ./internal/assistant
• mise exec -- task ci

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 94ccfdd6-7789-4e0b-bb30-450f98811cde

📥 Commits

Reviewing files that changed from the base of the PR and between c8b98a4 and d80444e.

📒 Files selected for processing (1)

• internal/database/session_store.go

🚧 Files skipped from review as they are similar to previous changes (1)

• internal/database/session_store.go

---

📝 Walkthrough

Summary by CodeRabbit

• New Features

  • Messages now persistently store token-usage metadata from the model provider.
  • Context compaction includes split-turn summaries to preserve earlier turn context when partially compacted.

• Improvements

  • Provider-anchored usage data is threaded into context construction to improve usage estimation across compaction boundaries.
  • Token accounting refined to better estimate input and trailing tokens when anchors are available.

• Tests

  • Added unit and integration tests validating usage anchoring, estimation, compaction behavior, and related error handling.

Walkthrough

The pull request threads provider-reported token usage anchors through context building and usage estimation, adds split-turn summaries for compaction when a boundary splits an in-progress turn, and refactors session-store append logic to persist per-entry token-usage metadata and track/clear anchored usage during context replay.

Changes

Token usage anchoring and split-turn context compaction

Layer / File(s)	Summary
Token usage data model and persistence internal/database/entity.go, internal/database/session_store.go, internal/database/session_usage_test.go, internal/database/session_usage_internal_test.go	EntryDataEntity gains an optional Usage field; new EntryTokenUsageEntity and ContextUsageAnchorEntity types persist per-entry and anchored usage metadata; SessionContextEntity includes optional UsageAnchor; repo append pipeline is refactored to support usage metadata and to set/clear UsageAnchor during context construction and compaction; tests validate anchor tracking and compaction clearing.
Usage-led token estimation helpers internal/assistant/context_usage_led.go, internal/assistant/context_usage_led_internal_test.go	Adds estimateUsageLedInputTokens that uses a provider ContextUsageAnchorEntity when present (anchor input tokens + trailing estimate) or falls back to full estimation; adds estimateTrailingInputTokens and providerUsageEntity mapping; unit tests cover anchor usage, fallback, and mapping behavior.
Context entity loading and usage anchor remapping internal/assistant/runtime_context.go	Replaces prior message-only loader with Runtime.modelContextEntity(...) returning SessionContextEntity; adds remapUsageAnchor to validate/remap anchored indexes into the filtered model-facing message sequence.
Context build pipeline usage anchor integration internal/assistant/context_build.go	contextBuildResult and modelContextBase gain UsageAnchor fields; Runtime.ContextUsage and Runtime.buildModelContext load full context entities and remap anchors; estimateContextBuildUsage accepts usageAnchor and delegates input-token calculation to estimateUsageLedInputTokens; anchors and computed Usage are propagated through initial/recalculation flows.
Compaction with split-turn summary feature internal/assistant/context_compaction.go, internal/assistant/context_compaction_internal_test.go	compactionPlan gains SplitTurnSummary; planCompaction uses compactionSummaryPayload to compute messages and optional split-turn summary when a cut splits a turn; formatSplitTurnSummary, compactionSystemPromptWithSplit, and splitTurnPromptSection produce prompt-ready split context in <split_turn_summary> tags; tests assert split-turn plan contents and prompt inclusion.
Session store entry appending and metadata support internal/database/session_store.go	Entry construction separated from metadata application; new exported AppendMessageWithMetadata(ctx, sessionID, parentID, message, modelFacing, usage) persists optional token-usage metadata; AppendMessageWithModelFacing delegates to it; context-building calls updateContextUsageAnchor for assistant messages with usage and clears anchors during compaction replay.
Runtime entry appending via metadata API internal/assistant/runtime_entries.go	appendAssistantResponseEntry now calls AppendMessageWithMetadata, passing providerUsageEntity(bundle.Usage) to persist provider-reported usage alongside the assistant message.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• omarluq/librecode#59: Related edits to context_build.go's usage estimation and model.TokenUsage content.
• omarluq/librecode#44: Changes overlapping context build token-usage plumbing and usage breakdown handling.
• omarluq/librecode#31: Modifies assistant context-building wiring and token-usage propagation.

Poem

🐰 I threaded anchors through the hay,

tokens counted where they lay,
split-turns tucked in a neat little line,
compaction sings, usage aligns,
hop, the context stays in time.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat(context): use provider usage for compaction' directly aligns with the main changes: incorporating provider usage data into context compaction and estimation logic.
Description check	✅ Passed	The description accurately summarizes the three core objectives of the changeset: using provider usage for estimates, ignoring stale usage after compaction, and adding split-turn summary handling.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/usage-led-compaction

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

❌ Patch coverage is 84.74576% with 27 lines in your changes missing coverage. Please review.
✅ Project coverage is 69.40%. Comparing base (3d391a4) to head (d80444e).

Files with missing lines	Patch %	Lines
internal/database/session_store.go	73.77%	12 Missing and 4 partials ⚠️
internal/assistant/context_compaction.go	89.79%	2 Missing and 3 partials ⚠️
internal/assistant/runtime_context.go	77.77%	2 Missing and 2 partials ⚠️
internal/assistant/context_usage_led.go	91.66%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #90      +/-   ##
==========================================
+ Coverage   69.24%   69.40%   +0.15%     
==========================================
  Files         215      217       +2     
  Lines       19104    19236     +132     
==========================================
+ Hits        13229    13350     +121     
- Misses       4722     4729       +7     
- Partials     1153     1157       +4     

Flag	Coverage Δ
unittests	69.40% <84.74%> (+0.15%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@internal/database/session_store.go`:
- Around line 582-597: The function updateContextUsageAnchor currently swallows
the error returned by dataFromEntry; change its signature to return error (func
updateContextUsageAnchor(...) error), check and return the err when
dataFromEntry fails, and update all callers to handle/propagate that error; keep
the existing early-returns for non-message/assistant and for nil/empty usage,
but ensure any dataFromEntry error is returned instead of ignored so callers of
updateContextUsageAnchor (and related callers in session store flow) can handle
or log it appropriately.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 4398eb74-c627-4b71-b5d6-40c718e93c4b

📥 Commits

Reviewing files that changed from the base of the PR and between 3d391a4 and d597fe3.

📒 Files selected for processing (10)

• internal/assistant/context_build.go
• internal/assistant/context_compaction.go
• internal/assistant/context_compaction_internal_test.go
• internal/assistant/context_usage_led.go
• internal/assistant/context_usage_led_internal_test.go
• internal/assistant/runtime_context.go
• internal/assistant/runtime_entries.go
• internal/database/entity.go
• internal/database/session_store.go
• internal/database/session_usage_test.go

[coderabbitai]

🧹 Nitpick comments (1)

internal/database/session_store.go (1)

661-680: 💤 Low value

Unreachable return nil at line 679.

The switch statement exhaustively returns in all branches (including the fallthrough for unhandled types at lines 670-676), making the final return nil dead code.

♻️ Suggested cleanup

 	case EntryTypeCompaction,
 		EntryTypeModelChange,
 		EntryTypeThinkingLevelChange,
 		EntryTypeCustom,
 		EntryTypeLabel,
 		EntryTypeSessionInfo:
 		return nil
+	default:
+		return nil
 	}
-
-	return nil
 }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@internal/database/session_store.go` around lines 661 - 680, The trailing
"return nil" in appendRetainedCompactionTailEntry is redundant/unreachable; add
an explicit default case in the switch that returns nil (or move the existing
final return into a default) and then remove the final standalone "return nil"
so all code paths return from inside the switch; update the switch in
appendRetainedCompactionTailEntry accordingly.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@internal/database/session_store.go`:
- Around line 661-680: The trailing "return nil" in
appendRetainedCompactionTailEntry is redundant/unreachable; add an explicit
default case in the switch that returns nil (or move the existing final return
into a default) and then remove the final standalone "return nil" so all code
paths return from inside the switch; update the switch in
appendRetainedCompactionTailEntry accordingly.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 0352b69e-014a-4daf-9777-ad6826ef2d68

📥 Commits

Reviewing files that changed from the base of the PR and between d597fe3 and c8b98a4.

📒 Files selected for processing (2)

• internal/database/session_store.go
• internal/database/session_usage_internal_test.go

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud