interfaces

type AgentMemoryListOptions struct {
	Offset   int
	Limit    int
	SortBy   string  // "score", "created_at", "last_used_at"
	SortDesc bool    // true for descending, false for ascending
	Keyword  *string // filter by query or claim content
	MinScore *float64
	MaxScore *float64
}

type AgentSummary struct {
	AgentID        string
	Count          int
	LatestMemoryAt time.Time
}

type AlertUsecases interface {
	// Alert related handlers
	HandleAlert(ctx context.Context, schema types.AlertSchema, alertData any) ([]*alert.Alert, error)
}

type ApiUsecases interface {
	// User related handlers
	GetUserIcon(ctx context.Context, userID string) ([]byte, string, error)
	GetUserProfile(ctx context.Context, userID string) (string, error)

	// Ticket related handlers
	GenerateTicketAlertsJSONL(ctx context.Context, ticketID types.TicketID) ([]byte, error)
}

type ChatResponder interface {
	// SendMessage sends a message to the specific chat session
	SendMessage(ctx context.Context, message string) error

	// SendTrace sends a trace message to the specific chat session
	SendTrace(ctx context.Context, message string) error

	// GetSession returns the chat session information
	GetSession() *ChatSession
}

type ChatSession struct {
	ID       ChatSessionID
	Source   ChatSource
	TicketID types.TicketID
	UserID   string
	// For WebSocket: specific connection ID
	// For Slack: thread information
	Metadata map[string]interface{}
}

type ChatSessionID string

type ChatSource string

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

type CommandExecutor interface {
	Execute(ctx context.Context, slackMsg *slack.Message, thread slack.Thread, command string) error
}

type EmbeddingClient interface {
	Embeddings(ctx context.Context, texts []string, dimensionality int) ([][]float32, error)
}

type LLMClient interface {
	gollem.LLMClient
}

type LLMSession interface {
	gollem.Session
}

type Notifier interface {
	// NotifyIngestPolicyResult is called when ingest policy evaluation completes
	NotifyIngestPolicyResult(ctx context.Context, ev *event.IngestPolicyResultEvent)

	// NotifyEnrichPolicyResult is called when enrich policy evaluation completes
	NotifyEnrichPolicyResult(ctx context.Context, ev *event.EnrichPolicyResultEvent)

	// NotifyTriagePolicyResult is called when triage policy evaluation completes
	NotifyTriagePolicyResult(ctx context.Context, ev *event.TriagePolicyResultEvent)

	// NotifyEnrichTaskPrompt is called when an enrichment task prompt is about to be sent to LLM
	NotifyEnrichTaskPrompt(ctx context.Context, ev *event.EnrichTaskPromptEvent)

	// NotifyEnrichTaskResponse is called when an enrichment task response is received from LLM
	NotifyEnrichTaskResponse(ctx context.Context, ev *event.EnrichTaskResponseEvent)

	// NotifyError is called when an error occurs during pipeline processing
	NotifyError(ctx context.Context, ev *event.ErrorEvent)
}

type Option func(*Clients)

type PolicyClient interface {
	Query(context.Context, string, any, any, ...opaq.QueryOption) error
	Sources() map[string]string
}

type PromptService interface {
	// GeneratePrompt generates a prompt from template name and alert data
	GeneratePrompt(ctx context.Context, templateName string, alert *alert.Alert) (string, error)

	// GeneratePromptWithParams generates a prompt from template name, alert data, and custom parameters
	GeneratePromptWithParams(ctx context.Context, templateName string, alert *alert.Alert, params map[string]any) (string, error)

	// ReadPromptFile reads a prompt file without template rendering
	ReadPromptFile(ctx context.Context, templateName string) (string, error)
}

