sessions

type ListFilter struct {
	AgentName string
	Status    SessionStatus
	Limit     int
}

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

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

type Session struct {
	// ID is the primary key. Stable across resumes. Format is
	// `s_<base36-millis>` from the runtime adapter, BUT callers must
	// not parse it — the format is an opaque identifier.
	ID string

	// AgentName is `spec.metadata.name` at session start. Stored for
	// list-by-agent queries; the canonical source is the Spec field.
	AgentName string

	// RuntimeType is `spec.runtime.type` at start. Pi vs opencode dispatch
	// looks at this to know which adapter the session was bound to;
	// resuming under a mismatched runtime is rejected by the caller
	// (slice 6.3 wires the check).
	RuntimeType string

	// Status is the session's current lifecycle position. See the
	// StatusXxx constants. Slice 6.1 only sets active/ended; later
	// slices wire paused/expired/failed.
	Status SessionStatus

	// CreatedAt is the wall-clock time the session was first created.
	// Stable. UTC at write; callers may localize for display.
	CreatedAt time.Time

	// LastActiveAt is the wall-clock time of the last Update — i.e.
	// the last time an adapter reported progress for this session.
	// Used for List() ordering and for the expiry TTL check in 6.4.
	LastActiveAt time.Time

	// Spec is the CompiledSpec the session was started with. Snapshotted
	// at creation so resume can replay it. Storing the full spec (not
	// just a path) lets the store outlive the spec file on disk.
	Spec adl.CompiledSpec

	// TraceContext is the W3C `traceparent` header of the session's
	// root OTel span. Each resumed turn opens a child span under it
	// (slice 6.5 wires this). Empty when tracing was off at creation.
	TraceContext string

	// AdapterState is an opaque map the adapter (Pi or opencode) uses
	// to find its own session state on disk. Format is adapter-defined.
	// For the Pi adapter today this carries the path to the underlying
	// Pi session directory; opencode's state surfaces here in 6.3.
	AdapterState map[string]any
}

type SessionStatus string

type Store interface {
	// Create persists a new session. Returns ErrAlreadyExists if a
	// session with the same ID is already in the store.
	Create(ctx context.Context, s Session) error

	// Get returns the session by ID. Returns ErrNotFound when the
	// session doesn't exist.
	Get(ctx context.Context, id string) (Session, error)

	// Update overwrites the mutable fields (Status, LastActiveAt,
	// AdapterState) of an existing session. Returns ErrNotFound when
	// the session doesn't exist. Immutable fields on the input
	// (ID, AgentName, RuntimeType, CreatedAt, Spec, TraceContext) are
	// kept at their original values — see the Session doc-comment.
	//
	// Returns ErrSessionExpired if the existing row's Status is
	// already StatusExpired AND the incoming update would change
	// it to something other than Expired. The terminal-status
	// guard is enforced atomically by the impl so a chat process
	// can't undo a concurrent `sessions sweep` even mid-turn.
	// Slice 6.4 (codex pass 2).
	Update(ctx context.Context, s Session) error

	// Delete removes the session. Idempotent: deleting a missing
	// session is NOT an error (matches the best-effort-cleanup pattern
	// the K8s backend uses for Pods and Secrets).
	Delete(ctx context.Context, id string) error

	// List returns sessions matching the filter, ordered by
	// LastActiveAt descending (most-recently-active first).
	// Empty filter returns every session.
	List(ctx context.Context, filter ListFilter) ([]Session, error)

	// MarkExpired bulk-transitions every currently-Active session
	// whose LastActiveAt is strictly before `cutoff` to
	// StatusExpired. Returns the IDs of sessions that were
	// transitioned. Used by the `agentctl sessions sweep`
	// subcommand to retire idle sessions past their TTL.
	//
	// Idempotent: a second sweep with the same cutoff is a no-op
	// because the sessions transitioned by the first sweep are no
	// longer StatusActive. Only Active sessions are touched —
	// already-Paused or already-Ended sessions are left alone so
	// the lifecycle history remains intact. Added in slice 6.4.
	MarkExpired(ctx context.Context, cutoff time.Time) ([]string, error)

	// Close releases any resources the store holds (DB handles, file
	// locks, etc.). Idempotent — calling Close on an already-closed
	// store is a no-op. MemoryStore.Close drops all data; SQLiteStore
	// (6.2) closes the DB handle but keeps the file.
	Close() error
}