connector

type AIClient struct {
	UserLogin *bridgev2.UserLogin
	// contains filtered or unexported fields
}

type AIClientHooks interface {
	BeforeResponse(ctx context.Context, portal *bridgev2.Portal, meta *PortalMetadata) error
	AfterResponse(ctx context.Context, portal *bridgev2.Portal, meta *PortalMetadata) error
	GetExtraSystemPrompt(ctx context.Context, portal *bridgev2.Portal, meta *PortalMetadata) string
	AdditionalTools(ctx context.Context, portal *bridgev2.Portal, meta *PortalMetadata) []ToolDefinition
}

type AIErrorContent struct {
	Body    string `json:"body"`
	MsgType string `json:"msgtype"`

	Error *AIErrorData `json:"com.beeper.ai.error"`
}

type AIErrorData struct {
	TurnID       string `json:"turn_id,omitempty"`
	ErrorCode    string `json:"error_code"`
	ErrorMessage string `json:"error_message"`
	Retryable    bool   `json:"retryable"`
	Suggestion   string `json:"suggestion,omitempty"`
}

type AIProvider interface {
	Name() string
	GenerateStream(ctx context.Context, params GenerateParams) (<-chan StreamEvent, error)
	Generate(ctx context.Context, params GenerateParams) (*GenerateResponse, error)
	ListModels(ctx context.Context) ([]ModelInfo, error)
}

type AckReactionGateParams struct {
	Scope              AckReactionScope
	IsDirect           bool
	IsGroup            bool
	IsMentionableGroup bool
	RequireMention     bool
	CanDetectMention   bool
	EffectiveMention   bool
	ShouldBypass       bool
}

type AckReactionScope string

type Annotation struct {
	Type      string            `json:"type"`            // "citation", "reference"
	Index     int               `json:"index,omitempty"` // Citation number [1], [2], etc.
	StartChar int               `json:"start_char,omitempty"`
	EndChar   int               `json:"end_char,omitempty"`
	Source    *AnnotationSource `json:"source,omitempty"`
}

type AnnotationSource struct {
	Type     string `json:"type"` // "web", "document", "file"
	URL      string `json:"url,omitempty"`
	Title    string `json:"title,omitempty"`
	Snippet  string `json:"snippet,omitempty"`
	FileID   string `json:"file_id,omitempty"`
	Filename string `json:"filename,omitempty"`
	Page     int    `json:"page,omitempty"`
}

type AssistantTurnAI struct {
	TurnID       string     `json:"turn_id"`
	Model        string     `json:"model"`
	Status       TurnStatus `json:"status"`
	FinishReason string     `json:"finish_reason,omitempty"`

	// Embedded thinking (not separate event)
	Thinking *ThinkingContent `json:"thinking,omitempty"`

	// Token usage
	Usage *EventUsageInfo `json:"usage,omitempty"`

	// Related events
	ToolCalls []string `json:"tool_calls,omitempty"`
	Images    []string `json:"images,omitempty"`

	// Timing information
	Timing *TimingInfo `json:"timing,omitempty"`

	// Annotations/citations
	Annotations []Annotation `json:"annotations,omitempty"`
}

type AssistantTurnContent struct {
	// Standard Matrix fallback fields
	Body          string `json:"body"`
	MsgType       string `json:"msgtype"`
	Format        string `json:"format,omitempty"`
	FormattedBody string `json:"formatted_body,omitempty"`

	// AI-specific metadata
	AI *AssistantTurnAI `json:"com.beeper.ai,omitempty"`
}

type AttachmentMetadata struct {
	Type     string `json:"type"` // "file", "image"
	FileID   string `json:"file_id,omitempty"`
	Filename string `json:"filename,omitempty"`
	MxcURI   string `json:"mxc_uri,omitempty"`
	Mimetype string `json:"mimetype,omitempty"`
	Size     int    `json:"size,omitempty"`
	Width    int    `json:"width,omitempty"`  // For images
	Height   int    `json:"height,omitempty"` // For images
}

type BeeperConfig struct {
	BaseURL string `yaml:"base_url"` // Beeper AI proxy endpoint
	Token   string `yaml:"token"`    // Beeper Matrix access token
}

type BridgeConfig struct {
	CommandPrefix      string `yaml:"command_prefix"`
	LogEphemeralEvents *bool  `yaml:"log_ephemeral_events"`
}

type BridgePolicy struct {
	Name             string
	NetworkID        string
	BeeperBridgeType string

	ProvisioningEnabled bool
	ResolveIdentifier   bridgev2.ResolveIdentifierCapabilities
}

type BridgeToolContext struct {
	Client        *AIClient
	Portal        *bridgev2.Portal
	Meta          *PortalMetadata
	SourceEventID id.EventID
	SenderID      string
}

type ChannelConfig struct {
	ResponsePrefix string `yaml:"responsePrefix"`
	ReplyToMode    string `yaml:"replyToMode"`   // off|first|all (Matrix)
	ThreadReplies  string `yaml:"threadReplies"` // off|inbound|always (Matrix)
}

type ChannelDefaultsConfig struct {
	ResponsePrefix string `yaml:"responsePrefix"`
}

type ChannelsConfig struct {
	Defaults *ChannelDefaultsConfig `yaml:"defaults"`
	Matrix   *ChannelConfig         `yaml:"matrix"`
}

type ClientFactory func(login *bridgev2.UserLogin, connector *OpenAIConnector, apiKey string) (bridgev2.NetworkAPI, error)

type CommandsConfig struct {
	OwnerAllowFrom []string `yaml:"ownerAllowFrom"`
}