type Repository interface {
	GetTicket(ctx context.Context, ticketID types.TicketID) (*ticket.Ticket, error)
	BatchGetTickets(ctx context.Context, ticketIDs []types.TicketID) ([]*ticket.Ticket, error)
	PutTicket(ctx context.Context, ticket ticket.Ticket) error
	BatchUpdateTicketsStatus(ctx context.Context, ticketIDs []types.TicketID, status types.TicketStatus) error
	GetTicketByThread(ctx context.Context, thread slack.Thread) (*ticket.Ticket, error)
	FindNearestTickets(ctx context.Context, embedding []float32, limit int) ([]*ticket.Ticket, error)
	FindNearestTicketsWithSpan(ctx context.Context, embedding []float32, begin, end time.Time, limit int) ([]*ticket.Ticket, error)
	GetTicketsByStatus(ctx context.Context, statuses []types.TicketStatus, offset, limit int) ([]*ticket.Ticket, error)
	CountTicketsByStatus(ctx context.Context, statuses []types.TicketStatus) (int, error)
	GetTicketsBySpan(ctx context.Context, begin, end time.Time) ([]*ticket.Ticket, error)
	GetTicketsByStatusAndSpan(ctx context.Context, status types.TicketStatus, begin, end time.Time) ([]*ticket.Ticket, error)

	// For comment management
	PutTicketComment(ctx context.Context, comment ticket.Comment) error
	GetTicketComments(ctx context.Context, ticketID types.TicketID) ([]ticket.Comment, error)
	GetTicketCommentsPaginated(ctx context.Context, ticketID types.TicketID, offset, limit int) ([]ticket.Comment, error)
	CountTicketComments(ctx context.Context, ticketID types.TicketID) (int, error)
	GetTicketUnpromptedComments(ctx context.Context, ticketID types.TicketID) ([]ticket.Comment, error)
	PutTicketCommentsPrompted(ctx context.Context, ticketID types.TicketID, commentIDs []types.CommentID) error

	BindAlertsToTicket(ctx context.Context, alertIDs []types.AlertID, ticketID types.TicketID) error
	UnbindAlertFromTicket(ctx context.Context, alertID types.AlertID) error

	PutAlert(ctx context.Context, alert alert.Alert) error
	BatchPutAlerts(ctx context.Context, alerts alert.Alerts) error
	GetAlert(ctx context.Context, alertID types.AlertID) (*alert.Alert, error)
	GetLatestAlertByThread(ctx context.Context, thread slack.Thread) (*alert.Alert, error)
	GetAlertsByThread(ctx context.Context, thread slack.Thread) (alert.Alerts, error)
	SearchAlerts(ctx context.Context, path, op string, value any, limit int) (alert.Alerts, error)
	GetAlertWithoutTicket(ctx context.Context, offset, limit int) (alert.Alerts, error)
	CountAlertsWithoutTicket(ctx context.Context) (int, error)
	GetAlertsBySpan(ctx context.Context, begin, end time.Time) (alert.Alerts, error)
	BatchGetAlerts(ctx context.Context, alertIDs []types.AlertID) (alert.Alerts, error)
	FindNearestAlerts(ctx context.Context, embedding []float32, limit int) (alert.Alerts, error)

	GetLatestHistory(ctx context.Context, ticketID types.TicketID) (*ticket.History, error)
	PutHistory(ctx context.Context, ticketID types.TicketID, history *ticket.History) error

	// For list management
	GetAlertList(ctx context.Context, listID types.AlertListID) (*alert.List, error)
	PutAlertList(ctx context.Context, list *alert.List) error
	GetAlertListByThread(ctx context.Context, thread slack.Thread) (*alert.List, error)
	GetLatestAlertListInThread(ctx context.Context, thread slack.Thread) (*alert.List, error)
	GetAlertListsInThread(ctx context.Context, thread slack.Thread) ([]*alert.List, error)

	GetAlertWithoutEmbedding(ctx context.Context) (alert.Alerts, error)
	GetAlertsWithInvalidEmbedding(ctx context.Context) (alert.Alerts, error)
	GetTicketsWithInvalidEmbedding(ctx context.Context) ([]*ticket.Ticket, error)

	// For authentication management
	PutToken(ctx context.Context, token *auth.Token) error
	GetToken(ctx context.Context, tokenID auth.TokenID) (*auth.Token, error)
	DeleteToken(ctx context.Context, tokenID auth.TokenID) error

	// For activity management
	PutActivity(ctx context.Context, activity *activity.Activity) error
	GetActivities(ctx context.Context, offset, limit int) ([]*activity.Activity, error)
	CountActivities(ctx context.Context) (int, error)

	// For tag management (legacy - deprecated, kept for external compatibility)
	RemoveTagFromAllAlerts(ctx context.Context, name string) error
	RemoveTagFromAllTickets(ctx context.Context, name string) error

	// For new tag management (ID-based)
	GetTagByID(ctx context.Context, tagID string) (*tag.Tag, error)
	GetTagsByIDs(ctx context.Context, tagIDs []string) ([]*tag.Tag, error)
	ListAllTags(ctx context.Context) ([]*tag.Tag, error)
	CreateTagWithID(ctx context.Context, tag *tag.Tag) error
	UpdateTag(ctx context.Context, tag *tag.Tag) error
	DeleteTagByID(ctx context.Context, tagID string) error
	RemoveTagIDFromAllAlerts(ctx context.Context, tagID string) error
	RemoveTagIDFromAllTickets(ctx context.Context, tagID string) error

	// For tag name lookup (compatibility)
	GetTagByName(ctx context.Context, name string) (*tag.Tag, error)
	IsTagNameExists(ctx context.Context, name string) (bool, error)
	GetOrCreateTagByName(ctx context.Context, name, description, color, createdBy string) (*tag.Tag, error)

	// For notice management
	CreateNotice(ctx context.Context, notice *notice.Notice) error
	GetNotice(ctx context.Context, id types.NoticeID) (*notice.Notice, error)
	UpdateNotice(ctx context.Context, notice *notice.Notice) error

	// For agent memory management
	// Note: Agent memories are stored in subcollection: agents/{agentID}/memories/{memoryID}
	SaveAgentMemory(ctx context.Context, mem *memory.AgentMemory) error
	GetAgentMemory(ctx context.Context, agentID string, id types.AgentMemoryID) (*memory.AgentMemory, error)
	SearchMemoriesByEmbedding(ctx context.Context, agentID string, embedding []float32, limit int) ([]*memory.AgentMemory, error)

	// BatchSaveAgentMemories saves multiple agent memories efficiently in a batch
	// Uses batch write operations to minimize round trips to the database
	BatchSaveAgentMemories(ctx context.Context, memories []*memory.AgentMemory) error

	// Memory scoring methods
	// UpdateMemoryScoreBatch updates quality scores and last used timestamps for multiple agent memories
	UpdateMemoryScoreBatch(ctx context.Context, agentID string, updates map[types.AgentMemoryID]struct {
		Score      float64
		LastUsedAt time.Time
	}) error

	// DeleteAgentMemoriesBatch deletes multiple agent memories in a batch
	// Returns the number of successfully deleted memories
	DeleteAgentMemoriesBatch(ctx context.Context, agentID string, memoryIDs []types.AgentMemoryID) (int, error)

	// ListAgentMemories lists all memories for an agent (for pruning)
	// Results are ordered by CreatedAt DESC
	ListAgentMemories(ctx context.Context, agentID string) ([]*memory.AgentMemory, error)

	// ListAgentMemoriesWithOptions lists memories with filtering, sorting, and pagination
	// Returns memories and total count (before pagination)
	ListAgentMemoriesWithOptions(ctx context.Context, agentID string, opts AgentMemoryListOptions) ([]*memory.AgentMemory, int, error)

	// ListAllAgentIDs returns all agent IDs that have memories with their counts and latest memory timestamp
	// Used for the agent summary list in the UI
	ListAllAgentIDs(ctx context.Context) ([]*AgentSummary, error)

	// Session management
	PutSession(ctx context.Context, session *session.Session) error
	GetSession(ctx context.Context, sessionID types.SessionID) (*session.Session, error)
	GetSessionsByTicket(ctx context.Context, ticketID types.TicketID) ([]*session.Session, error)
	DeleteSession(ctx context.Context, sessionID types.SessionID) error

	// Session message management
	PutSessionMessage(ctx context.Context, message *session.Message) error
	GetSessionMessages(ctx context.Context, sessionID types.SessionID) ([]*session.Message, error)

	// GetKnowledges retrieves all non-archived latest knowledges for a topic
	GetKnowledges(ctx context.Context, topic types.KnowledgeTopic) ([]*knowledge.Knowledge, error)

	// GetKnowledge retrieves a specific knowledge by topic and slug (latest version)
	GetKnowledge(ctx context.Context, topic types.KnowledgeTopic, slug types.KnowledgeSlug) (*knowledge.Knowledge, error)

	// GetKnowledgeByCommit retrieves a specific version by topic, slug, and commit ID
	GetKnowledgeByCommit(ctx context.Context, topic types.KnowledgeTopic, slug types.KnowledgeSlug, commitID string) (*knowledge.Knowledge, error)

	// ListKnowledgeSlugs returns all non-archived slugs and names for a topic
	ListKnowledgeSlugs(ctx context.Context, topic types.KnowledgeTopic) ([]*knowledge.SlugInfo, error)

	// PutKnowledge saves a new version of a knowledge (append-only)
	// CommitID must be generated by GenerateCommitID before calling
	PutKnowledge(ctx context.Context, k *knowledge.Knowledge) error

	// ArchiveKnowledge marks all versions of a slug as archived
	ArchiveKnowledge(ctx context.Context, topic types.KnowledgeTopic, slug types.KnowledgeSlug) error

	// CalculateKnowledgeSize returns total content size for non-archived knowledges in a topic
	CalculateKnowledgeSize(ctx context.Context, topic types.KnowledgeTopic) (int, error)

	// ListKnowledgeTopics returns all topics with their knowledge counts (non-archived only)
	ListKnowledgeTopics(ctx context.Context) ([]*knowledge.TopicSummary, error)
}

