@mastra/core/dist/browser/thread-manager.d.ts

Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.

/**
 * ThreadManager - Abstract base class for managing thread-scoped browser sessions.
 *
 * Similar to ProcessManager for workspaces, this centralizes thread lifecycle logic
 * and makes thread isolation reusable across browser providers.
 *
 * Browser scope modes:
 * - 'shared': All threads share a single browser instance
 * - 'thread': Each thread gets its own browser instance (full isolation)
 */
import type { IMastraLogger } from '../logger/index.js';
/** Browser scope mode - determines how browser instances are shared across threads */
export type BrowserScope = 'shared' | 'thread';
/** Default thread ID used when no thread is specified */
export declare const DEFAULT_THREAD_ID = "__default__";
/**
 * Represents a single tab's state for persistence.
 */
export interface BrowserTabState {
    url: string;
    title?: string;
}
/**
 * Full browser state for persistence and restoration.
 */
export interface BrowserState {
    tabs: BrowserTabState[];
    activeTabIndex: number;
}
/**
 * Represents an active thread session.
 */
export interface ThreadSession {
    /** Unique thread identifier */
    threadId: string;
    /** Timestamp when session was created */
    createdAt: number;
    /** Full browser state for this thread (for restore on relaunch) */
    browserState?: BrowserState;
}
/**
 * Configuration for ThreadManager.
 */
export interface ThreadManagerConfig {
    /** Browser scope mode */
    scope: BrowserScope;
    /** Logger instance */
    logger?: IMastraLogger;
    /** Callback when a new session is created */
    onSessionCreated?: (session: ThreadSession) => void;
    /** Callback when a session is destroyed */
    onSessionDestroyed?: (threadId: string) => void;
}
/**
 * Abstract base class for managing thread-scoped browser sessions.
 *
 * @typeParam TManager - The browser manager type (e.g., BrowserManagerLike, Stagehand)
 */
export declare abstract class ThreadManager<TManager = unknown> {
    protected readonly scope: BrowserScope;
    protected readonly logger?: IMastraLogger;
    protected readonly sessions: Map<string, ThreadSession>;
    protected activeThreadId: string;
    /** Preserved browser state that survives session clears (for browser restore) */
    protected readonly savedBrowserStates: Map<string, BrowserState>;
    /** Shared manager instance (used for 'shared' scope) */
    protected sharedManager: TManager | null;
    /** Map of thread ID to dedicated manager instance (for 'thread' scope) */
    protected readonly threadManagers: Map<string, TManager>;
    protected readonly onSessionCreated?: (session: ThreadSession) => void;
    protected readonly onSessionDestroyed?: (threadId: string) => void;
    constructor(config: ThreadManagerConfig);
    /**
     * Get the current browser scope mode.
     */
    getScope(): BrowserScope;
    /**
     * Get the currently active thread ID.
     */
    getActiveThreadId(): string;
    /**
     * Set the shared manager instance (called after browser launch).
     */
    setSharedManager(manager: TManager): void;
    /**
     * Clear the shared manager instance (called when browser disconnects).
     */
    clearSharedManager(): void;
    /**
     * Get the manager for an existing thread session without creating a new one.
     *
     * For 'thread' scope: Returns the thread-specific manager, or null if no session exists.
     * For 'shared' scope: Returns the shared manager (all threads use the same instance).
     *
     * @param threadId - Thread identifier (defaults to DEFAULT_THREAD_ID)
     * @returns The manager for the thread, or null if not found (thread scope only)
     */
    getExistingManagerForThread(threadId?: string): TManager | null;
    /**
     * Check if any thread managers are still running (for 'thread' scope).
     */
    hasActiveThreadManagers(): boolean;
    /**
     * Clear all session tracking without closing managers.
     * Used when browsers have been externally closed and we just need to reset state.
     */
    clearAllSessions(): void;
    /**
     * Get a session by thread ID.
     */
    getSession(threadId: string): ThreadSession | undefined;
    /**
     * Check if a session exists for a thread.
     */
    hasSession(threadId: string): boolean;
    /**
     * List all active sessions.
     */
    listSessions(): ThreadSession[];
    /**
     * Get the number of active sessions.
     */
    getSessionCount(): number;
    /**
     * Get or create a session for a thread, and return the browser manager for that thread.
     *
     * For 'shared' scope, returns the shared manager.
     * For 'thread' scope, creates/returns a dedicated manager for the thread.
     *
     * @param threadId - Thread identifier (uses DEFAULT_THREAD_ID if not provided)
     * @returns The browser manager for the thread
     */
    getManagerForThread(threadId?: string): Promise<TManager>;
    /**
     * Destroy a specific thread's session.
     *
     * @param threadId - Thread identifier
     */
    destroySession(threadId: string): Promise<void>;
    /**
     * Destroy all thread sessions.
     */
    destroyAllSessions(): Promise<void>;
    /**
     * Update the browser state for a thread session.
     * Also saves to persistent storage so state survives session clears.
     */
    updateBrowserState(threadId: string, state: BrowserState): void;
    /**
     * Get the saved browser state for a thread (survives session clears).
     */
    getSavedBrowserState(threadId: string): BrowserState | undefined;
    /**
     * Clear a specific thread's session without closing the browser.
     * Used when a thread's browser has been externally closed.
     * Preserves the browser state for potential restoration.
     *
     * @param threadId - The thread ID to clear
     */
    clearSession(threadId: string): void;
    /**
     * Get the shared browser manager (used for 'shared' scope and default thread).
     * @throws Error if shared manager is not initialized
     */
    protected getSharedManager(): TManager;
    /**
     * Create a new session for a thread.
     * Called when a thread is accessed for the first time.
     */
    protected abstract createSession(threadId: string): Promise<ThreadSession>;
    /**
     * Get the browser manager for a specific session.
     */
    protected abstract getManagerForSession(session: ThreadSession): TManager;
    /**
     * Destroy a session and clean up resources.
     */
    protected abstract doDestroySession(session: ThreadSession): Promise<void>;
}
//# sourceMappingURL=thread-manager.d.ts.map