channel

type Action struct {
	Type  string `json:"type"`
	Label string `json:"label,omitempty"`
	Value string `json:"value,omitempty"`
	URL   string `json:"url,omitempty"`
	// Row groups buttons into keyboard rows for renderers that support grids
	// (e.g. Telegram inline keyboards). Buttons sharing a Row render together;
	// rows appear in ascending numeric order. Renderers without grid support
	// ignore this field. 0 is the default (single row, prior behavior).
	Row int `json:"row,omitempty"`
}

type Adapter interface {
	Type() ChannelType
	Descriptor() Descriptor
}

type Attachment struct {
	Type           AttachmentType `json:"type"`
	URL            string         `json:"url,omitempty"`  // HTTP(S) or data URL
	Path           string         `json:"path,omitempty"` // workspace-local filesystem path
	PlatformKey    string         `json:"platform_key,omitempty"`
	SourcePlatform string         `json:"source_platform,omitempty"`
	ContentHash    string         `json:"content_hash,omitempty"`
	Base64         string         `json:"base64,omitempty"` // data URL for agent delivery
	Name           string         `json:"name,omitempty"`
	Size           int64          `json:"size,omitempty"`
	Mime           string         `json:"mime,omitempty"`
	DurationMs     int64          `json:"duration_ms,omitempty"`
	Width          int            `json:"width,omitempty"`
	Height         int            `json:"height,omitempty"`
	ThumbnailURL   string         `json:"thumbnail_url,omitempty"`
	Caption        string         `json:"caption,omitempty"`
	Metadata       map[string]any `json:"metadata,omitempty"`
}

type AttachmentPayload struct {
	Reader io.ReadCloser
	Mime   string
	Name   string
	Size   int64
}

type AttachmentResolver interface {
	ResolveAttachment(ctx context.Context, cfg ChannelConfig, attachment Attachment) (AttachmentPayload, error)
}

type AttachmentType string

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

type BindingCriteria struct {
	SubjectID  string
	Attributes map[string]string
}

type BindingMatcher interface {
	MatchBinding(config map[string]any, criteria BindingCriteria) bool
	BuildUserConfig(identity Identity) map[string]any
}

type BindingStore interface {
	ResolveChannelIdentityBinding(ctx context.Context, channelType ChannelType, criteria BindingCriteria) (string, error)
}

type ChannelCapabilities struct {
	Text            bool     `json:"text"`
	Markdown        bool     `json:"markdown"`
	RichText        bool     `json:"rich_text"`
	Attachments     bool     `json:"attachments"`
	Media           bool     `json:"media"`
	Reactions       bool     `json:"reactions"`
	Buttons         bool     `json:"buttons"`
	URLButtons      bool     `json:"url_buttons"`
	Reply           bool     `json:"reply"`
	Threads         bool     `json:"threads"`
	Streaming       bool     `json:"streaming"`
	Polls           bool     `json:"polls"`
	Edit            bool     `json:"edit"`
	Unsend          bool     `json:"unsend"`
	NativeCommands  bool     `json:"native_commands"`
	NativeUserInput bool     `json:"native_user_input"`
	BlockStreaming  bool     `json:"block_streaming"`
	ChatTypes       []string `json:"chat_types,omitempty"`
}

type ChannelConfig struct {
	ID               string         `json:"id"`
	TeamID           string         `json:"team_id"`
	BotID            string         `json:"bot_id"`
	ChannelType      ChannelType    `json:"channel_type"`
	Credentials      map[string]any `json:"credentials"`
	ExternalIdentity string         `json:"external_identity"`
	SelfIdentity     map[string]any `json:"self_identity"`
	Routing          map[string]any `json:"routing"`
	Disabled         bool           `json:"disabled"`
	VerifiedAt       time.Time      `json:"verified_at"`
	CreatedAt        time.Time      `json:"created_at"`
	UpdatedAt        time.Time      `json:"updated_at"`
}

