messenger

type AGUIConfig struct {
	// AppName is used as the session.Key AppName for thread tracking.
	// Defaults to "genie" if empty.
	AppName string `yaml:"app_name,omitempty" toml:"app_name,omitempty"`

	// --- Server settings ---
	CORSOrigins []string `yaml:"cors_origins,omitempty" toml:"cors_origins,omitempty"`
	Port        uint32   `yaml:"port,omitempty" toml:"port,omitempty"`
	// BindAddr is the listen address (e.g. ":9876" for all interfaces, "127.0.0.1:9876" for localhost only).
	// When empty, the server binds to ":port" so HTTP-push messengers (Teams, Google Chat, AGUI) are reachable from other hosts/containers.
	BindAddr      string  `yaml:"bind_addr,omitempty" toml:"bind_addr,omitempty"`
	RateLimit     float64 `yaml:"rate_limit,omitempty" toml:"rate_limit,omitempty"`         // req/sec per IP (0 = disabled)
	RateBurst     int     `yaml:"rate_burst,omitempty" toml:"rate_burst,omitempty"`         // burst allowance per IP
	MaxConcurrent int     `yaml:"max_concurrent,omitempty" toml:"max_concurrent,omitempty"` // max in-flight requests (0 = unlimited)
	MaxBodyBytes  int64   `yaml:"max_body_bytes,omitempty" toml:"max_body_bytes,omitempty"` // max request body in bytes (0 = unlimited)

	// Auth holds authentication settings (password, JWT/OIDC).
	// See auth.Config for all available options.
	Auth auth.Config `yaml:"auth,omitempty" toml:"auth,omitempty"`
}

type AdapterConfig struct {
	// MessageBufferSize is the capacity of the incoming message channel.
	// Defaults to DefaultMessageBufferSize.
	MessageBufferSize int
	// SecretProvider is optional; when set, adapters (e.g. Google Chat) can use it
	// to resolve OAuth tokens and credentials (logged-in user) instead of service account files.
	SecretProvider security.SecretProvider
}

type AdapterFactory func(params map[string]string, opts ...Option) (Messenger, error)

type ApprovalInfo struct {
	// ID is the unique approval identifier.
	ID string
	// ToolName is the tool that requires approval.
	ToolName string
	// Args is the pretty-printed JSON arguments.
	Args string
	// Feedback is the optional justification / reason for the call.
	Feedback string
}

type Attachment struct {
	// Name is the filename or label.
	Name string `json:"name"`
	// URL is the download/access URL for the attachment.
	URL string `json:"url"`
	// ContentType is the MIME type (e.g., "image/png", "application/pdf").
	ContentType string `json:"content_type"`
	// Size is the file size in bytes (0 if unknown).
	Size int64 `json:"size"`
	// LocalPath is the path to the downloaded file on disk. Populated when
	// the adapter downloads the attachment (e.g., WhatsApp encrypted media).
	// Empty if only metadata is available (e.g., Slack URLs that require auth).
	LocalPath string `json:"local_path"`
}

type Channel struct {
	// ID is the platform-specific channel identifier.
	ID string
	// Name is the human-readable channel name (may be empty for DMs).
	Name string
	// Type classifies the channel (DM, group, or channel).
	Type ChannelType
}

type ChannelType string

type ClarificationInfo struct {
	// RequestID is the unique clarification request identifier.
	RequestID string
	// Question is the question posed by the agent.
	Question string
	// Context is optional context explaining why the agent needs this info.
	Context string
}

type Config struct {
	// Platform selects which adapter to use (slack, discord, telegram, teams, googlechat).
	// Empty means messaging is disabled.
	Platform Platform `yaml:"platform,omitempty" toml:"platform,omitempty"`

	// BufferSize controls the incoming message channel buffer.
	// Defaults to DefaultMessageBufferSize if zero.
	BufferSize int `yaml:"buffer_size,omitempty" toml:"buffer_size,omitempty"`

	// AllowedSenders is an optional allowlist of sender IDs (phone numbers,
	// usernames, or user IDs depending on platform) that the bot will respond
	// to. When empty, the bot responds to all incoming messages.
	// For WhatsApp: use phone numbers without '+' (e.g., "15551234567").
	AllowedSenders []string `yaml:"allowed_senders,omitempty" toml:"allowed_senders,omitempty"`

	// Slack holds Slack-specific configuration.
	Slack SlackConfig `yaml:"slack,omitempty" toml:"slack,omitempty"`

	// Discord holds Discord-specific configuration.
	Discord DiscordConfig `yaml:"discord,omitempty" toml:"discord,omitempty"`

	// Telegram holds Telegram-specific configuration.
	Telegram TelegramConfig `yaml:"telegram,omitempty" toml:"telegram,omitempty"`

	// Teams holds Microsoft Teams-specific configuration.
	Teams TeamsConfig `yaml:"teams,omitempty" toml:"teams,omitempty"`

	// GoogleChat holds Google Chat-specific configuration.
	GoogleChat GoogleChatConfig `yaml:"googlechat,omitempty" toml:"googlechat,omitempty"`

	// WhatsApp holds WhatsApp Business-specific configuration.
	WhatsApp WhatsAppConfig `yaml:"whatsapp,omitempty" toml:"whatsapp,omitempty"`

	// AGUI holds AG-UI SSE adapter configuration.
	AGUI AGUIConfig `yaml:"agui,omitempty" toml:"agui,omitempty"`
}

