db

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 21, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Index

Constants

View Source 
const (

	// DefaultMessageLimit is the default number of messages returned.
	DefaultMessageLimit = 100
	// MaxMessageLimit is the maximum number of messages returned.
	MaxMessageLimit = 1000
)
View Source 
const (
	DefaultSearchLimit = 50
	MaxSearchLimit     = 500
)
View Source 
const (
	// DefaultSessionLimit is the default number of sessions returned.
	DefaultSessionLimit = 200
	// MaxSessionLimit is the maximum number of sessions returned.
	MaxSessionLimit = 500
)

Variables

View Source 
var ErrInvalidCursor = errors.New("invalid cursor")

ErrInvalidCursor is returned when a cursor cannot be decoded or verified.

Functions

This section is empty.

Types

type ActivityEntry 

type ActivityEntry struct {
	Date              string         `json:"date"`
	Sessions          int            `json:"sessions"`
	Messages          int            `json:"messages"`
	UserMessages      int            `json:"user_messages"`
	AssistantMessages int            `json:"assistant_messages"`
	ToolCalls         int            `json:"tool_calls"`
	ThinkingMessages  int            `json:"thinking_messages"`
	ByAgent           map[string]int `json:"by_agent"`
}

ActivityEntry is one time bucket in the activity timeline.

type ActivityResponse 

type ActivityResponse struct {
	Granularity string          `json:"granularity"`
	Series      []ActivityEntry `json:"series"`
}

ActivityResponse wraps the activity series.

type AgentSummary 

type AgentSummary struct {
	Sessions int `json:"sessions"`
	Messages int `json:"messages"`
}

AgentSummary holds per-agent counts for the summary.

type AnalyticsFilter 

type AnalyticsFilter struct {
	From      string // ISO date YYYY-MM-DD, inclusive
	To        string // ISO date YYYY-MM-DD, inclusive
	Machine   string // optional machine filter
	Project   string // optional project filter
	Timezone  string // IANA timezone for day bucketing
	DayOfWeek *int   // nil = all, 0=Mon, 6=Sun (ISO)
	Hour      *int   // nil = all, 0-23
}

AnalyticsFilter is the shared filter for all analytics queries.

func (AnalyticsFilter) HasTimeFilter 

func (f AnalyticsFilter) HasTimeFilter() bool

HasTimeFilter returns true when hour-of-day or day-of-week filtering is active.

type AnalyticsSummary 

type AnalyticsSummary struct {
	TotalSessions  int                      `json:"total_sessions"`
	TotalMessages  int                      `json:"total_messages"`
	ActiveProjects int                      `json:"active_projects"`
	ActiveDays     int                      `json:"active_days"`
	AvgMessages    float64                  `json:"avg_messages"`
	MedianMessages int                      `json:"median_messages"`
	P90Messages    int                      `json:"p90_messages"`
	MostActive     string                   `json:"most_active_project"`
	Concentration  float64                  `json:"concentration"`
	Agents         map[string]*AgentSummary `json:"agents"`
}

AnalyticsSummary is the response for the summary endpoint.

type DB 

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

DB manages a write connection and a read-only pool.

func Open 

func Open(path string) (*DB, error)

Open creates or opens a SQLite database at the given path. It configures WAL mode, mmap, and returns a DB with separate writer and reader connections.

func (*DB) Close 

func (db *DB) Close() error

Close closes both writer and reader connections.

func (*DB) DecodeCursor 

func (db *DB) DecodeCursor(s string) (SessionCursor, error)

DecodeCursor parses a base64-encoded cursor string.

func (*DB) DeleteSession 

func (db *DB) DeleteSession(id string) error

DeleteSession removes a session and its messages (cascading).

func (*DB) DeleteSessionMessages 

func (db *DB) DeleteSessionMessages(sessionID string) error

DeleteSessionMessages removes all messages for a session.

func (*DB) DeleteSessions 

func (db *DB) DeleteSessions(ids []string) (int, error)

DeleteSessions removes multiple sessions by ID in a single transaction. Batches DELETEs in groups of 500 to stay under SQLite variable limits. Returns count of deleted rows.

func (*DB) EncodeCursor 

func (db *DB) EncodeCursor(endedAt, id string, total ...int) string

