import { EventEmitter } from "events";
import { z } from "zod";
import { InferStagehandSchema, StagehandZodSchema } from "./zodCompat.js";
import { LLMClient } from "./llm/LLMClient.js";
import { AgentReplayStep } from "./types/private/index.js";
import { AgentConfig, AgentExecuteOptions, AgentStreamExecuteOptions, AgentResult, LogLine, StagehandMetrics, Action, ActOptions, ActResult, defaultExtractSchema, ExtractOptions, HistoryEntry, ObserveOptions, pageTextSchema, V3FunctionName, V3Options, AgentStreamResult } from "./types/public/index.js";
import { V3Context } from "./understudy/context.js";
/**
 * V3
 *
 * Purpose:
 * A high-level orchestrator for Stagehand V3. Abstracts away whether the browser
 * runs **locally via Chrome** or remotely on **Browserbase**, and exposes simple
 * entrypoints (`act`, `extract`, `observe`) that delegate to the corresponding
 * handler classes.
 *
 * Responsibilities:
 * - Bootstraps Chrome or Browserbase, ensures a working CDP WebSocket, and builds a `V3Context`.
 * - Manages lifecycle: init, context access, cleanup.
 * - Bridges external page objects (Playwright/Puppeteer) into internal frameIds for handlers.
 * - Provides a stable API surface for downstream code regardless of runtime environment.
 */