type Config struct {
	Beeper    BeeperConfig        `yaml:"beeper"`
	Providers ProvidersConfig     `yaml:"providers"`
	Models    *ModelsConfig       `yaml:"models"`
	Bridge    BridgeConfig        `yaml:"bridge"`
	Tools     ToolProvidersConfig `yaml:"tools"`
	Channels  *ChannelsConfig     `yaml:"channels"`
	Messages  *MessagesConfig     `yaml:"messages"`
	Commands  *CommandsConfig     `yaml:"commands"`

	// Global settings
	DefaultSystemPrompt string        `yaml:"default_system_prompt"`
	ModelCacheDuration  time.Duration `yaml:"model_cache_duration"`

	// Context pruning configuration (OpenClaw-style)
	Pruning *PruningConfig `yaml:"pruning"`

	// Link preview configuration
	LinkPreviews *linkpreview.Config `yaml:"link_previews"`

	// Inbound message processing configuration
	Inbound *InboundConfig `yaml:"inbound"`

	// Extra holds bridge-specific config that the core engine carries
	// opaquely.
	Extra any `yaml:"-"`
}

type ConnectorHooks interface {
	OnStart(ctx context.Context) error
	OnNewClient(client *AIClient) error
	RegisterCommands(proc *commands.Processor)
	RegisterEventHandlers(conn *matrix.Connector)
}

type ContentPart struct {
	Type        ContentPartType
	Text        string
	ImageURL    string
	ImageB64    string
	MimeType    string
	PDFURL      string
	PDFB64      string
	AudioB64    string
	AudioFormat string
	VideoURL    string
	VideoB64    string
}

type ContentPartType string

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

type DebounceEntry struct {
	Event        *event.Event
	Portal       *bridgev2.Portal
	Meta         *PortalMetadata
	RawBody      string
	SenderName   string
	RoomName     string
	IsGroup      bool
	WasMentioned bool
	AckEventID   id.EventID // Track ack reaction for removal after flush
	PendingSent  bool       // Whether a pending status was already sent for this event
}

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

type DirectChatConfig struct {
	HistoryLimit int `yaml:"historyLimit"`
}

type EffectiveSettings struct {
	Model           SettingExplanation `json:"model"`
	SystemPrompt    SettingExplanation `json:"system_prompt"`
	Temperature     SettingExplanation `json:"temperature"`
	ReasoningEffort SettingExplanation `json:"reasoning_effort"`
}

type EnvelopeFormatOptions struct {
	Timezone         string
	IncludeTimestamp bool
	IncludeElapsed   bool
	UserTimezone     string
}

type EventUsageInfo struct {
	PromptTokens     int64 `json:"prompt_tokens,omitempty"`
	CompletionTokens int64 `json:"completion_tokens,omitempty"`
	ReasoningTokens  int64 `json:"reasoning_tokens,omitempty"`
}

type FetchConfig struct {
	Provider  string   `yaml:"provider"`
	Fallbacks []string `yaml:"fallbacks"`

	Exa    ProviderExaConfig    `yaml:"exa"`
	Direct ProviderDirectConfig `yaml:"direct"`
}

type FileAnnotation struct {
	FileHash   string `json:"file_hash"`            // SHA256 hash of the file content
	ParsedText string `json:"parsed_text"`          // Extracted text content
	PageCount  int    `json:"page_count,omitempty"` // Number of pages
	CreatedAt  int64  `json:"created_at"`           // Unix timestamp when cached
}

type GenerateParams struct {
	Model               string
	Messages            []UnifiedMessage
	SystemPrompt        string
	Temperature         float64
	MaxCompletionTokens int
	Tools               []ToolDefinition
	ReasoningEffort     string
	PreviousResponseID  string
	WebSearchEnabled    bool
}

type GenerateResponse struct {
	Content      string
	FinishReason string
	ResponseID   string
	ToolCalls    []ToolCallResult
	Usage        UsageInfo
}

type GeneratedFileRef struct {
	URL      string `json:"url"`
	MimeType string `json:"mime_type"`
}

type GenerationDetails struct {
	CurrentTool    string `json:"current_tool,omitempty"`
	CallID         string `json:"call_id,omitempty"`
	ToolsCompleted int    `json:"tools_completed,omitempty"`
	ToolsTotal     int    `json:"tools_total,omitempty"`
}

type GenerationProgress struct {
	TokensGenerated int `json:"tokens_generated,omitempty"`
	ThinkingTokens  int `json:"thinking_tokens,omitempty"`
}

type GenerationStatusContent struct {
	TurnID        string `json:"turn_id"`
	TargetEvent   string `json:"target_event,omitempty"`
	Status        string `json:"status"` // "starting", "thinking", "generating", "tool_use", etc.
	StatusMessage string `json:"status_message,omitempty"`

	Details  *GenerationDetails  `json:"details,omitempty"`
	Progress *GenerationProgress `json:"progress,omitempty"`
	Display  *StatusDisplay      `json:"display,omitempty"`
}

type GhostMetadata struct {
	LastSync jsontime.Unix `json:"last_sync,omitempty"`
}

type GravatarProfile struct {
	Email     string         `json:"email,omitempty"`
	Hash      string         `json:"hash,omitempty"`
	Profile   map[string]any `json:"profile,omitempty"` // Full profile payload
	FetchedAt int64          `json:"fetched_at,omitempty"`
}

type GravatarState struct {
	Primary *GravatarProfile `json:"primary,omitempty"`
}

type GroupChatConfig struct {
	MentionPatterns []string `yaml:"mentionPatterns"`
	Activation      string   `yaml:"activation"` // mention|always
	HistoryLimit    int      `yaml:"historyLimit"`
}

type ImageGenerationMetadata struct {
	TurnID        string `json:"turn_id,omitempty"`
	Prompt        string `json:"prompt,omitempty"`
	RevisedPrompt string `json:"revised_prompt,omitempty"`
	Model         string `json:"model,omitempty"`
	Style         string `json:"style,omitempty"`   // "vivid", "natural"
	Quality       string `json:"quality,omitempty"` // "standard", "hd"
}

type InboundConfig struct {
	// Deduplication settings
	DedupeTTL     time.Duration `yaml:"dedupe_ttl"`      // Time-to-live for dedupe entries (default: 20m)
	DedupeMaxSize int           `yaml:"dedupe_max_size"` // Max entries in dedupe cache (default: 5000)

	// Debounce settings
	DefaultDebounceMs int `yaml:"default_debounce_ms"` // Default debounce delay in ms (default: 500)
}

