hotplex

type AssistantMessage struct {
	ID      string         `json:"id,omitempty"`      // Unique message ID
	Type    string         `json:"type,omitempty"`    // Typically "message"
	Role    string         `json:"role,omitempty"`    // Typically "assistant"
	Content []ContentBlock `json:"content,omitempty"` // Sequence of text and tool blocks
}

type Callback func(eventType string, data any) error

type Config struct {
	WorkDir          string // Absolute path to the isolated sandbox directory where CLI operations occur
	SessionID        string // Unique identifier used to route the request to a persistent process in the pool
	TaskSystemPrompt string // Instructions prepended to the user prompt for this specific turn
}

type ContentBlock struct {
	Type      string         `json:"type"`                  // Block type: "text", "tool_use", "tool_result"
	Text      string         `json:"text,omitempty"`        // Raw text content (for type="text")
	Name      string         `json:"name,omitempty"`        // Tool name (for type="tool_use")
	ID        string         `json:"id,omitempty"`          // Block identifier
	ToolUseID string         `json:"tool_use_id,omitempty"` // References the original tool_use (for type="tool_result")
	Input     map[string]any `json:"input,omitempty"`       // Tool input JSON (for type="tool_use")
	Content   string         `json:"content,omitempty"`     // Result content (for type="tool_result")
	IsError   bool           `json:"is_error,omitempty"`    // Whether the tool result indicates a failure
}

type DangerBlockEvent struct {
	Operation      string      `json:"operation"`             // The specific command line that triggered the block
	Reason         string      `json:"reason"`                // Description of the threat
	PatternMatched string      `json:"pattern_matched"`       // The specific signature that matched the input
	Level          DangerLevel `json:"level"`                 // Severity level
	Category       string      `json:"category"`              // Category classification
	BypassAllowed  bool        `json:"bypass_allowed"`        // Whether the user has administrative privileges to bypass this block
	Suggestions    []string    `json:"suggestions,omitempty"` // Safe alternatives to the blocked command
}

type DangerLevel int

type DangerPattern struct {
	Pattern     *regexp.Regexp // The compiled regex identifying the dangerous sequence
	Description string         // Human-readable explanation of why this pattern is blocked
	Level       DangerLevel    // Severity used for logging and alerting
	Category    string         // Functional category (e.g., "file_delete", "network", "system")
}

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

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

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).
}

type EventMeta struct {
	// Timing
	DurationMs      int64 `json:"duration_ms"`       // Event duration in milliseconds
	TotalDurationMs int64 `json:"total_duration_ms"` // Total elapsed time since start

	// Tool call info
	ToolName string `json:"tool_name"` // Tool name (e.g., "bash", "editor_write", "memo_search")
	ToolID   string `json:"tool_id"`   // Unique tool call ID
	Status   string `json:"status"`    // "running", "success", "error"
	ErrorMsg string `json:"error_msg"` // Error message if status=error

	// Token usage (when available)
	InputTokens      int32 `json:"input_tokens"`       // Input tokens
	OutputTokens     int32 `json:"output_tokens"`      // Output tokens
	CacheWriteTokens int32 `json:"cache_write_tokens"` // Cache write tokens
	CacheReadTokens  int32 `json:"cache_read_tokens"`  // Cache read tokens

	// Summaries for UI
	InputSummary  string `json:"input_summary"`  // Human-readable input summary
	OutputSummary string `json:"output_summary"` // Truncated output preview

	// File operations
	FilePath  string `json:"file_path"`  // Affected file path
	LineCount int32  `json:"line_count"` // Number of lines affected

	// Progress (for long-running operations)
	Progress    int32 `json:"progress"`     // Progress percentage (0-100)
	TotalSteps  int32 `json:"total_steps"`  // Total number of steps (for multi-stage operations)
	CurrentStep int32 `json:"current_step"` // Current step number
}

type EventWithMeta struct {
	EventType string     // Event type (thinking, tool_use, tool_result, etc.)
	EventData string     // Event data content
	Meta      *EventMeta // Enhanced metadata (never nil when created via NewEventWithMeta)
}

type HotPlexClient interface {
	// Execute runs a command or prompt within the HotPlex sandbox and streams events back via the Callback.
	// It uses Hot-Multiplexing to reuse existing processes if a matching SessionID is provided in the Config.
	Execute(ctx context.Context, cfg *Config, prompt string, callback Callback) error

	// Close gracefully terminates all managed sessions in the pool and releases all OS-level resources.
	// This includes sweeping process groups (PGID) to ensure no zombie processes remain.
	Close() error
}

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

	CreatedAt  time.Time     // When the process was first spawned
	LastActive time.Time     // When the process was last used (used for LRU/Idle GC)
	Status     SessionStatus // Runtime state: starting, ready, busy, or dead
	// contains filtered or unexported fields
}