type ChannelDirectoryAdapter interface {
	ListPeers(ctx context.Context, cfg ChannelConfig, query DirectoryQuery) ([]DirectoryEntry, error)
	ListGroups(ctx context.Context, cfg ChannelConfig, query DirectoryQuery) ([]DirectoryEntry, error)
	ListGroupMembers(ctx context.Context, cfg ChannelConfig, groupID string, query DirectoryQuery) ([]DirectoryEntry, error)
	ResolveEntry(ctx context.Context, cfg ChannelConfig, input string, kind DirectoryEntryKind) (DirectoryEntry, error)
}

type ChannelIdentityBinding struct {
	ID                string         `json:"id"`
	ChannelType       ChannelType    `json:"channel_type"`
	ChannelIdentityID string         `json:"channel_identity_id"`
	Config            map[string]any `json:"config"`
	CreatedAt         time.Time      `json:"created_at"`
	UpdatedAt         time.Time      `json:"updated_at"`
}

type ChannelType string

type Chunker func(text string, limit int) []string

type ChunkerMode string

type ConfigLister interface {
	ListConfigsByType(ctx context.Context, channelType ChannelType) ([]ChannelConfig, error)
}

type ConfigNormalizer interface {
	NormalizeConfig(raw map[string]any) (map[string]any, error)
	NormalizeUserConfig(raw map[string]any) (map[string]any, error)
}

type ConfigResolver interface {
	ResolveEffectiveConfig(ctx context.Context, botID string, channelType ChannelType) (ChannelConfig, error)
	GetChannelIdentityConfig(ctx context.Context, channelIdentityID string, channelType ChannelType) (ChannelIdentityBinding, error)
}

type ConfigSchema struct {
	Version int                    `json:"version"`
	Fields  map[string]FieldSchema `json:"fields"`
}

type ConfigStore interface {
	ConfigLister
	ConfigResolver
	BindingStore
	UpsertChannelIdentityConfig(ctx context.Context, channelIdentityID string, channelType ChannelType, req UpsertChannelIdentityConfigRequest) (ChannelIdentityBinding, error)
}

type Connection interface {
	ConfigID() string
	BotID() string
	ChannelType() ChannelType
	Stop(ctx context.Context) error
	Running() bool
}

type ConnectionController interface {
	EnsureConnection(ctx context.Context, cfg ChannelConfig) error
	RemoveConnection(ctx context.Context, botID string, channelType ChannelType)
}

type ConnectionStatus struct {
	ConfigID    string      `json:"config_id"`
	BotID       string      `json:"bot_id"`
	ChannelType ChannelType `json:"channel_type"`
	Running     bool        `json:"running"`
	LastError   string      `json:"last_error,omitempty"`
	UpdatedAt   time.Time   `json:"updated_at"`
}

type ContainerAttachmentIngester interface {
	IngestContainerFile(ctx context.Context, botID, containerPath string) (media.Asset, error)
}

type Conversation struct {
	ID       string
	Type     string
	Name     string
	ThreadID string
	Metadata map[string]any
}

type Descriptor struct {
	Type               ChannelType
	DisplayName        string
	Configless         bool
	AckDisabledWebhook bool
	// OwnerOnly marks channels that no third party can ever reach (e.g.
	// personal-assistant channels living inside the activator's own
	// account). Every sender on these channels is treated as the operator:
	// an unlinked sender resolves to the bot owner's account (so gates keyed
	// on the account principal, such as workspace exec and external runtimes,
	// see the owner), and the gates keyed on the channel identity instead —
	// chat ACL and write-gated slash commands — skip their /link requirement.
	OwnerOnly        bool
	Capabilities     ChannelCapabilities
	OutboundPolicy   OutboundPolicy
	ConfigSchema     ConfigSchema
	UserConfigSchema ConfigSchema
	TargetSpec       TargetSpec
}