type InboundDebounceConfig struct {
	DebounceMs int            `yaml:"debounceMs"`
	ByChannel  map[string]int `yaml:"byChannel"`
}

type MediaToolsConfig struct {
	Models      []MediaUnderstandingModelConfig `yaml:"models" json:"models,omitempty"`
	Concurrency int                             `yaml:"concurrency" json:"concurrency,omitempty"`
	Image       *MediaUnderstandingConfig       `yaml:"image" json:"image,omitempty"`
	Audio       *MediaUnderstandingConfig       `yaml:"audio" json:"audio,omitempty"`
	Video       *MediaUnderstandingConfig       `yaml:"video" json:"video,omitempty"`
}

type MediaUnderstandingAttachmentDecision struct {
	AttachmentIndex int                               `json:"attachment_index"`
	Attempts        []MediaUnderstandingModelDecision `json:"attempts,omitempty"`
	Chosen          *MediaUnderstandingModelDecision  `json:"chosen,omitempty"`
}

type MediaUnderstandingAttachmentsConfig struct {
	Mode           string `yaml:"mode" json:"mode,omitempty"`
	MaxAttachments int    `yaml:"maxAttachments" json:"maxAttachments,omitempty"`
	Prefer         string `yaml:"prefer" json:"prefer,omitempty"`
}

type MediaUnderstandingCapability string

type MediaUnderstandingConfig struct {
	Enabled         *bool                                `yaml:"enabled" json:"enabled,omitempty"`
	Scope           *MediaUnderstandingScopeConfig       `yaml:"scope" json:"scope,omitempty"`
	MaxBytes        int                                  `yaml:"maxBytes" json:"maxBytes,omitempty"`
	MaxChars        int                                  `yaml:"maxChars" json:"maxChars,omitempty"`
	Prompt          string                               `yaml:"prompt" json:"prompt,omitempty"`
	TimeoutSeconds  int                                  `yaml:"timeoutSeconds" json:"timeoutSeconds,omitempty"`
	Language        string                               `yaml:"language" json:"language,omitempty"`
	ProviderOptions map[string]map[string]any            `yaml:"providerOptions" json:"providerOptions,omitempty"`
	Deepgram        *MediaUnderstandingDeepgramConfig    `yaml:"deepgram" json:"deepgram,omitempty"`
	BaseURL         string                               `yaml:"baseUrl" json:"baseUrl,omitempty"`
	Headers         map[string]string                    `yaml:"headers" json:"headers,omitempty"`
	Attachments     *MediaUnderstandingAttachmentsConfig `yaml:"attachments" json:"attachments,omitempty"`
	Models          []MediaUnderstandingModelConfig      `yaml:"models" json:"models,omitempty"`
}

type MediaUnderstandingDecision struct {
	Capability  MediaUnderstandingCapability           `json:"capability"`
	Outcome     string                                 `json:"outcome,omitempty"`
	Attachments []MediaUnderstandingAttachmentDecision `json:"attachments,omitempty"`
}

type MediaUnderstandingDeepgramConfig struct {
	DetectLanguage *bool `yaml:"detectLanguage" json:"detectLanguage,omitempty"`
	Punctuate      *bool `yaml:"punctuate" json:"punctuate,omitempty"`
	SmartFormat    *bool `yaml:"smartFormat" json:"smartFormat,omitempty"`
}

type MediaUnderstandingKind string

type MediaUnderstandingModelConfig struct {
	Provider         string                            `yaml:"provider" json:"provider,omitempty"`
	Model            string                            `yaml:"model" json:"model,omitempty"`
	Capabilities     []string                          `yaml:"capabilities" json:"capabilities,omitempty"`
	Type             string                            `yaml:"type" json:"type,omitempty"`
	Command          string                            `yaml:"command" json:"command,omitempty"`
	Args             []string                          `yaml:"args" json:"args,omitempty"`
	Prompt           string                            `yaml:"prompt" json:"prompt,omitempty"`
	MaxChars         int                               `yaml:"maxChars" json:"maxChars,omitempty"`
	MaxBytes         int                               `yaml:"maxBytes" json:"maxBytes,omitempty"`
	TimeoutSeconds   int                               `yaml:"timeoutSeconds" json:"timeoutSeconds,omitempty"`
	Language         string                            `yaml:"language" json:"language,omitempty"`
	ProviderOptions  map[string]map[string]any         `yaml:"providerOptions" json:"providerOptions,omitempty"`
	Deepgram         *MediaUnderstandingDeepgramConfig `yaml:"deepgram" json:"deepgram,omitempty"`
	BaseURL          string                            `yaml:"baseUrl" json:"baseUrl,omitempty"`
	Headers          map[string]string                 `yaml:"headers" json:"headers,omitempty"`
	Profile          string                            `yaml:"profile" json:"profile,omitempty"`
	PreferredProfile string                            `yaml:"preferredProfile" json:"preferredProfile,omitempty"`
}

type MediaUnderstandingModelDecision struct {
	Type     string `json:"type,omitempty"`
	Provider string `json:"provider,omitempty"`
	Model    string `json:"model,omitempty"`
	Outcome  string `json:"outcome,omitempty"`
	Reason   string `json:"reason,omitempty"`
}

type MediaUnderstandingOutput struct {
	Kind            MediaUnderstandingKind `json:"kind"`
	AttachmentIndex int                    `json:"attachment_index"`
	Text            string                 `json:"text"`
	Provider        string                 `json:"provider"`
	Model           string                 `json:"model,omitempty"`
}

type MediaUnderstandingScopeConfig struct {
	Default string                        `yaml:"default" json:"default,omitempty"`
	Rules   []MediaUnderstandingScopeRule `yaml:"rules" json:"rules,omitempty"`
}

type MediaUnderstandingScopeMatch struct {
	Channel   string `yaml:"channel" json:"channel,omitempty"`
	ChatType  string `yaml:"chatType" json:"chatType,omitempty"`
	KeyPrefix string `yaml:"keyPrefix" json:"keyPrefix,omitempty"`
}