type SlackClient interface {
	PostMessageContext(ctx context.Context, channelID string, options ...slackSDK.MsgOption) (string, string, error)
	UpdateMessageContext(ctx context.Context, channelID, timestamp string, options ...slackSDK.MsgOption) (string, string, string, error)
	DeleteMessageContext(ctx context.Context, channelID, timestamp string) (string, string, error)
	AuthTest() (*slackSDK.AuthTestResponse, error)
	GetTeamInfo() (*slackSDK.TeamInfo, error)
	OpenView(triggerID string, view slackSDK.ModalViewRequest) (*slackSDK.ViewResponse, error)
	UpdateView(view slackSDK.ModalViewRequest, externalID, hash, viewID string) (*slackSDK.ViewResponse, error)
	UploadFileV2Context(ctx context.Context, params slackSDK.UploadFileV2Parameters) (*slackSDK.FileSummary, error)
	GetUserInfo(userID string) (*slackSDK.User, error)
	GetUsersInfo(users ...string) (*[]slackSDK.User, error)
	GetConversationInfo(input *slackSDK.GetConversationInfoInput) (*slackSDK.Channel, error)
	GetUserGroups(options ...slackSDK.GetUserGroupsOption) ([]slackSDK.UserGroup, error)
	GetBotInfoContext(ctx context.Context, parameters slackSDK.GetBotInfoParameters) (*slackSDK.Bot, error)
	GetConversationHistoryContext(ctx context.Context, params *slackSDK.GetConversationHistoryParameters) (*slackSDK.GetConversationHistoryResponse, error)
	GetConversationRepliesContext(ctx context.Context, params *slackSDK.GetConversationRepliesParameters) ([]slackSDK.Message, bool, string, error)
	SearchMessagesContext(ctx context.Context, query string, params slackSDK.SearchParameters) (*slackSDK.SearchMessages, error)
}