export declare class V3 {
    private readonly opts;
    private state;
    private actHandler;
    private extractHandler;
    private observeHandler;
    private ctx;
    llmClient: LLMClient;
    /**
     * Event bus for internal communication.
     * Emits events like 'screenshot' when screenshots are captured during agent execution.
     */
    readonly bus: EventEmitter;
    private modelName;
    private modelClientOptions;
    private llmProvider;
    private overrideLlmClients;
    private readonly domSettleTimeoutMs?;
    private _isClosing;
    browserbaseSessionId?: string;
    private browserbaseSessionUrl?;
    private browserbaseDebugUrl?;
    get browserbaseSessionID(): string | undefined;
    get browserbaseSessionURL(): string | undefined;
    get browserbaseDebugURL(): string | undefined;
    /**
     * Returns true if the browser is running on Browserbase.
     */
    get isBrowserbase(): boolean;
    /**
     * Returns true if advancedStealth is enabled in Browserbase settings.
     */
    get isAdvancedStealth(): boolean;
    /**
     * Returns the configured viewport dimensions from launch options.
     * Falls back to default 1288x711 if not configured.
     */
    get configuredViewport(): {
        width: number;
        height: number;
    };
    private _onCdpClosed;
    readonly experimental: boolean;
    readonly logInferenceToFile: boolean;
    readonly disableAPI: boolean;
    private externalLogger?;
    verbose: 0 | 1 | 2;
    private stagehandLogger;
    private _history;
    private readonly instanceId;
    private static _processGuardsInstalled;
    private static _instances;
    private cacheStorage;
    private actCache;
    private agentCache;
    private apiClient;
    private keepAlive?;
    private shutdownSupervisor;
    stagehandMetrics: StagehandMetrics;
    constructor(opts: V3Options);
    /**
     * Async property for metrics so callers can `await v3.metrics`.
     * When using API mode, fetches metrics from the API. Otherwise returns local metrics.
     */
    get metrics(): Promise<StagehandMetrics>;
    private resolveLlmClient;
    private beginAgentReplayRecording;
    private endAgentReplayRecording;
    private discardAgentReplayRecording;
    private isAgentReplayRecording;
    isAgentReplayActive(): boolean;
    recordAgentReplayStep(step: AgentReplayStep): void;
    /**
     * Async property for history so callers can `await v3.history`.
     * Returns a frozen copy to avoid external mutation.
     */
    get history(): Promise<ReadonlyArray<HistoryEntry>>;
    addToHistory(method: HistoryEntry["method"], parameters: unknown, result?: unknown): void;
    updateMetrics(functionName: V3FunctionName, promptTokens: number, completionTokens: number, reasoningTokens: number, cachedInputTokens: number, inferenceTimeMs: number): void;
    private updateTotalMetrics;
    private _immediateShutdown;
    /** Spawn a crash-only supervisor that cleans up when this process dies. */
    private startShutdownSupervisor;
    /** Stop the supervisor during a normal shutdown. */
    private stopShutdownSupervisor;
    /**
     * Entrypoint: initializes handlers, launches Chrome or Browserbase,
     * and sets up a CDP context.
     */
    init(): Promise<void>;
    /** Apply post-connect local browser options that require CDP. */
    private _applyPostConnectLocalOptions;
    private _ensureBrowserbaseDownloadsEnabled;
    private resetBrowserbaseSessionMetadata;
    /**
     * Run an "act" instruction through the ActHandler.
     *
     * New API:
     * - act(instruction: string, options?: ActOptions)
     * - act(action: Action, options?: ActOptions)
     */
    act(instruction: string, options?: ActOptions): Promise<ActResult>;
    act(action: Action, options?: ActOptions): Promise<ActResult>;
    /**
     * Run an "extract" instruction through the ExtractHandler.
     *
     * Accepted forms:
     * - extract() → pageText
     * - extract(options) → pageText
     * - extract(instruction) → defaultExtractSchema
     * - extract(instruction, schema) → schema-inferred
     * - extract(instruction, schema, options)
     */
    extract(): Promise<z.infer<typeof pageTextSchema>>;
    extract(options: ExtractOptions): Promise<z.infer<typeof pageTextSchema>>;
    extract(instruction: string, options?: ExtractOptions): Promise<z.infer<typeof defaultExtractSchema>>;
    extract<T extends StagehandZodSchema>(instruction: string, schema: T, options?: ExtractOptions): Promise<InferStagehandSchema<T>>;
    /**
     * Run an "observe" instruction through the ObserveHandler.
     */
    observe(): Promise<Action[]>;
    observe(options: ObserveOptions): Promise<Action[]>;
    observe(instruction: string, options?: ObserveOptions): Promise<Action[]>;
    /** Return the browser-level CDP WebSocket endpoint. */
    connectURL(): string;
    /** Expose the current CDP-backed context. */
    get context(): V3Context;
    /** Best-effort cleanup of context and launched resources. */
    close(opts?: {
        force?: boolean;
    }): Promise<void>;
    /** Guard: ensure Browserbase credentials exist in options. */
    private requireBrowserbaseCreds;
    get logger(): (logLine: LogLine) => void;
    /**
     * Normalize a Playwright/Puppeteer page object into its top frame id,
     * so handlers can resolve it to a `Page` within our V3Context.
     */
    private resolveTopFrameId;
    private isPlaywrightPage;
    private isPatchrightPage;
    private isPuppeteerPage;
    /** Resolve an external page reference or fall back to the active V3 page. */
    private resolvePage;
    private normalizeToV3Page;
    private _logBrowserbaseSessionStatus;
    /**
     * Prepares shared context for agent execution (both execute and stream).
     * Extracts duplicated setup logic into a single helper.
     */
    private prepareAgentExecution;
    /**
     * Create a v3 agent instance (AISDK tool-based) with execute().
     * Mirrors the v2 Stagehand.agent() tool mode (no CUA provider here).
     *
     * @overload When stream: true, returns a streaming agent where execute() returns AgentStreamResult
     * @overload When stream is false/undefined, returns a non-streaming agent where execute() returns AgentResult
     */
    agent(options: AgentConfig & {
        stream: true;
    }): {
        execute: (instructionOrOptions: string | AgentStreamExecuteOptions) => Promise<AgentStreamResult>;
    };
    agent(options?: AgentConfig & {
        stream?: false;
    }): {
        execute: (instructionOrOptions: string | AgentExecuteOptions) => Promise<AgentResult>;
    };
}