type MediaUnderstandingScopeRule struct {
	Action string                        `yaml:"action" json:"action,omitempty"`
	Match  *MediaUnderstandingScopeMatch `yaml:"match" json:"match,omitempty"`
}

type MessageMetadata struct {
	Role             string `json:"role,omitempty"`
	Body             string `json:"body,omitempty"`
	CompletionID     string `json:"completion_id,omitempty"`
	FinishReason     string `json:"finish_reason,omitempty"`
	PromptTokens     int64  `json:"prompt_tokens,omitempty"`
	CompletionTokens int64  `json:"completion_tokens,omitempty"`
	Model            string `json:"model,omitempty"`
	ReasoningTokens  int64  `json:"reasoning_tokens,omitempty"`
	HasToolCalls     bool   `json:"has_tool_calls,omitempty"`
	Transcript       string `json:"transcript,omitempty"`

	// Media understanding (OpenClaw-style)
	MediaUnderstanding          []MediaUnderstandingOutput   `json:"media_understanding,omitempty"`
	MediaUnderstandingDecisions []MediaUnderstandingDecision `json:"media_understanding_decisions,omitempty"`

	// Turn tracking for the new schema
	TurnID string `json:"turn_id,omitempty"` // Unique identifier for this assistant turn

	// Tool call tracking
	ToolCalls []ToolCallMetadata `json:"tool_calls,omitempty"` // List of tool calls in this turn

	// Canonical internal schema payload (AI SDK).
	CanonicalSchema    string         `json:"canonical_schema,omitempty"`     // e.g. ai-sdk-ui-message-v1
	CanonicalUIMessage map[string]any `json:"canonical_ui_message,omitempty"` // AI SDK UIMessage payload

	// Timing information
	StartedAtMs    int64 `json:"started_at_ms,omitempty"`     // Unix ms when generation started
	FirstTokenAtMs int64 `json:"first_token_at_ms,omitempty"` // Unix ms of first token
	CompletedAtMs  int64 `json:"completed_at_ms,omitempty"`   // Unix ms when completed

	// Thinking/reasoning content (embedded, not separate)
	ThinkingContent    string `json:"thinking_content,omitempty"`     // Full thinking text
	ThinkingTokenCount int    `json:"thinking_token_count,omitempty"` // Number of thinking tokens

	// History exclusion
	ExcludeFromHistory bool `json:"exclude_from_history,omitempty"` // Exclude from LLM context (e.g., welcome messages)

	// Multimodal history: media attached to this message for re-injection into prompts.
	MediaURL       string             `json:"media_url,omitempty"`       // mxc:// URL for user-sent media (image, PDF, audio, video)
	MimeType       string             `json:"mime_type,omitempty"`       // MIME type of user-sent media
	GeneratedFiles []GeneratedFileRef `json:"generated_files,omitempty"` // Files generated by the assistant in this turn
}

type MessageRole string

type MessagesConfig struct {
	ResponsePrefix   string                 `yaml:"responsePrefix"`
	AckReaction      string                 `yaml:"ackReaction"`
	AckReactionScope string                 `yaml:"ackReactionScope"` // group-mentions|group-all|direct|all|off|none
	RemoveAckAfter   bool                   `yaml:"removeAckAfterReply"`
	GroupChat        *GroupChatConfig       `yaml:"groupChat"`
	DirectChat       *DirectChatConfig      `yaml:"directChat"`
	Queue            *QueueConfig           `yaml:"queue"`
	InboundDebounce  *InboundDebounceConfig `yaml:"inbound"`
}

type ModelAPI string

type ModelCache struct {
	Models        []ModelInfo `json:"models,omitempty"`
	LastRefresh   int64       `json:"last_refresh,omitempty"`
	CacheDuration int64       `json:"cache_duration,omitempty"` // seconds
}

type ModelCapabilities struct {
	SupportsVision      bool `json:"supports_vision"`
	SupportsReasoning   bool `json:"supports_reasoning"` // Models that support reasoning_effort parameter
	SupportsPDF         bool `json:"supports_pdf"`
	SupportsImageGen    bool `json:"supports_image_gen"`
	SupportsAudio       bool `json:"supports_audio"`        // Models that accept audio input
	SupportsVideo       bool `json:"supports_video"`        // Models that accept video input
	SupportsToolCalling bool `json:"supports_tool_calling"` // Models that support function calling
}

type ModelCapabilitiesEventContent struct {
	AvailableModels []ModelInfo `json:"available_models"`
}

type ModelCatalogEntry struct {
	ID              string   `json:"id"`
	Name            string   `json:"name,omitempty"`
	Provider        string   `json:"provider"`
	ContextWindow   int      `json:"contextWindow,omitempty"`
	MaxOutputTokens int      `json:"maxTokens,omitempty"`
	Reasoning       bool     `json:"reasoning,omitempty"`
	Input           []string `json:"input,omitempty"`
}

type ModelDefinitionConfig struct {
	ID            string   `yaml:"id"`
	Name          string   `yaml:"name"`
	Reasoning     bool     `yaml:"reasoning"`
	Input         []string `yaml:"input"`
	ContextWindow int      `yaml:"context_window"`
	MaxTokens     int      `yaml:"max_tokens"`
}

type ModelInfo aimodels.ModelInfo

type ModelProviderConfig struct {
	Models []ModelDefinitionConfig `yaml:"models"`
}

type ModelsConfig struct {
	Mode      string                         `yaml:"mode"` // merge | replace
	Providers map[string]ModelProviderConfig `yaml:"providers"`
}

type NoopStreamingHooks struct{}

type NormalizedLocation struct {
	Latitude  float64
	Longitude float64
	Accuracy  *float64
	Name      string
	Address   string
	Caption   string
	Source    string // pin|place|live
	IsLive    bool
}

type OpenAIConnector struct {
	Config Config
	// contains filtered or unexported fields
}

type OpenAILogin struct {
	User      *bridgev2.User
	Connector *OpenAIConnector
	FlowID    string
}

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

