session

type RunMeta struct {
	// AgentID identifies which agent processed the run.
	AgentID string
	// RunID is the durable workflow run identifier.
	RunID string
	// SessionID associates related runs (e.g., chat sessions).
	SessionID string
	// Status indicates the current lifecycle state.
	Status RunStatus
	// StartedAt records when the run began.
	StartedAt time.Time
	// UpdatedAt records when the run metadata was last updated.
	UpdatedAt time.Time
	// Labels stores caller- or policy-provided labels.
	Labels map[string]string
	// PromptRefs captures the unique prompt versions rendered during the run.
	//
	// The runtime appends to this slice when it observes PromptRendered hook
	// events, de-duplicating by (prompt_id, version). This enables downstream
	// consumers to correlate run outcomes with the exact prompt versions that
	// were used without re-scanning the run event log.
	PromptRefs []prompt.PromptRef
	// ChildRunIDs captures direct child runs linked from this run.
	//
	// Child runs are produced by agent-as-tool execution. Consumers that need
	// full prompt attribution should walk this graph to include descendants.
	ChildRunIDs []string
	// Metadata stores implementation-specific metadata (e.g., error codes).
	Metadata map[string]any
}

type RunStatus string

type Session struct {
	// ID is the durable identifier of the session.
	ID string
	// Status is the current session lifecycle state.
	Status SessionStatus
	// CreatedAt records when the session was created.
	CreatedAt time.Time
	// EndedAt is set when the session is ended.
	EndedAt *time.Time
}

type SessionStatus string

type Store interface {
	// CreateSession creates (or returns) an active session.
	//
	// Contract:
	// - Idempotent for active sessions: returns the existing session.
	// - Returns ErrSessionEnded when the session exists but is terminal.
	CreateSession(ctx context.Context, sessionID string, createdAt time.Time) (Session, error)
	// LoadSession loads an existing session.
	// Returns ErrSessionNotFound when the session does not exist.
	LoadSession(ctx context.Context, sessionID string) (Session, error)
	// EndSession ends a session and returns its terminal state.
	// Idempotent: ending an already-ended session returns the stored session.
	EndSession(ctx context.Context, sessionID string, endedAt time.Time) (Session, error)

	// UpsertRun inserts or updates run metadata.
	UpsertRun(ctx context.Context, run RunMeta) error
	// LinkChildRun links a child run to a parent run atomically.
	//
	// Contract:
	// - parentRunID and child identifiers must be non-empty.
	// - The parent run must already exist, otherwise ErrRunNotFound is returned.
	// - Parent and child runs must belong to the same session.
	// - Child linkage is idempotent (duplicate links are ignored).
	// - The implementation must ensure no observer can observe a linked child ID
	//   without a corresponding child run record.
	LinkChildRun(ctx context.Context, parentRunID string, child RunMeta) error
	// LoadRun loads run metadata. Returns ErrRunNotFound when missing.
	LoadRun(ctx context.Context, runID string) (RunMeta, error)
	// ListRunsBySession lists runs for the given session. When statuses is
	// non-empty, only runs whose status matches one of the provided values
	// are returned.
	ListRunsBySession(ctx context.Context, sessionID string, statuses []RunStatus) ([]RunMeta, error)
}