Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

feat(agent): report and attribute per-turn LLM token usage

ochan.kwon894cbec48ab8
diff --git a/internal/agent/engine.go b/internal/agent/engine.go
index a63809461..e710ef433 100644
--- a/internal/agent/engine.go
+++ b/internal/agent/engine.go
@@ -559,6 +559,7 @@ func (e *AgentEngine) runReActIteration(
response = resp
if response.Usage.TotalTokens > 0 {
e.lastUsage = response.Usage
+ state.TurnUsage.Accumulate(response.Usage)
logger.Debugf(ctx, "[Agent][Round-%d] Usage: prompt=%d, completion=%d, total=%d",
round, response.Usage.PromptTokens,
response.Usage.CompletionTokens, response.Usage.TotalTokens)
diff --git a/internal/agent/finalize.go b/internal/agent/finalize.go
index c5c4b2fa6..d33d70b1a 100644
--- a/internal/agent/finalize.go
+++ b/internal/agent/finalize.go
@@ -144,6 +144,12 @@ Now generate the final answer:`, query, imageRequirement)
})
}
+ // The synthesis call is often the largest of the turn — fold its usage
+ // into the turn aggregate like every ReAct round.
+ if llmResult.Usage != nil {
+ state.TurnUsage.Accumulate(*llmResult.Usage)
+ }
+
// Safety net: strip any residual <think> blocks that may have leaked through
fullAnswer := agenttools.StripThinkBlocks(llmResult.Content)
logger.Infof(ctx, "[Agent][FinalAnswer] Final answer generated: %d characters", len(fullAnswer))
@@ -195,6 +201,7 @@ func (e *AgentEngine) emitCompletionEvent(
FinalAnswer: state.FinalAnswer,
KnowledgeRefs: knowledgeRefsInterface,
AgentSteps: state.RoundSteps, // Include detailed execution steps for message storage
+ Usage: turnUsage(state),
TotalSteps: len(state.RoundSteps),
TotalDurationMs: time.Since(startTime).Milliseconds(),
MessageID: messageID, // Include message ID for proper message update
@@ -203,3 +210,14 @@ func (e *AgentEngine) emitCompletionEvent(
logger.Infof(ctx, "Agent execution completed in %d rounds", state.CurrentRound)
}
+
+// turnUsage returns the turn's aggregated LLM usage, or nil when no round
+// reported usage so the field stays absent from the completion event and the
+// persisted message alike.
+func turnUsage(state *types.AgentState) *types.TokenUsage {
+ if state == nil || state.TurnUsage.TotalTokens == 0 {
+ return nil
+ }
+ usage := state.TurnUsage
+ return &usage
+}
diff --git a/internal/agent/turn_usage_test.go b/internal/agent/turn_usage_test.go
new file mode 100644
index 000000000..195956b12
--- /dev/null
+++ b/internal/agent/turn_usage_test.go
@@ -0,0 +1,33 @@
+package agent
+
+import (
+ "testing"
+
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+func TestTurnUsageNilWhenNothingReported(t *testing.T) {
+ if turnUsage(nil) != nil {
+ t.Fatal("nil state must yield no usage")
+ }
+ if turnUsage(&types.AgentState{}) != nil {
+ t.Fatal("a turn whose rounds reported no usage must omit the field entirely")
+ }
+}
+
+func TestTurnUsageCopiesTheAggregate(t *testing.T) {
+ state := &types.AgentState{}
+ state.TurnUsage.Accumulate(types.TokenUsage{PromptTokens: 100, CompletionTokens: 20, TotalTokens: 120})
+
+ usage := turnUsage(state)
+ if usage == nil || usage.TotalTokens != 120 {
+ t.Fatalf("aggregate not propagated: %+v", usage)
+ }
+
+ // The returned pointer must be a copy: later state mutation must not
+ // reach an event that has already been emitted.
+ state.TurnUsage.Accumulate(types.TokenUsage{PromptTokens: 1, TotalTokens: 1})
+ if usage.TotalTokens != 120 {
+ t.Fatalf("emitted usage must be detached from state: %+v", usage)
+ }
+}
diff --git a/internal/database/migration_sqlite_versioned_schema_test.go b/internal/database/migration_sqlite_versioned_schema_test.go
index cfd7e9d9b..e38a2bc70 100644
--- a/internal/database/migration_sqlite_versioned_schema_test.go
+++ b/internal/database/migration_sqlite_versioned_schema_test.go
@@ -27,13 +27,13 @@ var versionedSQLiteColumns = map[string][]string{
"tenants": {"api_principal_config"}, // 000064
"users": {"is_system_admin"}, // 000053
"knowledges": {"pending_subtasks_count"}, // 000056
- "messages": {"attachments"}, // 000034
+ "messages": {"attachments", "usage"}, // 000034, 000085
"tenant_invitations": {"token", "accepted_count"}, // 000054
"embed_channels": {"allow_memory"}, // 000060
"mcp_oauth_tokens": {"principal_type", "principal_id"}, // 000064
}
-const expectedSQLiteMigrationVersion = 11
+const expectedSQLiteMigrationVersion = 12
func TestSQLiteMigrationsCreateVersionedSchema(t *testing.T) {
repoRoot := sqliteRepoRoot(t)
diff --git a/internal/event/event_data.go b/internal/event/event_data.go
index fc7f11ea4..fa4557037 100644
--- a/internal/event/event_data.go
+++ b/internal/event/event_data.go
@@ -139,6 +139,7 @@ type AgentCompleteData struct {
FinalAnswer string `json:"final_answer"`
KnowledgeRefs []interface{} `json:"knowledge_refs,omitempty"` // []*types.SearchResult
AgentSteps interface{} `json:"agent_steps,omitempty"` // []types.AgentStep - detailed execution steps
+ Usage interface{} `json:"usage,omitempty"` // *types.TokenUsage - LLM token usage aggregated over the turn
TotalDurationMs int64 `json:"total_duration_ms"`
MessageID string `json:"message_id,omitempty"` // Assistant message ID
RequestID string `json:"request_id,omitempty"`
diff --git a/internal/handler/session/agent_stream_handler.go b/internal/handler/session/agent_stream_handler.go
index 18e68911b..0cdfccdaa 100644
--- a/internal/handler/session/agent_stream_handler.go
+++ b/internal/handler/session/agent_stream_handler.go
@@ -646,6 +646,12 @@ func (h *AgentStreamHandler) handleComplete(ctx context.Context, evt event.Event
}
}
+ // Persist the turn's aggregated LLM usage with the message so history
+ // reads still carry it after the live stream is gone.
+ if usage, ok := data.Usage.(*types.TokenUsage); ok && usage != nil {
+ h.assistantMessage.Usage = usage
+ }
+
// Drain skill-generated files from the sandbox into persistent
// storage. Best-effort: any failure is logged and the turn is
// persisted without artifacts. Collect is a no-op when either the
@@ -728,6 +734,13 @@ func (h *AgentStreamHandler) handleComplete(ctx context.Context, evt event.Event
if len(h.assistantMessage.Artifacts) > 0 {
completeData["artifacts"] = publicArtifactViews(h.assistantMessage.Artifacts)
}
+ // Carry the turn's aggregated LLM usage both inside data (map consumers)
+ // and on the typed event field, which buildStreamResponse promotes to the
+ // response's top-level usage.
+ turnUsage, _ := data.Usage.(*types.TokenUsage)
+ if turnUsage != nil {
+ completeData["usage"] = turnUsage
+ }
if err := h.streamManager.AppendEvent(h.ctx, h.sessionID, h.assistantMessageID, interfaces.StreamEvent{
ID: evt.ID,
Type: types.ResponseTypeComplete,
@@ -735,6 +748,7 @@ func (h *AgentStreamHandler) handleComplete(ctx context.Context, evt event.Event
Done: true,
Timestamp: time.Now(),
Data: completeData,
+ Usage: turnUsage,
}); err != nil {
logger.GetLogger(h.ctx).Errorf("Append complete event to stream failed: %v", err)
}
diff --git a/internal/handler/session/helpers.go b/internal/handler/session/helpers.go
index feacb0551..0a9d34ded 100644
--- a/internal/handler/session/helpers.go
+++ b/internal/handler/session/helpers.go
@@ -194,6 +194,7 @@ func buildStreamResponse(evt interfaces.StreamEvent, requestID string) *types.St
Content: evt.Content,
Done: evt.Done,
Data: evt.Data,
+ Usage: evt.Usage,
}
// Extract session_id and assistant_message_id for agent_query events
diff --git a/internal/handler/session/stream_usage_test.go b/internal/handler/session/stream_usage_test.go
new file mode 100644
index 000000000..2832efe0d
--- /dev/null
+++ b/internal/handler/session/stream_usage_test.go
@@ -0,0 +1,50 @@
+package session
+
+import (
+ "encoding/json"
+ "testing"
+
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/Tencent/WeKnora/internal/types/interfaces"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestBuildStreamResponsePromotesUsageOnCompleteEvents(t *testing.T) {
+ usage := &types.TokenUsage{PromptTokens: 100, CompletionTokens: 20, TotalTokens: 120}
+
+ response := buildStreamResponse(interfaces.StreamEvent{
+ Type: types.ResponseTypeComplete,
+ Done: true,
+ Data: map[string]interface{}{"total_steps": 3, "usage": usage},
+ Usage: usage,
+ }, "req-1")
+
+ require.NotNil(t, response.Usage)
+ assert.Equal(t, 120, response.Usage.TotalTokens)
+ assert.Equal(t, usage, response.Data["usage"])
+}
+
+func TestBuildStreamResponseLeavesUsageNilWhenAbsent(t *testing.T) {
+ response := buildStreamResponse(interfaces.StreamEvent{
+ Type: types.ResponseTypeAnswer,
+ Data: map[string]interface{}{"event_id": "e-1"},
+ }, "req-1")
+
+ assert.Nil(t, response.Usage)
+}
+
+func TestStreamEventUsageSurvivesJSONRoundTrip(t *testing.T) {
+ // The stream manager persists events as JSON (Redis) before the SSE loop
+ // reads them back — the typed usage must survive that round trip.
+ usage := &types.TokenUsage{PromptTokens: 100, CompletionTokens: 20, TotalTokens: 120}
+ usage.SetPromptCacheUsage(80, 0, 20, true)
+
+ raw, err := json.Marshal(interfaces.StreamEvent{Type: types.ResponseTypeComplete, Usage: usage})
+ require.NoError(t, err)
+
+ var restored interfaces.StreamEvent
+ require.NoError(t, json.Unmarshal(raw, &restored))
+ require.NotNil(t, restored.Usage)
+ assert.Equal(t, *usage, *restored.Usage)
+}
diff --git a/internal/im/service.go b/internal/im/service.go
index 850ae1554..5c832d317 100644
--- a/internal/im/service.go
+++ b/internal/im/service.go
@@ -701,6 +701,9 @@ func applyIMCompleteDataToMessage(msg *types.Message, data event.AgentCompleteDa
}
msg.IsCompleted = true
msg.AgentDurationMs = data.TotalDurationMs
+ if usage, ok := data.Usage.(*types.TokenUsage); ok && usage != nil {
+ msg.Usage = usage
+ }
if len(data.KnowledgeRefs) > 0 {
refs := make([]*types.SearchResult, 0, len(data.KnowledgeRefs))
collectIMKnowledgeReferences(&refs, data.KnowledgeRefs)
diff --git a/internal/models/chat/usage.go b/internal/models/chat/usage.go
index aed550afb..f51189e02 100644
--- a/internal/models/chat/usage.go
+++ b/internal/models/chat/usage.go
@@ -2,6 +2,7 @@ package chat
import (
"context"
+ "strings"
"github.com/Tencent/WeKnora/internal/logger"
"github.com/Tencent/WeKnora/internal/types"
@@ -16,8 +17,30 @@ func logUsage(ctx context.Context, model string, u *types.TokenUsage) {
}
purpose, prefixFingerprint := types.LLMCallMetadataFromContext(ctx)
logger.Infof(ctx,
- "[LLM Usage] model=%s, purpose=%s, prompt_prefix=%s, prompt_tokens=%d, completion_tokens=%d, total_tokens=%d, cached_tokens=%d, cache_read_tokens=%d, cache_write_tokens=%d, cache_miss_tokens=%d, cache_reported=%t, cache_status=%s",
+ "[LLM Usage] model=%s, purpose=%s, prompt_prefix=%s, prompt_tokens=%d, completion_tokens=%d, "+
+ "total_tokens=%d, cached_tokens=%d, cache_read_tokens=%d, cache_write_tokens=%d, "+
+ "cache_miss_tokens=%d, cache_reported=%t, cache_status=%s%s",
model, purpose, prefixFingerprint, u.PromptTokens, u.CompletionTokens, u.TotalTokens,
u.CachedTokens, u.CacheReadTokens, u.CacheWriteTokens, u.CacheMissTokens,
- u.CacheReported, u.CacheStatus)
+ u.CacheReported, u.CacheStatus, usageAttribution(ctx))
+}
+
+// usageAttribution renders the ", session_id=…, principal=…" suffix that
+// attributes a usage line to the session and terminal principal that
+// triggered the call. Calls that run outside a session or without a resolved
+// principal (document parsing, title generation, background jobs) render an
+// empty suffix, keeping their lines byte-identical to before.
+func usageAttribution(ctx context.Context) string {
+ var b strings.Builder
+ if sessionID, ok := types.SessionIDFromContext(ctx); ok && sessionID != "" {
+ b.WriteString(", session_id=")
+ b.WriteString(sessionID)
+ }
+ if principal, ok := types.PrincipalFromContext(ctx); ok {
+ b.WriteString(", principal=")
+ b.WriteString(principal.Type)
+ b.WriteString(":")
+ b.WriteString(principal.ID)
+ }
+ return b.String()
}
diff --git a/internal/models/chat/usage_attribution_test.go b/internal/models/chat/usage_attribution_test.go
new file mode 100644
index 000000000..0425260a5
--- /dev/null
+++ b/internal/models/chat/usage_attribution_test.go
@@ -0,0 +1,34 @@
+package chat
+
+import (
+ "context"
+ "testing"
+
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+func TestUsageAttributionEmptyOutsideSessions(t *testing.T) {
+ // Calls without session or principal context (document parsing, title
+ // generation, background jobs) must keep the usage line byte-identical.
+ if got := usageAttribution(context.Background()); got != "" {
+ t.Fatalf("expected empty suffix, got %q", got)
+ }
+}
+
+func TestUsageAttributionCarriesSessionAndPrincipal(t *testing.T) {
+ ctx := types.WithSessionID(context.Background(), "sess-123")
+ ctx = types.WithPrincipal(ctx, types.Principal{Type: types.PrincipalAPIExternalUser, ID: "10000:42"})
+
+ got := usageAttribution(ctx)
+ want := ", session_id=sess-123, principal=api_external_user:10000:42"
+ if got != want {
+ t.Fatalf("got %q want %q", got, want)
+ }
+}
+
+func TestUsageAttributionSessionOnly(t *testing.T) {
+ ctx := types.WithSessionID(context.Background(), "sess-9")
+ if got := usageAttribution(ctx); got != ", session_id=sess-9" {
+ t.Fatalf("got %q", got)
+ }
+}
diff --git a/internal/types/agent.go b/internal/types/agent.go
index 8591b0b3e..d1ba32549 100644
--- a/internal/types/agent.go
+++ b/internal/types/agent.go
@@ -256,6 +256,7 @@ type AgentState struct {
IsComplete bool `json:"is_complete"` // Whether agent has finished
FinalAnswer string `json:"final_answer"` // The final answer to the query
KnowledgeRefs []*SearchResult `json:"knowledge_refs"` // Collected knowledge references
+ TurnUsage TokenUsage `json:"turn_usage"` // LLM token usage accumulated across every round of this turn
}
// FunctionDefinition represents a function definition for LLM function calling
diff --git a/internal/types/chat.go b/internal/types/chat.go
index 71d75968b..93c14980a 100644
--- a/internal/types/chat.go
+++ b/internal/types/chat.go
@@ -73,6 +73,79 @@ func (u *TokenUsage) MarkPromptCacheUnsupported() {
u.CacheStatus = PromptCacheStatusUnsupported
}
+// Accumulate adds another call's usage into u, preserving the subset
+// semantics: prompt/completion/total and every cache counter sum
+// independently (cache counters stay subsets of the prompt count and are
+// never folded into it). CacheReported ORs, and the cache status is
+// recomputed from the combined counters so a single cache hit anywhere in
+// the accumulated calls reads as a hit.
+func (u *TokenUsage) Accumulate(other TokenUsage) {
+ if u == nil {
+ return
+ }
+ u.PromptTokens += other.PromptTokens
+ u.CompletionTokens += other.CompletionTokens
+ u.TotalTokens += other.TotalTokens
+ u.CachedTokens += other.CachedTokens
+ u.CacheReadTokens += other.CacheReadTokens
+ u.CacheWriteTokens += other.CacheWriteTokens
+ u.CacheMissTokens += other.CacheMissTokens
+ u.CacheReported = u.CacheReported || other.CacheReported
+ switch {
+ case !u.CacheReported:
+ u.CacheStatus = mergeUnreportedCacheStatus(u.CacheStatus, other.CacheStatus)
+ case u.CacheReadTokens > 0:
+ u.CacheStatus = PromptCacheStatusHit
+ default:
+ u.CacheStatus = PromptCacheStatusMiss
+ }
+}
+
+// mergeUnreportedCacheStatus folds the statuses of never-reported usage.
+// "unsupported" survives only while every accumulated call was itself
+// classified unsupported — the first accumulation adopts the incoming
+// classification, and any later call that is not known-unsupported (an
+// unreported or unclassified one) degrades the aggregate to unreported.
+func mergeUnreportedCacheStatus(accumulated, incoming PromptCacheStatus) PromptCacheStatus {
+ if accumulated == "" {
+ if incoming == "" {
+ return PromptCacheStatusUnreported
+ }
+ return incoming
+ }
+ if accumulated == PromptCacheStatusUnsupported && incoming == PromptCacheStatusUnsupported {
+ return PromptCacheStatusUnsupported
+ }
+ return PromptCacheStatusUnreported
+}
+
+// Value persists the usage as a jsonb column (assistant messages carry the
+// turn's aggregate); nil writes SQL NULL. Mirrors the nullable-pointer
+// pattern APIPrincipalConfig uses.
+func (u *TokenUsage) Value() (driver.Value, error) {
+ if u == nil {
+ return nil, nil
+ }
+ return json.Marshal(u)
+}
+
+// Scan restores a jsonb usage column; NULL leaves the receiver zero-valued.
+func (u *TokenUsage) Scan(value interface{}) error {
+ if value == nil {
+ return nil
+ }
+ var b []byte
+ switch v := value.(type) {
+ case []byte:
+ b = v
+ case string:
+ b = []byte(v)
+ default:
+ return nil
+ }
+ return json.Unmarshal(b, u)
+}
+
// LLMToolCall represents a function/tool call from the LLM
type LLMToolCall struct {
ID string `json:"id"`
diff --git a/internal/types/interfaces/stream_manager.go b/internal/types/interfaces/stream_manager.go
index 41499d056..6ff3acd92 100644
--- a/internal/types/interfaces/stream_manager.go
+++ b/internal/types/interfaces/stream_manager.go
@@ -9,12 +9,13 @@ import (
// StreamEvent represents a single event in the stream
type StreamEvent struct {
- ID string `json:"id"` // Unique event ID
- Type types.ResponseType `json:"type"` // Event type (thinking, tool_call, tool_result, references, complete, etc.)
- Content string `json:"content"` // Event content (chunk for streaming events)
- Done bool `json:"done"` // Whether this event is done
- Timestamp time.Time `json:"timestamp"` // When this event occurred
- Data map[string]interface{} `json:"data,omitempty"` // Additional event data (references, metadata, etc.)
+ ID string `json:"id"` // Unique event ID
+ Type types.ResponseType `json:"type"` // Event type (thinking, tool_call, complete, etc.)
+ Content string `json:"content"` // Event content (chunk for streaming events)
+ Done bool `json:"done"` // Whether this event is done
+ Timestamp time.Time `json:"timestamp"` // When this event occurred
+ Data map[string]interface{} `json:"data,omitempty"` // Additional event data (references, metadata, etc.)
+ Usage *types.TokenUsage `json:"usage,omitempty"` // LLM token usage aggregated over the turn (complete events)
}
// StreamManager stream manager interface - minimal append-only design
diff --git a/internal/types/message.go b/internal/types/message.go
index 308c101a2..fc0d9d917 100644
--- a/internal/types/message.go
+++ b/internal/types/message.go
@@ -285,6 +285,10 @@ type Message struct {
IsFallback bool `json:"is_fallback,omitempty"`
// Agent total execution duration in milliseconds (from query start to answer start)
AgentDurationMs int64 `json:"agent_duration_ms,omitempty" gorm:"column:agent_duration_ms;default:0"`
+ // LLM token usage aggregated across every round of the turn that produced this
+ // assistant message. Persisted so history reads can attribute cost after the
+ // live stream is gone; NULL (nil) for user messages and pre-feature rows.
+ Usage *TokenUsage `json:"usage,omitempty" gorm:"type:jsonb;column:usage"`
// RenderedContent stores the full RAG-augmented user message (with retrieved context)
// sent to the LLM. Used to preserve retrieval context across conversation turns.
// Empty for non-retrieval intents or assistant messages.
diff --git a/internal/types/token_usage_test.go b/internal/types/token_usage_test.go
new file mode 100644
index 000000000..3b27dea2d
--- /dev/null
+++ b/internal/types/token_usage_test.go
@@ -0,0 +1,119 @@
+package types
+
+import (
+ "encoding/json"
+ "testing"
+)
+
+func TestTokenUsageAccumulateSumsEveryCounter(t *testing.T) {
+ var turn TokenUsage
+
+ first := TokenUsage{PromptTokens: 1000, CompletionTokens: 200, TotalTokens: 1200}
+ first.SetPromptCacheUsage(800, 0, 200, true)
+ second := TokenUsage{PromptTokens: 1500, CompletionTokens: 300, TotalTokens: 1800}
+ second.SetPromptCacheUsage(0, 1500, 1500, true)
+
+ turn.Accumulate(first)
+ turn.Accumulate(second)
+
+ if turn.PromptTokens != 2500 || turn.CompletionTokens != 500 || turn.TotalTokens != 3000 {
+ t.Fatalf("token sums wrong: %+v", turn)
+ }
+ if turn.CacheReadTokens != 800 || turn.CacheWriteTokens != 1500 || turn.CacheMissTokens != 1700 {
+ t.Fatalf("cache sums wrong: %+v", turn)
+ }
+ if turn.CachedTokens != turn.CacheReadTokens {
+ t.Fatalf("legacy alias diverged from cache reads: %+v", turn)
+ }
+ if !turn.CacheReported || turn.CacheStatus != PromptCacheStatusHit {
+ t.Fatalf("a hit anywhere in the turn must read as a hit: %+v", turn)
+ }
+}
+
+func TestTokenUsageAccumulateStatusFollowsCombinedCounters(t *testing.T) {
+ var unreported TokenUsage
+ unreported.Accumulate(TokenUsage{PromptTokens: 10, TotalTokens: 10})
+ if unreported.CacheReported || unreported.CacheStatus != PromptCacheStatusUnreported {
+ t.Fatalf("all-unreported accumulation must stay unreported: %+v", unreported)
+ }
+
+ var missOnly TokenUsage
+ reportedMiss := TokenUsage{PromptTokens: 10, TotalTokens: 10}
+ reportedMiss.SetPromptCacheUsage(0, 0, 10, true)
+ missOnly.Accumulate(reportedMiss)
+ if missOnly.CacheStatus != PromptCacheStatusMiss {
+ t.Fatalf("reported without reads must read as miss: %+v", missOnly)
+ }
+}
+
+func TestTokenUsageAccumulatePreservesUnsupported(t *testing.T) {
+ var unsupported TokenUsage
+ call := TokenUsage{PromptTokens: 10, TotalTokens: 10}
+ call.MarkPromptCacheUnsupported()
+
+ unsupported.Accumulate(call)
+ unsupported.Accumulate(call)
+ if unsupported.CacheStatus != PromptCacheStatusUnsupported {
+ t.Fatalf("all-unsupported accumulation must stay unsupported: %+v", unsupported)
+ }
+
+ // Mixing in a merely-unreported call degrades the aggregate: the turn no
+ // longer proves every provider path was incapable of reporting.
+ unsupported.Accumulate(TokenUsage{PromptTokens: 5, TotalTokens: 5})
+ if unsupported.CacheStatus != PromptCacheStatusUnreported {
+ t.Fatalf("unsupported+unreported mix must read unreported: %+v", unsupported)
+ }
+}
+
+func TestTokenUsageAccumulateOnNilReceiverIsNoOp(t *testing.T) {
+ var u *TokenUsage
+ u.Accumulate(TokenUsage{PromptTokens: 1, TotalTokens: 1}) // must not panic
+}
+
+func TestTokenUsageValueScanRoundTrip(t *testing.T) {
+ original := &TokenUsage{PromptTokens: 42, CompletionTokens: 7, TotalTokens: 49}
+ original.SetPromptCacheUsage(30, 0, 12, true)
+
+ value, err := original.Value()
+ if err != nil {
+ t.Fatalf("Value failed: %v", err)
+ }
+ raw, ok := value.([]byte)
+ if !ok {
+ t.Fatalf("Value must produce bytes, got %T", value)
+ }
+
+ var restored TokenUsage
+ if err := restored.Scan(raw); err != nil {
+ t.Fatalf("Scan failed: %v", err)
+ }
+ if restored != *original {
+ t.Fatalf("round trip diverged: got %+v want %+v", restored, *original)
+ }
+
+ // json.Marshal must agree with Value so API responses and the persisted
+ // column carry the same shape.
+ direct, err := json.Marshal(original)
+ if err != nil {
+ t.Fatalf("json.Marshal failed: %v", err)
+ }
+ if string(direct) != string(raw) {
+ t.Fatalf("Value diverged from json.Marshal: %s vs %s", raw, direct)
+ }
+}
+
+func TestTokenUsageValueNilAndScanNull(t *testing.T) {
+ var u *TokenUsage
+ value, err := u.Value()
+ if err != nil || value != nil {
+ t.Fatalf("nil usage must persist as SQL NULL, got (%v, %v)", value, err)
+ }
+
+ restored := TokenUsage{PromptTokens: 5}
+ if err := restored.Scan(nil); err != nil {
+ t.Fatalf("Scan(NULL) failed: %v", err)
+ }
+ if restored.PromptTokens != 5 {
+ t.Fatalf("Scan(NULL) must leave the receiver untouched: %+v", restored)
+ }
+}
diff --git a/migrations/sqlite/000012_message_usage.down.sql b/migrations/sqlite/000012_message_usage.down.sql
new file mode 100644
index 000000000..0ee025eb5
--- /dev/null
+++ b/migrations/sqlite/000012_message_usage.down.sql
@@ -0,0 +1 @@
+ALTER TABLE messages DROP COLUMN usage;
diff --git a/migrations/sqlite/000012_message_usage.up.sql b/migrations/sqlite/000012_message_usage.up.sql
new file mode 100644
index 000000000..cbc3bc8fe
--- /dev/null
+++ b/migrations/sqlite/000012_message_usage.up.sql
@@ -0,0 +1,4 @@
+-- Mirrors versioned migration 000085_message_usage:
+-- per-turn LLM token usage persisted with the assistant message.
+
+ALTER TABLE messages ADD COLUMN usage TEXT;
diff --git a/migrations/versioned/000085_message_usage.down.sql b/migrations/versioned/000085_message_usage.down.sql
new file mode 100644
index 000000000..9688136a7
--- /dev/null
+++ b/migrations/versioned/000085_message_usage.down.sql
@@ -0,0 +1 @@
+ALTER TABLE messages DROP COLUMN IF EXISTS usage;
diff --git a/migrations/versioned/000085_message_usage.up.sql b/migrations/versioned/000085_message_usage.up.sql
new file mode 100644
index 000000000..d0b510615
--- /dev/null
+++ b/migrations/versioned/000085_message_usage.up.sql
@@ -0,0 +1 @@
+ALTER TABLE messages ADD COLUMN IF NOT EXISTS usage JSONB;