type OpenAIRemoteMessage struct {
	PortalKey networkid.PortalKey
	ID        networkid.MessageID
	Sender    bridgev2.EventSender
	Content   string
	Timestamp time.Time
	Metadata  *MessageMetadata

	FormattedContent string
	ReplyToEventID   id.EventID
	ToolCallEventIDs []string
	ImageEventIDs    []string
}

type PDFConfig struct {
	Engine string `json:"engine,omitempty"` // pdf-text (free), mistral-ocr (OCR, paid, default), native
}

type PDFPluginConfig struct {
	ID     string          `json:"id"`
	Config json.RawMessage `json:"config,omitempty"`
}

type PortalInitOpts struct {
	ModelID      string
	Title        string
	SystemPrompt string
	CopyFrom     *PortalMetadata // For forked chats - copies config from source
	PortalKey    *networkid.PortalKey
}

type PortalMetadata struct {
	Model               string            `json:"model,omitempty"`                 // Set from room state
	SystemPrompt        string            `json:"system_prompt,omitempty"`         // Set from room state
	ResponsePrefix      string            `json:"response_prefix,omitempty"`       // Per-room response prefix override
	Temperature         float64           `json:"temperature,omitempty"`           // Set from room state
	MaxContextMessages  int               `json:"max_context_messages,omitempty"`  // Set from room state
	MaxCompletionTokens int               `json:"max_completion_tokens,omitempty"` // Set from room state
	ReasoningEffort     string            `json:"reasoning_effort,omitempty"`      // none, low, medium, high, xhigh
	Slug                string            `json:"slug,omitempty"`
	Title               string            `json:"title,omitempty"`
	TitleGenerated      bool              `json:"title_generated,omitempty"` // True if title was auto-generated
	WelcomeSent         bool              `json:"welcome_sent,omitempty"`
	AutoGreetingSent    bool              `json:"auto_greeting_sent,omitempty"`
	Capabilities        ModelCapabilities `json:"capabilities,omitempty"`
	LastRoomStateSync   int64             `json:"last_room_state_sync,omitempty"` // Track when we've synced room state
	PDFConfig           *PDFConfig        `json:"pdf_config,omitempty"`           // Per-room PDF processing configuration

	ConversationMode          string `json:"conversation_mode,omitempty"`
	LastResponseID            string `json:"last_response_id,omitempty"`
	EmitThinking              bool   `json:"emit_thinking,omitempty"`
	EmitToolArgs              bool   `json:"emit_tool_args,omitempty"`
	ThinkingLevel             string `json:"thinking_level,omitempty"`   // off|minimal|low|medium|high|xhigh
	VerboseLevel              string `json:"verbose_level,omitempty"`    // off|on|full
	GroupActivation           string `json:"group_activation,omitempty"` // mention|always
	GroupActivationNeedsIntro bool   `json:"group_activation_needs_intro,omitempty"`
	GroupIntroSent            bool   `json:"group_intro_sent,omitempty"`
	SendPolicy                string `json:"send_policy,omitempty"` // allow|deny
	SessionResetAt            int64  `json:"session_reset_at,omitempty"`
	AbortedLastRun            bool   `json:"aborted_last_run,omitempty"`
	CompactionCount           int    `json:"compaction_count,omitempty"`
	SessionBootstrappedAt     int64  `json:"session_bootstrapped_at,omitempty"`

	IsRawMode bool `json:"is_raw_mode,omitempty"` // True if this is a playground/raw mode room (no directive processing)

	// Ack reaction config - similar to OpenClaw's ack reactions
	AckReactionEmoji       string `json:"ack_reaction_emoji,omitempty"`        // Emoji to react with when message received (e.g., "👀", "🤔"). Empty = disabled.
	AckReactionRemoveAfter bool   `json:"ack_reaction_remove_after,omitempty"` // Remove the ack reaction after replying

	// Runtime-only overrides (not persisted)
	DisabledTools []string `json:"-"`

	// Debounce configuration (0 = use default, -1 = disabled)
	DebounceMs int `json:"debounce_ms,omitempty"`

	// Per-session typing overrides (OpenClaw-style).
	TypingMode            string `json:"typing_mode,omitempty"`             // never|instant|thinking|message
	TypingIntervalSeconds *int   `json:"typing_interval_seconds,omitempty"` // Optional per-session override

	// Anthropic prompt cache TTL tracking
	LastCacheTTLRefresh int64 `json:"last_cache_ttl_refresh,omitempty"` // Unix millis of last cache-eligible request

	// Extra holds bridge-specific metadata that the core engine carries
	// opaquely.
	Extra any `json:"extra,omitempty"`
}

type ProviderBraveConfig struct {
	Enabled          *bool  `yaml:"enabled"`
	BaseURL          string `yaml:"base_url"`
	APIKey           string `yaml:"api_key"`
	TimeoutSecs      int    `yaml:"timeout_seconds"`
	CacheTtlSecs     int    `yaml:"cache_ttl_seconds"`
	SearchLang       string `yaml:"search_lang"`
	UILang           string `yaml:"ui_lang"`
	DefaultCountry   string `yaml:"default_country"`
	DefaultFreshness string `yaml:"default_freshness"`
}

type ProviderConfig struct {
	APIKey           string `yaml:"api_key"`
	BaseURL          string `yaml:"base_url"`
	DefaultModel     string `yaml:"default_model"`
	DefaultPDFEngine string `yaml:"default_pdf_engine"` // pdf-text, mistral-ocr (default), native
}

type ProviderDirectConfig struct {
	Enabled      *bool  `yaml:"enabled"`
	TimeoutSecs  int    `yaml:"timeout_seconds"`
	UserAgent    string `yaml:"user_agent"`
	Readability  bool   `yaml:"readability"`
	MaxChars     int    `yaml:"max_chars"`
	MaxRedirects int    `yaml:"max_redirects"`
	CacheTtlSecs int    `yaml:"cache_ttl_seconds"`
}

