/**
 * Embedded Playwright MCP server for ai-service.
 *
 * Manages lifecycle of the Playwright MCP server that enables
 * judge evaluations to interact with browsers.
 */
import type { BootstrapData, InitData } from "@superblocksteam/library-shared/types";
import type { Logger } from "../../util/logger.js";
import type { InteractiveElement } from "../agent/subagents/testing/types.js";
import type { FileArtifact } from "../types.js";
/**
 * Handle for the embedded MCP server.
 */
export interface PlaywrightMcpServer {
    /** Server URL for client connections */
    url: string;
    /** Stops the server and cleans up resources */
    close: () => Promise<void>;
    /** Save the current action log and reset for a new session */
    flushLog: () => Promise<void>;
    /** Capture interactive elements from the current page for DOM context */
    captureInteractiveElements: () => Promise<InteractiveElement[]>;
}
/**
 * Options for starting the MCP server.
 */
export interface PlaywrightMcpServerOptions {
    /**
     * Optional path to a Playwright storage state file for authentication.
     * This allows the MCP server's browser to use the same auth cookies/localStorage.
     */
    storageStatePath?: string;
    /**
     * Optional JWT to inject via Authorization headers for all requests.
     */
    jwt?: string;
    /**
     * Optional appUrl for deriving cookie domains when seeding auth.
     */
    appUrl?: string;
    /**
     * Browser to use (chromium, firefox, webkit).
     * Defaults to chromium.
     */
    browser?: "chromium" | "firefox" | "webkit";
    /**
     * Whether to run in headless mode.
     * Defaults to true.
     */
    headless?: boolean;
    /**
     * Optional websocket endpoint for connecting to an existing Playwright browser.
     */
    connectWsEndpoint?: string;
    /**
     * Optional raw storage state data to seed the context.
     */
    storageStateData?: any;
    /**
     * Init data from sb-init message - required for socket connection setup.
     */
    initData?: InitData;
    /**
     * Bootstrap data for initializing the vite dev server app directly.
     * When provided, the app will be initialized without needing a parent iframe.
     */
    bootstrapData?: BootstrapData;
    /**
     * Optional session storage items to seed for the app origin.
     */
    sessionStorageData?: {
        origin: string;
        items: Array<{
            name: string;
            value: string;
        }>;
    };
    /**
     * Additional origins storage to seed (e.g., auth domain).
     */
    extraOrigins?: Array<{
        origin: string;
        localStorage: Array<{
            name: string;
            value: string;
        }>;
        sessionStorage?: Array<{
            name: string;
            value: string;
        }>;
    }>;
    /**
     * Optional function to save log artifacts.
     * When provided, Playwright action logs will be saved as .log files.
     */
    saveArtifact?: (artifact: FileArtifact, stepId: string, runTimestamp: string) => Promise<void>;
    /**
     * Optional run timestamp for log file organization.
     * Defaults to current ISO timestamp.
     */
    runTimestamp?: string;
}
/**
 * Lifecycle manager for the embedded Playwright MCP server.
 *
 * Handles starting, stopping, and status checking of the server.
 * The server runs in the same process as the ai-service.
 */
export declare class PlaywrightMcpServerManager {
    private server;
    private logger;
    constructor(logger: Logger);
    /**
     * Starts the MCP server if not already running.
     *
     * @param options - Server configuration options
     * @returns Server URL for client connections
     * @throws Error if server fails to start
     */
    start(options?: PlaywrightMcpServerOptions): Promise<string>;
    /**
     * Stops the MCP server if running.
     *
     * Gracefully shuts down the server and cleans up browser resources.
     */
    stop(): Promise<void>;
    /**
     * Checks if the server is currently running.
     *
     * @returns True if server is running
     */
    isRunning(): boolean;
    /**
     * Gets the server URL if running.
     *
     * @returns Server URL or null if not running
     */
    getUrl(): string | null;
    /**
     * Flushes the current action log and resets for a new session.
     * Call this after each test run to save logs without stopping the server.
     */
    flushLog(): Promise<void>;
    /**
     * Captures interactive elements from the current page.
     * This provides DOM context that can be passed to the test LLM
     * so it knows which elements are available for interaction.
     *
     * @returns Array of interactive element info, or empty array if server not running
     */
    captureInteractiveElements(): Promise<InteractiveElement[]>;
}
//# sourceMappingURL=playwright-server.d.ts.map