feat(usage): usage_log schema + OpenRouter capture + router hook (Stage A.1)

First of three stages splitting the admin-UI umbrella task into
Usage+Cost infrastructure (A.1), remaining-provider capture (A.2), and
Usage/Cost admin sections (A.3).

What lands here:

* internal/llm/usage.go
  - UsageLog struct (one row per LLM call — agentic loops produce N rows
    sharing the same user_message_id)
  - UsageStore interface with PutUsage + UpdateAssistantMessageID
  - Usage struct attached to llm.Response, populated by providers that
    report token counts; zero-value otherwise
  - TurnMeta + WithTurnMeta/TurnMetaFrom context helpers for threading
    chat_id / user_message_id / role-hint from agent down to router
    without changing every provider's Chat signature
  - ClassifyErrorClass bucketing for dashboards (rate_limit / 5xx / 4xx
    / network / timeout / other)

* Schema in usage_log (SQLite migration + Postgres CREATE IF NOT EXISTS)
  - id, ts, provider, model_id, role, chat_id
  - prompt_tokens, completion_tokens, cached_prompt_tokens,
    reasoning_tokens (prompt caching + thinking overhead accounted
    from the start, per API reference)
  - latency_ms, success, error_class, request_id, tool_call_count
  - user_message_id, assistant_message_id (nullable FKs to messages.id)
  - indexes on (ts, model_id), (chat_id, ts), (user_message_id)

* Store implementations — PutUsage + UpdateAssistantMessageID for both
  SQLite and Postgres backends, wired through main.go via type assertion
  to llm.UsageStore (works with either backend the bot is configured to
  use).

* openai_compat.go — parse OpenRouter usage block including
  prompt_tokens_details.cached_tokens (Anthropic caching via bridge /
  OpenAI prompt caching) and completion_tokens_details.reasoning_tokens
  (thinking models). Also captures the provider's request id for
  cross-referencing with their dashboard when debugging a call.

* Router.Chat records a UsageLog row after every provider call (primary
  AND each fallback hop), best-effort with a 3s timeout on a background
  ctx so usage logging never blocks or fails a user request. Error
  class is auto-classified; turn meta is pulled from ctx when present.

Scope covered: OpenRouter traffic (~90% of real requests) is now
logged end-to-end with full token breakdown. Other providers (gemini /
claude_bridge / ollama / local) still land rows but with zero tokens
until their response parsers are updated — that's Stage A.2.

Tests added:
- ClassifyErrorClass bucket mapping (8 cases)
- TurnMeta round-trip through context
- rawChatResponse parses usage block + cached + reasoning + request_id
- SQLite round-trip: insert with all fields, backfill
  assistant_message_id, verify NULL handling for background tasks

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

Author: Alexey Panfilov

cmd/agent/main.go