EncodeCursor returns a base64-encoded cursor string.

func (*DB) FindPruneCandidates 

func (db *DB) FindPruneCandidates(
	f PruneFilter,
) ([]Session, error)

FindPruneCandidates returns sessions matching all filter criteria. Returns full Session rows including file metadata.

func (*DB) GetAllMessages 

func (db *DB) GetAllMessages(
	ctx context.Context, sessionID string,
) ([]Message, error)

GetAllMessages returns all messages for a session ordered by ordinal.

func (*DB) GetAnalyticsActivity 

func (db *DB) GetAnalyticsActivity(
	ctx context.Context, f AnalyticsFilter,
	granularity string,
) (ActivityResponse, error)

GetAnalyticsActivity returns session/message counts grouped by time bucket.

func (*DB) GetAnalyticsHeatmap 

func (db *DB) GetAnalyticsHeatmap(
	ctx context.Context, f AnalyticsFilter,
	metric string,
) (HeatmapResponse, error)

GetAnalyticsHeatmap returns daily counts with intensity levels.

func (*DB) GetAnalyticsHourOfWeek 

func (db *DB) GetAnalyticsHourOfWeek(
	ctx context.Context, f AnalyticsFilter,
) (HourOfWeekResponse, error)

GetAnalyticsHourOfWeek returns message counts bucketed by day-of-week and hour-of-day in the user's timezone.

func (*DB) GetAnalyticsProjects 

func (db *DB) GetAnalyticsProjects(
	ctx context.Context, f AnalyticsFilter,
) (ProjectsAnalyticsResponse, error)

GetAnalyticsProjects returns per-project analytics.

func (*DB) GetAnalyticsSessionShape 

func (db *DB) GetAnalyticsSessionShape(
	ctx context.Context, f AnalyticsFilter,
) (SessionShapeResponse, error)

GetAnalyticsSessionShape returns distribution histograms for session length, duration, and autonomy ratio.

func (*DB) GetAnalyticsSummary 

func (db *DB) GetAnalyticsSummary(
	ctx context.Context, f AnalyticsFilter,
) (AnalyticsSummary, error)

GetAnalyticsSummary returns aggregate statistics.

func (*DB) GetAnalyticsTools 

func (db *DB) GetAnalyticsTools(
	ctx context.Context, f AnalyticsFilter,
) (ToolsAnalyticsResponse, error)

GetAnalyticsTools returns tool usage analytics aggregated from the tool_calls table.

func (*DB) GetAnalyticsTopSessions 

func (db *DB) GetAnalyticsTopSessions(
	ctx context.Context, f AnalyticsFilter, metric string,
) (TopSessionsResponse, error)

GetAnalyticsTopSessions returns the top 10 sessions by the given metric ("messages" or "duration") within the filter.

func (*DB) GetAnalyticsVelocity 

func (db *DB) GetAnalyticsVelocity(
	ctx context.Context, f AnalyticsFilter,
) (VelocityResponse, error)

GetAnalyticsVelocity computes turn cycle, first response, and throughput metrics with breakdowns by agent and complexity.

func (*DB) GetMachines 

func (db *DB) GetMachines(
	ctx context.Context,
) ([]string, error)

GetMachines returns distinct machine names.

func (*DB) GetMessageByOrdinal 

func (db *DB) GetMessageByOrdinal(
	sessionID string, ordinal int,
) (*Message, error)

GetMessageByOrdinal returns a single message by session ID and ordinal.

func (*DB) GetMessages 

func (db *DB) GetMessages(
	ctx context.Context,
	sessionID string, from, limit int, asc bool,
) ([]Message, error)

GetMessages returns paginated messages for a session. from: starting ordinal (inclusive) limit: max messages to return asc: true for ascending ordinal order, false for descending

func (*DB) GetMinimap 

func (db *DB) GetMinimap(
	ctx context.Context, sessionID string,
) ([]MinimapEntry, error)

GetMinimap returns lightweight metadata for all messages in a session.

func (*DB) GetMinimapFrom 

func (db *DB) GetMinimapFrom(
	ctx context.Context, sessionID string, from int,
) ([]MinimapEntry, error)

GetMinimapFrom returns lightweight metadata for messages in a session starting at ordinal >= from.

func (*DB) GetProjects 

