bot

type Adapter interface {
	// Platform 返回平台标识。
	Platform() Platform

	// Start 启动适配器，连接平台 gateway。
	Start(ctx context.Context) error

	// Stop 优雅关闭适配器。
	Stop() error

	// Send 发送一条出站消息。
	Send(ctx context.Context, msg OutboundMessage) (SendResult, error)

	// SendTyping 发送"正在输入"状态。
	SendTyping(ctx context.Context, chatID string) error

	// Messages 返回入站消息通道。
	Messages() <-chan InboundMessage

	// Name 返回适配器实例名（用于日志）。
	Name() string
}

type AllowlistConfig struct {
	Enabled  bool
	AllowAll bool
	Mode     string // "open"（自动加入）| "review"（需审批）
	Users    map[Platform][]string
	Groups   map[Platform][]string
}

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

type ChannelConfig struct {
	Model         string
	WorkspaceRoot string
}

type ChatType string

type DesktopBridge interface {
	// Sessions 枚举当前所有桌面 live 会话。
	Sessions() []DesktopSessionInfo
	// SetWatch 订阅/退订当前聊天的桌面事件推送（审批请求、任务完成/出错）。
	SetWatch(route DesktopWatchRoute, enable bool) error
	// Watching 返回该聊天当前是否在订阅。
	Watching(route DesktopWatchRoute) bool
	// Approve 应答任意桌面会话的待审批项，返回用户可读的结果文案。
	Approve(approvalID string, allow bool) (string, error)
	// AskQuestions 返回某个待回答 ask 的问题列表（用于把 IM 文本解析成选项）。
	AskQuestions(askID string) ([]event.AskQuestion, bool)
	// Answer 应答任意桌面会话的待回答 ask，返回用户可读的结果文案。
	Answer(askID string, answers []event.AskAnswer) (string, error)
}

type DesktopPendingInfo struct {
	ID   string
	Kind string // "approval" | "ask"
	Tool string
}

type DesktopSessionInfo struct {
	TabID         string
	Label         string
	Workspace     string
	Topic         string
	Ready         bool
	Running       bool
	PendingPrompt bool
	// Pending 列出该会话当前待处理的审批/问答，便于用户在推送丢失时仍能
	// 用 /desktop approve|answer <id> 处理。
	Pending []DesktopPendingInfo
}

type DesktopWatchRoute struct {
	Platform Platform
	ChatType ChatType
	ChatID   string
}

type GatewayConfig struct {
	Model         string
	MaxSteps      int
	WorkspaceRoot string
	Channels      map[Platform]ChannelConfig
	Allowlist     AllowlistConfig
	Enabled       map[Platform]bool
	Debounce      time.Duration
	// SessionIdleTimeout controls how long a bot session can sit idle (no
	// incoming messages) before its controller is closed to reclaim memory.
	// A busy bot serving many users/-groups would otherwise keep every
	// controller alive forever. Default 30m; 0 disables reaping.
	SessionIdleTimeout time.Duration
	// AllowlistSaver 当新用户被自动加入白名单时调用，用于持久化。
	// 参数为更新后的完整 AllowlistConfig。nil 表示不持久化。
	AllowlistSaver func(AllowlistConfig)
	// OnTurnFinished 在一轮对话结束后调用（无论成功或出错），用于让上层（desktop）
	// 把对话方的会话来源（platform/chatType/chatID/userID）和本次会话的本地 transcript
	// 路径回写到 BotConnection 的 SessionMappings —— 否则只有手动「测试连接」才记录
	// remoteID、而 SessionID（本地话题）永远为空，UI 显示「等待首条消息」。传整个
	// SessionSource 而非单个 remoteID，是为了让 chatType/chatID 也带上：同一人在不同
	// 群里的对话才能分开。放在 turn 结束后是因为 sessionPath 要等首轮 RunTurn 才确定
	// （prewarm 时为空）。nil 表示不回写。
	OnTurnFinished func(src SessionSource, sessionPath string)
	// Netdev，非 nil 时启用 /netdev 系列命令（发现列表 / 证据详情）——
	// 运维告警与早报推送的回话侧（FDE 的耳朵）。
	Netdev NetdevBridge
	// Desktop，非 nil 时启用 /desktop 系列命令（远程观察 + 审批桌面 live 会话）。
	// 由桌面端进程注入；独立 bot 进程（无桌面）保持 nil，/desktop 会提示不可用。
	Desktop DesktopBridge
}