type DirectoryEntry struct {
	Kind      DirectoryEntryKind `json:"kind"`
	ID        string             `json:"id"`
	Name      string             `json:"name,omitempty"`
	Handle    string             `json:"handle,omitempty"`
	AvatarURL string             `json:"avatar_url,omitempty"`
	Metadata  map[string]any     `json:"metadata,omitempty"`
}

type DirectoryEntryKind string

type DirectoryQuery struct {
	Query string             `json:"query,omitempty"`
	Limit int                `json:"limit,omitempty"`
	Kind  DirectoryEntryKind `json:"kind,omitempty"`
}

type FieldSchema struct {
	Type        FieldType `json:"type"`
	Required    bool      `json:"required"`
	Order       int       `json:"order,omitempty"`
	Title       string    `json:"title,omitempty"`
	Description string    `json:"description,omitempty"`
	Enum        []string  `json:"enum,omitempty"`
	Example     any       `json:"example,omitempty"`
}

type FieldType string

type ForwardRef struct {
	MessageID          string `json:"message_id,omitempty"`
	FromUserID         string `json:"from_user_id,omitempty"`
	FromConversationID string `json:"from_conversation_id,omitempty"`
	Sender             string `json:"sender,omitempty"`
	Date               int64  `json:"date,omitempty"`
	AttachmentsKnown   bool   `json:"attachments_known,omitempty"`
}

type Identity struct {
	SubjectID   string
	DisplayName string
	Attributes  map[string]string
}

type InboundHandler func(ctx context.Context, cfg ChannelConfig, msg InboundMessage) error

type InboundMessage struct {
	Channel      ChannelType
	Message      Message
	BotID        string
	ReplyTarget  string
	RouteKey     string
	Sender       Identity
	Conversation Conversation
	ReceivedAt   time.Time
	Source       string
	Metadata     map[string]any
}

type InboundProcessor interface {
	HandleInbound(ctx context.Context, cfg ChannelConfig, msg InboundMessage, sender StreamReplySender) error
}

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

type LifecycleStore interface {
	ResolveEffectiveConfig(ctx context.Context, botID string, channelType ChannelType) (ChannelConfig, error)
	UpsertConfig(ctx context.Context, botID string, channelType ChannelType, req UpsertConfigRequest) (ChannelConfig, error)
	UpdateConfigDisabled(ctx context.Context, botID string, channelType ChannelType, disabled bool) (ChannelConfig, error)
	DeleteConfig(ctx context.Context, botID string, channelType ChannelType) error
}

type LocalRuntime struct {
	Lifecycle *Lifecycle
	Store     *Store
	Manager   *Manager
}

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

type ManagerOption func(*Manager)

type ManagerStore interface {
	ConfigLister
	ConfigResolver
}

type Message struct {
	ID          string         `json:"id,omitempty"`
	Format      MessageFormat  `json:"format,omitempty"`
	Text        string         `json:"text,omitempty"`
	Parts       []MessagePart  `json:"parts,omitempty"`
	Attachments []Attachment   `json:"attachments,omitempty"`
	Actions     []Action       `json:"actions,omitempty"`
	Thread      *ThreadRef     `json:"thread,omitempty"`
	Reply       *ReplyRef      `json:"reply,omitempty"`
	Forward     *ForwardRef    `json:"forward,omitempty"`
	Metadata    map[string]any `json:"metadata,omitempty"`
}

type MessageEditor interface {
	Update(ctx context.Context, cfg ChannelConfig, target string, messageID string, msg PreparedMessage) error
	Unsend(ctx context.Context, cfg ChannelConfig, target string, messageID string) error
}

type MessageFormat string

type MessagePart struct {
	Type              MessagePartType    `json:"type"`
	Text              string             `json:"text,omitempty"`
	URL               string             `json:"url,omitempty"`
	Styles            []MessageTextStyle `json:"styles,omitempty"`
	Language          string             `json:"language,omitempty"`
	ChannelIdentityID string             `json:"channel_identity_id,omitempty"`
	Emoji             string             `json:"emoji,omitempty"`
	Metadata          map[string]any     `json:"metadata,omitempty"`
}

