channel

type AgentInfo struct {
	ID   string
	Name string
}

type AssetSaveAdmitter interface {
	AdmitAssetSave(ctx context.Context, msg IncomingMessage) error
}

type AssetSaver interface {
	// SaveAsset returns a portable $STELLA_ASSETS_DIR expression, never a host path.
	SaveAsset(ctx context.Context, msg IncomingMessage, fileName string, data []byte) (string, error)
}

type BotNameRegistrar interface {
	RegisterBotName(platform, displayName, channelID string)
}

type BotRegistrar interface {
	RegisterBotIdentity(platform, platformBotID, channelID string)
}

type Channel interface {
	// Name returns a unique identifier (e.g. "telegram", "qq").
	Name() string

	// Start begins listening for messages. Blocks until ctx is cancelled.
	Start(ctx context.Context) error

	// Stop gracefully shuts down the channel.
	Stop()

	// Notify sends a push notification to a target within this channel.
	Notify(ctx context.Context, n Notification) error
}

type ChatStream struct {
	Events    <-chan Event
	SessionID string
}

type DingTalkConfig struct {
	InstanceID                 string `json:"-"`
	ClientID                   string `json:"client_id"`
	ClientSecret               string `json:"client_secret"`
	AllowGroup                 bool   `json:"allow_group"`
	AllowDM                    bool   `json:"allow_dm"`
	AllowUnlinkedDM            bool   `json:"allow_unlinked_dm"`
	GuestMessageLimitPerMinute int    `json:"guest_message_limit_per_minute"`
	GuestMaxPerChannel         int    `json:"guest_max_per_channel"`
	GuestRetentionDays         int    `json:"guest_retention_days"`
	RequireMention             bool   `json:"require_mention"`
}

type DiscordConfig struct {
	InstanceID                 string   `json:"-"`
	Token                      string   `json:"token"`
	AllowGroup                 bool     `json:"allow_group"`
	AllowAllGuilds             bool     `json:"allow_all_guilds"`
	AllowedGuildIDs            []string `json:"allowed_guild_ids"`
	AllowedChannelIDs          []string `json:"allowed_channel_ids"`
	AllowedUserIDs             []string `json:"allowed_user_ids"`
	AllowedRoleIDs             []string `json:"allowed_role_ids"`
	AllowDM                    bool     `json:"allow_dm"`
	AllowUnlinkedDM            bool     `json:"allow_unlinked_dm"`
	GuestMessageLimitPerMinute int      `json:"guest_message_limit_per_minute"`
	GuestMaxPerChannel         int      `json:"guest_max_per_channel"`
	GuestRetentionDays         int      `json:"guest_retention_days"`
	RequireMention             bool     `json:"require_mention"`
}

type Event struct {
	Text       string
	Reasoning  string
	Image      *ImageEvent
	File       *FileEvent
	ToolUse    *ToolUseEvent
	References []renderrefs.Reference
	Err        error
}

type FeishuConfig struct {
	InstanceID                 string                 `json:"-"`
	AppID                      string                 `json:"app_id"`
	AppSecret                  string                 `json:"app_secret"`
	EncryptKey                 string                 `json:"encrypt_key"`
	VerificationToken          string                 `json:"verification_token"`
	Groups                     map[string]FeishuGroup `json:"groups"`
	AllowGroup                 bool                   `json:"allow_group"`
	AllowDM                    bool                   `json:"allow_dm"`
	AllowUnlinkedDM            bool                   `json:"allow_unlinked_dm"`
	GuestMessageLimitPerMinute int                    `json:"guest_message_limit_per_minute"`
	GuestMaxPerChannel         int                    `json:"guest_max_per_channel"`
	GuestRetentionDays         int                    `json:"guest_retention_days"`
	RequireMention             bool                   `json:"require_mention"`
	EnableNotify               bool                   `json:"enable_notify"`
	TenantKey                  string                 `json:"tenant_key"`
	AutoProvision              bool                   `json:"auto_provision"`
}

type FeishuGroup struct {
	SystemPrompt    string   `json:"system_prompt"`
	ToolAllow       []string `json:"tool_allow"`
	ToolDeny        []string `json:"tool_deny"`
	Enabled         *bool    `json:"enabled,omitempty"`
	RequireMention  *bool    `json:"require_mention,omitempty"`
	AllowedUsers    []string `json:"allowed_users,omitempty"`
	DisallowedUsers []string `json:"disallowed_users,omitempty"`
}

type FileEvent struct {
	Path string // absolute path on disk
	Name string // display filename (with extension)
}

type GuestConfig struct {
	AllowDM                    bool
	AllowUnlinkedDM            bool
	GuestMessageLimitPerMinute int
	GuestMaxPerChannel         int
	GuestRetentionDays         int
}

type Handler interface {
	MessageHandler
}

type ImageEvent struct {
	Data     string // base64 encoded
	MimeType string // e.g. "image/jpeg"
}

