engine

Documentation

Overview

Package engine provides the core session management and process pool for HotPlex.

The engine package implements the Hot-Multiplexing pattern, maintaining persistent CLI agent processes that can be reused across multiple execution turns. This eliminates the cold-start latency of spawning heavy Node.js processes for each request.

Key components:

• SessionPool: Thread-safe process pool with idle GC
• Session: Individual CLI process wrapper with full-duplex I/O
• SessionManager: Interface for process lifecycle management

Index

• Constants
• type Callback
• type EngineOptions
• type Session
  • func NewTestSession(id string, status SessionStatus) *Session
  • func (s *Session) GetCallback() Callback
  • func (s *Session) GetExt() any
  • func (s *Session) GetLastActive() time.Time
  • func (s *Session) GetStatus() SessionStatus
  • func (s *Session) GetStatusChange() <-chan SessionStatus
  • func (s *Session) IsAlive() bool
  • func (s *Session) ReadStderr()
  • func (s *Session) ReadStdout()
  • func (s *Session) SetCallback(cb Callback)
  • func (s *Session) SetExt(data any)
  • func (s *Session) SetStatus(status SessionStatus)
  • func (s *Session) Touch()
  • func (s *Session) WriteInput(msg map[string]any) error
• type SessionConfig
• type SessionManager
• type SessionPool
  • func NewSessionPool(logger *slog.Logger, timeout time.Duration, opts EngineOptions, cliPath string, ...) *SessionPool
  • func (sm *SessionPool) GetOrCreateSession(ctx context.Context, sessionID string, cfg SessionConfig, prompt string) (*Session, bool, error)
  • func (sm *SessionPool) GetSession(sessionID string) (*Session, bool)
  • func (sm *SessionPool) ListActiveSessions() []*Session
  • func (sm *SessionPool) Shutdown()
  • func (sm *SessionPool) TerminateSession(sessionID string) error
• type SessionStatus

Constants

const (
	ScannerInitialBufSize = 256 * 1024       // 256 KB
	ScannerMaxBufSize     = 10 * 1024 * 1024 // 10 MB
)

Scanner buffer sizes for CLI output parsing.

const (
	DefaultReadyTimeout  = 10 * time.Second // Maximum time to wait for session to be ready
	CleanupCheckInterval = 1 * time.Minute  // Interval between idle session cleanup checks
)

Session lifecycle constants.

Types

type Callback

type Callback func(eventType string, data any) error

Callback handles streaming events from the CLI. Events are dispatched as they occur, allowing real-time UI updates.

type EngineOptions

type EngineOptions struct {
	Timeout     time.Duration // Maximum time to wait for a single execution turn to complete
	IdleTimeout time.Duration // Time after which an idle session is eligible for termination
	Logger      *slog.Logger  // Optional logger instance; defaults to slog.Default()

	// Namespace is used to generate isolated, deterministic UUID v5 Session IDs.
	// This ensures that the same Conversation ID creates an isolated but persistent sandbox,
	// preventing cross-application or cross-user session leaks.
	Namespace string

	// Foundational Security & Context (Engine-level boundaries)
	PermissionMode   string   // Controls CLI permissions (e.g., "bypass-permissions"). Defaults to strict mode.
	BaseSystemPrompt string   // Foundational instructions injected at CLI startup for all sessions.
	AllowedTools     []string // Explicit list of tools allowed (whitelist). If empty, all tools are allowed.
	DisallowedTools  []string // Explicit list of tools forbidden (blacklist).

	// AdminToken is the secret required to toggle security bypass mode.
	// If empty, bypass will be disabled for security.
	AdminToken string

	// Provider is the AI CLI provider (e.g., Claude Code, OpenCode).
	// If nil, defaults to ClaudeCodeProvider.
	Provider provider.Provider
}

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

type Session

type Session struct {
	ID                string        // Internal SDK identifier (provided by the user)
	ProviderSessionID string        // The deterministic UUID (v5) passed to CLI for persistent DB storage
	Config            SessionConfig // Snapshot of the configuration used to initialize the session
	TaskInstructions  string        // Persistent instructions for the session

	CreatedAt  time.Time
	LastActive time.Time
	Status     SessionStatus
	// contains filtered or unexported fields
}

Session represents a persistent, hot-multiplexed instance of an AI CLI agent. It manages the underlying OS process group, handles streaming I/O via full-duplex pipes, and tracks the operational readiness and lifecycle status of the agent sandbox.

