sessions

type CapabilitySet struct {
	Roots            bool `json:"roots,omitempty"`
	RootsListChanged bool `json:"roots_list_changed,omitempty"`
	Sampling         bool `json:"sampling,omitempty"`
	Elicitation      bool `json:"elicitation,omitempty"`
}

type ClientInfo struct {
	Name    string
	Version string
}

type ElicitAction string

type ElicitConfig struct {
	Strict bool
	RawDst *map[string]any
}

type ElicitOption func(*ElicitConfig)

type ElicitationCapability interface {
	// Elicit sends an elicitation request with the provided user-facing message text.
	// subject may be either:
	//   1. an elicitation.SchemaDecoder (advanced / pre-built form), OR
	//   2. a non-nil pointer to a struct (shorthand). In this case the implementation
	//      will internally call elicitation.BindStruct(subject) to derive a schema
	//      and bind the decoder to that pointer.
	//
	// Most callers should simply pass &MyStruct{} (or a pointer they keep around)
	// directly:
	//
	//  type Input struct { Name string `json:"name" jsonschema:"minLength=1"` }
	//  var in Input
	//  action, err := elicCap.Elicit(ctx, "Who are you?", &in)
	//
	// Backwards-compatible usage with an explicit SchemaDecoder still works:
	//
	//  dec, _ := elicitation.BindStruct(&in)
	//  action, err := elicCap.Elicit(ctx, "Who are you?", dec)
	//
	// If binding / schema construction fails (e.g. subject not a *struct), the
	// returned action will be ElicitActionCancel along with a descriptive error.
	Elicit(ctx context.Context, text string, subject any, opts ...ElicitOption) (ElicitAction, error)
}

type EventHandlerFunction func(ctx context.Context, payload []byte) error

type MessageHandlerFunction func(ctx context.Context, msgID string, msg []byte) error

type MetadataClientInfo struct {
	Name       string `json:"name,omitempty"`
	Version    string `json:"version,omitempty"`
	InstanceID string `json:"instance_id,omitempty"`
}

type RootsCapability interface {
	ListRoots(ctx context.Context) (*mcp.ListRootsResult, error)

	RegisterRootsListChangedListener(ctx context.Context, listener RootsListChangedListener) (supported bool, err error)
}

type RootsListChangedListener func(ctx context.Context) error

type SampleResult struct {
	Message sampling.Message
	// Usage, Model, StopReason etc. can be added once surfaced by the engine.
	Model      string
	StopReason string
	Meta       map[string]any
}

type SamplingCapability interface {
	// CreateMessage requests the client host sample a single assistant message.
	// system: required system prompt string (may be empty for no system context).
	// user: the current user-authored message (RoleUser; exactly one content block).
	// opts: functional options configuring model preferences, history, streaming, etc.
	CreateMessage(ctx context.Context, system string, user sampling.Message, opts ...sampling.Option) (*SampleResult, error)
}

type Session interface {
	SessionID() string
	UserID() string
	// ProtocolVersion is the negotiated MCP protocol version baked into the session.
	ProtocolVersion() string

	GetSamplingCapability() (cap SamplingCapability, ok bool)
	GetRootsCapability() (cap RootsCapability, ok bool)
	GetElicitationCapability() (cap ElicitationCapability, ok bool)

	// PutData stores raw bytes value under key scoped to this session. The
	// storage is best-effort bounded by host TTL / size constraints. Callers
	// SHOULD keep values small (host-specific limits may apply). Context governs
	// cancellation. Returns a backend error on failure.
	PutData(ctx context.Context, key string, value []byte) error
	// GetData retrieves raw bytes previously stored with PutData. It returns
	// (nil, false, nil) ONLY when the key does not exist. It MUST NOT collapse
	// backend/storage errors into (ok=false). Any transport, context cancellation
	// or backend failure MUST surface via a non-nil err (caller should ignore ok
	// when err != nil). An empty stored value returns ([]byte{}, true, nil).
	GetData(ctx context.Context, key string) (value []byte, ok bool, err error)
	// DeleteData removes the key if present. Missing keys are not an error.
	DeleteData(ctx context.Context, key string) error
}

type SessionData interface {
	PutData(ctx context.Context, key string, value []byte) error
	GetData(ctx context.Context, key string) ([]byte, error)
	DeleteData(ctx context.Context, key string) error
}