@@ -197,6 +197,11 @@ func main() {
 	if err := router.LoadPersistedOverrides(); err != nil {
 		logger.Warn("failed to load routing overrides", "err", err)
 	}
+	// Wire usage log sink (best-effort: router tolerates nil store).
+	if us, ok := s.(llm.UsageStore); ok {
+		router.SetUsageStore(us)
+		logger.Info("usage logging enabled")
+	}
 	// Apply persisted per-slot OpenRouter model overrides (e.g. admin UI picked
 	// a different model last session). Pull caps from the store.
 	if orOverrides := router.TakePendingOpenRouterOverrides(); len(orOverrides) > 0 {

internal/llm/openai_compat.go

@@ -196,18 +196,35 @@ type rawToolFunctionDef struct {
 }
 
 type rawChatResponse struct {
+	ID      string `json:"id"` // provider request id (OpenRouter: "gen-...")
 	Choices []struct {
 		Message struct {
 			Content   string        `json:"content"`
 			ToolCalls []rawToolCall `json:"tool_calls"`
 		} `json:"message"`
 	} `json:"choices"`
+	Usage *rawUsage `json:"usage"`
 	Error *struct {
 		Message string `json:"message"`
 		Type    string `json:"type"`
 	} `json:"error"`
 }
 
+// rawUsage covers OpenAI-compatible usage fields plus the nested *_details
+// blocks that OpenRouter / Anthropic / OpenAI populate for prompt caching
+// and reasoning tokens.
+type rawUsage struct {
+	PromptTokens        int `json:"prompt_tokens"`
+	CompletionTokens    int `json:"completion_tokens"`
+	TotalTokens         int `json:"total_tokens"`
+	PromptTokensDetails *struct {
+		CachedTokens int `json:"cached_tokens"`
+	} `json:"prompt_tokens_details"`
+	CompletionTokensDetails *struct {
+		ReasoningTokens int `json:"reasoning_tokens"`
+	} `json:"completion_tokens_details"`
+}
+
 func (p *openAICompatProvider) Chat(ctx context.Context, messages []Message, systemPrompt string, tools []Tool) (Response, error) {
 	model, vision := p.snapshot()
 	rawMsgs := buildMessages(messages, systemPrompt, vision)
@@ -272,6 +289,19 @@ func (p *openAICompatProvider) Chat(ctx context.Context, messages []Message, sys
 			Arguments: tc.Function.Arguments,
 		})
 	}
+	if u := chatResp.Usage; u != nil {
+		result.Usage = Usage{
+			PromptTokens:     u.PromptTokens,
+			CompletionTokens: u.CompletionTokens,
+			RequestID:        chatResp.ID,
+		}
+		if u.PromptTokensDetails != nil {
+			result.Usage.CachedPromptTokens = u.PromptTokensDetails.CachedTokens
+		}
+		if u.CompletionTokensDetails != nil {
+			result.Usage.ReasoningTokens = u.CompletionTokensDetails.ReasoningTokens
+		}
+	}
 	return result, nil
 }
 

internal/llm/provider.go