type SlackEventUsecases interface {
	// Slack event handlers
	HandleSlackMessage(ctx context.Context, slackMsg slack.Message) error
	HandleSlackAppMention(ctx context.Context, slackMsg slack.Message) error
}

type SlackInteractionUsecases interface {
	// Slack interaction handlers
	HandleSlackInteractionViewSubmission(ctx context.Context, user slack.User, callbackID slack.CallbackID, metadata string, values slack.StateValue) error
	HandleSlackInteractionBlockActions(ctx context.Context, user slack.User, slackThread slack.Thread, actionID slack.ActionID, value, triggerID string) error
	HandleSalvageRefresh(ctx context.Context, user slack.User, metadata string, values slack.StateValue, viewID string) error
}

type SlackThreadService interface {
	// Thread information
	ChannelID() string
	ThreadID() string
	Entity() *slack.Thread

	// Posting operations
	PostAlert(ctx context.Context, alert *alert.Alert) error
	PostComment(ctx context.Context, comment string) error
	PostCommentWithMessageID(ctx context.Context, comment string) (string, error)
	PostContextBlock(ctx context.Context, text string) error
	PostTicket(ctx context.Context, ticket *ticket.Ticket, alerts alert.Alerts) (string, error)
	PostLinkToTicket(ctx context.Context, ticketURL, ticketTitle string) error
	PostFinding(ctx context.Context, finding *ticket.Finding) error

	// Update operations
	UpdateAlert(ctx context.Context, alert alert.Alert) error
	UpdateAlertList(ctx context.Context, list *alert.List, status string) error

	// List operations
	PostAlerts(ctx context.Context, alerts alert.Alerts) error
	PostAlertList(ctx context.Context, list *alert.List) (string, error)
	PostAlertLists(ctx context.Context, clusters []*alert.List) error
	PostTicketList(ctx context.Context, tickets []*ticket.Ticket) error

	// Interactive operations
	Reply(ctx context.Context, message string)
	NewStateFunc(ctx context.Context, message string) func(ctx context.Context, msg string)
	NewUpdatableMessage(ctx context.Context, initialMessage string) func(ctx context.Context, newMsg string)
	NewTraceMessage(ctx context.Context, initialMessage string) func(ctx context.Context, traceMsg string)

	// File operations
	AttachFile(ctx context.Context, title, fileName string, data []byte) error
}

type StorageClient interface {
	PutObject(ctx context.Context, object string) io.WriteCloser
	GetObject(ctx context.Context, object string) (io.ReadCloser, error)
	Close(ctx context.Context)
}

type Tool interface {
	Name() string
	Flags() []cli.Flag
	Configure(ctx context.Context) error
	LogValue() slog.Value
	Helper() *cli.Command
	Prompt(ctx context.Context) (string, error)
	gollem.ToolSet
}