usage

Documentation

Overview

Package usage is the coding product's token and cost ledger. It is kept separate from any delivery mechanism: the ledger is written from the session event stream and read by whichever client asks for a report, so nothing here depends on HTTP.

Index

• type Event
• type EventPage
• type ModelSummary
• type Report
• type Store
  • func NewStore(path string) (*Store, error)
  • func (s *Store) Backfill(sessionID string, messages []agent.AgentMessage) error
  • func (s *Store) BackfillEntries(sessionID string, entries []transcript.Entry) error
  • func (s *Store) Events(provider, model string, since time.Time, offset, limit int) EventPage
  • func (s *Store) RecordEvent(sessionID string, event engine.Event) error
  • func (s *Store) Report(since time.Time) Report
• type Totals

Types

type Event

type Event struct {
	ID            string    `json:"id"`
	SessionID     string    `json:"sessionId"`
	Provider      string    `json:"provider"`
	Model         string    `json:"model"`
	ResponseModel string    `json:"responseModel,omitempty"`
	ResponseID    string    `json:"responseId,omitempty"`
	Timestamp     time.Time `json:"timestamp"`
	Usage         llm.Usage `json:"usage"`
}

Event is one billable provider response. It is stored independently from conversations so deleting a session does not rewrite usage history.

type EventPage

type EventPage struct {
	Events []Event `json:"events"`
	Total  int     `json:"total"`
	Limit  int     `json:"limit"`
	Offset int     `json:"offset"`
}

EventPage is a newest-first slice of individual provider requests.

type ModelSummary

type ModelSummary struct {
	Provider      string    `json:"provider"`
	Model         string    `json:"model"`
	Name          string    `json:"name"`
	ResponseModel string    `json:"responseModel,omitempty"`
	LastUsedAt    time.Time `json:"lastUsedAt"`
	Totals
}

ModelSummary groups usage by the requested provider and model.

type Report

type Report struct {
	Total       Totals         `json:"total"`
	Models      []ModelSummary `json:"models"`
	GeneratedAt time.Time      `json:"generatedAt"`
}

Report is an aggregate over a requested time range.

type Store

type Store struct {
	// contains filtered or unexported fields
}

Store is an append-only, deduplicated usage ledger.

func NewStore

func NewStore(path string) (*Store, error)

func (*Store) Backfill

func (s *Store) Backfill(sessionID string, messages []agent.AgentMessage) error

Backfill adds provider responses already present in a restored transcript. Stable event IDs make the operation safe to run on every startup.

func (*Store) BackfillEntries

func (s *Store) BackfillEntries(sessionID string, entries []transcript.Entry) error

BackfillEntries restores usage for both ordinary assistant responses and the direct model requests used to create compaction checkpoints.

func (*Store) Events

func (s *Store) Events(provider, model string, since time.Time, offset, limit int) EventPage

Events returns individual requests filtered by provider and model. Results are newest first and paginated so the usage page stays fast as the ledger grows.

func (*Store) RecordEvent

func (s *Store) RecordEvent(sessionID string, event engine.Event) error

RecordEvent persists one live MessageCompleted event. Empty usage records are ignored because some providers emit terminal metadata without billing.

func (*Store) Report

func (s *Store) Report(since time.Time) Report

Report aggregates a stable snapshot without holding the lock while sorting. A zero since value includes the complete ledger.

type Totals

type Totals struct {
	Requests     int64         `json:"requests"`
	Input        int64         `json:"input"`
	InputUnknown bool          `json:"inputUnknown,omitempty"`
	Output       int64         `json:"output"`
	CacheRead    int64         `json:"cacheRead"`
	CacheWrite   int64         `json:"cacheWrite"`
	TotalTokens  int64         `json:"totalTokens"`
	Cost         llm.UsageCost `json:"cost"`
}

Totals is an aggregate returned by the usage API.