func (db *DB) GetProjects(
	ctx context.Context,
) ([]ProjectInfo, error)

GetProjects returns project names with session counts.

func (*DB) GetSession 

func (db *DB) GetSession(
	ctx context.Context, id string,
) (*Session, error)

GetSession returns a single session by ID.

func (*DB) GetSessionFileInfo 

func (db *DB) GetSessionFileInfo(
	id string,
) (size int64, hash string, ok bool)

GetSessionFileInfo returns file_size and file_hash for a session.

func (*DB) GetSessionFull 

func (db *DB) GetSessionFull(
	ctx context.Context, id string,
) (*Session, error)

GetSessionFull returns a single session by ID with all file metadata.

func (*DB) GetStats 

func (db *DB) GetStats(ctx context.Context) (Stats, error)

GetStats returns O(1) statistics from the stats table, supplemented with project/machine counts from indexes.

func (*DB) HasFTS 

func (db *DB) HasFTS() bool

HasFTS checks if Full Text Search is available.

func (*DB) InsertMessages 

func (db *DB) InsertMessages(msgs []Message) error

InsertMessages batch-inserts messages for a session.

func (*DB) ListSessions 

func (db *DB) ListSessions(
	ctx context.Context, f SessionFilter,
) (SessionPage, error)

ListSessions returns a cursor-paginated list of sessions.

func (*DB) MessageCount 

func (db *DB) MessageCount(sessionID string) (int, error)

MessageCount returns the number of messages for a session.

func (*DB) Reader 

func (db *DB) Reader() *sql.DB

Reader returns the read-only connection pool.

func (*DB) ReplaceSessionMessages 

func (db *DB) ReplaceSessionMessages(
	sessionID string, msgs []Message,
) error

ReplaceSessionMessages deletes existing and inserts new messages in a single transaction.

func (*DB) Search 

func (db *DB) Search(
	ctx context.Context, f SearchFilter,
) (SearchPage, error)

Search performs FTS5 full-text search across messages.

func (*DB) SetCursorSecret 

func (db *DB) SetCursorSecret(secret []byte)

SetCursorSecret updates the secret key used for cursor signing.

func (*DB) Update 

func (db *DB) Update(fn func(tx *sql.Tx) error) error

Update executes fn within a write lock and transaction. The transaction is committed if fn returns nil, rolled back otherwise.

func (*DB) UpsertSession 

func (db *DB) UpsertSession(s Session) error

UpsertSession inserts or updates a session.

type DistributionBucket 

type DistributionBucket struct {
	Label string `json:"label"`
	Count int    `json:"count"`
}

DistributionBucket is a labeled count for histogram display.

type HeatmapEntry 

type HeatmapEntry struct {
	Date  string `json:"date"`
	Value int    `json:"value"`
	Level int    `json:"level"`
}

HeatmapEntry is one day in the heatmap calendar.

type HeatmapLevels 

type HeatmapLevels struct {
	L1 int `json:"l1"`
	L2 int `json:"l2"`
	L3 int `json:"l3"`
	L4 int `json:"l4"`
}

HeatmapLevels defines the quartile thresholds for levels 1-4.

type HeatmapResponse 

type HeatmapResponse struct {
	Metric  string         `json:"metric"`
	Entries []HeatmapEntry `json:"entries"`
	Levels  HeatmapLevels  `json:"levels"`
}

HeatmapResponse wraps the heatmap data.

type HourOfWeekCell 

type HourOfWeekCell struct {
	DayOfWeek int `json:"day_of_week"` // 0=Mon, 6=Sun
	Hour      int `json:"hour"`        // 0-23
	Messages  int `json:"messages"`
}

HourOfWeekCell is one cell in the 7x24 hour-of-week grid.

type HourOfWeekResponse 

type HourOfWeekResponse struct {
	Cells []HourOfWeekCell `json:"cells"`
}

HourOfWeekResponse wraps the hour-of-week heatmap data.

type Message 

type Message struct {
	ID            int64      `json:"id"`
	SessionID     string     `json:"session_id"`
	Ordinal       int        `json:"ordinal"`
	Role          string     `json:"role"`
	Content       string     `json:"content"`
	Timestamp     string     `json:"timestamp"`
	HasThinking   bool       `json:"has_thinking"`
	HasToolUse    bool       `json:"has_tool_use"`
	ContentLength int        `json:"content_length"`
	ToolCalls     []ToolCall `json:"-"` // transient, not a DB column
}