type ProviderExaConfig struct {
	Enabled           *bool  `yaml:"enabled"`
	BaseURL           string `yaml:"base_url"`
	APIKey            string `yaml:"api_key"`
	Type              string `yaml:"type"`
	Category          string `yaml:"category"`
	NumResults        int    `yaml:"num_results"`
	IncludeText       bool   `yaml:"include_text"`
	TextMaxCharacters int    `yaml:"text_max_chars"`
	Highlights        bool   `yaml:"highlights"`
}

type ProviderOpenRouterConfig struct {
	Enabled      *bool  `yaml:"enabled"`
	APIKey       string `yaml:"api_key"`
	BaseURL      string `yaml:"base_url"`
	Model        string `yaml:"model"`
	TimeoutSecs  int    `yaml:"timeout_seconds"`
	CacheTtlSecs int    `yaml:"cache_ttl_seconds"`
}

type ProviderPerplexityConfig struct {
	Enabled      *bool  `yaml:"enabled"`
	APIKey       string `yaml:"api_key"`
	BaseURL      string `yaml:"base_url"`
	Model        string `yaml:"model"`
	TimeoutSecs  int    `yaml:"timeout_seconds"`
	CacheTtlSecs int    `yaml:"cache_ttl_seconds"`
}

type ProvidersConfig struct {
	Beeper     ProviderConfig `yaml:"beeper"`
	OpenAI     ProviderConfig `yaml:"openai"`
	OpenRouter ProviderConfig `yaml:"openrouter"`
}

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

type PruningConfig pruning.Config

type QueueConfig struct {
	Mode                string            `yaml:"mode"`
	ByChannel           map[string]string `yaml:"byChannel"`
	DebounceMs          *int              `yaml:"debounceMs"`
	DebounceMsByChannel map[string]int    `yaml:"debounceMsByChannel"`
	Cap                 *int              `yaml:"cap"`
	Drop                string            `yaml:"drop"`
}

type ReactionFeedback struct {
	Emoji     string    // The emoji used (e.g., "👍", "👎")
	Timestamp time.Time // When the reaction was added
	Sender    string    // Who sent the reaction (display name or user ID)
	MessageID string    // Which message was reacted to (event ID or timestamp)
	RoomName  string    // Room/channel name for context
	Action    string    // "added" or "removed"
}

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

type ReasoningEffortOption struct {
	Value string `json:"value"` // minimal, low, medium, high, xhigh
	Label string `json:"label"` // Display name
}

type ReplyTarget struct {
	ReplyTo    id.EventID
	ThreadRoot id.EventID
}

type ReqSetDefaults struct {
	Model           *string  `json:"model,omitempty"`
	SystemPrompt    *string  `json:"system_prompt,omitempty"`
	Temperature     *float64 `json:"temperature,omitempty"`
	ReasoningEffort *string  `json:"reasoning_effort,omitempty"`
}

type ResponseDirectives struct {
	// Text is the cleaned response text with directives stripped.
	Text string

	// IsSilent indicates the response should not be sent (NO_REPLY token present).
	IsSilent bool

	// ReplyToEventID is the Matrix event ID to reply to (from [[reply_to:<id>]] or [[reply_to_current]]).
	ReplyToEventID id.EventID

	// ReplyToCurrent indicates [[reply_to_current]] was used (reply to triggering message).
	ReplyToCurrent bool

	// HasReplyTag indicates a reply tag was present in the original text.
	HasReplyTag bool
}

type ResponseFunc func(ctx context.Context, evt *event.Event, portal *bridgev2.Portal, meta *PortalMetadata, prompt []openai.ChatCompletionMessageParamUnion) (bool, *aierrors.ContextLengthError, error)

type ResponsePrefixContext struct {
	Model         string
	ModelFull     string
	Provider      string
	ThinkingLevel string
}

type ResultStatus string

type RoomCapabilitiesEventContent struct {
	Capabilities           *ModelCapabilities      `json:"capabilities,omitempty"`
	AvailableTools         []ToolInfo              `json:"available_tools,omitempty"`
	ReasoningEffortOptions []ReasoningEffortOption `json:"reasoning_effort_options,omitempty"`
	Provider               string                  `json:"provider,omitempty"`
	EffectiveSettings      *EffectiveSettings      `json:"effective_settings,omitempty"`
}

type RoomSettingsEventContent struct {
	Model               string   `json:"model,omitempty"`
	SystemPrompt        string   `json:"system_prompt,omitempty"`
	Temperature         *float64 `json:"temperature,omitempty"`
	MaxContextMessages  int      `json:"max_context_messages,omitempty"`
	MaxCompletionTokens int      `json:"max_completion_tokens,omitempty"`
	ReasoningEffort     string   `json:"reasoning_effort,omitempty"`
	ConversationMode    string   `json:"conversation_mode,omitempty"` // "messages" or "responses"
	EmitThinking        *bool    `json:"emit_thinking,omitempty"`
	EmitToolArgs        *bool    `json:"emit_tool_args,omitempty"`
}

type SearchConfig struct {
	Provider  string   `yaml:"provider"`
	Fallbacks []string `yaml:"fallbacks"`

	Exa        ProviderExaConfig        `yaml:"exa"`
	Brave      ProviderBraveConfig      `yaml:"brave"`
	Perplexity ProviderPerplexityConfig `yaml:"perplexity"`
	OpenRouter ProviderOpenRouterConfig `yaml:"openrouter"`
}

type ServiceConfig struct {
	BaseURL string
	APIKey  string
}

type ServiceConfigMap map[string]ServiceConfig

type ServiceTokens struct {
	OpenAI     string `json:"openai,omitempty"`
	OpenRouter string `json:"openrouter,omitempty"`
	Exa        string `json:"exa,omitempty"`
	Brave      string `json:"brave,omitempty"`
	Perplexity string `json:"perplexity,omitempty"`
}

type SettingExplanation struct {
	Value  any           `json:"value"`
	Source SettingSource `json:"source"`
	Reason string        `json:"reason,omitempty"` // Only when limited/unavailable
}

type SettingSource string

