engine

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

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

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., "bypassPermissions", "acceptEdits", "default"). 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 HTTPSessionIO struct {
	// contains filtered or unexported fields
}

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

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
	FirstMessageOnSession bool // True until the first BuildInputMessage is sent (for HTTP hot-multiplexing gate)
	// contains filtered or unexported fields
}

type SessionCallback func(eventType string, data any) error

type SessionConfig struct {
	WorkDir          string        // Absolute path to the isolated sandbox directory
	TaskInstructions string        // Persistent instructions for the session
	BaseSystemPrompt string        // Session-level system prompt override (takes precedence over Engine-level)
	IdleTimeout      time.Duration // Per-session idle timeout; 0 means use pool default
	Namespace        string        // Per-session namespace override; empty means use pool default
}

type SessionIO interface {
	// WriteInput serializes msg as JSON and delivers it to the agent session.
	WriteInput(msg map[string]any) error

	// Close releases all resources held by the SessionIO.
	// Close is idempotent and goroutine-safe.
	Close() error

	// Logger returns the session logger.
	Logger() *slog.Logger

	// IsCLI returns true if this is a CLI subprocess transport.
	// Used by cleanupSessionLocked to determine cleanup strategy.
	IsCLI() bool

	// IsAlive returns true if the transport is still active.
	// For CLI: checks if the process is still running.
	// For HTTP: checks if the session connection is still open.
	IsAlive() bool
}

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 SessionStarter interface {
	// StartSession starts a new session and returns it fully initialized.
	// The callback is invoked for each raw event from the session.
	StartSession(ctx context.Context, sessionID string, cfg SessionConfig, prompt string, cb Callback) (*Session, error)

	// TransportType returns the transport type identifier ("cli" or "http").
	TransportType() string

	// CleanupOnError cleans up any partially-initialized session resources
	// when StartSession returns an error. This is needed because HTTPSessionStarter
	// starts the StartReading goroutine before returning; if StartSession returns
	// an error, the goroutine's 30s timeout is the only cleanup unless this is called.
	// For CLISessionStarter this is a no-op.
	CleanupOnError()
}

type SessionStatus string

type StreamDataSaver interface {
	// GetBuffer retrieves the stream buffer for a session.
	// Returns nil if no buffer exists.
	GetBuffer(sessionID string) any

	// SaveIncompleteStream saves uncommitted stream data before termination.
	// This is a synchronous operation to ensure data is persisted before
	// the session is destroyed.
	SaveIncompleteStream(ctx context.Context, sessionID string, buffer any) error
}