core

package
v0.1.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 28, 2026 License: MIT Imports: 21 Imported by: 0

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

View Source
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)
	BaseURL           string       `yaml:"base_url"`           // WeChat iLink: API base URL (optional)
	CredentialsPath   string       `yaml:"credentials_path"`   // WeChat iLink: credentials file path (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

func LoadConfig(configPath string) (*Config, error)

LoadConfig loads configuration from file and expands environment variables

func (*Config) GetBotConfig

func (c *Config) GetBotConfig(botType string) (BotConfig, error)

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) IsAdmin

func (c *Config) IsAdmin(platform, userID string) bool

IsAdmin checks if a user is an admin

func (*Config) IsUserAuthorized

func (c *Config) IsUserAuthorized(platform, userID string) bool

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 NewEngine

func NewEngine(config *Config) *Engine

NewEngine creates a new Engine instance

func (*Engine) GetActiveSession

func (e *Engine) GetActiveSession(channel string) *Session

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) Run

func (e *Engine) Run(ctx context.Context) error

Run starts the engine and begins processing messages

func (*Engine) SendResponseToSession

func (e *Engine) SendResponseToSession(sessionName, message string)

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

func (e *Engine) SendToAllBots(message string)

SendToAllBots sends a message to all active bots

func (*Engine) SendToBot

func (e *Engine) SendToBot(platform, channel, message string)

SendToBot sends a message to a specific bot

func (*Engine) Stop

func (e *Engine) Stop() error

Stop gracefully stops the engine

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

type ResponseEvent struct {
	SessionName string
	Response    string
	Timestamp   string
}

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

func (s *Session) NeedsWatchdog() bool

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)
	Env       map[string]string `yaml:"env"`       // Session-level environment variables (merged with adapter-level env)
}

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL