core

package
v0.1.5 Latest Latest
Warning

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

Go to latest
Published: May 15, 2026 License: MIT Imports: 27 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"

	// DefaultIdleTimeout is the default idle timeout for auto-cleaning dynamic sessions.
	// Set to "0" to disable.
	DefaultIdleTimeout = "1h"

	// DefaultMaxMessageLength is the default maximum message length before splitting.
	// Messages exceeding this length are split by lines.
	DefaultMaxMessageLength = 4000
)

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 BotChannelRef added in v0.1.5

type BotChannelRef struct {
	Platform string `json:"platform"`
	Channel  string `json:"channel"`
}

BotChannelRef is the persistable subset of BotChannel.

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
	MaxMessageLength  int          `yaml:"max_message_length"` // Max chars per message before splitting by lines (0 = no limit)
}

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"`
	SessionTemplates map[string]SessionTemplate  `yaml:"session_templates"`
	Bots             map[string]BotConfig        `yaml:"bots"`
	CLIAdapters      map[string]CLIAdapterConfig `yaml:"cli_adapters"`
	Logging          LoggingConfig               `yaml:"logging"`
	Proxy            ProxyConfig                 `yaml:"proxy"`
	DataDir          string                      `yaml:"data_dir"` // Directory for persistent state (default: ~/.clibot)
}

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

func (*CoreConfigAdapter) SetConfig added in v0.1.5

func (a *CoreConfigAdapter) SetConfig(config *Config)

SetConfig atomically updates the config pointer. Used during hot-reload.

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) 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) ReloadConfig added in v0.1.5

func (e *Engine) ReloadConfig(configPath string) error

ReloadConfig loads config from the given path and atomically swaps it in. Only runtime-safe fields take effect immediately; startup-baked fields (logging, hook port, bot credentials, CLI adapters, static sessions) require a restart.

func (*Engine) Run

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

Run starts the engine and begins processing messages

func (*Engine) SendPermissionPrompt added in v0.1.5

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

SendPermissionPrompt sends a permission request notification to the user.

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) SetConfigPath added in v0.1.5

func (e *Engine) SetConfigPath(path string)

SetConfigPath stores the config file path for hot-reload.

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            `json:"name"`                   // tmux session name
	CLIType      string            `json:"cli_type"`               // claude/gemini/opencode
	WorkDir      string            `json:"work_dir"`               // Working directory
	StartCmd     string            `json:"start_cmd"`              // Command to start the CLI (default: same as CLIType)
	State        SessionState      `json:"-"`                      // Current state (not persisted)
	CreatedAt    string            `json:"created_at"`             // Creation timestamp
	LastActiveAt time.Time         `json:"last_active_at"`         // Last activity timestamp (input sent or response received)
	IsDynamic    bool              `json:"is_dynamic"`             // true if session was created dynamically via IM
	CreatedBy    string            `json:"created_by"`             // creator identity (format: "platform:userID")
	Env          map[string]string `json:"env,omitempty"`          // Environment variables for the session
	LastChannel  *BotChannelRef    `json:"last_channel,omitempty"` // Last active bot channel for response routing
	// 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 and stdio 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)
	IdleTimeout        string `yaml:"idle_timeout"`         // Auto-cleanup idle dynamic sessions (default: 1h, "0" to disable)
}

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 SessionTemplate added in v0.1.5

type SessionTemplate struct {
	CLIType string            `yaml:"cli_type"` // Required: e.g., codex-stdio, claude-stdio
	Yolo    bool              `yaml:"yolo"`     // Auto-approve all permission prompts
	Env     map[string]string `yaml:"env"`      // Template-level env vars
}

SessionTemplate defines a reusable blueprint for creating sessions via IM. Built-in defaults: codex, claude, gemini, opencode (zero config needed).

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