session

type ConversationStats struct {
	// UserMessages counts messages the user actually wrote. A background
	// event travels as a user-role message because no provider has a portable
	// role for one, and counting those as things the user said would inflate
	// the number that reads most like effort.
	UserMessages int
	// BackgroundMessages counts the user-role messages that carry a Source:
	// command results, subagent results, monitor events.
	BackgroundMessages int
	// AssistantTurns counts assistant messages, including the ones whose whole
	// content was a tool call.
	AssistantTurns int
	// ToolCalls counts calls the assistant issued. ToolResults counts the
	// results that came back; the two differ when a run was cut short between
	// the call and its result.
	ToolCalls   int
	ToolResults int
	// Tools is the per-tool breakdown, heaviest by result bytes first. A tool
	// the assistant called but whose result never arrived still appears, with
	// zero bytes.
	Tools []ToolStats
	// TextBytes is what the conversation's own text weighs — user prompts and
	// assistant replies. ToolResultBytes is what came back from tools.
	//
	// Kept apart because they are spent differently: the first is the
	// conversation, the second is what the run pulled into it, and on a long
	// agent session the second is usually the larger by an order of magnitude.
	TextBytes       int
	ToolResultBytes int
	// CompactedMessages is how many messages sit before the compaction
	// boundary — summarized away, still stored.
	CompactedMessages int
	// Notes and Todos are the durable state the session carries.
	Notes int
	Todos int
}

type Session struct {
	ID               string        `json:"id"`
	Title            string        `json:"title,omitempty"`
	CreatedAt        time.Time     `json:"created_at"`
	Messages         []llm.Message `json:"messages,omitempty"`
	PromptTokens     int           `json:"prompt_tokens,omitempty"`
	CompletionTokens int           `json:"completion_tokens,omitempty"`
	// CacheReadTokens and CacheWriteTokens are the session's provider-reported
	// cached prompt. They break PromptTokens down rather than add to it, so a
	// reader totalling a session must not sum all three.
	CacheReadTokens  int `json:"cache_read_tokens,omitempty"`
	CacheWriteTokens int `json:"cache_write_tokens,omitempty"`
	// Cost is what this session is estimated to have spent, accumulated as it
	// ran. It is a running total rather than something recomputed on read,
	// because the rates that applied to an earlier turn are not necessarily
	// the ones configured now. Nil means nothing here was priced.
	Cost *llm.Cost `json:"cost,omitempty"`
	// CostIncomplete says the total above is missing part of the session: a
	// turn ran against an unpriced model, or against one quoted in a different
	// currency, which BuildMax does not convert. A number that silently
	// dropped half a session is worse than one labelled incomplete.
	CostIncomplete bool `json:"cost_incomplete,omitempty"`
	// CompactionIdx is the index into Messages where the latest compaction boundary falls.
	// Messages before this index have been summarized into CompactionSummary.
	// Zero means no compaction has occurred.
	CompactionIdx     int    `json:"compaction_idx,omitempty"`
	CompactionSummary string `json:"compaction_summary,omitempty"`
	// NoteEntries and TodoEntries are durable session state: unlike a tool result, they are
	// not messages, so compaction cannot take them. The fields are named apart from the
	// Notes/Todos accessors that implement agent.NoteStore; the JSON keys are the plain names.
	NoteEntries []agent.Note `json:"notes,omitempty"`
	TodoEntries []agent.Todo `json:"todos,omitempty"`
	// AdditionalSystemPrompt records the extra system-prompt text this session actually ran
	// under. It is a record — for the trace, and so a resumed session does not silently lose
	// its identity when the flag that set it is not repeated — not the authority. Whoever
	// assembles a run resolves it afresh, and the last writer wins.
	AdditionalSystemPrompt string `json:"additional_system_prompt,omitempty"`
}

type SessionItem struct {
	ID        string `json:"id"`
	Title     string `json:"title,omitempty"`
	Workspace string `json:"workspace,omitempty"`
	CreatedAt string `json:"created_at"` // RFC3339
	Pinned    bool   `json:"pinned,omitempty"`
}

type ToolStats struct {
	Name string
	// Calls is how many times the assistant asked for it.
	Calls int
	// ResultBytes is what its results put back into the context. This is the
	// number that answers which tool is filling the context window, and it is
	// not derivable from the call count: one search can outweigh fifty reads.
	ResultBytes int
	// MaxResultBytes is the largest single result, so one outlier is not
	// hidden inside an average.
	MaxResultBytes int
}