Message represents a row in the messages table.

type MinimapEntry 

type MinimapEntry struct {
	Ordinal       int    `json:"ordinal"`
	Role          string `json:"role"`
	ContentLength int    `json:"content_length"`
	HasThinking   bool   `json:"has_thinking"`
	HasToolUse    bool   `json:"has_tool_use"`
}

MinimapEntry is a lightweight message summary for minimap rendering.

func SampleMinimap 

func SampleMinimap(
	entries []MinimapEntry, max int,
) []MinimapEntry

SampleMinimap downsamples entries to at most max points while preserving ordering and both endpoints.

type Percentiles 

type Percentiles struct {
	P50 float64 `json:"p50"`
	P90 float64 `json:"p90"`
}

Percentiles holds p50 and p90 values.

type ProjectAnalytics 

type ProjectAnalytics struct {
	Name           string         `json:"name"`
	Sessions       int            `json:"sessions"`
	Messages       int            `json:"messages"`
	FirstSession   string         `json:"first_session"`
	LastSession    string         `json:"last_session"`
	AvgMessages    float64        `json:"avg_messages"`
	MedianMessages int            `json:"median_messages"`
	Agents         map[string]int `json:"agents"`
	DailyTrend     float64        `json:"daily_trend"`
}

ProjectAnalytics holds analytics for a single project.

type ProjectInfo 

type ProjectInfo struct {
	Name         string `json:"name"`
	SessionCount int    `json:"session_count"`
}

ProjectInfo holds a project name and its session count.

type ProjectsAnalyticsResponse 

type ProjectsAnalyticsResponse struct {
	Projects []ProjectAnalytics `json:"projects"`
}

ProjectsAnalyticsResponse wraps the projects list.

type PruneFilter 

type PruneFilter struct {
	Project      string // substring match (LIKE '%x%')
	MaxMessages  *int   // user messages <= N (nil = no filter)
	Before       string // ended_at < date (YYYY-MM-DD)
	FirstMessage string // first_message LIKE 'prefix%'
}

PruneFilter defines criteria for finding sessions to prune. Filters combine with AND. At least one must be set.

func (PruneFilter) HasFilters 

func (f PruneFilter) HasFilters() bool

HasFilters reports whether at least one filter is set.

type SearchFilter 

type SearchFilter struct {
	Query   string
	Project string
	Cursor  int // offset for pagination
	Limit   int
}

SearchFilter specifies search parameters.

type SearchPage 

type SearchPage struct {
	Results    []SearchResult `json:"results"`
	NextCursor int            `json:"next_cursor,omitempty"`
}

SearchPage holds paginated search results.

type SearchResult 

type SearchResult struct {
	SessionID string  `json:"session_id"`
	Project   string  `json:"project"`
	Ordinal   int     `json:"ordinal"`
	Role      string  `json:"role"`
	Timestamp string  `json:"timestamp"`
	Snippet   string  `json:"snippet"`
	Rank      float64 `json:"rank"`
}

SearchResult holds a message match with session context.

type Session 

type Session struct {
	ID           string  `json:"id"`
	Project      string  `json:"project"`
	Machine      string  `json:"machine"`
	Agent        string  `json:"agent"`
	FirstMessage *string `json:"first_message"`
	StartedAt    *string `json:"started_at"`
	EndedAt      *string `json:"ended_at"`
	MessageCount int     `json:"message_count"`
	FilePath     *string `json:"file_path,omitempty"`
	FileSize     *int64  `json:"file_size,omitempty"`
	FileMtime    *int64  `json:"file_mtime,omitempty"`
	FileHash     *string `json:"file_hash,omitempty"`
	CreatedAt    string  `json:"created_at"`
}

Session represents a row in the sessions table.

type SessionCursor 

type SessionCursor struct {
	EndedAt string `json:"e"`
	ID      string `json:"i"`
	Total   int    `json:"t,omitempty"`
}

SessionCursor is the opaque pagination token.

type SessionFilter 