type StatusDisplay struct {
	Icon      string `json:"icon,omitempty"`
	Animation string `json:"animation,omitempty"` // "pulse", "spin", etc.
	Color     string `json:"color,omitempty"`
}

type StepBoundaryContent struct {
	TurnID            string       `json:"turn_id"`
	StepNumber        int          `json:"step_number"`
	StepType          string       `json:"step_type"` // "tool_response_processed", etc.
	PreviousToolCalls []string     `json:"previous_tool_calls,omitempty"`
	Display           *StepDisplay `json:"display,omitempty"`
}

type StepDisplay struct {
	Label string `json:"label,omitempty"`
}

type StreamContentType string

type StreamCursor struct {
	BlockType  string `json:"block_type,omitempty"` // "text", "code", etc.
	CharOffset int    `json:"char_offset,omitempty"`
	Field      string `json:"field,omitempty"` // For tool_input, which field
}

type StreamDeltaContent struct {
	TurnID      string            `json:"turn_id"`
	TargetEvent string            `json:"target_event,omitempty"` // Event ID being updated
	ContentType StreamContentType `json:"content_type"`
	Delta       string            `json:"delta"`
	Seq         int               `json:"seq"`

	// For tool_input streaming
	CallID   string `json:"call_id,omitempty"`
	ToolName string `json:"tool_name,omitempty"`

	// Cursor information
	Cursor *StreamCursor `json:"cursor,omitempty"`
}

type StreamEvent struct {
	Type           StreamEventType
	Delta          string
	ReasoningDelta string
	ToolCall       *ToolCallResult
	FinishReason   string
	ResponseID     string
	Usage          *UsageInfo
	Error          error
}

type StreamEventType string

type StreamingConfig struct {
	Enabled bool `json:"enabled,omitempty"`
}

type StreamingHooks interface {
	// AdditionalTools returns extra tool parameters to include in API requests.
	// Called during buildResponsesAPIParams after builtin tools are added.
	// Downstream bridges can inject additional tool definitions.
	AdditionalTools(ctx context.Context, meta *PortalMetadata) []responses.ToolUnionParam

	// OnContinuationPreSend is called before each continuation round in the
	// streaming loop. It may modify the pending function outputs (e.g. to
	// inject bridge-specific events) and return additional input items to prepend
	// to the continuation request.
	OnContinuationPreSend(ctx context.Context, state *streamingState, outputs []functionCallOutput) (extraInput responses.ResponseInputParam, modifiedOutputs []functionCallOutput)

	// ShouldContinue is called at the top of each continuation iteration.
	// Return false to break out of the tool-call loop early.
	ShouldContinue(state *streamingState) bool

	// OnToolCallComplete is called after a builtin tool finishes execution,
	// before the result is recorded for continuation.
	OnToolCallComplete(ctx context.Context, toolCallID, toolName string, state *streamingState)

	// OnStreamFinished is called after the streaming response is fully
	// complete (messages sent, state saved).
	OnStreamFinished(ctx context.Context, portal *bridgev2.Portal, state *streamingState, meta *PortalMetadata)
}

type ThinkingContent struct {
	Content    string `json:"content,omitempty"`
	TokenCount int    `json:"token_count,omitempty"`
	DurationMs int64  `json:"duration_ms,omitempty"`
	Summary    string `json:"summary,omitempty"`
}

type TimingInfo struct {
	StartedAt    int64 `json:"started_at,omitempty"`     // Unix ms
	FirstTokenAt int64 `json:"first_token_at,omitempty"` // Unix ms
	CompletedAt  int64 `json:"completed_at,omitempty"`   // Unix ms
}

type ToolArtifact struct {
	Type     string `json:"type"` // "file", "image"
	MxcURI   string `json:"mxc_uri,omitempty"`
	Filename string `json:"filename,omitempty"`
	Mimetype string `json:"mimetype,omitempty"`
	Size     int    `json:"size,omitempty"`
}

type ToolCallContent struct {
	// Standard Matrix fallback
	Body    string `json:"body"`
	MsgType string `json:"msgtype"`

	// Tool call details
	ToolCall *ToolCallData `json:"com.beeper.ai.tool_call"`
}

type ToolCallData struct {
	CallID   string     `json:"call_id"`
	TurnID   string     `json:"turn_id"`
	ToolName string     `json:"tool_name"`
	ToolType ToolType   `json:"tool_type"`
	Status   ToolStatus `json:"status"`

	// Input arguments (fully accumulated)
	Input map[string]any `json:"input,omitempty"`

	// Display hints
	Display *ToolDisplay `json:"display,omitempty"`

	// Reference to result event (set after completion)
	ResultEvent string `json:"result_event,omitempty"`

	// Timing
	Timing *TimingInfo `json:"timing,omitempty"`
}

type ToolCallMetadata struct {
	CallID        string         `json:"call_id"`
	ToolName      string         `json:"tool_name"`
	ToolType      string         `json:"tool_type"` // builtin, provider, function
	Input         map[string]any `json:"input,omitempty"`
	Output        map[string]any `json:"output,omitempty"`
	Status        string         `json:"status"`                  // pending, running, completed, failed, timeout, cancelled
	ResultStatus  string         `json:"result_status,omitempty"` // success, error, partial
	ErrorMessage  string         `json:"error_message,omitempty"`
	StartedAtMs   int64          `json:"started_at_ms,omitempty"`
	CompletedAtMs int64          `json:"completed_at_ms,omitempty"`

	// Event IDs for timeline events (if emitted as separate events)
	CallEventID   string `json:"call_event_id,omitempty"`
	ResultEventID string `json:"result_event_id,omitempty"`
}

type ToolCallResult struct {
	ID        string
	Name      string
	Arguments string
}

type ToolDefinition struct {
	Name        string
	Description string
	Parameters  map[string]any
	Execute     func(ctx context.Context, args map[string]any) (string, error)
}

type ToolDisplay struct {
	Title     string `json:"title,omitempty"`
	Icon      string `json:"icon,omitempty"` // mxc:// URL
	Collapsed bool   `json:"collapsed,omitempty"`
}

