session

type AbandonedEffect struct {
	ToolCallID string
	ToolName   string
	// Returned reports whether the tool produced a result. A call that crossed
	// the execution boundary without returning is listed too, and is the more
	// dangerous of the two: it may have changed as much as one that finished,
	// and nothing recorded what.
	Returned bool
}

type AbandonedWork struct {
	// Messages is how many model-visible messages leave the branch.
	Messages int
	// Effects are the tool calls that reached their tools, in the order they
	// ran. Empty means the abandoned span was conversation only — the one case
	// where a rewind really does undo everything it moved past.
	Effects []AbandonedEffect
}

type AdditionalPromptSet struct {
	Text string `json:"text"`
}

type Compaction struct {
	CoveredHeadID string `json:"covered_head_id"`
	Summary       string `json:"summary"`
}

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 ForkedFrom struct {
	SessionID    string `json:"session_id"`
	CheckpointID string `json:"checkpoint_id"`
	HeadID       string `json:"head_id"`
}

type HeadSelected struct {
	Reason string `json:"reason,omitempty"`
}

type Header struct {
	Type      string    `json:"type"`
	Version   int       `json:"version"`
	SessionID string    `json:"session_id"`
	CreatedAt time.Time `json:"created_at"`
}

type Item struct {
	Seq      uint64
	ID       string
	ParentID string
	TS       time.Time
	Required bool
	TurnID   string
	Payload  Payload
}

type ItemSummary struct {
	ID string `json:"id"`
	// ProjectID is what the picker and --continue filter by, so it is in the
	// projection: scoping a list to the current Project must not cost a read of
	// every session's meta.json.
	ProjectID string `json:"project_id,omitempty"`
	Kind      Kind   `json:"kind"`
	// CreatedAt is carried as well as UpdatedAt because the picker orders by
	// it: a list that reordered itself every time a session was touched would
	// move entries under the cursor.
	CreatedAt  time.Time   `json:"created_at"`
	UpdatedAt  time.Time   `json:"updated_at"`
	Title      string      `json:"title,omitempty"`
	Workspace  string      `json:"workspace,omitempty"`
	Pinned     bool        `json:"pinned,omitempty"`
	ForkedFrom *ForkedFrom `json:"forked_from,omitempty"`
}

type Kind string

type LoadMode int

type Loaded struct {
	Meta Meta
	// Head is the current head's id, or "" for a session with no items yet.
	Head string
	// Items is the branch from the root to Head, in logical order. Populated
	// only for LoadFull.
	Items []Item
	// State is Reduce(Items, Head). Populated only for LoadFull.
	State State
	// Recovery classifies an interrupted turn on this branch, per §7.3.
	// Populated only for LoadFull.
	Recovery Recovery
}

type MessageItem struct {
	Message llm.Message `json:"message"`
}

type Meta struct {
	Version   int       `json:"version"`
	ID        string    `json:"id"`
	Kind      Kind      `json:"kind"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`

	// ProjectID is the local Project this session belongs to. It is the
	// relationship key --continue, the picker, and project memory all select
	// by, and it is immutable: a session may move among the Workspace roots of
	// its Project, but it never silently moves to another Project. MetaUpdate
	// has no field for it.
	//
	// It is optional at this boundary rather than required because task-run and
	// other non-local sessions have no local Project, and giving them a
	// fabricated one to satisfy the shape would put fake rows in the catalog.
	// CLI and Desktop enforce the stronger local invariant where they create
	// sessions. See docs/design/local-project-memory.md §6.3.
	ProjectID string `json:"project_id,omitempty"`

	Title     string `json:"title,omitempty"`
	Workspace string `json:"workspace,omitempty"`
	Pinned    bool   `json:"pinned,omitempty"`

	// SelectedModel is what the next turn should use. A completed or
	// interrupted turn's own TurnStarted record is what it actually used;
	// see §5.
	SelectedModel string `json:"selected_model,omitempty"`

	// Usage and cost are local aggregate reporting, not resume input, and are
	// carried forward by MetaUpdate rather than recomputed from history: the
	// rates that applied to an earlier turn are not necessarily the ones
	// configured now.
	PromptTokens     int       `json:"prompt_tokens,omitempty"`
	CompletionTokens int       `json:"completion_tokens,omitempty"`
	CacheReadTokens  int       `json:"cache_read_tokens,omitempty"`
	CacheWriteTokens int       `json:"cache_write_tokens,omitempty"`
	Cost             *llm.Cost `json:"cost,omitempty"`
	CostIncomplete   bool      `json:"cost_incomplete,omitempty"`

	// Lineage fields are set only when Kind is KindSubagent, and are immutable
	// once written: they describe how this session came to exist, not
	// anything it is currently doing.
	ParentSessionID  string `json:"parent_session_id,omitempty"`
	ParentRunID      string `json:"parent_run_id,omitempty"`
	ParentToolCallID string `json:"parent_tool_call_id,omitempty"`
	AgentType        string `json:"agent_type,omitempty"`
	DelegationDepth  int    `json:"delegation_depth,omitempty"`
	// Hidden excludes the session from the ordinary picker and --continue. It
	// is set by kind, not toggled independently.
	Hidden bool `json:"hidden,omitempty"`

	// ForkedFrom is set only on a user session created by forking another.
	ForkedFrom *ForkedFrom `json:"forked_from,omitempty"`
}

