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 AssetSaver interface {
	// SaveAsset writes data as a new file under assetsDir and returns the local
	// materialized path, durably persisting it in the asset authority. An
	// authority failure returns an error (the asset is never silently local-only).
	SaveAsset(ctx context.Context, assetsDir, fileName string, data []byte) (string, error)
}

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 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"`
	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"`
}

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
	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
}

type IndexedAgent struct {
	AgentInfo
	GlobalIdx int
}

type IndexedModel struct {
	ModelOption
	GlobalIdx int
}

type Mention struct {
	Raw        string // raw @ text (@username / <at open_id> ...), for audit/fallback
	PlatformID string // platform-side mentioned id (username / open_id / qq number)
	AgentID    string // 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 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
}

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"`
	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 UserRootResolver interface {
	ResolveUserRoot(ctx context.Context, msg IncomingMessage) (string, error)
}

type WebhookConfig struct {
	// DefaultWait selects synchronous (true) vs. fire-and-forget (false) when a
	// request does not set the ?wait query parameter.
	DefaultWait bool `json:"default_wait"`
	// WaitTimeoutSeconds bounds how long a synchronous caller waits for the
	// agent's reply before receiving 504 (the run continues in the background).
	WaitTimeoutSeconds int `json:"wait_timeout_seconds"`
	// MaxRunTimeoutSeconds is the hard ceiling on the agent run itself.
	MaxRunTimeoutSeconds int `json:"max_run_timeout_seconds"`
	// SessionMode is "ephemeral" (fresh session per trigger, default) or
	// "persistent" (one stable session per caller per webhook instance).
	SessionMode string `json:"session_mode"`
}

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"`
}