engine

Documentation

Index

• type Engine
  • func NewEngine(options EngineOptions) (*Engine, error)
  • func (r *Engine) Close() error
  • func (r *Engine) Execute(ctx context.Context, cfg *types.Config, prompt string, callback event.Callback) error
  • func (r *Engine) GetAllowedTools() []string
  • func (r *Engine) GetCLIVersion() (string, error)
  • func (r *Engine) GetDisallowedTools() []string
  • func (r *Engine) GetSession(sessionID string) (*intengine.Session, bool)
  • func (r *Engine) GetSessionStats(sessionID string) *SessionStats
  • func (r *Engine) SetAllowedTools(tools []string)
  • func (r *Engine) SetDangerAllowPaths(paths []string)
  • func (r *Engine) SetDangerBypassEnabled(token string, enabled bool) error
  • func (r *Engine) SetDisallowedTools(tools []string)
  • func (r *Engine) StopSession(sessionID string, reason string) error
  • func (r *Engine) ValidateConfig(cfg *types.Config) error
• type EngineOptions
• type SessionStats
  • func (s *SessionStats) EndGeneration()
  • func (s *SessionStats) EndThinking()
  • func (s *SessionStats) FinalizeDuration() *SessionStats
  • func (s *SessionStats) RecordFileModification(filePath string)
  • func (s *SessionStats) RecordTokens(input, output, cacheWrite, cacheRead int32)
  • func (s *SessionStats) RecordToolResult() (durationMs int64)
  • func (s *SessionStats) RecordToolUse(toolName, toolID string)
  • func (s *SessionStats) StartGeneration()
  • func (s *SessionStats) StartThinking()
  • func (s *SessionStats) ToSummary() map[string]interface{}

Types

type Engine

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

Engine is the core Control Plane for AI CLI agent integration. Configured as a long-lived Singleton, it transforms local CLI tools into production-ready services by managing a hot-multiplexed process pool, enforcing security WAF rules, and providing a unified event-driven SDK for application integration.

func NewEngine

func NewEngine(options EngineOptions) (*Engine, error)

NewEngine creates a new HotPlex Engine instance.

func (*Engine) Close

func (r *Engine) Close() error

Close terminates all active sessions managed by this runner and cleans up resources. It triggers Graceful Shutdown by cascading termination signals down to the SessionManager, which drops the entire process group (PGID) to prevent zombie processes.

func (*Engine) Execute

func (r *Engine) Execute(ctx context.Context, cfg *types.Config, prompt string, callback event.Callback) error

Execute runs Claude Code CLI with the given configuration and streams

func (*Engine) GetAllowedTools

func (r *Engine) GetAllowedTools() []string

GetAllowedTools returns the current allowed tools list. Thread-safe: uses internal mutex.

func (*Engine) GetCLIVersion

func (r *Engine) GetCLIVersion() (string, error)

GetCLIVersion returns the Claude Code CLI version.

func (*Engine) GetDisallowedTools

func (r *Engine) GetDisallowedTools() []string

GetDisallowedTools returns the current disallowed tools list. Thread-safe: uses internal mutex.

func (*Engine) GetSession

func (r *Engine) GetSession(sessionID string) (*intengine.Session, bool)

GetSession retrieves an active session by sessionID. Returns the session and true if found, or nil and false if not found.

func (*Engine) GetSessionStats

func (r *Engine) GetSessionStats(sessionID string) *SessionStats

GetSessionStats returns a copy of the accumulated session stats.

func (*Engine) SetAllowedTools

func (r *Engine) SetAllowedTools(tools []string)

SetAllowedTools sets the allowed tools for the engine. This affects new sessions created after the call. Thread-safe: uses internal mutex.

func (*Engine) SetDangerAllowPaths

func (r *Engine) SetDangerAllowPaths(paths []string)

SetDangerAllowPaths sets the allowed safe paths for the danger detector.

func (*Engine) SetDangerBypassEnabled

func (r *Engine) SetDangerBypassEnabled(token string, enabled bool) error

SetDangerBypassEnabled enables or disables danger detection bypass. WARNING: Only use for Evolution mode (admin only).

func (*Engine) SetDisallowedTools

func (r *Engine) SetDisallowedTools(tools []string)

SetDisallowedTools sets the disallowed tools for the engine. This affects new sessions created after the call. Thread-safe: uses internal mutex.

func (*Engine) StopSession

func (r *Engine) StopSession(sessionID string, reason string) error

StopSession terminates a running session by session ID. This is the implementation for session.stop from the spec.

func (*Engine) ValidateConfig

func (r *Engine) ValidateConfig(cfg *types.Config) error

ValidateConfig validates the Config.

type EngineOptions

type EngineOptions = intengine.EngineOptions

EngineOptions defines the configuration parameters for initializing a new HotPlex Engine. It allows customization of timeouts, logging, and foundational security boundaries that apply to all sessions managed by this engine instance.

type SessionStats

type SessionStats struct {
	SessionID            string          `json:"session_id"`
	StartTime            time.Time       `json:"-"` // Internal use only, use ToSummary() for JSON
	TotalDurationMs      int64           `json:"total_duration_ms"`
	ThinkingDurationMs   int64           `json:"thinking_duration_ms"`
	ToolDurationMs       int64           `json:"tool_duration_ms"`
	GenerationDurationMs int64           `json:"generation_duration_ms"`
	InputTokens          int32           `json:"input_tokens"`
	OutputTokens         int32           `json:"output_tokens"`
	CacheWriteTokens     int32           `json:"cache_write_tokens"`
	CacheReadTokens      int32           `json:"cache_read_tokens"`
	ToolCallCount        int32           `json:"tool_call_count"`
	ToolsUsed            map[string]bool `json:"-"` // Internal set, use ToSummary() for array
	FilesModified        int32           `json:"files_modified"`
	FilePaths            []string        `json:"file_paths"`
	// contains filtered or unexported fields
}

SessionStats collects session-level statistics for Geek/Evolution modes.

func (*SessionStats) EndGeneration

func (s *SessionStats) EndGeneration()

EndGeneration marks the end of the generation phase and records its duration.

func (*SessionStats) EndThinking

func (s *SessionStats) EndThinking()

EndThinking marks the end of the thinking phase and records its duration.

func (*SessionStats) FinalizeDuration

func (s *SessionStats) FinalizeDuration() *SessionStats

FinalizeDuration finalizes any ongoing phase tracking and returns the final stats.

func (*SessionStats) RecordFileModification

func (s *SessionStats) RecordFileModification(filePath string)

RecordFileModification records that a file was modified. Uses O(1) map lookup for deduplication instead of O(n) linear scan.

func (*SessionStats) RecordTokens

func (s *SessionStats) RecordTokens(input, output, cacheWrite, cacheRead int32)

RecordTokens records token usage.

func (*SessionStats) RecordToolResult

func (s *SessionStats) RecordToolResult() (durationMs int64)

RecordToolResult records the end of a tool call. If RecordToolUse was not called (e.g., Claude Code didn't send tool_use event), this will record a minimal duration (1ms) to indicate the tool completed.

func (*SessionStats) RecordToolUse

func (s *SessionStats) RecordToolUse(toolName, toolID string)

RecordToolUse records the start of a tool call.

func (*SessionStats) StartGeneration

func (s *SessionStats) StartGeneration()

StartGeneration marks the start of the generation phase.

func (*SessionStats) StartThinking

func (s *SessionStats) StartThinking()

StartThinking marks the start of the thinking phase.

func (*SessionStats) ToSummary

func (s *SessionStats) ToSummary() map[string]interface{}

ToSummary converts stats to a summary map for JSON serialization.