fix(usage): capture OR cost, tag turn context, record logical role

Three corrections to Stage A.1 after seeing the first real usage_log
row in prod:

1. Missing OpenRouter cost. OR's response carries `usage.cost` (the
   actual USD charged for this request, already accounting for which
   upstream was routed to and any volume discounts). Added cost_usd
   column + parse from both sync and streaming paths. Keeps our
   computed cost (tokens × model_capabilities prices) as a fallback
   for providers that don't report.

2. Role column held the slot name ("simple-or") instead of the logical
   role ("simple"). I'd been passing primaryKey (map key) to
   recordUsage. Fix: Router.pick() now returns (Provider, role) where
   role is the concept — simple/default/complex/multimodal/override/
   tool-continuation/fallback. Every caller (Chat, ChatStream, sync +
   fallback streams) threads the role through, so usage_log.role is
   now analytics-friendly regardless of how slots are named locally.

3. user_message_id was always NULL — agent.Process never tagged ctx
   with TurnMeta. Reshape Store.AddMessage / AddMessageWithEmbedding
   to return int64 (Memory returns 0). storeUserMessage returns the
   new id; Process + ProcessStream call llm.WithTurnMeta on ctx before
   the router invocation so every LLM call for the turn links back to
   the user message that triggered it. Changed interface: callers that
   ignore the return value (most assistant/tool writes) don't need
   updates.

Store migrations add cost_usd column to usage_log (SQLite + Postgres
with ALTER IF NOT EXISTS for the already-deployed table).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: Alexey Panfilov

internal/agent/agent.go