type SessionHost interface {

	// PublishSession appends a message to the durable per-session client-facing
	// event stream.
	PublishSession(ctx context.Context, sessionID string, data []byte) (eventID string, err error)
	// SubscribeSession registers a handler that will compete for messages from the
	// per-session client-facing event stream starting after lastEventID (empty
	// string means from the beginning). The passed context governs the lifetime.
	// Returning a non-nil error from the handler ends the subscription with that
	// error. Implementations MUST make a best-effort to avoid dropping messages,
	// but at-least-once (not exactly-once) delivery is the contract.
	SubscribeSession(ctx context.Context, sessionID string, lastEventID string, handler MessageHandlerFunction) error

	// PublishEvent appends an event to the internal event stream scoped by topic
	// and used for server-side coordination (never delivered directly to the MCP
	// client). Semantics:
	//   * Ordering: Events are totally ordered per topic according to the order
	//     PublishEvent is called successfully.
	//   * Visibility: Subscribers only receive events published AFTER they
	//     subscribe (no historical replay obligation).
	//   * Delivery: At-least-once to every active subscriber. Implementations
	//     strive for exactly-once but callers must tolerate duplicates under
	//     rare failure / reconnect scenarios (especially in distributed hosts).
	//   * Fan-out: All current subscribers for the topic get every subsequent
	//     subsequent event (subject to at-least-once guarantee).
	//   * Retention: Minimal retention is sufficient; implementations may prune
	//     or discard already-delivered events as long as future delivery
	//     guarantees hold. No replay API is exposed.
	//   * Lifetime: Events need not survive process restarts; durability is best
	//     effort unless an implementation chooses otherwise. Removing a topic MAY
	//     discard its associated event stream.
	PublishEvent(ctx context.Context, topic string, payload []byte) error
	// SubscribeEvents registers a handler that will receive (in order) each
	// event published after subscription time for the given topic.
	// The passed context governs the lifetime. Returning a non-nil error from the
	// handler ends the subscription with that error. Implementations SHOULD make
	// a best-effort to avoid dropping events, but at-least-once (not exactly-once)
	//  delivery is the contract.
	SubscribeEvents(ctx context.Context, topic string, handler EventHandlerFunction) error

	// --- Session metadata lifecycle ---
	CreateSession(ctx context.Context, meta *SessionMetadata) error
	GetSession(ctx context.Context, sessionID string) (*SessionMetadata, error)
	MutateSession(ctx context.Context, sessionID string, fn func(*SessionMetadata) error) error
	TouchSession(ctx context.Context, sessionID string) error
	DeleteSession(ctx context.Context, sessionID string) error // idempotent hard delete

	// --- Per-session bounded KV storage ---
	PutSessionData(ctx context.Context, sessionID, key string, value []byte) error
	// GetSessionData returns (nil,false,nil) if the key does not exist, (v,true,nil)
	// on success, and (nil,false,err) on backend / context error.
	GetSessionData(ctx context.Context, sessionID, key string) (value []byte, found bool, err error)
	DeleteSessionData(ctx context.Context, sessionID, key string) error
}

type SessionMetadata struct {
	MetaVersion     int                `json:"meta_version"`               // For forward migration; starts at 1
	SessionID       string             `json:"session_id"`                 // immutable
	UserID          string             `json:"user_id"`                    // immutable
	Issuer          string             `json:"issuer,omitempty"`           // immutable (empty if not enforced)
	ProtocolVersion string             `json:"protocol_version,omitempty"` // immutable after creation handshake
	Client          MetadataClientInfo `json:"client,omitempty"`           // immutable (can relax later if needed)
	Capabilities    CapabilitySet      `json:"capabilities,omitempty"`     // immutable
	// State tracks whether the session is pending or open. Missing state should
	// be interpreted as open for backward compatibility.
	State SessionState `json:"state,omitempty"`

	CreatedAt   time.Time     `json:"created_at"`
	UpdatedAt   time.Time     `json:"updated_at"`
	LastAccess  time.Time     `json:"last_access"`
	TTL         time.Duration `json:"ttl"`
	MaxLifetime time.Duration `json:"max_lifetime,omitempty"`
	// OpenedAt records when the session transitioned to open.
	OpenedAt time.Time `json:"opened_at,omitempty"`

	Revoked bool `json:"revoked"`
}

type SessionState string