channel

type AgentCommandHandler struct {
	Ctx         context.Context
	Incoming    IncomingMessage
	Args        string
	Reply       func(string)
	ListAgents  func(context.Context, IncomingMessage) ([]AgentInfo, string, error)
	SwitchAgent func(context.Context, IncomingMessage, string) error
	FormatList  func([]IndexedAgent, string) string
	OnSwitched  func(string)
}

type AgentInfo struct {
	ID   string
	Name string
}

type AgentManager interface {
	// ListAgents returns enabled agents the user can access and the current agent ID.
	ListAgents(ctx context.Context, msg IncomingMessage) ([]AgentInfo, string, error)

	// SwitchAgent switches the active agent for this chat context.
	SwitchAgent(ctx context.Context, msg IncomingMessage, agentSlug string) error
}

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 Event struct {
	Text    string
	Image   *ImageEvent
	File    *FileEvent
	ToolUse *ToolUseEvent
	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"`
	GroupMode         string                 `json:"group_mode"`
	Groups            map[string]FeishuGroup `json:"groups"`
	EnableNotify      bool                   `json:"enable_notify"`
	TenantKey         string                 `json:"tenant_key"`
	AutoProvision     bool                   `json:"auto_provision"`
}

type FeishuGroup struct {
	GroupMode    string   `json:"group_mode"`
	SystemPrompt string   `json:"system_prompt"`
	ToolAllow    []string `json:"tool_allow"`
	ToolDeny     []string `json:"tool_deny"`
}

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

type Handler interface {
	MessageHandler
	ModelManager
	AgentManager
}

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
	Content    []ai.ContentBlock
}

type IndexedAgent struct {
	AgentInfo
	GlobalIdx int
}

type IndexedModel struct {
	ModelOption
	GlobalIdx int
}

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 ModelCommandHandler struct {
	Args                string
	Reply               func(string)
	ListModels          func() []ModelOption
	SwitchModel         func(provider, model string) error
	FormatList          func([]IndexedModel, string) string
	AllowIndexSelection bool
	OnSwitched          func(ModelOption)
}

type ModelManager interface {
	// ListModels returns available models.
	ListModels() []ModelOption

	// SwitchModel switches the active model.
	SwitchModel(provider, model string) 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
	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
	Name       string
	EmailHint  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"`
	GroupMode    string `json:"group_mode"`
	EnableNotify bool   `json:"enable_notify"`
}

type TelegramConfig struct {
	InstanceID   string `json:"-"`
	Token        string `json:"token"`
	ChannelID    string `json:"channel_id"`
	GroupMode    string `json:"group_mode"`
	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 {
	Tool   string // tool name, e.g. "bash", "read"
	Status string // "running", "done", "error"
	Input  string // short summary of the tool input
	Detail string // error detail or result summary
}

type UserRootResolver interface {
	ResolveUserRoot(ctx context.Context, msg IncomingMessage) (string, error)
}

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"`
	EnableNotify bool   `json:"enable_notify"`
}