type MessagePartType string

type MessageTextStyle string

type Middleware func(next InboundHandler) InboundHandler

type OutboundAttachmentStore interface {
	// Stat returns asset metadata by content hash without opening the file.
	Stat(ctx context.Context, botID, contentHash string) (media.Asset, error)
	Open(ctx context.Context, botID, contentHash string) (io.ReadCloser, media.Asset, error)
	Ingest(ctx context.Context, input media.IngestInput) (media.Asset, error)
	GetByStorageKey(ctx context.Context, botID, storageKey string) (media.Asset, error)
	AccessPath(ctx context.Context, asset media.Asset) string
}

type OutboundCapabilityResolver interface {
	ResolveOutboundCapabilities(cfg ChannelConfig, target string, base ChannelCapabilities) ChannelCapabilities
}

type OutboundMessage struct {
	Target  string  `json:"target"`
	Message Message `json:"message"`
}

type OutboundOrder string

type OutboundPolicy struct {
	TextChunkLimit      int           `json:"text_chunk_limit,omitempty"`
	RichTextChunkLimit  int           `json:"rich_text_chunk_limit,omitempty"`
	ChunkerMode         ChunkerMode   `json:"chunker_mode,omitempty"`
	Chunker             Chunker       `json:"-"`
	MediaOrder          OutboundOrder `json:"media_order,omitempty"`
	InlineTextWithMedia bool          `json:"inline_text_with_media,omitempty"`
	RetryMax            int           `json:"retry_max,omitempty"`
	RetryBackoffMs      int           `json:"retry_backoff_ms,omitempty"`
}

type OutboundStream interface {
	Push(ctx context.Context, event StreamEvent) error
	Close(ctx context.Context) error
}

type OutboundTargetResolver interface {
	ResolveOutboundTarget(ctx context.Context, cfg ChannelConfig, target string) (string, error)
}

type PreparedAttachment struct {
	Logical   Attachment
	Kind      PreparedAttachmentKind
	NativeRef string
	PublicURL string
	Name      string
	Mime      string
	Size      int64
	// Open must return a fresh reader each time so retries are safe.
	Open func(ctx context.Context) (io.ReadCloser, error)
}

type PreparedAttachmentKind string

type PreparedMessage struct {
	Message     Message
	Attachments []PreparedAttachment
}

type PreparedOutboundMessage struct {
	Target  string
	Message PreparedMessage
}

type PreparedOutboundStream interface {
	Push(ctx context.Context, event PreparedStreamEvent) error
	Close(ctx context.Context) error
}

type PreparedOutboundValidator interface {
	ValidatePreparedOutbound(ctx context.Context, cfg ChannelConfig, target string, msg PreparedOutboundMessage) error
}

type PreparedStreamEvent struct {
	Type        StreamEventType
	Status      StreamStatus
	Delta       string
	Final       *PreparedStreamFinalizePayload
	Error       string
	ErrorCode   string
	ToolCall    *StreamToolCall
	Phase       StreamPhase
	Attachments []PreparedAttachment
	Reactions   []ReactRequest
	Speeches    []SpeechRequest
	Metadata    map[string]any
}

type PreparedStreamFinalizePayload struct {
	Message PreparedMessage
}

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

type ProcessingStatusErrorFunc func(ctx context.Context, stage string, err error)

type ProcessingStatusHandle struct {
	Token string
}

type ProcessingStatusInfo struct {
	BotID             string
	ChatID            string
	RouteID           string
	ChannelIdentityID string
	UserID            string
	Query             string
	ReplyTarget       string
	SourceMessageID   string
}

