engine

type Callback func(eventType string, data any) error

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.
	DangerouslySkipPermissions bool     // Bypasses all permission checks. Equivalent to --dangerously-skip-permissions.
	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
}

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

	IsResuming bool // True if session was resumed from persistent marker
	// contains filtered or unexported fields
}

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

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

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

type SessionStatus string