adapter

type Adapter interface {
	Name() string
	Start(ctx context.Context, incoming chan<- IncomingMessage) error
	Send(ctx context.Context, msg OutgoingMessage) error
	// SendTyping sends a typing/activity indicator to the given chat.
	// Used by the Dispatcher to keep the indicator alive during long processing.
	SendTyping(ctx context.Context, externalID string) error
	Stop() error
}

type CallbackResolver interface {
	Resolve(ctx context.Context, callbackData string) (responseText string, err error)
}

type IncomingMessage struct {
	Adapter    string
	ExternalID string // chat/conversation ID
	UserID     string
	UserName   string
	Text       string
	Timestamp  time.Time
	// ConversationID, when non-empty, overrides the default adapter:externalID
	// conversation key. Used by the scheduler to create isolated sessions.
	ConversationID string
	// SessionTier, when non-empty, overrides the engine's global permission
	// tier for this message. Used by the scheduler to enforce per-schedule tiers.
	SessionTier string
	// SkillName, when non-empty, indicates this message targets a specific skill.
	// Used by the scheduler to activate schedule-triggered skills.
	SkillName string
	// IsVoice is true when the original message was a voice note.
	// The adapter sets this after transcribing the audio via STT.
	IsVoice bool
}

type KeyboardButton struct {
	Label        string
	CallbackData string
}

type OutgoingMessage struct {
	// Adapter is the name of the adapter to route the response through (e.g.
	// "telegram", "discord"). Set by Engine.HandleMessage from the incoming
	// message's Adapter field. The SendFunc implementation (typically a
	// Dispatcher wrapper) uses this to select the correct outbound adapter.
	Adapter    string
	ExternalID string
	Text       string
	// IsVoice signals that the adapter should attempt to send a voice reply
	// (via TTS) instead of plain text, if configured to do so.
	IsVoice bool
	// Buttons, when non-empty, requests the adapter render an inline keyboard.
	// Ignored during voice replies.
	Buttons []KeyboardButton
}