type ProcessingStatusNotifier interface {
	ProcessingStarted(ctx context.Context, cfg ChannelConfig, msg InboundMessage, info ProcessingStatusInfo) (ProcessingStatusHandle, error)
	ProcessingCompleted(ctx context.Context, cfg ChannelConfig, msg InboundMessage, info ProcessingStatusInfo, handle ProcessingStatusHandle) error
	ProcessingFailed(ctx context.Context, cfg ChannelConfig, msg InboundMessage, info ProcessingStatusInfo, handle ProcessingStatusHandle, cause error) error
}

type ProcessingStatusRefresher interface {
	// ProcessingRefreshInterval is how often the indicator is re-sent. A
	// non-positive interval disables refreshing.
	ProcessingRefreshInterval() time.Duration
	ProcessingRefresh(ctx context.Context, cfg ChannelConfig, msg InboundMessage, info ProcessingStatusInfo, handle ProcessingStatusHandle) error
}

type ReactRequest struct {
	Target    string `json:"target"`
	MessageID string `json:"message_id"`
	Emoji     string `json:"emoji"`
	Remove    bool   `json:"remove,omitempty"`
}

type Reactor interface {
	React(ctx context.Context, cfg ChannelConfig, target string, messageID string, emoji string) error
	Unreact(ctx context.Context, cfg ChannelConfig, target string, messageID string, emoji string) error
}

type Receiver interface {
	Connect(ctx context.Context, cfg ChannelConfig, handler InboundHandler) (Connection, error)
}

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

type ReplyRef struct {
	Target           string       `json:"target,omitempty"`
	MessageID        string       `json:"message_id,omitempty"`
	Sender           string       `json:"sender,omitempty"`
	Preview          string       `json:"preview,omitempty"`
	Attachments      []Attachment `json:"attachments,omitempty"`
	AttachmentsKnown bool         `json:"attachments_known,omitempty"`
}

type Runtime interface {
	UpsertBotChannelConfig(context.Context, string, ChannelType, UpsertConfigRequest) (ChannelConfig, error)
	SetBotChannelStatus(context.Context, string, ChannelType, bool) (ChannelConfig, error)
	DeleteBotChannelConfig(context.Context, string, ChannelType) error
	SetWebhookEndpoint(context.Context, string, ChannelType, SetWebhookEndpointRequest) (SetWebhookEndpointResponse, error)
	Send(context.Context, string, ChannelType, SendRequest) error
	React(context.Context, string, ChannelType, ReactRequest) error
	ConnectionStatusesByBot(string) []ConnectionStatus
}

type SelfDiscoverer interface {
	DiscoverSelf(ctx context.Context, credentials map[string]any) (identity map[string]any, externalID string, err error)
}

type SelfIdentityPolicy struct {
	RefreshOnCredentialsChange       bool
	RequireDiscoveryOnEnable         bool
	RequiredSelfIdentityKey          string
	DiscoveryErrorMessage            string
	MissingIdentityMessage           string
	DuplicateExternalIdentityMessage string
}

type SelfIdentityPolicyProvider interface {
	SelfIdentityPolicy() SelfIdentityPolicy
}

type SendRequest struct {
	// ExcludedTarget is checked after platform target resolution, before publication.
	ExcludedTarget    string  `json:"excluded_target,omitempty"`
	Target            string  `json:"target,omitempty"`
	ChannelIdentityID string  `json:"channel_identity_id,omitempty"`
	Message           Message `json:"message"`
}

type Sender interface {
	Send(ctx context.Context, cfg ChannelConfig, msg PreparedOutboundMessage) error
}

type SetWebhookEndpointRequest struct {
	Endpoint string `json:"endpoint"`
}

type SetWebhookEndpointResponse struct {
	Endpoint string `json:"endpoint"`
}

type SpeechRequest struct {
	Text string `json:"text"`
}

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