type IncomingMessage struct {
	Platform   string   // "telegram", "qq", etc.
	ChannelID  string   // configured channel instance ID; defaults to Platform.
	SenderID   string   // preferred platform-specific user ID
	SenderIDs  []string // ordered candidate sender IDs, most stable first
	SenderName string   // display name
	ChatID     string   // group/channel ID (empty for DMs)
	IsGroup    bool
	ThreadID   string // platform sub-thread/topic id within ChatID (e.g. Telegram forum topic); empty if none
	Content    []ai.ContentBlock

	// Group-chat metadata (D3). Adapters fill what they can; empty/zero is allowed.
	MessageID         string    // platform-native message ID (stable delivery/update id), empty if unavailable
	Timestamp         time.Time // platform-reported send time, zero if unavailable
	ReplyTo           string    // platform message ID this message replies to, empty if none
	Mentions          []Mention // @-mentions, normalized; AgentID is resolved later by the dispatcher
	LifecycleFeedback bool      // platform adapter should show addressed-turn completion feedback
}

type JoinedChat struct {
	ID   string
	Name string
}

type JoinedChatLister interface {
	ListJoinedChats(ctx context.Context, pageSize int, pageToken string) (JoinedChatPage, error)
}

type JoinedChatPage struct {
	Chats         []JoinedChat
	NextPageToken string
}

type Mention struct {
	Raw        string `json:"Raw"`        // raw @ text (@username / <at open_id> ...), for audit/fallback
	PlatformID string `json:"PlatformID"` // platform-side mentioned id (username / open_id / qq number)
	AgentID    string `json:"AgentID"`    // resolved Stella agent; empty if unresolved
}

type MessageHandler interface {
	// HandleIncoming resolves the user once, tries command handling, and if the
	// command is not handled, streams a chat response.
	// Returns (commandResponse, handled, stream, err).
	// If handled is true, commandResponse contains the reply and stream is nil.
	// If handled is false, stream contains the chat response.
	HandleIncoming(ctx context.Context, msg IncomingMessage, command, args string) (string, bool, *ChatStream, error)
}

type ModelOption struct {
	Provider string
	Model    string
}

type Notification struct {
	Channel     string // optional: route to a specific backend
	ChatID      string // target chat/channel within the backend
	RecipientID string // linked platform user identity; empty for explicit ChatID targets
	AgentID     string // optional: agent that produced the notification
	Text        string // markdown content
	Silent      bool   // send without notification sound
}

type ProvisionRequest struct {
	Platform   string
	ExternalID string
	TenantKey  string
	Email      string
	Name       string
	AvatarURL  string
}

type Provisioner interface {
	ProvisionUser(ctx context.Context, req ProvisionRequest) error
}

type QQConfig struct {
	InstanceID   string `json:"-"`
	AppID        string `json:"app_id"`
	AppSecret    string `json:"app_secret"`
	EnableNotify bool   `json:"enable_notify"`
}

type TelegramConfig struct {
	InstanceID                 string   `json:"-"`
	Token                      string   `json:"token"`
	ChannelID                  string   `json:"channel_id"`
	AllowGroup                 bool     `json:"allow_group"`
	AllowedChatIDs             []string `json:"allowed_chat_ids"`
	AllowedTopicIDs            []string `json:"allowed_topic_ids"`
	AllowDM                    bool     `json:"allow_dm"`
	AllowUnlinkedDM            bool     `json:"allow_unlinked_dm"`
	GuestMessageLimitPerMinute int      `json:"guest_message_limit_per_minute"`
	GuestMaxPerChannel         int      `json:"guest_max_per_channel"`
	GuestRetentionDays         int      `json:"guest_retention_days"`
	RequireMention             bool     `json:"require_mention"`
	EnableNotify               bool     `json:"enable_notify"`
}

type ToolRecord struct {
	Tool     string
	Input    string
	Status   string // "done" or "error"
	Detail   string
	Duration time.Duration
}

type ToolTracker struct {
	History      []ToolRecord
	ActiveTool   string
	ActiveInput  string
	ActiveStart  time.Time
	DisplayUntil time.Time // minimum time to keep showing the last-finished tool

	// MinDisplayDuration controls how long a finished tool stays visible.
	// Zero means no minimum.
	MinDisplayDuration time.Duration
}

type ToolUseEvent struct {
	ID         string
	Tool       string // tool name, e.g. "bash", "read"
	Status     string // "running", "done", "error"
	Input      string // short summary of the tool input
	Arguments  map[string]any
	Detail     string // error detail or result summary
	Content    string
	References []renderrefs.Reference
}

type WeixinConfig struct {
	InstanceID   string `json:"-"`
	BotToken     string `json:"bot_token"`
	BaseURL      string `json:"base_url"`
	BotID        string `json:"bot_id"`
	UserID       string `json:"user_id"`
	SKRouteTag   string `json:"sk_route_tag"`
	EnableNotify bool   `json:"enable_notify"`
}