type ToolExecutor func(ctx context.Context, args map[string]any) (string, error)

type ToolInfo struct {
	Name        string        `json:"name"`
	DisplayName string        `json:"display_name"` // Human-readable name for UI
	Type        string        `json:"type"`         // "builtin", "provider", "plugin"
	Description string        `json:"description,omitempty"`
	Enabled     bool          `json:"enabled"`
	Available   bool          `json:"available"`        // Based on model capabilities and provider
	Source      SettingSource `json:"source,omitempty"` // Where enabled state came from
	Reason      string        `json:"reason,omitempty"` // Only when limited/unavailable
}

type ToolOutputPreview struct {
	Stdout    string `json:"stdout,omitempty"`
	Stderr    string `json:"stderr,omitempty"`
	Truncated bool   `json:"truncated,omitempty"`
}

type ToolProgressContent struct {
	CallID   string `json:"call_id"`
	TurnID   string `json:"turn_id"`
	ToolName string `json:"tool_name"`

	Status   ToolStatus           `json:"status"`
	Progress *ToolProgressDetails `json:"progress,omitempty"`

	// Output preview (for long-running tools, etc.)
	OutputPreview *ToolOutputPreview `json:"output_preview,omitempty"`
}

type ToolProgressDetails struct {
	Stage   string `json:"stage,omitempty"`   // "executing", "processing", etc.
	Percent int    `json:"percent,omitempty"` // 0-100
	Message string `json:"message,omitempty"`
}

type ToolProvidersConfig struct {
	Search *SearchConfig     `yaml:"search"`
	Fetch  *FetchConfig      `yaml:"fetch"`
	Media  *MediaToolsConfig `yaml:"media"`
}

type ToolResultContent struct {
	// Standard Matrix fallback
	Body          string `json:"body"`
	MsgType       string `json:"msgtype"`
	Format        string `json:"format,omitempty"`
	FormattedBody string `json:"formatted_body,omitempty"`

	// Tool result details
	ToolResult *ToolResultData `json:"com.beeper.ai.tool_result"`
}

type ToolResultData struct {
	CallID   string       `json:"call_id"`
	TurnID   string       `json:"turn_id"`
	ToolName string       `json:"tool_name"`
	Status   ResultStatus `json:"status"`

	// Output data
	Output map[string]any `json:"output,omitempty"`

	// Artifacts (files, images generated by tool)
	Artifacts []ToolArtifact `json:"artifacts,omitempty"`

	// Display hints
	Display *ToolResultDisplay `json:"display,omitempty"`
}

type ToolResultDisplay struct {
	Format          string `json:"format,omitempty"` // "search_results", "code_output", etc.
	Expandable      bool   `json:"expandable,omitempty"`
	DefaultExpanded bool   `json:"default_expanded,omitempty"`
	ShowStdout      bool   `json:"show_stdout,omitempty"`
	ShowArtifacts   bool   `json:"show_artifacts,omitempty"`
}

type ToolStatus string

type ToolStrictMode string

type ToolType string

type TurnCancelledContent struct {
	TurnID             string   `json:"turn_id"`
	CancelledAt        int64    `json:"cancelled_at"` // Unix ms
	Reason             string   `json:"reason,omitempty"`
	PartialContent     string   `json:"partial_content,omitempty"`
	ToolCallsCancelled []string `json:"tool_calls_cancelled,omitempty"`
}

type TurnStatus string

type TypingContext struct {
	IsGroup      bool
	WasMentioned bool
}

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

type TypingControllerOptions struct {
	Interval time.Duration
	TTL      time.Duration
}

type TypingMode string

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

type UnifiedMessage struct {
	Role       MessageRole
	Content    []ContentPart
	ToolCalls  []ToolCallResult
	ToolCallID string
	Name       string
}

type UsageInfo struct {
	PromptTokens     int
	CompletionTokens int
	TotalTokens      int
	ReasoningTokens  int
}

type UserDefaults struct {
	Model           string   `json:"model,omitempty"`
	SystemPrompt    string   `json:"system_prompt,omitempty"`
	Temperature     *float64 `json:"temperature,omitempty"`
	ReasoningEffort string   `json:"reasoning_effort,omitempty"`
}

type UserLoginMetadata struct {
	Persona              string         `json:"persona,omitempty"`
	Provider             string         `json:"provider,omitempty"` // Selected provider
	APIKey               string         `json:"api_key,omitempty"`
	BaseURL              string         `json:"base_url,omitempty"`               // Per-user API endpoint
	TitleGenerationModel string         `json:"title_generation_model,omitempty"` // Model to use for generating chat titles
	NextChatIndex        int            `json:"next_chat_index,omitempty"`
	DefaultChatPortalID  string         `json:"default_chat_portal_id,omitempty"`
	ModelCache           *ModelCache    `json:"model_cache,omitempty"`
	ChatsSynced          bool           `json:"chats_synced,omitempty"` // True after initial bootstrap completed successfully
	Gravatar             *GravatarState `json:"gravatar,omitempty"`
	Timezone             string         `json:"timezone,omitempty"`
	ResponsePrefix       string         `json:"response_prefix,omitempty"`

	// FileAnnotationCache stores parsed PDF content from OpenRouter's file-parser plugin
	// Key is the file hash (SHA256), pruned after 7 days
	FileAnnotationCache map[string]FileAnnotation `json:"file_annotation_cache,omitempty"`

	// User-level defaults for new chats (set via provisioning API)
	Defaults *UserDefaults `json:"defaults,omitempty"`

	// Optional per-login tokens for external services
	ServiceTokens *ServiceTokens `json:"service_tokens,omitempty"`

	// Provider health tracking
	ConsecutiveErrors int   `json:"consecutive_errors,omitempty"`
	LastErrorAt       int64 `json:"last_error_at,omitempty"` // Unix timestamp

	// Extra holds bridge-specific login metadata that the core engine
	// carries opaquely.
	Extra any `json:"extra,omitempty"`
}