type SessionFilter struct {
	Project     string
	Machine     string
	Agent       string
	Date        string // exact date YYYY-MM-DD
	DateFrom    string // range start (inclusive)
	DateTo      string // range end (inclusive)
	MinMessages int    // message_count >= N (0 = no filter)
	MaxMessages int    // message_count <= N (0 = no filter)
	Cursor      string // opaque cursor from previous page
	Limit       int
}

SessionFilter specifies how to query sessions.

type SessionPage 

type SessionPage struct {
	Sessions   []Session `json:"sessions"`
	NextCursor string    `json:"next_cursor,omitempty"`
	Total      int       `json:"total"`
}

SessionPage is a page of session results.

type SessionShapeResponse 

type SessionShapeResponse struct {
	Count                int                  `json:"count"`
	LengthDistribution   []DistributionBucket `json:"length_distribution"`
	DurationDistribution []DistributionBucket `json:"duration_distribution"`
	AutonomyDistribution []DistributionBucket `json:"autonomy_distribution"`
}

SessionShapeResponse holds distribution histograms for session characteristics.

type Stats 

type Stats struct {
	SessionCount int `json:"session_count"`
	MessageCount int `json:"message_count"`
	ProjectCount int `json:"project_count"`
	MachineCount int `json:"machine_count"`
}

Stats holds database statistics from the trigger-maintained table.

type ToolAgentBreakdown 

type ToolAgentBreakdown struct {
	Agent      string              `json:"agent"`
	Total      int                 `json:"total"`
	Categories []ToolCategoryCount `json:"categories"`
}

ToolAgentBreakdown holds tool usage breakdown for one agent.

type ToolCall 

type ToolCall struct {
	MessageID int64
	SessionID string
	ToolName  string
	Category  string
}

ToolCall represents a single tool invocation stored in the tool_calls table.

type ToolCategoryCount 

type ToolCategoryCount struct {
	Category string  `json:"category"`
	Count    int     `json:"count"`
	Pct      float64 `json:"pct"`
}

ToolCategoryCount holds a count and percentage for one tool category.

type ToolTrendEntry 

type ToolTrendEntry struct {
	Date  string         `json:"date"`
	ByCat map[string]int `json:"by_category"`
}

ToolTrendEntry holds tool call counts for one time bucket.

type ToolsAnalyticsResponse 

type ToolsAnalyticsResponse struct {
	TotalCalls int                  `json:"total_calls"`
	ByCategory []ToolCategoryCount  `json:"by_category"`
	ByAgent    []ToolAgentBreakdown `json:"by_agent"`
	Trend      []ToolTrendEntry     `json:"trend"`
}

ToolsAnalyticsResponse wraps tool usage analytics.

type TopSession 

type TopSession struct {
	ID           string  `json:"id"`
	Project      string  `json:"project"`
	FirstMessage *string `json:"first_message"`
	MessageCount int     `json:"message_count"`
	DurationMin  float64 `json:"duration_min"`
}

TopSession holds summary info for a ranked session.

type TopSessionsResponse 

type TopSessionsResponse struct {
	Metric   string       `json:"metric"`
	Sessions []TopSession `json:"sessions"`
}

TopSessionsResponse wraps the top sessions list.

type VelocityBreakdown 

type VelocityBreakdown struct {
	Label    string           `json:"label"`
	Sessions int              `json:"sessions"`
	Overview VelocityOverview `json:"overview"`
}

VelocityBreakdown is velocity metrics for a subgroup.

type VelocityOverview 

type VelocityOverview struct {
	TurnCycleSec          Percentiles `json:"turn_cycle_sec"`
	FirstResponseSec      Percentiles `json:"first_response_sec"`
	MsgsPerActiveMin      float64     `json:"msgs_per_active_min"`
	CharsPerActiveMin     float64     `json:"chars_per_active_min"`
	ToolCallsPerActiveMin float64     `json:"tool_calls_per_active_min"`
}

VelocityOverview holds aggregate velocity metrics.

type VelocityResponse 

type VelocityResponse struct {
	Overall      VelocityOverview    `json:"overall"`
	ByAgent      []VelocityBreakdown `json:"by_agent"`
	ByComplexity []VelocityBreakdown `json:"by_complexity"`
}

VelocityResponse wraps overall and grouped velocity metrics.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.