type DiscordConfig struct {
	// BotToken is the Discord bot token from the Developer Portal.
	BotToken string `yaml:"bot_token,omitempty" toml:"bot_token,omitempty"`
}

type GoogleChatConfig struct{}

type IncomingMessage struct {
	// ID is the platform-assigned message identifier.
	ID string
	// Platform identifies which platform the message came from.
	Platform Platform
	// Type distinguishes regular messages from reactions and interactions.
	// Empty string means a normal text/media message.
	Type MessageType
	// Channel is the conversation where the message was posted.
	Channel Channel
	// Sender is the author of the message.
	Sender Sender
	// Content is the message body and any attachments.
	Content MessageContent
	// ThreadID is the thread/reply-chain ID (empty if top-level).
	ThreadID string
	// Timestamp is when the message was sent.
	Timestamp time.Time
	// Metadata holds platform-specific data not captured by common fields.
	Metadata map[string]any

	// ReactionEmoji is the emoji used in a reaction (e.g. "👍", "👎").
	// Only populated when Type == MessageTypeReaction.
	ReactionEmoji string
	// ReactedMessageID is the platform-assigned ID of the message being
	// reacted to. Only populated when Type == MessageTypeReaction.
	ReactedMessageID string

	// Interaction carries structured data when Type == MessageTypeInteraction.
	// Populated by adapters that support interactive UI elements (buttons,
	// menus, card actions). Nil for all other message types.
	Interaction *InteractionData
}

type InteractionData struct {
	// ActionID is the platform-specific action identifier.
	// Convention: "{verb}_{resourceID}" (e.g. "approve_abc123",
	// "reject_abc123", "clarify_respond_xyz").
	ActionID string
	// ActionValue is the value associated with the action. For approval
	// buttons, this is the approval ID.
	ActionValue string
	// BlockID is the container block/card identifier
	// (e.g. "approval_abc123" in Slack Block Kit).
	BlockID string
	// ActionType describes the UI element type (e.g. "button", "select").
	ActionType string
	// ResponseURL is an optional, time-limited URL provided by the
	// platform for updating or replacing the message that contained the
	// interactive element. Slack provides this for 30 minutes after a
	// block_actions event. Adapters that don't support it leave this empty.
	ResponseURL string
}

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

type MessageContent struct {
	// Text is the plain-text or markdown message body.
	Text string
	// Attachments are optional file/media attachments.
	Attachments []Attachment
}

type MessageLedger interface {
	// Record associates a sent message ID with its agent context.
	Record(ctx context.Context, messageID string, goal, output, senderKey string)
}

type MessageOrigin struct {
	// Platform identifies which messaging platform (whatsapp, slack, etc).
	Platform Platform
	// Channel is the conversation where the message was posted.
	Channel Channel
	// Sender is the author of the message.
	Sender Sender
	// ThreadID is the thread/reply-chain ID (empty if top-level).
	ThreadID string
	// MessageID is the platform-assigned ID of the original incoming message.
	// Used to quote/reply-to the user's message in outgoing responses.
	MessageID string
}

type MessageType string