type InboundMessage struct {
	Platform  Platform `json:"platform"`
	ChatType  ChatType `json:"chat_type"`
	ChatID    string   `json:"chat_id"`
	UserID    string   `json:"user_id"`
	UserName  string   `json:"user_name"`
	Text      string   `json:"text"`
	MessageID string   `json:"message_id"`
	ThreadID  string   `json:"thread_id,omitempty"`
	MediaURLs []string `json:"media_urls,omitempty"`
	Raw       any      `json:"-"`
}

type InlineKeyboard struct {
	Rows []InlineKeyboardRow `json:"rows"`
}

type InlineKeyboardButton struct {
	ID         string `json:"id"`
	Label      string `json:"label"`
	Style      int    `json:"style,omitempty"` // 0=default, 1=primary, 2=danger
	CallbackID string `json:"callback_id,omitempty"`
}

type InlineKeyboardRow struct {
	Buttons []InlineKeyboardButton `json:"buttons"`
}

type InteractiveCard struct {
	Header   string                   `json:"header"`
	Elements []InteractiveCardElement `json:"elements"`
}

type InteractiveCardElement struct {
	Tag     string         `json:"tag"`
	Content string         `json:"content,omitempty"`
	Extra   map[string]any `json:"extra,omitempty"`
}

type MessageHandler func(ctx context.Context, msg InboundMessage)

type NetdevActionResult struct {
	OK  bool
	Msg string
}

type NetdevBridge interface {
	// NetdevActiveFindings lists unresolved findings, newest first.
	NetdevActiveFindings() []NetdevFindingSummary
	// NetdevFindingByID renders one finding (NotFound=true when absent).
	NetdevFindingByID(id string) NetdevFindingDetail
	// NetdevAckFinding acknowledges one finding from IM (completion-spec §5.3:
	// 收到告警后可操作——ack 不解决，只标记已被人看过).
	NetdevAckFinding(id string) NetdevActionResult
	// NetdevProposals lists proposals pending a human decision.
	NetdevProposals() []NetdevProposalSummary
	// NetdevProposalApprove / NetdevProposalReject run the SAME guarded path
	// as the desktop approval UI (group policy + change window + audit).
	NetdevProposalApprove(id string) NetdevActionResult
	NetdevProposalReject(id, reason string) NetdevActionResult
}

type NetdevEvidenceView struct {
	Device  string
	Command string
	Output  string
}

type NetdevFindingDetail struct {
	ID       string
	Severity string
	Title    string
	Devices  []string
	Detail   string
	Status   string
	Evidence []NetdevEvidenceView
	NotFound bool
}

type NetdevFindingSummary struct {
	ID       string
	Severity string
	Title    string
	Devices  []string
	Status   string
}

type NetdevProposalSummary struct {
	ID     string
	Status string
	Title  string
}

type OutboundMessage struct {
	ChatID       string           `json:"chat_id"`
	ChatType     ChatType         `json:"chat_type,omitempty"`
	Text         string           `json:"text,omitempty"`
	MediaURLs    []string         `json:"media_urls,omitempty"`
	ReplyToMsgID string           `json:"reply_to_msg_id,omitempty"`
	Keyboard     *InlineKeyboard  `json:"keyboard,omitempty"`
	Card         *InteractiveCard `json:"card,omitempty"`
}

type Platform string

type RecentChat struct {
	Platform Platform `json:"platform"`
	ChatType ChatType `json:"chatType"`
	ChatID   string   `json:"chatId"`
	UserName string   `json:"userName"`
	LastSeen int64    `json:"lastSeen"` // unix seconds
}

type SendResult struct {
	MessageID string `json:"message_id,omitempty"`
	Err       error  `json:"err,omitempty"`
}

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

type SessionSource struct {
	Platform Platform `json:"platform"`
	ChatType ChatType `json:"chat_type"`
	ChatID   string   `json:"chat_id"`
	UserID   string   `json:"user_id"`
	ThreadID string   `json:"thread_id,omitempty"`
}