type SessionManager interface {
	// GetOrCreateSession retrieves an active session or performs a Cold Start if none exists.
	GetOrCreateSession(ctx context.Context, sessionID string, cfg Config) (*Session, 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()
}

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

type SessionStats struct {
	SessionID            string          // Unique identifier for the session
	StartTime            time.Time       // Timestamp when the session started
	TotalDurationMs      int64           // Total duration of the session in milliseconds
	ThinkingDurationMs   int64           // Total time spent in thinking phase in milliseconds
	ToolDurationMs       int64           // Total time spent executing tools in milliseconds
	GenerationDurationMs int64           // Total time spent generating text in milliseconds
	InputTokens          int32           // Total input tokens consumed
	OutputTokens         int32           // Total output tokens generated
	CacheWriteTokens     int32           // Total tokens written to cache
	CacheReadTokens      int32           // Total tokens read from cache
	ToolCallCount        int32           // Number of tool calls made
	ToolsUsed            map[string]bool // Set of unique tool names used
	FilesModified        int32           // Number of files modified
	FilePaths            []string        // List of paths of files modified
	// contains filtered or unexported fields
}

type SessionStatsData struct {
	SessionID            string   `json:"session_id"`
	StartTime            int64    `json:"start_time"` // Unix timestamp
	EndTime              int64    `json:"end_time"`   // Unix timestamp
	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"`
	TotalTokens          int32    `json:"total_tokens"`
	ToolCallCount        int32    `json:"tool_call_count"`
	ToolsUsed            []string `json:"tools_used"`
	FilesModified        int32    `json:"files_modified"`
	FilePaths            []string `json:"file_paths"`
	TotalCostUSD         float64  `json:"total_cost_usd"`
	ModelUsed            string   `json:"model_used"`
	IsError              bool     `json:"is_error"`
	ErrorMessage         string   `json:"error_message,omitempty"`
}

type SessionStatus string

type StreamMessage struct {
	Message      *AssistantMessage `json:"message,omitempty"`        // Details of an assistant-generated message
	Input        map[string]any    `json:"input,omitempty"`          // Arguments passed to a tool invocation
	Type         string            `json:"type"`                     // Event category: "assistant", "tool_use", "result", "thought", etc.
	Timestamp    string            `json:"timestamp,omitempty"`      // ISO8601 timestamp of the event
	SessionID    string            `json:"session_id,omitempty"`     // The persistent session identifier in the CLI's internal DB
	Role         string            `json:"role,omitempty"`           // Message role: "user", "assistant", or "system"
	Name         string            `json:"name,omitempty"`           // Name of the tool being used or the block type
	Output       string            `json:"output,omitempty"`         // Raw string output from a tool or assistant
	Status       string            `json:"status,omitempty"`         // Lifecycle status of the event (e.g., "running", "success")
	Error        string            `json:"error,omitempty"`          // Detailed error message if an operation fails
	Content      []ContentBlock    `json:"content,omitempty"`        // Hierarchical content blocks (text, tool_use, etc.)
	Duration     int               `json:"duration_ms,omitempty"`    // Execution time in milliseconds for "result" messages
	Subtype      string            `json:"subtype,omitempty"`        // Fine-grained type classification (e.g., for "result" events)
	IsError      bool              `json:"is_error,omitempty"`       // Flag indicating if the overall turn resulted in an error
	TotalCostUSD float64           `json:"total_cost_usd,omitempty"` // Cumulative cost of the turn in USD
	Usage        *UsageStats       `json:"usage,omitempty"`          // Precise token consumption for the turn
	Result       string            `json:"result,omitempty"`         // Final summarized result of the execution
}

type UsageStats struct {
	InputTokens           int32 `json:"input_tokens"`                          // Total tokens in the prompt (including system and context)
	OutputTokens          int32 `json:"output_tokens"`                         // Total tokens generated by the model
	CacheWriteInputTokens int32 `json:"cache_creation_input_tokens,omitempty"` // Tokens saved to the provider's prompt cache
	CacheReadInputTokens  int32 `json:"cache_read_input_tokens,omitempty"`     // Tokens retrieved from the provider's prompt cache
}