@@ -54,6 +54,7 @@ type ToolCall struct {
 type Response struct {
 	Content   string
 	ToolCalls []ToolCall
+	Usage     Usage // populated by providers that report token counts; zero-value otherwise
 }
 
 type Provider interface {

internal/llm/router.go

@@ -69,6 +69,7 @@ type Router struct {
 	persistPath string // legacy: file for routing overrides. Read once on first start
 	//                   for migration, then the binary writes to the settings store.
 	settings      SettingsStore // primary persistence; DB-backed
+	usage         UsageStore    // optional; when set, Router records UsageLog after every call
 	lastRouted    string        // display name of last provider (for UI)
 	lastRoutedKey string        // map key of last provider (for tool continuation)
 	// Set by LoadPersistedOverrides; main.go drains via TakePendingOpenRouterOverrides
@@ -79,6 +80,14 @@ type Router struct {
 	logger     *slog.Logger
 }
 
+// SetUsageStore wires the UsageLog sink. Calls before Chat() is invoked take
+// effect on the next request; Chat() reads the field under r.mu.
+func (r *Router) SetUsageStore(u UsageStore) {
+	r.mu.Lock()
+	r.usage = u
+	r.mu.Unlock()
+}
+
 func NewRouter(providers map[string]Provider, cfg RouterConfig) *Router {
 	return &Router{
 		providers: providers,
@@ -332,12 +341,16 @@ 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)
 	r.mu.Lock()
 	r.lastRouted = provider.Name()
-	r.lastRoutedKey = r.keyFor(provider)
+	r.lastRoutedKey = primaryKey
 	r.mu.Unlock()
 
+	start := time.Now()
 	resp, err := provider.Chat(ctx, messages, systemPrompt, tools)
+	r.recordUsage(ctx, provider, primaryKey, resp, err, time.Since(start))
+
 	if err != nil && isUnavailable(err) {
 		// Build fallback chain: override → default → fallback.
 		// Skip providers already tried or equal to current.
@@ -354,7 +367,9 @@ func (r *Router) Chat(ctx context.Context, messages []Message, systemPrompt stri
 			if r.OnFallback != nil {
 				r.OnFallback(provider.Name(), next.Name())
 			}
+			fbStart := time.Now()
 			resp, err = next.Chat(ctx, messages, systemPrompt, tools)
+			r.recordUsage(ctx, next, "fallback", resp, err, time.Since(fbStart))
 			if err == nil || !isUnavailable(err) {
 				break
 			}
@@ -364,6 +379,59 @@ func (r *Router) Chat(ctx context.Context, messages []Message, systemPrompt stri
 	return resp, err
 }
 
+// recordUsage persists a UsageLog row for one LLM call. Runs best-effort —
+// errors are logged but never fail the request. Extracts turn meta from ctx
+// when present; falls back to 0s when absent.
+func (r *Router) recordUsage(ctx context.Context, p Provider, role string, resp Response, callErr error, latency time.Duration) {
+	r.mu.RLock()
+	store := r.usage
+	r.mu.RUnlock()
+	if store == nil {
+		return
+	}
+	meta, _ := TurnMetaFrom(ctx)
+	if meta.RoleHint != "" {
+		role = meta.RoleHint
+	}
+	provKind, modelID := splitProviderName(p.Name())
+	log := UsageLog{
+		Provider:           provKind,
+		ModelID:            modelID,
+		Role:               role,
+		ChatID:             meta.ChatID,
+		PromptTokens:       resp.Usage.PromptTokens,
+		CompletionTokens:   resp.Usage.CompletionTokens,
+		CachedPromptTokens: resp.Usage.CachedPromptTokens,
+		ReasoningTokens:    resp.Usage.ReasoningTokens,
+		LatencyMs:          int(latency / time.Millisecond),
+		Success:            callErr == nil,
+		ErrorClass:         ClassifyErrorClass(callErr),
+		RequestID:          resp.Usage.RequestID,
+		ToolCallCount:      len(resp.ToolCalls),
+	}
+	if meta.UserMessageID != 0 {
+		id := meta.UserMessageID
+		log.UserMessageID = &id
+	}
+	// Best-effort write with short timeout — usage logging must never block or
+	// fail a user request.
+	writeCtx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+	defer cancel()
+	if _, err := store.PutUsage(writeCtx, log); err != nil {
+		r.logger.Warn("usage log write failed", "err", err, "provider", provKind, "model", modelID)
+	}
+}
+
+// splitProviderName breaks a "provider/model" Name() into its parts. For
+// providers whose Name() does not contain a slash, provider = full name and
+// model = "".
+func splitProviderName(name string) (provider, model string) {
+	if i := strings.IndexByte(name, '/'); i >= 0 {
+		return name[:i], name[i+1:]
+	}
+	return name, ""
+}
+
 // 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) {

internal/llm/usage.go

@@ -0,0 +1,137 @@
+package llm
+
+import (
+	"context"
+	"time"
+)
+
+// UsageLog is a billing-grained record of a single LLM call. One record per
+// call, independent of the messages table — an agentic loop with N tool
+// iterations produces N records, all sharing the same UserMessageID.
+//
+// Schema lives in SQLite + Postgres migrations under usage_log.
+type UsageLog struct {
+	ID                 int64
+	Ts                 time.Time
+	Provider           string // "openrouter" / "gemini" / "claude_bridge" / "ollama" / "local"
+	ModelID            string // provider-specific model identifier at call time
+	Role               string // routing role chosen ("simple" / "default" / "complex" / "multimodal" / "compaction" / "classifier" / "fallback" / "override")
+	ChatID             int64
+	PromptTokens       int
+	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)
+	LatencyMs          int
+	Success            bool
+	ErrorClass         string // "" / "rate_limit" / "5xx" / "network" / "timeout" / "other"
+	RequestID          string // provider's request id (e.g. OpenRouter gen-xxxxx) — useful for cross-referencing with provider dashboards
+	ToolCallCount      int    // number of tool_calls in the response
+	UserMessageID      *int64 // FK to messages.id; NULL for background tasks (compaction, scheduled jobs)
+	AssistantMessageID *int64 // FK to messages.id; NULL except on the final successful call of a turn
+}
+
+// UsageStore persists UsageLog records and exposes aggregation queries used
+// by the admin UI (implemented in Stage A.3).
+type UsageStore interface {
+	PutUsage(ctx context.Context, u UsageLog) (int64, error)
+	UpdateAssistantMessageID(ctx context.Context, usageID, msgID int64) error
+}
+
+// Usage is a per-response token breakdown attached to Response. Providers
+// populate it when their API reports counts; zero-value otherwise. Router
+// copies these fields into UsageLog.
+type Usage struct {
+	PromptTokens       int
+	CompletionTokens   int
+	CachedPromptTokens int
+	ReasoningTokens    int
+	RequestID          string
+}
+
+// TurnMeta carries the conversation-layer identity (chat, user message id,
+// role) across layers so Router.Chat can tag UsageLog records without every
+// caller having to thread the data through function signatures.
+//
+// When absent, usage is still logged but with ChatID=0 / UserMessageID=nil.
+type TurnMeta struct {
+	ChatID        int64
+	UserMessageID int64 // 0 = not applicable (compaction, scheduled jobs)
+	// RoleHint overrides the role that Router would normally record. Used for
+	// classifier calls (bypass Router.pick, role="classifier") and compaction
+	// (role="compaction"). Empty = let Router decide.
+	RoleHint string
+}
+
+type turnMetaKey struct{}
+
+// WithTurnMeta returns a context carrying the supplied TurnMeta. Router's
+// usage logger reads this via TurnMetaFrom.
+func WithTurnMeta(ctx context.Context, m TurnMeta) context.Context {
+	return context.WithValue(ctx, turnMetaKey{}, m)
+}
+
+// TurnMetaFrom retrieves the TurnMeta put into ctx by WithTurnMeta.
+func TurnMetaFrom(ctx context.Context) (TurnMeta, bool) {
+	m, ok := ctx.Value(turnMetaKey{}).(TurnMeta)
+	return m, ok
+}
+
+// ClassifyErrorClass maps an error into a short bucket suitable for usage_log.
+// Unknown errors land in "other" so dashboards aren't polluted by one-off
+// messages. Returns "" when err is nil.
+func ClassifyErrorClass(err error) string {
+	if err == nil {
+		return ""
+	}
+	var apiErr *APIError
+	if ok := asAPIError(err, &apiErr); ok {
+		switch {
+		case apiErr.StatusCode == 429:
+			return "rate_limit"
+		case apiErr.StatusCode >= 500:
+			return "5xx"
+		case apiErr.StatusCode >= 400:
+			return "4xx"
+		}
+	}
+	msg := err.Error()
+	switch {
+	case contains(msg, "context deadline exceeded"):
+		return "timeout"
+	case contains(msg, "connection refused"), contains(msg, "no such host"), contains(msg, "i/o timeout"), contains(msg, "connection reset"):
+		return "network"
+	}
+	return "other"
+}
+
+// small helpers kept here to avoid an extra import of errors/strings in cold
+// paths of tests.
+func asAPIError(err error, target **APIError) bool {
+	for e := err; e != nil; {
+		if a, ok := e.(*APIError); ok {
+			*target = a
+			return true
+		}
+		type wrapped interface{ Unwrap() error }
+		if w, ok := e.(wrapped); ok {
+			e = w.Unwrap()
+			continue
+		}
+		return false
+	}
+	return false
+}
+
+func contains(s, sub string) bool {
+	return len(sub) > 0 && len(s) >= len(sub) && indexOf(s, sub) >= 0
+}
+
+func indexOf(s, sub string) int {
+	n, m := len(s), len(sub)
+	for i := 0; i+m <= n; i++ {
+		if s[i:i+m] == sub {
+			return i
+		}
+	}
+	return -1
+}