type MetaUpdate struct {
	Title         *string
	Workspace     *string
	Pinned        *bool
	SelectedModel *string

	AddPromptTokens     int
	AddCompletionTokens int
	AddCacheReadTokens  int
	AddCacheWriteTokens int
	// AddCost is added to the running total. A currency mismatch against the
	// existing total is not an error here: it marks the total incomplete
	// instead, because BuildMax holds no exchange rate and inventing one would
	// produce a figure that is wrong in both currencies.
	AddCost            *llm.Cost
	MarkCostIncomplete bool
}

type NotesReplaced struct {
	Notes []agent.Note `json:"notes"`
}

type Payload interface {
	// contains filtered or unexported methods
}

type Recovery struct {
	// TurnID is the interrupted turn. Empty when nothing needs repair.
	TurnID string
	// Uncertain are calls that crossed the execution boundary without
	// returning. Each needs a durable unknown result before the model sees the
	// branch again, so it is told to verify rather than left to assume.
	Uncertain []ToolCallOutcome
	// NotStarted are calls the model requested that never reached a tool. They
	// need no repair record; they are reported because a caller deciding what
	// to say to the user wants the distinction.
	NotStarted []ToolCallOutcome
}

type State struct {
	Messages          []llm.Message
	CompactionIdx     int
	CompactionSummary string
	Notes             []agent.Note
	Todos             []agent.Todo
	AdditionalPrompt  string
	// LastTurn is the turn id of the most recent TurnStarted on this branch,
	// and Open reports whether it lacks a matching TurnFinished. Together they
	// are what tells a caller whether it is resuming or repairing.
	LastTurn string
	Open     bool
}

type Store interface {
	// Create makes a new session directory with its metadata and an empty,
	// headered journal. It fails if the session already exists.
	Create(ctx context.Context, meta Meta) error

	// Open acquires the writer lock and returns a Writer for id, along with
	// what was already on this session's journal — repairing a torn tail and
	// classifying an interrupted turn for recovery in the process. It fails
	// with ErrLocked if another process already holds the lock.
	Open(ctx context.Context, id string) (Writer, error)

	// Load reads a session without acquiring the writer lock or repairing
	// anything. A writer may be active concurrently; Load only ever sees a
	// stable prefix.
	Load(ctx context.Context, id string, mode LoadMode) (Loaded, error)

	// UpdateMeta changes current selections or running aggregates. It cannot
	// change anything resumable — MetaUpdate has no field for that — so it
	// never touches the journal.
	UpdateMeta(ctx context.Context, id string, update MetaUpdate) error

	// List returns the picker projection. includeHidden controls whether
	// subagent sessions (§9) are included; the ordinary picker passes false.
	List(ctx context.Context, includeHidden bool) ([]ItemSummary, error)
}

type TodosReplaced struct {
	Todos []agent.Todo `json:"todos"`
}

type ToolCallOutcome struct {
	ToolCallID string
	ToolName   string
	Class      string
}

type ToolExecutionStarted struct {
	ToolCallID string `json:"tool_call_id"`
	ToolName   string `json:"tool_name"`
}

type ToolResult struct {
	ToolCallID string            `json:"tool_call_id"`
	Status     string            `json:"status"`
	Content    string            `json:"content,omitempty"`
	Parts      []llm.ContentPart `json:"parts,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
}

type TurnFinished struct {
	Status     string `json:"status"`
	ErrorClass string `json:"error_class,omitempty"`
}

type TurnRecovered struct {
	TurnID               string   `json:"turn_id"`
	UncertainToolCallIDs []string `json:"uncertain_tool_call_ids,omitempty"`
}

type TurnStarted struct {
	RunID         string `json:"run_id"`
	Model         string `json:"model,omitempty"`
	WorkspaceRoot string `json:"workspace_root,omitempty"`
	ContextWindow int    `json:"context_window,omitempty"`
	InputKind     string `json:"input_kind,omitempty"`
}

type UnknownPayload struct {
	Kind string
	Raw  json.RawMessage
}

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

type Writer interface {
	// Loaded is what Open found when the writer lock was acquired.
	Loaded() Loaded

	// Append writes items and returns only once they are durable. items must
	// continue the branch this Writer opened: each item's ParentID must chain
	// from Loaded().Head (or from a preceding item in the same call), and
	// their Seq values must be contiguous starting after the highest Seq this
	// Writer has appended so far. A caller that gets this wrong is a bug, not
	// a race — the lock already rules out a second writer — so Append reports
	// it as an ordinary error rather than needing an optimistic-concurrency
	// retry.
	Append(ctx context.Context, items ...Item) error

	// Close releases the writer lock. It is always safe to call, including
	// after Append has failed.
	Close() error
}