func NewTestSession

func NewTestSession(id string, status SessionStatus) *Session

NewTestSession creates a Session for testing purposes. This should only be used in test code.

func (*Session) GetCallback

func (s *Session) GetCallback() Callback

GetCallback returns the current callback.

func (*Session) GetExt

func (s *Session) GetExt() any

GetExt retrieves the external state attached to the session.

func (*Session) GetLastActive

func (s *Session) GetLastActive() time.Time

GetLastActive returns the last active time with proper locking.

func (*Session) GetStatus

func (s *Session) GetStatus() SessionStatus

GetStatus returns the current session status.

func (*Session) GetStatusChange

func (s *Session) GetStatusChange() <-chan SessionStatus

GetStatusChange returns the status change channel for waiting on status updates.

func (*Session) IsAlive

func (s *Session) IsAlive() bool

IsAlive checks if the process is still running.

func (*Session) ReadStderr

func (s *Session) ReadStderr()

ReadStderr asynchronously reads CLI stderr to prevent buffer deadlocks.

func (*Session) ReadStdout

func (s *Session) ReadStdout()

ReadStdout asynchronously reads CLI stdout, parses JSON, and dispatches callbacks.

func (*Session) SetCallback

func (s *Session) SetCallback(cb Callback)

SetCallback registers the callback to handle stream events for the current turn.

func (*Session) SetExt

func (s *Session) SetExt(data any)

SetExt attaches external state to the session.

func (*Session) SetStatus

func (s *Session) SetStatus(status SessionStatus)

SetStatus updates the session status with proper locking.

func (*Session) Touch

func (s *Session) Touch()

Touch updates LastActive time.

func (*Session) WriteInput

func (s *Session) WriteInput(msg map[string]any) error

WriteInput injects a JSON message to Stdin.

type SessionConfig

type SessionConfig struct {
	WorkDir          string // Absolute path to the isolated sandbox directory
	TaskInstructions string // Persistent instructions for the session
}

SessionConfig contains the minimal configuration needed for session management. This is a subset of the root Config to avoid circular dependencies.

type SessionManager

type SessionManager interface {
	// GetOrCreateSession retrieves an active session or performs a Cold Start if none exists.
	// Returns the session, a boolean indicating if it was a Cold Start, and an error if any.
	GetOrCreateSession(ctx context.Context, sessionID string, cfg SessionConfig, prompt string) (*Session, bool, error)
	// GetSession performs a non-side-effect lookup of an active session.
	GetSession(sessionID string) (*Session, bool)
	// TerminateSession kills the OS process group and removes the session from the pool.
	TerminateSession(sessionID string) error
	// ListActiveSessions provides a snapshot of all tracked sessions.
	ListActiveSessions() []*Session
	// Shutdown performing a total cleanup of the pool and its background workers.
	Shutdown()
}

SessionManager defines the behavioral interface for managing a process pool.

type SessionPool

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

SessionPool implements the SessionManager as a thread-safe singleton. It orchestrates the lifecycle of multiple CLI processes, ensuring that idle processes are garbage collected to conserve system memory.

func NewSessionPool

func NewSessionPool(logger *slog.Logger, timeout time.Duration, opts EngineOptions, cliPath string, prv provider.Provider) *SessionPool

NewSessionPool creates a new session manager with default file-based marker storage.

func (*SessionPool) GetOrCreateSession

func (sm *SessionPool) GetOrCreateSession(ctx context.Context, sessionID string, cfg SessionConfig, prompt string) (*Session, bool, error)

GetOrCreateSession returns an existing session or starts a new one.

func (*SessionPool) GetSession

func (sm *SessionPool) GetSession(sessionID string) (*Session, bool)

GetSession retrieves an active session.

func (*SessionPool) ListActiveSessions

func (sm *SessionPool) ListActiveSessions() []*Session

ListActiveSessions returns all active sessions.

func (*SessionPool) Shutdown

func (sm *SessionPool) Shutdown()

Shutdown gracefully stops the session manager and all active sessions.

func (*SessionPool) TerminateSession

func (sm *SessionPool) TerminateSession(sessionID string) error

TerminateSession stops and removes a session.

type SessionStatus

type SessionStatus string

SessionStatus defines the current state of a session.

const (
	SessionStatusStarting SessionStatus = "starting"
	SessionStatusReady    SessionStatus = "ready"
	SessionStatusBusy     SessionStatus = "busy"
	SessionStatusDead     SessionStatus = "dead"
)