@@ -122,8 +122,10 @@ func (a *Agent) Process(ctx context.Context, chatID int64, userMsg llm.Message,
 
 	// Store user message; embed it if semantic store + MCP embeddings are both available.
 	endEmbed := tr.begin("embed")
-	queryEmb := a.storeUserMessage(ctx, chatID, userMsg, queryText)
+	queryEmb, userMsgID := a.storeUserMessage(ctx, chatID, userMsg, queryText)
 	endEmbed()
+	// Tag ctx so Router.recordUsage can link usage_log rows to this turn.
+	ctx = llm.WithTurnMeta(ctx, llm.TurnMeta{ChatID: chatID, UserMessageID: userMsgID})
 
 	// Auto-compact if needed
 	if a.compacter != nil && NeedsCompaction(a.store, chatID) {
@@ -226,8 +228,9 @@ func (a *Agent) ProcessStream(ctx context.Context, chatID int64, userMsg llm.Mes
 	queryText := messageText(userMsg)
 
 	endEmbed := tr.begin("embed")
-	queryEmb := a.storeUserMessage(ctx, chatID, userMsg, queryText)
+	queryEmb, userMsgID := a.storeUserMessage(ctx, chatID, userMsg, queryText)
 	endEmbed()
+	ctx = llm.WithTurnMeta(ctx, llm.TurnMeta{ChatID: chatID, UserMessageID: userMsgID})
 
 	if a.compacter != nil && NeedsCompaction(a.store, chatID) {
 		a.logger.Info("auto-compacting conversation", "chat_id", chatID)
@@ -549,19 +552,20 @@ func (a *Agent) callTool(ctx context.Context, name, argsJSON string) (string, er
 
 // storeUserMessage saves the user message. If the store and MCP client both support
 // embeddings, it also computes and stores the embedding for semantic history retrieval.
-// Returns the embedding (may be nil if unavailable).
-func (a *Agent) storeUserMessage(ctx context.Context, chatID int64, msg llm.Message, text string) []float32 {
+// Returns the embedding (may be nil) and the inserted row's id (0 if the backend
+// does not expose IDs).
+func (a *Agent) storeUserMessage(ctx context.Context, chatID int64, msg llm.Message, text string) ([]float32, int64) {
 	sem, hasSem := a.store.(store.SemanticStore)
 	if hasSem && a.mcp != nil {
 		emb, err := a.mcp.EmbedText(ctx, text)
 		if err == nil {
-			sem.AddMessageWithEmbedding(chatID, msg, emb)
-			return emb
+			id := sem.AddMessageWithEmbedding(chatID, msg, emb)
+			return emb, id
 		}
 		a.logger.Info("embedding unavailable, storing without", "chat_id", chatID, "err", err)
 	}
-	a.store.AddMessage(chatID, msg)
-	return nil
+	id := a.store.AddMessage(chatID, msg)
+	return nil, id
 }
 
 // buildCrossSessionContext searches past sessions and returns a formatted block

internal/agent/compact_test.go

@@ -91,7 +91,7 @@ func newMockCompactableStore(charCount int) *mockCompactableStore {
 }
 
 func (m *mockCompactableStore) GetHistory(_ int64) []llm.Message        { return nil }
-func (m *mockCompactableStore) AddMessage(_ int64, _ llm.Message)       {}
+func (m *mockCompactableStore) AddMessage(_ int64, _ llm.Message) int64 { return 0 }
 func (m *mockCompactableStore) ClearHistory(_ int64)                    {}
 func (m *mockCompactableStore) AddSummary(_ int64, _ string)            {}
 func (m *mockCompactableStore) MarkCompacted(_ []int64) error           { return nil }

internal/llm/openai_compat.go

@@ -214,11 +214,14 @@ type rawChatResponse struct {
 
 // rawUsage covers OpenAI-compatible usage fields plus the nested *_details
 // blocks that OpenRouter / Anthropic / OpenAI populate for prompt caching
-// and reasoning tokens.
+// and reasoning tokens. `cost` is OpenRouter-specific and surfaces the
+// actual USD amount OR charged for this request (after routing to the
+// selected upstream + any volume discounts).
 type rawUsage struct {
-	PromptTokens        int `json:"prompt_tokens"`
-	CompletionTokens    int `json:"completion_tokens"`
-	TotalTokens         int `json:"total_tokens"`
+	PromptTokens        int     `json:"prompt_tokens"`
+	CompletionTokens    int     `json:"completion_tokens"`
+	TotalTokens         int     `json:"total_tokens"`
+	Cost                float64 `json:"cost"`
 	PromptTokensDetails *struct {
 		CachedTokens int `json:"cached_tokens"`
 	} `json:"prompt_tokens_details"`
@@ -295,6 +298,7 @@ func (p *openAICompatProvider) Chat(ctx context.Context, messages []Message, sys
 		result.Usage = Usage{
 			PromptTokens:     u.PromptTokens,
 			CompletionTokens: u.CompletionTokens,
+			Cost:             u.Cost,
 			RequestID:        chatResp.ID,
 		}
 		if u.PromptTokensDetails != nil {
@@ -485,6 +489,7 @@ func (p *openAICompatProvider) readSSE(resp *http.Response, ch chan<- StreamChun
 		if delta.Usage != nil {
 			usage.PromptTokens = delta.Usage.PromptTokens
 			usage.CompletionTokens = delta.Usage.CompletionTokens
+			usage.Cost = delta.Usage.Cost
 			if delta.Usage.PromptTokensDetails != nil {
 				usage.CachedPromptTokens = delta.Usage.PromptTokensDetails.CachedTokens
 			}

internal/llm/router.go

@@ -340,16 +340,15 @@ func (r *Router) SetClassifierMinLen(n int) {
 }
 
 func (r *Router) Chat(ctx context.Context, messages []Message, systemPrompt string, tools []Tool) (Response, error) {
-	provider := r.pick(ctx, messages)
-	primaryKey := r.keyFor(provider)
+	provider, role := r.pick(ctx, messages)
 	r.mu.Lock()
 	r.lastRouted = provider.Name()
-	r.lastRoutedKey = primaryKey
+	r.lastRoutedKey = r.keyFor(provider)
 	r.mu.Unlock()
 
 	start := time.Now()
 	resp, err := provider.Chat(ctx, messages, systemPrompt, tools)
-	r.recordUsage(ctx, provider, primaryKey, resp, err, time.Since(start))
+	r.recordUsage(ctx, provider, role, resp, err, time.Since(start))
 
 	if err != nil && isUnavailable(err) {
 		// Build fallback chain: override → default → fallback.
@@ -403,6 +402,7 @@ func (r *Router) recordUsage(ctx context.Context, p Provider, role string, resp
 		CompletionTokens:   resp.Usage.CompletionTokens,
 		CachedPromptTokens: resp.Usage.CachedPromptTokens,
 		ReasoningTokens:    resp.Usage.ReasoningTokens,
+		Cost:               resp.Usage.Cost,
 		LatencyMs:          int(latency / time.Millisecond),
 		Success:            callErr == nil,
 		ErrorClass:         ClassifyErrorClass(callErr),
@@ -435,27 +435,26 @@ func splitProviderName(name string) (provider, model string) {
 // ChatStream returns a streaming channel if the current provider supports it.
 // Falls back to wrapping a synchronous Chat() in a single-chunk channel.
 func (r *Router) ChatStream(ctx context.Context, messages []Message, systemPrompt string, tools []Tool) (<-chan StreamChunk, error) {
-	provider := r.pick(ctx, messages)
-	primaryKey := r.keyFor(provider)
+	provider, role := r.pick(ctx, messages)
 	r.mu.Lock()
 	r.lastRouted = provider.Name()
-	r.lastRoutedKey = primaryKey
+	r.lastRoutedKey = r.keyFor(provider)
 	r.mu.Unlock()
 	if sp, ok := provider.(StreamProvider); ok {
 		ch, err := sp.ChatStream(ctx, messages, systemPrompt, tools)
 		if err != nil {
 			// Even a start-of-stream failure deserves a usage record with
 			// error_class set so dashboards see it.
-			r.recordUsage(ctx, provider, primaryKey, Response{}, err, 0)
+			r.recordUsage(ctx, provider, role, Response{}, err, 0)
 			if isUnavailable(err) {
 				return r.syncFallbackStream(ctx, provider, messages, systemPrompt, tools, err)
 			}
 			return nil, err
 		}
-		return r.instrumentedStream(ctx, provider, primaryKey, ch), nil
+		return r.instrumentedStream(ctx, provider, role, ch), nil
 	}
 	// Provider does not stream — wrap synchronous call.
-	return r.syncStream(ctx, provider, messages, systemPrompt, tools)
+	return r.syncStream(ctx, provider, role, messages, systemPrompt, tools)
 }
 
 // instrumentedStream tees the provider's stream to the caller and records a
@@ -484,8 +483,7 @@ func (r *Router) instrumentedStream(ctx context.Context, provider Provider, role
 // syncStream wraps a synchronous Chat() call in a channel. Usage is recorded
 // via the same path as Router.Chat so streaming callers that hit non-stream
 // providers still produce UsageLog rows.
-func (r *Router) syncStream(ctx context.Context, provider Provider, messages []Message, systemPrompt string, tools []Tool) (<-chan StreamChunk, error) {
-	role := r.keyFor(provider)
+func (r *Router) syncStream(ctx context.Context, provider Provider, role string, messages []Message, systemPrompt string, tools []Tool) (<-chan StreamChunk, error) {
 	start := time.Now()
 	resp, err := provider.Chat(ctx, messages, systemPrompt, tools)
 	r.recordUsage(ctx, provider, role, resp, err, time.Since(start))
@@ -522,21 +520,22 @@ func (r *Router) syncFallbackStream(ctx context.Context, failed Provider, messag
 			r.recordUsage(ctx, next, "fallback", Response{}, err, 0)
 		}
 		// Otherwise sync.
-		return r.syncStream(ctx, next, messages, systemPrompt, tools)
+		return r.syncStream(ctx, next, "fallback", messages, systemPrompt, tools)
 	}
 	return nil, origErr
 }
 
 // SupportsStreaming returns true if the currently active provider implements StreamProvider.
 func (r *Router) SupportsStreaming() bool {
-	provider := r.pick(context.Background(), nil)
+	provider, _ := r.pick(context.Background(), nil)
 	_, ok := provider.(StreamProvider)
 	return ok
 }
 
 // Name returns the name of the currently active provider (respecting override).
 func (r *Router) Name() string {
-	return r.pick(context.Background(), nil).Name()
+	p, _ := r.pick(context.Background(), nil)
+	return p.Name()
 }
 
 // SetOverride sets a named model override. Pass "" to clear. Returns error if name is unknown.
@@ -590,10 +589,16 @@ func (r *Router) ProviderNames() []string {
 	return names
 }
 
-func (r *Router) pick(ctx context.Context, messages []Message) Provider {
+// pick selects the provider for this request AND returns the logical routing
+// role that drove the decision (simple/default/complex/multimodal/override/
+// tool-continuation). Role is what ends up in usage_log — conceptually
+// useful for analytics. Separate from the provider's slot key (e.g. the same
+// "simple" role may be backed by different slot names across deployments).
+func (r *Router) pick(ctx context.Context, messages []Message) (Provider, string) {
 	r.mu.RLock()
 	cfg := r.cfg
 	override := r.override
+	lastRoutedKey := r.lastRoutedKey
 	r.mu.RUnlock()
 
 	multimodal := hasMultimodalContent(messages)
@@ -602,7 +607,7 @@ func (r *Router) pick(ctx context.Context, messages []Message) Provider {
 		if p := r.get(override); p != nil {
 			if !multimodal || supportsVision(p) {
 				slog.Info("routing", "reason", "override", "provider", p.Name())
-				return p
+				return p, "override"
 			}
 			// Override doesn't support vision — fall through to multimodal
 		}
@@ -612,23 +617,23 @@ func (r *Router) pick(ctx context.Context, messages []Message) Provider {
 	if multimodal {
 		if p := r.get(cfg.Simple); p != nil && supportsVision(p) {
 			slog.Info("routing", "reason", "simple+vision", "provider", p.Name())
-			return p
+			return p, "simple"
 		}
 		if p := r.get(cfg.Default); p != nil && supportsVision(p) {
 			slog.Info("routing", "reason", "default+vision", "provider", p.Name())
-			return p
+			return p, "default"
 		}
 		if p := r.get(cfg.Multimodal); p != nil {
 			slog.Info("routing", "reason", "multimodal", "provider", p.Name())
-			return p
+			return p, "multimodal"
 		}
 	}
 
 	// Tool continuation — keep using the same provider that started the tool loop.
-	if hasToolMessages(messages) && r.lastRoutedKey != "" {
-		if last := r.get(r.lastRoutedKey); last != nil {
+	if hasToolMessages(messages) && lastRoutedKey != "" {
+		if last := r.get(lastRoutedKey); last != nil {
 			slog.Info("routing", "reason", "tool-continuation", "provider", last.Name())
-			return last
+			return last, "tool-continuation"
 		}
 	}
 
@@ -644,12 +649,12 @@ func (r *Router) pick(ctx context.Context, messages []Message) Provider {
 			case 1:
 				if p := r.get(cfg.Simple); p != nil {
 					slog.Info("routing", "reason", "classifier→simple", "level", 1, "provider", p.Name())
-					return p
+					return p, "simple"
 				}
 			case 3:
 				if p := r.get(cfg.Complex); p != nil {
 					slog.Info("routing", "reason", "classifier→complex", "level", 3, "provider", p.Name())
-					return p
+					return p, "complex"
 				}
 			}
 			// level 2 or fallback → default
@@ -658,13 +663,13 @@ func (r *Router) pick(ctx context.Context, messages []Message) Provider {
 
 	if p := r.get(cfg.Default); p != nil {
 		slog.Info("routing", "reason", "default", "provider", p.Name())
-		return p
+		return p, "default"
 	}
 	// Should never happen if config is valid
 	for _, p := range r.providers {
-		return p
+		return p, "default"
 	}
-	return nil
+	return nil, ""
 }
 
 func (r *Router) get(key string) Provider {

internal/llm/usage.go

@@ -21,6 +21,7 @@ type UsageLog struct {
 	CompletionTokens   int
 	CachedPromptTokens int // subset of PromptTokens that hit provider's prompt cache (Anthropic/OpenAI)
 	ReasoningTokens    int // for thinking-enabled models: tokens spent on internal reasoning (billed as completion but semantically distinct)
+	Cost               float64 // USD, authoritative per-request cost reported by the provider (OpenRouter's usage.cost). 0 when the provider doesn't surface this.
 	LatencyMs          int
 	Success            bool
 	ErrorClass         string // "" / "rate_limit" / "5xx" / "network" / "timeout" / "other"
@@ -45,6 +46,7 @@ type Usage struct {
 	CompletionTokens   int
 	CachedPromptTokens int
 	ReasoningTokens    int
+	Cost               float64 // USD (OpenRouter `usage.cost`); 0 when provider doesn't report it
 	RequestID          string
 }
 

internal/store/memory.go

@@ -33,7 +33,7 @@ func (m *Memory) GetHistory(chatID int64) []llm.Message {
 	return result
 }
 
-func (m *Memory) AddMessage(chatID int64, msg llm.Message) {
+func (m *Memory) AddMessage(chatID int64, msg llm.Message) int64 {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 
@@ -42,6 +42,7 @@ func (m *Memory) AddMessage(chatID int64, msg llm.Message) {
 	if len(m.sessions[chatID]) > maxHistory {
 		m.sessions[chatID] = m.sessions[chatID][len(m.sessions[chatID])-maxHistory:]
 	}
+	return 0 // memory backend has no stable IDs
 }
 
 func (m *Memory) ClearHistory(chatID int64) {

internal/store/postgres.go

@@ -86,6 +86,7 @@ func (p *Postgres) migrate(ctx context.Context) error {
 			completion_tokens    INTEGER     NOT NULL DEFAULT 0,
 			cached_prompt_tokens INTEGER     NOT NULL DEFAULT 0,
 			reasoning_tokens     INTEGER     NOT NULL DEFAULT 0,
+			cost_usd             DOUBLE PRECISION NOT NULL DEFAULT 0,
 			latency_ms           INTEGER     NOT NULL DEFAULT 0,
 			success              BOOLEAN     NOT NULL DEFAULT TRUE,
 			error_class          TEXT        NOT NULL DEFAULT '',
@@ -94,6 +95,7 @@ func (p *Postgres) migrate(ctx context.Context) error {
 			user_message_id      BIGINT,
 			assistant_message_id BIGINT
 		)`,
+		`ALTER TABLE usage_log ADD COLUMN IF NOT EXISTS cost_usd DOUBLE PRECISION NOT NULL DEFAULT 0`,
 		`CREATE INDEX IF NOT EXISTS idx_usage_ts_model ON usage_log(ts, model_id)`,
 		`CREATE INDEX IF NOT EXISTS idx_usage_chat_ts  ON usage_log(chat_id, ts)`,
 		`CREATE INDEX IF NOT EXISTS idx_usage_user_msg ON usage_log(user_message_id)`,
@@ -214,22 +216,26 @@ func (p *Postgres) GetHistory(chatID int64) []llm.Message {
 	return reverseMessages(scanMessagesPg(rows))
 }
 
-func (p *Postgres) AddMessage(chatID int64, msg llm.Message) {
+func (p *Postgres) AddMessage(chatID int64, msg llm.Message) int64 {
 	ctx := context.Background()
 	p.maybeSessionBreak(ctx, chatID, msg.Role)
 	tcJSON, tcID := encodeToolFields(msg)
 	partsJSON := encodePartsJSON(msg.Parts)
 
-	_, err := p.pool.Exec(ctx, `
+	var id int64
+	err := p.pool.QueryRow(ctx, `
 		INSERT INTO messages (chat_id, role, content, parts, tool_calls, tool_call_id)
-		VALUES ($1, $2, $3, $4, $5, $6)`,
-		chatID, msg.Role, msg.Content, partsJSON, tcJSON, tcID)
+		VALUES ($1, $2, $3, $4, $5, $6)
+		RETURNING id`,
+		chatID, msg.Role, msg.Content, partsJSON, tcJSON, tcID).Scan(&id)
 	if err != nil {
 		slog.Error("pg AddMessage failed", "chat_id", chatID, "role", msg.Role, "content_len", len(msg.Content), "err", err)
+		return 0
 	}
+	return id
 }
 
-func (p *Postgres) AddMessageWithEmbedding(chatID int64, msg llm.Message, emb []float32) {
+func (p *Postgres) AddMessageWithEmbedding(chatID int64, msg llm.Message, emb []float32) int64 {
 	ctx := context.Background()
 	p.maybeSessionBreak(ctx, chatID, msg.Role)
 	tcJSON, tcID := encodeToolFields(msg)
@@ -240,13 +246,17 @@ func (p *Postgres) AddMessageWithEmbedding(chatID int64, msg llm.Message, emb []
 		embBlob = floatsToBlob(emb)
 	}
 
-	_, err := p.pool.Exec(ctx, `
+	var id int64
+	err := p.pool.QueryRow(ctx, `
 		INSERT INTO messages (chat_id, role, content, parts, tool_calls, tool_call_id, embedding)
-		VALUES ($1, $2, $3, $4, $5, $6, $7)`,
-		chatID, msg.Role, msg.Content, partsJSON, tcJSON, tcID, embBlob)
+		VALUES ($1, $2, $3, $4, $5, $6, $7)
+		RETURNING id`,
+		chatID, msg.Role, msg.Content, partsJSON, tcJSON, tcID, embBlob).Scan(&id)
 	if err != nil {
 		slog.Error("pg AddMessageWithEmbedding failed", "chat_id", chatID, "role", msg.Role, "content_len", len(msg.Content), "err", err)
+		return 0
 	}
+	return id
 }
 
 func (p *Postgres) maybeSessionBreak(ctx context.Context, chatID int64, role string) {
@@ -642,13 +652,13 @@ func (p *Postgres) PutUsage(ctx context.Context, u llm.UsageLog) (int64, error)
 		INSERT INTO usage_log (
 			provider, model_id, role, chat_id,
 			prompt_tokens, completion_tokens, cached_prompt_tokens, reasoning_tokens,
-			latency_ms, success, error_class, request_id, tool_call_count,
+			cost_usd, latency_ms, success, error_class, request_id, tool_call_count,
 			user_message_id, assistant_message_id
-		) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15)
+		) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16)
 		RETURNING id`,
 		u.Provider, u.ModelID, u.Role, u.ChatID,
 		u.PromptTokens, u.CompletionTokens, u.CachedPromptTokens, u.ReasoningTokens,
-		u.LatencyMs, u.Success, u.ErrorClass, u.RequestID, u.ToolCallCount,
+		u.Cost, u.LatencyMs, u.Success, u.ErrorClass, u.RequestID, u.ToolCallCount,
 		u.UserMessageID, u.AssistantMessageID,
 	).Scan(&id)
 	if err != nil {