type Messenger interface {
	// Connect establishes a connection to the messaging platform and returns
	// an optional http.Handler for receiving inbound webhook/push events.
	//
	// HTTP-push adapters (Teams, Google Chat, Slack Events API, Telegram
	// webhook) return a non-nil handler that the caller mounts on a shared
	// HTTP mux at the desired context path (e.g., /agents/{name}/{platform}/events).
	// The adapter MUST NOT start its own http.Server.
	//
	// Outbound-only adapters (Slack Socket Mode, Discord WebSocket, Telegram
	// long-polling, WhatsApp) return a nil handler because they initiate
	// connections to the platform rather than receiving inbound HTTP.
	//
	// Calling Connect on an already-connected Messenger returns
	// (nil, ErrAlreadyConnected).
	Connect(ctx context.Context) (http.Handler, error)

	// Disconnect gracefully shuts down the platform connection.
	// After Disconnect, the Receive channel will be closed and further
	// Send calls will return ErrNotConnected.
	Disconnect(ctx context.Context) error

	// Send delivers a message to a specific channel/conversation.
	// Returns ErrNotConnected if Connect has not been called.
	Send(ctx context.Context, req SendRequest) (SendResponse, error)

	// Receive returns a read-only channel that delivers incoming messages.
	// The channel is closed when the context is cancelled or Disconnect is called.
	// Returns ErrNotConnected if Connect has not been called.
	Receive(ctx context.Context) (<-chan IncomingMessage, error)

	// Platform returns the platform identifier for this adapter.
	Platform() Platform

	// FormatApproval enriches a SendRequest with platform-specific rich
	// formatting (e.g. Slack Block Kit, Google Chat Cards v2, Teams Adaptive
	// Cards) for the given approval. Adapters that do not support rich
	// formatting should return the request unchanged.
	FormatApproval(req SendRequest, info ApprovalInfo) SendRequest

	ConnectionInfo() string

	// FormatClarification enriches a SendRequest with platform-specific rich
	// formatting for a clarifying question posed by the agent.
	// Adapters that do not support rich formatting should return the request unchanged.
	FormatClarification(req SendRequest, info ClarificationInfo) SendRequest

	// UpdateMessage replaces the content of a previously sent message.
	// Used to disarm interactive buttons after resolution (e.g. replacing
	// approval buttons with "✅ Approved by @user") and to update
	// progress messages. Adapters that do not support message editing
	// should return nil (a no-op).
	// Returns ErrNotConnected if Connect has not been called.
	UpdateMessage(ctx context.Context, req UpdateRequest) error
}

type Option func(*AdapterConfig)

type Platform string

type SendMessageToolOption func(*messageTool)

type SendRequest struct {
	// Type selects the action. Default ("") sends a normal message.
	// Use SendTypeReaction to react to an existing message with an emoji.
	Type SendType
	// Channel is the target channel/conversation.
	Channel Channel
	// Content is the message body (ignored for reactions).
	Content MessageContent
	// ThreadID is an optional thread/reply-chain identifier for threaded replies.
	// Leave empty to post at top level.
	ThreadID string
	// ReplyToMessageID, if set, quotes/replies to the specified message.
	// For reactions, this is the message ID to react to.
	ReplyToMessageID string
	// Emoji is the reaction emoji (e.g. "👍"). Only used when Type is SendTypeReaction.
	Emoji string
	// Metadata holds platform-specific key-value pairs that adapters can use
	// for features not covered by the common interface (e.g., Slack blocks,
	// Discord embeds).
	Metadata map[string]any
}

type SendResponse struct {
	// MessageID is the platform-assigned identifier for the sent message.
	MessageID string
	// Timestamp is when the platform recorded the message.
	Timestamp time.Time
}

type SendType string

type Sender struct {
	// ID is the platform-specific user identifier.
	ID string
	// Username is the unique handle (e.g., Slack member ID, Discord username).
	Username string
	// DisplayName is the user's friendly name (e.g. "John Doe").
	// Adapters should populate both if possible; otherwise DisplayName generally falls back to Username.
	DisplayName string
}

type SlackConfig struct {
	// AppToken is the Slack app-level token (xapp-...) for Socket Mode.
	AppToken string `yaml:"app_token,omitempty" toml:"app_token,omitempty"`
	// BotToken is the Slack bot user OAuth token (xoxb-...).
	BotToken string `yaml:"bot_token,omitempty" toml:"bot_token,omitempty"`
}

type TeamsConfig struct {
	// AppID is the Microsoft Bot Framework App ID.
	AppID string `yaml:"app_id,omitempty" toml:"app_id,omitempty"`
	// AppPassword is the Microsoft Bot Framework App Password.
	AppPassword string `yaml:"app_password,omitempty" toml:"app_password,omitempty"`
	// ListenAddr is the address for incoming Bot Framework activities (e.g., ":3978").
	ListenAddr string `yaml:"listen_addr,omitempty" toml:"listen_addr,omitempty"`
}

type TelegramConfig struct {
	// Token is the Telegram Bot API token from BotFather.
	Token string `yaml:"token,omitempty" toml:"token,omitempty"`
}

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

type UpdateRequest struct {
	// MessageID is the platform-assigned identifier of the message to update.
	MessageID string
	// Channel is the channel/conversation containing the message.
	Channel Channel
	// Content is the replacement message body.
	Content MessageContent
	// Metadata holds platform-specific key-value pairs for the update
	// (e.g. replacement Slack blocks, updated Adaptive Card).
	Metadata map[string]any
}

type WhatsAppConfig struct {
}