type StreamEvent struct {
	Type        StreamEventType        `json:"type"`
	Status      StreamStatus           `json:"status,omitempty"`
	Delta       string                 `json:"delta,omitempty"`
	Final       *StreamFinalizePayload `json:"final,omitempty"`
	Error       string                 `json:"error,omitempty"`
	ErrorCode   string                 `json:"error_code,omitempty"`
	ToolCall    *StreamToolCall        `json:"tool_call,omitempty"`
	Phase       StreamPhase            `json:"phase,omitempty"`
	Attachments []Attachment           `json:"attachments,omitempty"`
	Reactions   []ReactRequest         `json:"reactions,omitempty"`
	Speeches    []SpeechRequest        `json:"speeches,omitempty"`
	Metadata    map[string]any         `json:"metadata,omitempty"`
}

type StreamEventType string

type StreamFinalizePayload struct {
	Message Message `json:"message"`
}

type StreamObserver interface {
	// OnStreamEvent is called for every event pushed to an outbound stream.
	// botID identifies the bot that owns the conversation.
	// source is the channel type that originated the event (e.g. "telegram").
	OnStreamEvent(ctx context.Context, botID string, source ChannelType, event StreamEvent)
}

type StreamOptions struct {
	Reply           *ReplyRef      `json:"reply,omitempty"`
	SourceMessageID string         `json:"source_message_id,omitempty"`
	Metadata        map[string]any `json:"metadata,omitempty"`
}

type StreamPhase string

type StreamReplySender interface {
	Send(ctx context.Context, msg OutboundMessage) error
	OpenStream(ctx context.Context, target string, opts StreamOptions) (OutboundStream, error)
}

type StreamSender interface {
	OpenStream(ctx context.Context, cfg ChannelConfig, target string, opts StreamOptions) (PreparedOutboundStream, error)
}

type StreamStatus string

type StreamToolCall struct {
	Name       string   `json:"name"`
	CallID     string   `json:"call_id,omitempty"`
	Locale     string   `json:"locale,omitempty"`
	Input      any      `json:"input,omitempty"`
	Result     any      `json:"result,omitempty"`
	ApprovalID string   `json:"approval_id,omitempty"`
	ShortID    int      `json:"short_id,omitempty"`
	Actions    []Action `json:"actions,omitempty"`
}

type TargetHint struct {
	Example string `json:"example,omitempty"`
	Label   string `json:"label,omitempty"`
}

type TargetResolver interface {
	NormalizeTarget(raw string) string
	ResolveTarget(userConfig map[string]any) (string, error)
}

type TargetSpec struct {
	Format string       `json:"format"`
	Hints  []TargetHint `json:"hints,omitempty"`
}

type ThreadRef struct {
	ID string `json:"id"`
}

type ToolCallBlock struct {
	Type  ToolCallBlockType
	Title string
	URL   string
	Desc  string
	Text  string
}

type ToolCallBlockType string

type ToolCallPresentation struct {
	Emoji    string
	ToolName string
	Status   ToolCallStatus
	// HideToolHeader is for user-facing interactions whose implementation as
	// a tool is not meaningful to the recipient, such as ask_user prompts.
	HideToolHeader bool

	Header string
	Body   []ToolCallBlock
	Footer string

	InputSummary  string
	ResultSummary string
}

type ToolCallStatus string

type UpdateChannelStatusRequest struct {
	Disabled bool `json:"disabled"`
}

type UpsertChannelIdentityConfigRequest struct {
	Config map[string]any `json:"config"`
}

type UpsertConfigRequest struct {
	Credentials      map[string]any `json:"credentials"`
	ExternalIdentity string         `json:"external_identity,omitempty"`
	SelfIdentity     map[string]any `json:"self_identity,omitempty"`
	Routing          map[string]any `json:"routing,omitempty"`
	Disabled         *bool          `json:"disabled,omitempty"`
	VerifiedAt       *time.Time     `json:"verified_at,omitempty"`
}

type WebhookEndpointSetter interface {
	SetWebhookEndpoint(ctx context.Context, credentials map[string]any, endpoint string) error
}

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

type WebhookReceiver interface {
	HandleWebhook(ctx context.Context, cfg ChannelConfig, handler InboundHandler, r *http.Request, w http.ResponseWriter) error
}