feat(vibe): read provider cache-hit tokens from session stats (#1309)

Mistral Vibe v2.23.2 (mistralai/mistral-vibe#969) started recording provider cache-hit (cached) tokens in the session stats written to `meta.json`. This teaches the Vibe parser to read them.

`stats.session_cached_tokens` is the provider cache-read count, reported as a subset of `session_prompt_tokens` (the OpenAI/Mistral `prompt_tokens` / `prompt_tokens_details.cached_tokens` wire shape). The parser now splits it out into the usage event's cache-read field and subtracts it from input tokens, so the cached prefix is priced at the discounted cache-read rate rather than the full input rate and is not double-counted. This mirrors the convention already used by the workbuddy and grok parsers.

Vibe exposes a single cached counter with no cache-creation breakdown, so `CacheCreationInputTokens` stays zero.

Reviewers should look at `vibeUsageEvents` in `internal/parser/vibe.go`. The format provenance entry in `docs/internal/session-format-sources.md` is updated in the same change.

Co-authored-by: Grégoire <verdie-g@users.noreply.github.com>

Author: verdie-g

internal/db/db.go

@@ -342,7 +342,12 @@ const projectIdentityRemoteScrubCompletedKey = "project_identity_remote_scrub_v1
 // (76: Copilot CLI tool execution boundaries. Re-parsing persists
 // tool.execution_start and tool.execution_complete timestamps as result events
 // so Session Analysis excludes resumed-session idle time from completed calls.)
-const dataVersion = 76
+// (77: Vibe usage reparse. The Vibe parser now reads
+// stats.session_cached_tokens, splitting the provider cache-hit count out of
+// input tokens into the usage event's cache-read field. Existing rows need
+// re-parsing so the cached prefix is priced at the discounted cache-read rate
+// instead of the full input rate.)
+const dataVersion = 77
 
 const tokenCoverageRepairStatsKey = "token_coverage_repair_v1"
 

internal/db/db_test.go

@@ -1008,9 +1008,9 @@ func TestMigration_ToolResultEventsTable(t *testing.T) {
 		"expected tool_result_events table after reopen")
 }
 
-func TestCurrentDataVersionCopilotToolTiming(t *testing.T) {
-	assert.Equal(t, 76, CurrentDataVersion(),
-		"Copilot tool execution timing requires a data version bump")
+func TestCurrentDataVersionVibeCachedTokensReparse(t *testing.T) {
+	assert.Equal(t, 77, CurrentDataVersion(),
+		"reading Vibe cache-hit tokens requires a data version bump")
 }
 
 func TestInsertMessages_PreservesToolResultEvents(t *testing.T) {

internal/parser/vibe.go

@@ -60,9 +60,11 @@ type VibeStats struct {
 	Steps                    int   `json:"steps"`
 	SessionPromptTokens      int   `json:"session_prompt_tokens"`
 	SessionCompletionTokens  int   `json:"session_completion_tokens"`
+	SessionCachedTokens      int   `json:"session_cached_tokens"`
 	ContextTokens            int   `json:"context_tokens"`
 	LastTurnPromptTokens     int   `json:"last_turn_prompt_tokens"`
 	LastTurnCompletionTokens int   `json:"last_turn_completion_tokens"`
+	LastTurnCachedTokens     int   `json:"last_turn_cached_tokens"`
 	SessionTotalLLMTokens    int64 `json:"session_total_llm_tokens"`
 	LastTurnTotalTokens      int   `json:"last_turn_total_tokens"`
 }
@@ -441,7 +443,13 @@ func vibeUsageEvents(
 	// Use SessionPromptTokens for input tokens and SessionCompletionTokens for output tokens.
 	// SessionTotalLLMTokens appears to be the sum of input + output tokens,
 	// so we don't use it as a direct source but it can serve as validation.
-	inputTokens := stats.SessionPromptTokens
+	//
+	// SessionCachedTokens is the provider cache-hit (read) count, reported as a
+	// subset of SessionPromptTokens (OpenAI/Mistral wire shape). Split it out
+	// so cache reads are priced at the discounted cache-read rate and not
+	// double-counted against the full input rate.
+	cacheReadTokens := max(stats.SessionCachedTokens, 0)
+	inputTokens := max(stats.SessionPromptTokens-cacheReadTokens, 0)
 	outputTokens := stats.SessionCompletionTokens
 
 	return []ParsedUsageEvent{{
@@ -450,9 +458,9 @@ func vibeUsageEvents(
 		Model:        model,
 		InputTokens:  inputTokens,
 		OutputTokens: outputTokens,
-		// Vibe doesn't currently expose cache token breakdown in meta.json
+		// Vibe doesn't currently expose cache-creation breakdown
 		CacheCreationInputTokens: 0,
-		CacheReadInputTokens:     0,
+		CacheReadInputTokens:     cacheReadTokens,
 		ReasoningTokens:          0,
 		// Vibe doesn't currently expose cost information
 		Cost:       nil,

internal/parser/vibe_test.go

@@ -520,6 +520,55 @@ func TestParseVibeSessionModelFromConfig(t *testing.T) {
 	assert.Equal(t, 40, usageEvent.OutputTokens)
 }
 
+// TestParseVibeSessionCachedTokens verifies that the provider cache-hit count
+// recorded under stats.session_cached_tokens is split out into the cache-read
+// field and subtracted from input tokens, since Vibe reports it as a subset of
+// session_prompt_tokens (OpenAI/Mistral wire shape). Counting it in both places
+// would double-bill the cached prefix.
+func TestParseVibeSessionCachedTokens(t *testing.T) {
+	tmpDir := t.TempDir()
+
+	content := `{"role": "user", "content": "test message", "message_id": "1"}
+{"role": "assistant", "content": "test response", "message_id": "2"}
+`
+	metaContent := `{
+		"session_id": "test-session-cached",
+		"start_time": "2026-06-13T10:00:00Z",
+		"end_time": "2026-06-13T10:05:00Z",
+		"title": "Test session with cached tokens",
+		"config": {"active_model": "mistral-medium-3.5"},
+		"stats": {
+			"session_prompt_tokens": 100,
+			"session_completion_tokens": 40,
+			"session_cached_tokens": 30,
+			"context_tokens": 140,
+			"last_turn_cached_tokens": 10,
+			"session_total_llm_tokens": 140
+		}
+	}
+`
+	files := map[string]string{
+		"session_test/messages.jsonl": content,
+		"session_test/meta.json":      metaContent,
+	}
+	setupFileSystem(t, tmpDir, files)
+
+	path := filepath.Join(tmpDir, "session_test", "messages.jsonl")
+	fileInfo := FileInfo{Path: path, Mtime: time.Now().UnixNano()}
+
+	result, err := parseVibeTestSession(t, path, fileInfo)
+	require.NoError(t, err)
+
+	require.Len(t, result.UsageEvents, 1)
+	usageEvent := result.UsageEvents[0]
+	assert.Equal(t, "mistral-medium-3.5", usageEvent.Model)
+	// Input is the fresh (non-cached) prefix: 100 - 30.
+	assert.Equal(t, 70, usageEvent.InputTokens)
+	assert.Equal(t, 40, usageEvent.OutputTokens)
+	assert.Equal(t, 30, usageEvent.CacheReadInputTokens)
+	assert.Equal(t, 0, usageEvent.CacheCreationInputTokens)
+}
+
 // TestParseVibeSessionInjectedUserExcluded verifies that an injected user
 // record (system context) is marked system and excluded from both the first
 // message and the user-message count, so it cannot masquerade as the user's