Documentation
¶
Overview ¶
Package core provides the central engine and configuration management for clibot.
The core package implements the main orchestration logic that connects IM platforms with AI CLI tools. It handles:
- Configuration loading and validation (from YAML files)
- Session management for CLI tools
- Message routing between bots and CLI adapters
- HTTP hook server for receiving CLI notifications
- Graceful shutdown and cleanup
Main Components ¶
- Engine: Central orchestration engine
- Config: Configuration structure and loading
- Session: CLI session state management
Configuration ¶
Configuration is loaded from a YAML file with the following main sections:
- hook_server: HTTP server settings
- sessions: CLI tool sessions to manage
- bots: IM platform bot configurations
- cli_adapters: CLI tool adapter configurations
- security: Access control and whitelisting
- logging: Log configuration
Example Configuration ¶
hook_server:
port: 8080
sessions:
- name: "my-session"
cli_type: "claude"
work_dir: "/path/to/project"
bots:
discord:
enabled: true
token: "your-bot-token"
cli_adapters:
claude:
history_dir: "~/.config/claude"
Index ¶
- Constants
- type BotChannel
- type BotConfig
- type CLIAdapterConfig
- type Config
- func (c *Config) GetBotConfig(botType string) (BotConfig, error)
- func (c *Config) GetCLIAdapterConfig(cliType string) (CLIAdapterConfig, error)
- func (c *Config) GetSessionConfig(sessionName string) (SessionConfig, error)
- func (c *Config) IsAdmin(platform, userID string) bool
- func (c *Config) IsUserAuthorized(platform, userID string) bool
- type CoreConfigAdapter
- func (a *CoreConfigAdapter) GetBotProxyEnabled(botType string) bool
- func (a *CoreConfigAdapter) GetBotProxyPassword(botType string) string
- func (a *CoreConfigAdapter) GetBotProxyURL(botType string) string
- func (a *CoreConfigAdapter) GetBotProxyUsername(botType string) string
- func (a *CoreConfigAdapter) GetGlobalProxyEnabled() bool
- func (a *CoreConfigAdapter) GetGlobalProxyPassword() string
- func (a *CoreConfigAdapter) GetGlobalProxyURL() string
- func (a *CoreConfigAdapter) GetGlobalProxyUsername() string
- type Engine
- func (e *Engine) GetActiveSession(channel string) *Session
- func (e *Engine) GetProxyManager() *proxy.ProxyManager
- func (e *Engine) HandleBotMessage(msg bot.BotMessage)
- func (e *Engine) HandleSpecialCommand(cmd string, msg bot.BotMessage)
- func (e *Engine) HandleSpecialCommandWithArgs(command string, args []string, msg bot.BotMessage)
- func (e *Engine) HandleUserMessage(msg bot.BotMessage)
- func (e *Engine) RegisterBotAdapter(botType string, adapter bot.BotAdapter)
- func (e *Engine) RegisterCLIAdapter(cliType string, adapter cli.CLIAdapter)
- func (e *Engine) Run(ctx context.Context) error
- func (e *Engine) SendResponseToSession(sessionName, message string)
- func (e *Engine) SendToAllBots(message string)
- func (e *Engine) SendToBot(platform, channel, message string)
- func (e *Engine) Stop() error
- type HookServerConfig
- type LoggingConfig
- type ProcessInfo
- type ProxyConfig
- type ResponseEvent
- type SecurityConfig
- type Session
- type SessionConfig
- type SessionGlobalConfig
- type SessionState
- type SessionStatus
- type WatchdogConfig
Constants ¶
const ( DefaultHookPort = 8080 DefaultLogLevel = "info" DefaultLogMaxSize = 100 // MB DefaultLogMaxBackups = 5 DefaultLogMaxAge = 30 // days DefaultLogCompress = true DefaultLogEnableStdout = true // Default timeout values DefaultWatchdogMaxRetries = 10 DefaultWatchdogInitialDelay = "500ms" DefaultWatchdogRetryDelay = "800ms" // DefaultTimeout is the default timeout for CLI adapters // - For hook mode: 1 hour (maximum time to wait for response after hook triggers) // - For ACP mode: 5 minutes (idle timeout) DefaultTimeout = "1h" )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BotChannel ¶
type BotChannel struct {
Platform string // "discord", "telegram", "feishu", etc.
Channel string // Channel ID (platform-specific)
MessageID string // Message ID (for typing indicator removal)
}
BotChannel represents a bot channel for sending responses
type BotConfig ¶
type BotConfig struct {
Enabled bool `yaml:"enabled"`
AppID string `yaml:"app_id"`
AppSecret string `yaml:"app_secret"`
Token string `yaml:"token"`
ChannelID string `yaml:"channel_id"` // For Discord: server channel ID
EncryptKey string `yaml:"encrypt_key"` // Feishu: event encryption key (optional)
VerificationToken string `yaml:"verification_token"` // Feishu: verification token (optional)
Proxy *ProxyConfig `yaml:"proxy"` // Optional bot-level proxy override
}
BotConfig represents bot configuration
type CLIAdapterConfig ¶
type CLIAdapterConfig struct {
// Timeout configuration
// - Hook mode: maximum time to wait for response after hook triggers
// - ACP mode: idle timeout (max time without activity before cancelling)
// Default: 5 minutes for ACP, 1 hour for hook mode
Timeout string `yaml:"timeout"`
// Environment variables to set for the CLI process
Env map[string]string `yaml:"env"`
}
CLIAdapterConfig represents CLI adapter configuration
type Config ¶
type Config struct {
HookServer HookServerConfig `yaml:"hook_server"`
Security SecurityConfig `yaml:"security"`
Watchdog WatchdogConfig `yaml:"watchdog"`
Session SessionGlobalConfig `yaml:"session"`
Sessions []SessionConfig `yaml:"sessions"`
Bots map[string]BotConfig `yaml:"bots"`
CLIAdapters map[string]CLIAdapterConfig `yaml:"cli_adapters"`
Logging LoggingConfig `yaml:"logging"`
Proxy ProxyConfig `yaml:"proxy"`
}
Config represents the complete clibot configuration structure
func LoadConfig ¶
LoadConfig loads configuration from file and expands environment variables
func (*Config) GetBotConfig ¶
GetBotConfig retrieves configuration for a specific bot
func (*Config) GetCLIAdapterConfig ¶
func (c *Config) GetCLIAdapterConfig(cliType string) (CLIAdapterConfig, error)
GetCLIAdapterConfig retrieves configuration for a specific CLI adapter
func (*Config) GetSessionConfig ¶
func (c *Config) GetSessionConfig(sessionName string) (SessionConfig, error)
GetSessionConfig retrieves configuration for a specific session
func (*Config) IsUserAuthorized ¶
IsUserAuthorized checks if a user is in the whitelist
type CoreConfigAdapter ¶
type CoreConfigAdapter struct {
// contains filtered or unexported fields
}
CoreConfigAdapter wraps core.Config to implement proxy.ConfigProvider This allows ProxyManager to access configuration without creating circular dependency
func NewCoreConfigAdapter ¶
func NewCoreConfigAdapter(config *Config) *CoreConfigAdapter
func (*CoreConfigAdapter) GetBotProxyEnabled ¶
func (a *CoreConfigAdapter) GetBotProxyEnabled(botType string) bool
func (*CoreConfigAdapter) GetBotProxyPassword ¶
func (a *CoreConfigAdapter) GetBotProxyPassword(botType string) string
func (*CoreConfigAdapter) GetBotProxyURL ¶
func (a *CoreConfigAdapter) GetBotProxyURL(botType string) string
func (*CoreConfigAdapter) GetBotProxyUsername ¶
func (a *CoreConfigAdapter) GetBotProxyUsername(botType string) string
func (*CoreConfigAdapter) GetGlobalProxyEnabled ¶
func (a *CoreConfigAdapter) GetGlobalProxyEnabled() bool
func (*CoreConfigAdapter) GetGlobalProxyPassword ¶
func (a *CoreConfigAdapter) GetGlobalProxyPassword() string
func (*CoreConfigAdapter) GetGlobalProxyURL ¶
func (a *CoreConfigAdapter) GetGlobalProxyURL() string
func (*CoreConfigAdapter) GetGlobalProxyUsername ¶
func (a *CoreConfigAdapter) GetGlobalProxyUsername() string
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine is the core scheduling engine that manages CLI sessions and bot connections
func (*Engine) GetActiveSession ¶
GetActiveSession gets the active session for a channel Currently returns the default session. Per-channel session mapping is not yet implemented.
Future enhancement: Map each bot channel to a specific session for multi-tenancy support. See: https://github.com/keepmind9/clibot/issues/124
func (*Engine) GetProxyManager ¶
func (e *Engine) GetProxyManager() *proxy.ProxyManager
GetProxyManager returns the proxy manager
func (*Engine) HandleBotMessage ¶
func (e *Engine) HandleBotMessage(msg bot.BotMessage)
HandleBotMessage is the callback function for bots to deliver messages
func (*Engine) HandleSpecialCommand ¶
func (e *Engine) HandleSpecialCommand(cmd string, msg bot.BotMessage)
HandleSpecialCommand handles special clibot commands
func (*Engine) HandleSpecialCommandWithArgs ¶
func (e *Engine) HandleSpecialCommandWithArgs(command string, args []string, msg bot.BotMessage)
HandleSpecialCommandWithArgs handles special commands with pre-parsed arguments This is more efficient as it avoids re-parsing the command string
func (*Engine) HandleUserMessage ¶
func (e *Engine) HandleUserMessage(msg bot.BotMessage)
HandleUserMessage processes a message from a user
func (*Engine) RegisterBotAdapter ¶
func (e *Engine) RegisterBotAdapter(botType string, adapter bot.BotAdapter)
RegisterBotAdapter registers a bot adapter
func (*Engine) RegisterCLIAdapter ¶
func (e *Engine) RegisterCLIAdapter(cliType string, adapter cli.CLIAdapter)
RegisterCLIAdapter registers a CLI adapter
func (*Engine) SendResponseToSession ¶
SendResponseToSession sends a message to the bot channel associated with a session This is used by CLI adapters to send responses back to users
func (*Engine) SendToAllBots ¶
SendToAllBots sends a message to all active bots
type HookServerConfig ¶
type HookServerConfig struct {
Port int `yaml:"port"`
}
HookServerConfig represents HTTP Hook server configuration
type LoggingConfig ¶
type LoggingConfig struct {
Level string `yaml:"level"` // debug, info, warn, error
File string `yaml:"file"` // Log file path
MaxSize int `yaml:"max_size"` // Single file max size in MB (default: 100)
MaxBackups int `yaml:"max_backups"` // Number of backups to keep (default: 5)
MaxAge int `yaml:"max_age"` // Maximum days to retain (default: 30)
Compress bool `yaml:"compress"` // Whether to compress old logs (default: true)
EnableStdout bool `yaml:"enable_stdout"` // Also output to stdout (default: true)
}
LoggingConfig represents logging configuration
type ProcessInfo ¶
type ProcessInfo struct {
PID int
Memory string // Human-readable memory usage
Uptime string // Human-readable uptime
Command string // Process command
}
ProcessInfo contains process-related information
type ProxyConfig ¶
type ProxyConfig struct {
Enabled bool `yaml:"enabled"` // Whether proxy is enabled
URL string `yaml:"url"` // Proxy URL (e.g., http://127.0.0.1:7890, socks5://127.0.0.1:1080)
Username string `yaml:"username"` // Optional username for authentication
Password string `yaml:"password"` // Optional password for authentication
}
ProxyConfig represents network proxy configuration
type ResponseEvent ¶
ResponseEvent represents a CLI response event
type SecurityConfig ¶
type SecurityConfig struct {
WhitelistEnabled bool `yaml:"whitelist_enabled"`
AllowedUsers map[string][]string `yaml:"allowed_users"`
Admins map[string][]string `yaml:"admins"`
}
SecurityConfig represents security and access control configuration
type Session ¶
type Session struct {
Name string // tmux session name
CLIType string // claude/gemini/opencode
WorkDir string // Working directory
StartCmd string // Command to start the CLI (default: same as CLIType)
State SessionState // Current state
CreatedAt string // Creation timestamp
IsDynamic bool // true if session was created dynamically via IM
CreatedBy string // creator identity (format: "platform:userID")
// contains filtered or unexported fields
}
Session represents a tmux session with its metadata
func (*Session) NeedsWatchdog ¶
NeedsWatchdog returns true if session requires watchdog monitoring ACP sessions handle responses asynchronously via callbacks, so they don't need watchdog (tmux polling or hook waiting)
type SessionConfig ¶
type SessionConfig struct {
Name string `yaml:"name"`
CLIType string `yaml:"cli_type"`
WorkDir string `yaml:"work_dir"`
AutoStart bool `yaml:"auto_start"`
StartCmd string `yaml:"start_cmd"` // Command to start the CLI (default: same as CLIType)
Transport string `yaml:"transport"` // Connection URL for ACP: stdio://, tcp://host:port, unix:///path (for acp cli_type only)
}
SessionConfig represents a session configuration
type SessionGlobalConfig ¶
type SessionGlobalConfig struct {
MaxDynamicSessions int `yaml:"max_dynamic_sessions"` // Maximum number of dynamic sessions allowed (default: 50)
}
SessionGlobalConfig represents global session configuration
type SessionState ¶
type SessionState string
SessionState represents the current state of a session
const ( StateIdle SessionState = "idle" // Idle and ready for new tasks StateProcessing SessionState = "processing" // Currently processing a command StateWaitingInput SessionState = "waiting_input" // Waiting for user input (mid-interaction) StateError SessionState = "error" // Error state )
type SessionStatus ¶
type SessionStatus struct {
Name string
State SessionState
CLIType string
WorkDir string
IsDynamic bool
CreatedBy string
IsAlive bool
ProcessInfo *ProcessInfo
LastActivity string
}
SessionStatus represents detailed status information about a session
type WatchdogConfig ¶
type WatchdogConfig struct {
Enabled bool `yaml:"enabled"`
CheckIntervals []string `yaml:"check_intervals"`
Timeout string `yaml:"timeout"`
MaxRetries int `yaml:"max_retries"`
InitialDelay string `yaml:"initial_delay"`
RetryDelay string `yaml:"retry_delay"`
}
WatchdogConfig represents watchdog monitoring configuration