Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.
Go agentagenticaichatbotdsh-pluginembeddingsevaluationgenerative-aigolangknowledge-basellmmulti-tenantollamaopenaiquestion-answeringragrerankingsemantic-searchvector-searchwiki
feat(agent): report and attribute per-turn LLM token usage
ochan.kwon894cbec48ab8
diff --git a/internal/agent/engine.go b/internal/agent/engine.goindex a63809461..e710ef433 100644--- a/internal/agent/engine.go+++ b/internal/agent/engine.go@@ -559,6 +559,7 @@ func (e *AgentEngine) runReActIteration(response = respif 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.goindex 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 throughfullAnswer := 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.gonew file mode 100644index 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.goindex 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 = 12func TestSQLiteMigrationsCreateVersionedSchema(t *testing.T) {repoRoot := sqliteRepoRoot(t)diff --git a/internal/event/event_data.go b/internal/event/event_data.goindex 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.SearchResultAgentSteps interface{} `json:"agent_steps,omitempty"` // []types.AgentStep - detailed execution steps+ Usage interface{} `json:"usage,omitempty"` // *types.TokenUsage - LLM token usage aggregated over the turnTotalDurationMs int64 `json:"total_duration_ms"`MessageID string `json:"message_id,omitempty"` // Assistant message IDRequestID string `json:"request_id,omitempty"`diff --git a/internal/handler/session/agent_stream_handler.go b/internal/handler/session/agent_stream_handler.goindex 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.Eventif 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.EventDone: 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.goindex 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.StContent: evt.Content,Done: evt.Done,Data: evt.Data,+ Usage: evt.Usage,}// Extract session_id and assistant_message_id for agent_query eventsdiff --git a/internal/handler/session/stream_usage_test.go b/internal/handler/session/stream_usage_test.gonew file mode 100644index 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.goindex 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 = truemsg.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.goindex aed550afb..f51189e02 100644--- a/internal/models/chat/usage.go+++ b/internal/models/chat/usage.go@@ -2,6 +2,7 @@ package chatimport ("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.gonew file mode 100644index 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.goindex 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 finishedFinalAnswer string `json:"final_answer"` // The final answer to the queryKnowledgeRefs []*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 callingdiff --git a/internal/types/chat.go b/internal/types/chat.goindex 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 LLMtype LLMToolCall struct {ID string `json:"id"`diff --git a/internal/types/interfaces/stream_manager.go b/internal/types/interfaces/stream_manager.goindex 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 streamtype 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 designdiff --git a/internal/types/message.go b/internal/types/message.goindex 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.gonew file mode 100644index 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.sqlnew file mode 100644index 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.sqlnew file mode 100644index 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.sqlnew file mode 100644index 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.sqlnew file mode 100644index 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;