sessionview

type AssetRef struct {
	ID          string    `json:"id" example:"ast_7c1e"`
	Name        string    `json:"name" example:"Q3 revenue by region"`
	ContentType string    `json:"content_type" example:"text/csv"`
	CreatedAt   time.Time `json:"created_at"`
}

type Detail struct {
	Summary
	Assets   []AssetRef      `json:"assets"`
	Insights []InsightRef    `json:"insights"`
	Timeline []TimelineEntry `json:"timeline"`
	// TimelineTotal is the session's full call count, which exceeds
	// len(Timeline) when the timeline is paged.
	TimelineTotal int `json:"timeline_total" example:"5"`
}

type Filter struct {
	// SessionID selects exactly one session. Set by Get; the list leaves
	// it empty.
	SessionID string
	UserID    string
	// Kind restricts to one id origin. The zero value matches every kind.
	Kind Kind
	// StartTime and EndTime bound the session's events, so a session is
	// listed when any of its calls falls in the window.
	StartTime *time.Time
	EndTime   *time.Time
	// HasAssets keeps only sessions that saved at least one asset.
	HasAssets bool
	// HasFailures keeps only sessions with at least one failed call.
	HasFailures bool
	Limit       int
	Offset      int
}

type InsightRef struct {
	ID        string    `json:"id" example:"ins_3a9f"`
	Category  string    `json:"category" example:"data_quality"`
	Text      string    `json:"text" example:"orders.amount is null for canceled rows."`
	Status    string    `json:"status" example:"pending"`
	CreatedAt time.Time `json:"created_at"`
}

type Kind string

type Match struct {
	SessionID    string
	Kind         Kind
	StartedAt    time.Time
	LastActiveAt time.Time
	CallCount    int
	FailureCount int
	// Purposes are the distinct reasons the session's calls stated. Empty on a
	// session whose calls were all ungated, which is then reachable only
	// through the names of what it produced.
	Purposes []string
	// AssetNames are the names of the assets the session saved, oldest first.
	AssetNames []string
	// Score is the lexical relevance of the session's document to the query.
	Score float64
}

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

type Reader interface {
	Store
	// Search ranks the caller's own sessions against a query.
	Search(ctx context.Context, q SearchQuery) ([]Match, error)
}

type Scope struct {
	SessionID string
	// UserID restricts the read to the calls that caller made. Empty is
	// unrestricted.
	UserID string
	// Limit and Offset page the timeline. They do not affect Get.
	Limit  int
	Offset int
}

type SearchQuery struct {
	// Text is the natural-language query, matched against the purposes the
	// session's calls stated and the names of the assets it saved.
	Text string
	// UserID scopes the search to the sessions that caller ran. A search with
	// no caller returns nothing rather than everyone's sessions.
	UserID string
	Limit  int
}

type Store interface {
	// List returns sessions matching the filter, most recently active
	// first.
	List(ctx context.Context, filter Filter) ([]Summary, error)
	// Count returns how many sessions match the filter, ignoring its
	// limit and offset.
	Count(ctx context.Context, filter Filter) (int, error)
	// Get returns one session, or ErrNotFound when the audit log holds no
	// call the scope admits — an unknown id and another caller's id are the
	// same answer.
	Get(ctx context.Context, scope Scope) (*Summary, error)
	// Timeline returns the session's calls in the order they were made,
	// with the session's total call count, both narrowed by the scope.
	Timeline(ctx context.Context, scope Scope) ([]TimelineEntry, int, error)
	// Assets returns the assets the session saved, oldest first. It takes
	// no scope: it is reached only through Load, after the scoped Get has
	// established that the caller may read this session.
	Assets(ctx context.Context, sessionID string) ([]AssetRef, error)
	// Insights returns the insights the session captured, oldest first.
	// Scoped the same way Assets is.
	Insights(ctx context.Context, sessionID string) ([]InsightRef, error)
}

type Summary struct {
	SessionID string `json:"session_id" example:"dps_9f2c1a4b8e7d6c5a4b3e2d1c0f9e8a7b"`
	// Kind is the id's origin (agent handle, portal run, script run,
	// transport). Derived from the id, so it is never absent.
	Kind Kind `json:"kind" example:"agent"`
	// UserID and UserEmail come from the session's first event. A session
	// belongs to one caller; the audit rows repeat that caller per row.
	UserID    string `json:"user_id" example:"550e8400-e29b-41d4-a716-446655440000"`
	UserEmail string `json:"user_email,omitempty" example:"marcus.johnson@example.com"`
	// Persona is the live session row's minted persona when the row still
	// exists, and the first event's persona once it has expired.
	Persona      string    `json:"persona,omitempty" example:"data-engineer"`
	StartedAt    time.Time `json:"started_at"`
	LastActiveAt time.Time `json:"last_active_at"`
	CallCount    int       `json:"call_count" example:"5"`
	FailureCount int       `json:"failure_count" example:"1"`
	// Tools and Connections are the distinct names the session touched,
	// sorted. Empty slices, never null, so the UI need not model both.
	Tools        []string `json:"tools"`
	Connections  []string `json:"connections"`
	AssetCount   int      `json:"asset_count" example:"1"`
	InsightCount int      `json:"insight_count" example:"0"`
}

type TimelineEntry struct {
	// EventID is the audit event's id, which the admin events surface
	// addresses a single row by.
	EventID   string    `json:"event_id" example:"evt_a1b2c3d4e5f6"`
	Timestamp time.Time `json:"timestamp"`
	ToolName  string    `json:"tool_name" example:"trino_query"`
	// Purpose is the reason the agent stated for this call (#1317). Empty
	// on a call the platform does not gate and on rows older than it.
	Purpose      string `json:"purpose,omitempty" example:"Sizing Q3 revenue by region for the board deck."`
	ToolkitKind  string `json:"toolkit_kind,omitempty" example:"trino"`
	Connection   string `json:"connection,omitempty" example:"acme-warehouse"`
	Success      bool   `json:"success" example:"true"`
	ErrorMessage string `json:"error_message,omitempty"`
	DurationMS   int64  `json:"duration_ms" example:"143"`
}