opensteer 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,718 @@
+import * as playwright from 'playwright';
+import { BrowserContextOptions, Page, BrowserContext, Cookie, ElementHandle, Browser } from 'playwright';
+
+type MatchOperator = 'exact' | 'startsWith' | 'contains';
+interface AttributeMatchClause {
+    kind: 'attr';
+    key: string;
+    op?: MatchOperator;
+    value?: string;
+}
+interface PositionMatchClause {
+    kind: 'position';
+    axis: 'nthOfType' | 'nthChild';
+}
+type MatchClause = AttributeMatchClause | PositionMatchClause;
+interface PathNodePosition {
+    nthChild: number;
+    nthOfType: number;
+}
+interface PathNode {
+    tag: string;
+    attrs: Record<string, string>;
+    position: PathNodePosition;
+    match: MatchClause[];
+}
+type DomPath = PathNode[];
+interface ContextHop {
+    kind: 'iframe' | 'shadow';
+    host: DomPath;
+}
+interface ElementPath {
+    context: ContextHop[];
+    nodes: DomPath;
+}
+
+type ActionFailureCode = 'TARGET_NOT_FOUND' | 'TARGET_UNAVAILABLE' | 'TARGET_STALE' | 'TARGET_AMBIGUOUS' | 'BLOCKED_BY_INTERCEPTOR' | 'NOT_VISIBLE' | 'NOT_ENABLED' | 'NOT_EDITABLE' | 'INVALID_TARGET' | 'INVALID_OPTIONS' | 'ACTION_TIMEOUT' | 'UNKNOWN';
+type ActionFailureClassificationSource = 'typed_error' | 'playwright_call_log' | 'dom_probe' | 'message_heuristic' | 'unknown';
+interface ActionFailureBlocker {
+    tag: string;
+    id: string | null;
+    classes: string[];
+    role: string | null;
+    text: string | null;
+}
+interface ActionFailureDetails {
+    blocker?: ActionFailureBlocker;
+    observation?: string;
+}
+interface ActionFailure {
+    code: ActionFailureCode;
+    message: string;
+    retryable: boolean;
+    classificationSource: ActionFailureClassificationSource;
+    details?: ActionFailureDetails;
+}
+
+type SnapshotMode = 'action' | 'extraction' | 'clickable' | 'scrollable' | 'full';
+interface SnapshotOptions {
+    mode?: SnapshotMode;
+    withCounters?: boolean;
+    markInteractive?: boolean;
+}
+interface ScreenshotOptions {
+    fullPage?: boolean;
+    type?: 'png' | 'jpeg';
+    /** Ignored for PNG. */
+    quality?: number;
+    omitBackground?: boolean;
+}
+interface AiResolveArgs {
+    html: string;
+    action: string;
+    description: string;
+    url: string | null;
+}
+interface AiResolveResult {
+    element?: number;
+    selector?: string;
+    path?: ElementPath;
+}
+type AiResolveCallbackResult = AiResolveResult | number | string | null | undefined;
+type AiResolveCallback = (args: AiResolveArgs) => Promise<AiResolveCallbackResult>;
+interface AiExtractArgs<TSchema = ExtractSchema> {
+    html: string;
+    schema: TSchema;
+    description?: string;
+    prompt?: string;
+    url: string | null;
+}
+type AiExtractResult<TData = unknown> = TData | ExtractionPlan | string;
+type AiExtractCallback = <TSchema = ExtractSchema, TData = unknown>(args: AiExtractArgs<TSchema>) => Promise<AiExtractResult<TData>>;
+interface GotoOptions {
+    timeout?: number;
+    waitUntil?: 'commit' | 'domcontentloaded' | 'load' | 'networkidle';
+    settleMs?: number;
+}
+interface LaunchOptions {
+    headless?: boolean;
+    executablePath?: string;
+    slowMo?: number;
+    context?: BrowserContextOptions;
+    /** Connect to a running browser. Example: "http://localhost:9222" */
+    connectUrl?: string;
+    /** Browser channel: "chrome", "chrome-beta", or "msedge" */
+    channel?: string;
+    /** Browser profile directory. Preserves cookies, extensions, and sessions. */
+    profileDir?: string;
+    /** Connection timeout in milliseconds. */
+    timeout?: number;
+}
+interface OpensteerBrowserConfig {
+    headless?: boolean;
+    executablePath?: string;
+    slowMo?: number;
+    /** Connect to a running browser. Example: "http://localhost:9222" */
+    connectUrl?: string;
+    /** Browser channel: "chrome", "chrome-beta", or "msedge" */
+    channel?: string;
+    /** Browser profile directory. Preserves cookies, extensions, and sessions. */
+    profileDir?: string;
+}
+interface OpensteerStorageConfig {
+    rootDir?: string;
+}
+type OpensteerMode = 'local' | 'remote';
+interface OpensteerRemoteOptions {
+    apiKey?: string;
+    baseUrl?: string;
+}
+interface OpensteerConfig {
+    name?: string;
+    browser?: OpensteerBrowserConfig;
+    storage?: OpensteerStorageConfig;
+    mode?: OpensteerMode;
+    remote?: OpensteerRemoteOptions;
+    model?: string;
+    debug?: boolean;
+}
+interface ActionWaitOptions {
+    enabled?: boolean;
+    timeout?: number;
+    settleMs?: number;
+    networkQuietMs?: number;
+    includeNetwork?: boolean;
+}
+interface BaseActionOptions {
+    description?: string;
+    element?: number;
+    selector?: string;
+    wait?: false | ActionWaitOptions;
+}
+interface ClickOptions extends BaseActionOptions {
+    button?: 'left' | 'right' | 'middle';
+    clickCount?: number;
+    modifiers?: Array<'Alt' | 'Control' | 'Meta' | 'Shift'>;
+}
+interface HoverOptions extends BaseActionOptions {
+    force?: boolean;
+    position?: {
+        x: number;
+        y: number;
+    };
+}
+interface InputOptions extends BaseActionOptions {
+    text: string;
+    clear?: boolean;
+    pressEnter?: boolean;
+}
+interface SelectOptions extends BaseActionOptions {
+    value?: string;
+    label?: string;
+    index?: number;
+}
+interface ScrollOptions extends BaseActionOptions {
+    direction?: 'up' | 'down' | 'left' | 'right';
+    amount?: number;
+}
+interface ExtractSchemaField {
+    element?: number;
+    selector?: string;
+    attribute?: string;
+    source?: 'current_url';
+}
+type ExtractSchemaValue = ExtractSchemaField | string | number | boolean | null | ExtractSchema | ExtractSchema[];
+interface ExtractSchema {
+    [key: string]: ExtractSchemaValue;
+}
+interface ExtractOptions<TSchema = ExtractSchema> extends BaseActionOptions {
+    schema?: TSchema;
+    prompt?: string;
+    snapshot?: SnapshotOptions;
+}
+interface ExtractionFieldPlan {
+    element?: number;
+    selector?: string;
+    attribute?: string;
+    source?: 'current_url';
+}
+interface ExtractionPlan {
+    fields?: Record<string, ExtractionFieldPlan>;
+    paths?: Record<string, ElementPath>;
+    data?: unknown;
+}
+interface ExtractFromPlanOptions<TSchema = ExtractSchema> {
+    description?: string;
+    schema: TSchema;
+    plan: ExtractionPlan;
+}
+interface ActionResult {
+    method: string;
+    namespace: string;
+    persisted: boolean;
+    pathFile: string | null;
+    selectorUsed?: string | null;
+}
+interface ExtractionRunResult<T = unknown> {
+    namespace: string;
+    persisted: boolean;
+    pathFile: string | null;
+    data: T;
+    paths: Record<string, ElementPath>;
+}
+interface StateResult {
+    url: string;
+    title: string;
+    html: string;
+}
+interface TabInfo {
+    index: number;
+    url: string;
+    title: string;
+    active: boolean;
+}
+interface CookieParam {
+    name: string;
+    value: string;
+    url?: string;
+    domain?: string;
+    path?: string;
+    expires?: number;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+}
+interface FileUploadOptions extends BaseActionOptions {
+    paths: string[];
+}
+interface BoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+
+interface RegistryEntry {
+    file: string;
+    method: string;
+    description?: string;
+    createdAt: number;
+    updatedAt?: number;
+}
+interface SelectorRegistry {
+    name: string;
+    selectors: Record<string, RegistryEntry>;
+}
+declare function createEmptyRegistry(name: string): SelectorRegistry;
+
+interface SelectorFile<T = unknown> {
+    id: string;
+    method: string;
+    description: string;
+    path: T;
+    schemaHash?: string;
+    metadata: {
+        createdAt: number;
+        updatedAt?: number;
+        sourceUrl?: string | null;
+    };
+}
+declare class LocalSelectorStorage {
+    private rootDir;
+    private namespace;
+    constructor(rootDir: string, namespace: string);
+    getRootDir(): string;
+    getNamespace(): string;
+    getSelectorFileName(id: string): string;
+    getOpensteerDir(): string;
+    getNamespaceDir(): string;
+    getRegistryPath(): string;
+    getSelectorPath(id: string): string;
+    ensureDirs(): void;
+    loadRegistry(): SelectorRegistry;
+    saveRegistry(registry: SelectorRegistry): void;
+    readSelector<T = unknown>(id: string): SelectorFile<T> | null;
+    writeSelector<T = unknown>(payload: SelectorFile<T>): void;
+    clearNamespace(): void;
+}
+
+declare class Opensteer {
+    private readonly config;
+    private readonly aiResolve;
+    private readonly aiExtract;
+    private readonly namespace;
+    private readonly storage;
+    private readonly pool;
+    private readonly remote;
+    private browser;
+    private pageRef;
+    private contextRef;
+    private ownsBrowser;
+    private snapshotCache;
+    constructor(config?: OpensteerConfig);
+    private createLazyResolveCallback;
+    private createLazyExtractCallback;
+    private invokeRemoteActionAndResetCache;
+    private invokeRemoteAction;
+    private buildActionError;
+    get page(): Page;
+    get context(): BrowserContext;
+    launch(options?: LaunchOptions): Promise<void>;
+    static from(page: Page, config?: OpensteerConfig): Opensteer;
+    close(): Promise<void>;
+    private syncLocalSelectorCacheToRemote;
+    goto(url: string, options?: GotoOptions): Promise<void>;
+    snapshot(options?: SnapshotOptions): Promise<string>;
+    state(): Promise<StateResult>;
+    screenshot(options?: ScreenshotOptions): Promise<Buffer>;
+    click(options: ClickOptions): Promise<ActionResult>;
+    dblclick(options: ClickOptions): Promise<ActionResult>;
+    rightclick(options: ClickOptions): Promise<ActionResult>;
+    hover(options: HoverOptions): Promise<ActionResult>;
+    input(options: InputOptions): Promise<ActionResult>;
+    select(options: SelectOptions): Promise<ActionResult>;
+    scroll(options?: ScrollOptions): Promise<ActionResult>;
+    tabs(): Promise<TabInfo[]>;
+    newTab(url?: string): Promise<TabInfo>;
+    switchTab(index: number): Promise<void>;
+    closeTab(index?: number): Promise<void>;
+    getCookies(url?: string): Promise<playwright.Cookie[]>;
+    setCookie(cookie: CookieParam): Promise<void>;
+    clearCookies(): Promise<void>;
+    exportCookies(filePath: string, url?: string): Promise<void>;
+    importCookies(filePath: string): Promise<void>;
+    pressKey(key: string): Promise<void>;
+    type(text: string): Promise<void>;
+    getElementText(options: BaseActionOptions): Promise<string>;
+    getElementValue(options: BaseActionOptions): Promise<string>;
+    getElementAttributes(options: BaseActionOptions): Promise<Record<string, string>>;
+    getElementBoundingBox(options: BaseActionOptions): Promise<BoundingBox | null>;
+    getHtml(selector?: string): Promise<string>;
+    getTitle(): Promise<string>;
+    private executeElementInfoAction;
+    uploadFile(options: FileUploadOptions): Promise<ActionResult>;
+    waitForText(text: string, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    extract<T = unknown>(options: ExtractOptions): Promise<T>;
+    extractFromPlan<T = unknown>(options: ExtractFromPlanOptions): Promise<ExtractionRunResult<T>>;
+    getNamespace(): string;
+    getConfig(): OpensteerConfig;
+    getStorage(): LocalSelectorStorage;
+    clearCache(): void;
+    private runWithPostActionWait;
+    private executeClickVariant;
+    private resolvePath;
+    private resolvePathWithAi;
+    private buildPathFromElement;
+    private tryBuildPathFromCounter;
+    private resolveCounterHandle;
+    private resolveCounterHandleForAction;
+    private buildPathFromResolvedHandle;
+    private withIndexedIframeContext;
+    private readPathFromCounterIndex;
+    private buildPathFromSelector;
+    private ensureSnapshotWithCounters;
+    private persistPath;
+    private persistExtractPaths;
+    private extractPersistedPayload;
+    private extractPersistedObjectNode;
+    private extractPersistedArrayVariants;
+    private extractPersistedArrayVariantRows;
+    private parseAiExtractPlan;
+    private buildFieldTargetsFromSchema;
+    private collectFieldTargetsFromSchemaObject;
+    private collectFieldTargetsFromValue;
+    private buildFieldTargetsFromPlan;
+    private buildFieldTargetsFromData;
+    private extractFields;
+    private resolveFieldTargetsToPersistableFields;
+    private buildActionResult;
+    private resolveStorageKey;
+    private normalizePath;
+}
+
+interface VisualStabilityOptions {
+    timeout?: number;
+    settleMs?: number;
+}
+declare function waitForVisualStability(page: Page, options?: VisualStabilityOptions): Promise<void>;
+
+interface ActionExecutionResult {
+    ok: boolean;
+    path?: ElementPath;
+    usedSelector?: string;
+    error?: string;
+    failure?: ActionFailure;
+}
+
+interface OpensteerActionErrorOptions {
+    action: string;
+    failure: ActionFailure;
+    selectorUsed?: string | null;
+    message?: string;
+    cause?: unknown;
+}
+declare class OpensteerActionError extends Error {
+    readonly action: string;
+    readonly code: ActionFailureCode;
+    readonly failure: ActionFailure;
+    readonly selectorUsed: string | null;
+    constructor(options: OpensteerActionErrorOptions);
+}
+
+declare function performClick(page: Page, path: ElementPath, options: ClickOptions): Promise<ActionExecutionResult>;
+
+declare function performHover(page: Page, path: ElementPath, options: HoverOptions): Promise<ActionExecutionResult>;
+
+declare function performInput(page: Page, path: ElementPath, options: InputOptions): Promise<ActionExecutionResult>;
+
+declare function performSelect(page: Page, path: ElementPath, options: SelectOptions): Promise<ActionExecutionResult>;
+
+declare function performScroll(page: Page, path: ElementPath | null, options: ScrollOptions): Promise<ActionExecutionResult>;
+
+interface FieldSelector {
+    key: string;
+    path: ElementPath;
+    attribute?: string;
+}
+interface ArraySelector {
+    itemParentPath: ElementPath;
+    fields: FieldSelector[];
+}
+interface ArrayRowMetadata {
+    key: string;
+    order: number;
+}
+interface ArrayExtractedRow {
+    values: Record<string, unknown>;
+    meta: ArrayRowMetadata;
+}
+declare function extractWithPaths(page: Page, fields: FieldSelector[]): Promise<Record<string, unknown>>;
+declare function extractArrayWithPaths(page: Page, array: ArraySelector): Promise<Array<Record<string, unknown>>>;
+declare function extractArrayRowsWithPaths(page: Page, array: ArraySelector): Promise<Array<ArrayExtractedRow>>;
+declare function countArrayItemsWithPath(page: Page, itemParentPath: ElementPath): Promise<number>;
+
+declare function listTabs(context: BrowserContext, activePage: Page): Promise<TabInfo[]>;
+declare function createTab(context: BrowserContext, url?: string, gotoOptions?: GotoOptions): Promise<{
+    page: Page;
+    info: TabInfo;
+}>;
+declare function switchTab(context: BrowserContext, index: number): Promise<Page>;
+declare function closeTab(context: BrowserContext, activePage: Page, index?: number): Promise<Page | null>;
+
+declare function getCookies(context: BrowserContext, url?: string): Promise<Cookie[]>;
+declare function setCookie(context: BrowserContext, cookie: CookieParam): Promise<void>;
+declare function clearCookies(context: BrowserContext): Promise<void>;
+declare function exportCookies(context: BrowserContext, filePath: string, url?: string): Promise<void>;
+declare function importCookies(context: BrowserContext, filePath: string): Promise<void>;
+
+declare function pressKey(page: Page, key: string): Promise<void>;
+declare function typeText(page: Page, text: string): Promise<void>;
+
+declare function getElementText(page: Page, path: ElementPath): Promise<string>;
+declare function getElementValue(page: Page, path: ElementPath): Promise<string>;
+declare function getElementAttributes(page: Page, path: ElementPath): Promise<Record<string, string>>;
+declare function getElementBoundingBox(page: Page, path: ElementPath): Promise<BoundingBox | null>;
+declare function getPageHtml(page: Page, selector?: string): Promise<string>;
+declare function getPageTitle(page: Page): Promise<string>;
+
+declare function performFileUpload(page: Page, path: ElementPath, filePaths: string[]): Promise<ActionExecutionResult>;
+
+declare function cloneElementPath(path: ElementPath): ElementPath;
+declare function buildPathSelectorHint(path: ElementPath): string;
+declare function buildElementPathFromSelector(page: Page, selector: string): Promise<ElementPath | null>;
+declare function buildElementPathFromHandle(handle: ElementHandle): Promise<ElementPath | null>;
+declare function sanitizeElementPath(path: ElementPath): ElementPath;
+
+interface ResolvedElementPath {
+    element: ElementHandle<Element>;
+    usedSelector: string;
+}
+declare function resolveElementPath(page: Page, rawPath: ElementPath): Promise<ResolvedElementPath>;
+
+type ElementPathErrorCode = 'ERR_PATH_CONTEXT_HOST_NOT_FOUND' | 'ERR_PATH_IFRAME_UNAVAILABLE' | 'ERR_PATH_SHADOW_ROOT_UNAVAILABLE' | 'ERR_PATH_TARGET_NOT_FOUND' | 'ERR_PATH_TARGET_NOT_UNIQUE';
+declare class ElementPathError extends Error {
+    readonly code: ElementPathErrorCode;
+    constructor(code: ElementPathErrorCode, message: string);
+}
+
+declare const OS_NODE_ID_ATTR = "data-os-node-id";
+declare const OS_BOUNDARY_ATTR = "data-os-boundary";
+declare const OS_UNAVAILABLE_ATTR = "data-os-unavailable";
+declare const OS_IFRAME_BOUNDARY_TAG = "os-iframe-root";
+declare const OS_SHADOW_BOUNDARY_TAG = "os-shadow-root";
+interface SerializeOptions {
+    detectOverlays?: boolean;
+}
+interface SerializedPageHTML {
+    html: string;
+    nodePaths: Map<string, ElementPath>;
+    nodeMeta: Map<string, SerializedNodeMeta>;
+}
+interface SerializedNodeMeta {
+    frameToken: string;
+    instanceToken: string;
+}
+declare function serializePageHTML(page: Page, _options?: SerializeOptions): Promise<SerializedPageHTML>;
+
+declare const OPENSTEER_INTERACTIVE_ATTR = "data-opensteer-interactive";
+declare const OPENSTEER_HIDDEN_ATTR = "data-opensteer-hidden";
+declare const OPENSTEER_SCROLLABLE_ATTR = "data-opensteer-scrollable";
+interface MarkInteractivityOptions {
+    markAttribute?: string;
+    skipIfAlreadyMarked?: boolean;
+}
+declare function markInteractiveElements(page: Page, { markAttribute, skipIfAlreadyMarked, }?: MarkInteractivityOptions): Promise<void>;
+
+declare function cleanForFull(html: string): string;
+/**
+ * Clean HTML for extraction mode. Mirrors the server's cleanHtmlContent()
+ * with leaveAttributes=false, leaveImage=true, leaveLinks=true.
+ *
+ * 1. Remove noise (scripts, styles, hidden elements, comments).
+ * 2. Strip ALL attributes, then re-add only:
+ *    - `c` and internal pipeline attrs on every element
+ *    - `src`, `srcset`, `alt` on <img>
+ *    - `src`, `srcset` on <source> inside <picture>
+ *    - `href` on <a>
+ * 3. Flatten tree (preserve images and links, collapse wrappers).
+ * 4. Deduplicate images.
+ * 5. Serialize with compact LLM-friendly serializer.
+ */
+declare function cleanForExtraction(html: string): string;
+declare function cleanForClickable(html: string): string;
+declare function cleanForScrollable(html: string): string;
+declare function cleanForAction(html: string): string;
+
+interface CounterBinding {
+    sessionId: string;
+    frameToken: string;
+    nodeId: string;
+    instanceToken: string;
+}
+interface CounterRequest {
+    key: string;
+    counter: number;
+    attribute?: string;
+}
+interface CounterSnapshotLike {
+    snapshotSessionId: string;
+    counterBindings: Map<number, CounterBinding> | null;
+}
+type CounterResolutionErrorCode = 'ERR_COUNTER_NOT_FOUND' | 'ERR_COUNTER_FRAME_UNAVAILABLE' | 'ERR_COUNTER_STALE_OR_NOT_FOUND' | 'ERR_COUNTER_AMBIGUOUS';
+declare class CounterResolutionError extends Error {
+    readonly code: CounterResolutionErrorCode;
+    constructor(code: CounterResolutionErrorCode, message: string);
+}
+declare function ensureLiveCounters(page: Page, nodeMeta: Map<string, SerializedNodeMeta>, nodeIds: string[]): Promise<Map<string, number>>;
+declare function resolveCounterElement(page: Page, snapshot: CounterSnapshotLike, counter: number): Promise<ElementHandle<Element>>;
+declare function resolveCountersBatch(page: Page, snapshot: CounterSnapshotLike, requests: CounterRequest[]): Promise<Record<string, unknown>>;
+
+interface PreparedSnapshot {
+    snapshotSessionId: string;
+    mode: SnapshotMode;
+    url: string | null;
+    rawHtml: string;
+    processedHtml: string;
+    reducedHtml: string;
+    cleanedHtml: string;
+    counterIndex: Map<number, ElementPath> | null;
+    counterBindings: Map<number, CounterBinding> | null;
+}
+declare function prepareSnapshot(page: Page, options?: SnapshotOptions): Promise<PreparedSnapshot>;
+
+declare function normalizeNamespace(input?: string): string;
+declare function resolveNamespaceDir(rootDir: string, namespace: string): string;
+
+declare function createResolveCallback(model: string, options?: {
+    temperature?: number;
+    maxTokens?: number | null;
+}): AiResolveCallback;
+
+declare function createExtractCallback(model: string, options?: {
+    temperature?: number;
+    maxTokens?: number | null;
+}): AiExtractCallback;
+
+declare function getModelProvider(modelStr: string): Promise<unknown>;
+
+interface AiModelConfig {
+    model: string;
+    temperature?: number;
+    maxTokens?: number | null;
+}
+
+type RemoteActionMethod = 'goto' | 'snapshot' | 'state' | 'click' | 'dblclick' | 'rightclick' | 'hover' | 'input' | 'select' | 'scroll' | 'tabs' | 'newTab' | 'switchTab' | 'closeTab' | 'getCookies' | 'setCookie' | 'clearCookies' | 'pressKey' | 'type' | 'getElementText' | 'getElementValue' | 'getElementAttributes' | 'getElementBoundingBox' | 'getHtml' | 'getTitle' | 'waitForText' | 'extract' | 'extractFromPlan' | 'clearCache' | 'uploadFile' | 'exportCookies' | 'importCookies' | 'screenshot';
+type RemoteErrorCode = 'REMOTE_AUTH_FAILED' | 'REMOTE_SESSION_NOT_FOUND' | 'REMOTE_SESSION_CLOSED' | 'REMOTE_UNSUPPORTED_METHOD' | 'REMOTE_INVALID_REQUEST' | 'REMOTE_MODEL_NOT_ALLOWED' | 'REMOTE_ACTION_FAILED' | 'REMOTE_CAPACITY_EXHAUSTED' | 'REMOTE_RUNTIME_UNAVAILABLE' | 'REMOTE_RUNTIME_MISMATCH' | 'REMOTE_SESSION_STALE' | 'REMOTE_CONTROL_PLANE_ERROR' | 'REMOTE_INTERNAL';
+interface RemoteSessionCreateRequest {
+    name?: string;
+    model?: string;
+    launchContext?: Record<string, unknown>;
+}
+interface RemoteSessionCreateResponse {
+    sessionId: string;
+    actionWsUrl: string;
+    cdpWsUrl: string;
+    actionToken: string;
+    cdpToken: string;
+    expiresAt?: number;
+}
+interface RemoteSelectorCacheImportEntry {
+    namespace: string;
+    siteOrigin: string;
+    method: string;
+    descriptionHash: string;
+    path: unknown;
+    schemaHash?: string;
+    createdAt: number;
+    updatedAt: number;
+}
+interface RemoteSelectorCacheImportRequest {
+    entries: RemoteSelectorCacheImportEntry[];
+}
+interface RemoteSelectorCacheImportResponse {
+    imported: number;
+    inserted: number;
+    updated: number;
+    skipped: number;
+}
+interface RemoteActionRequest {
+    id: number;
+    method: RemoteActionMethod;
+    args: Record<string, unknown>;
+    sessionId: string;
+    token: string;
+}
+interface RemoteActionSuccess {
+    id: number;
+    ok: true;
+    result: unknown;
+}
+interface RemoteActionFailure {
+    id: number;
+    ok: false;
+    error: string;
+    code: RemoteErrorCode;
+    details?: RemoteActionFailureDetails;
+}
+type RemoteActionResponse = RemoteActionSuccess | RemoteActionFailure;
+interface RemoteActionFailureDetails {
+    actionFailure?: ActionFailure;
+}
+
+declare class OpensteerRemoteError extends Error {
+    readonly code: RemoteErrorCode | 'REMOTE_TRANSPORT_ERROR';
+    readonly status?: number;
+    readonly details?: RemoteActionFailureDetails | Record<string, unknown>;
+    constructor(code: RemoteErrorCode | 'REMOTE_TRANSPORT_ERROR', message: string, status?: number, details?: RemoteActionFailureDetails | Record<string, unknown>);
+}
+declare function remoteUnsupportedMethodError(method: string, message?: string): OpensteerRemoteError;
+declare function remoteNotLaunchedError(): OpensteerRemoteError;
+
+declare class RemoteSessionClient {
+    private readonly baseUrl;
+    private readonly key;
+    constructor(baseUrl: string, key: string);
+    create(request: RemoteSessionCreateRequest): Promise<RemoteSessionCreateResponse>;
+    close(sessionId: string): Promise<void>;
+    importSelectorCache(request: RemoteSelectorCacheImportRequest): Promise<RemoteSelectorCacheImportResponse>;
+    private importSelectorCacheBatch;
+}
+
+interface ActionWsClientOptions {
+    url: string;
+    token: string;
+    sessionId: string;
+}
+declare class ActionWsClient {
+    private readonly ws;
+    private readonly sessionId;
+    private readonly token;
+    private nextRequestId;
+    private readonly pending;
+    private closed;
+    private constructor();
+    static connect(options: ActionWsClientOptions): Promise<ActionWsClient>;
+    request<T>(method: RemoteActionMethod, args: Record<string, unknown>): Promise<T>;
+    close(): Promise<void>;
+    private handleMessage;
+    private rejectAll;
+}
+
+interface RemoteCdpConnectArgs {
+    wsUrl: string;
+    token: string;
+}
+interface RemoteCdpConnection {
+    browser: Browser;
+    context: BrowserContext;
+    page: Page;
+}
+declare class RemoteCdpClient {
+    connect(args: RemoteCdpConnectArgs): Promise<RemoteCdpConnection>;
+}
+
+declare function collectLocalSelectorCacheEntries(storage: LocalSelectorStorage): RemoteSelectorCacheImportEntry[];
+
+export { type ActionExecutionResult, type ActionFailure, type ActionFailureBlocker, type ActionFailureClassificationSource, type ActionFailureCode, type ActionFailureDetails, type ActionResult, type ActionWaitOptions, ActionWsClient, type AiExtractArgs, type AiExtractCallback, type AiExtractResult, type AiModelConfig, type AiResolveArgs, type AiResolveCallback, type AiResolveCallbackResult, type AiResolveResult, type ArrayExtractedRow, type ArrayRowMetadata, type ArraySelector, type AttributeMatchClause, type BaseActionOptions, type BoundingBox, type ClickOptions, type ContextHop, type CookieParam, type CounterBinding, type CounterRequest, CounterResolutionError, type CounterResolutionErrorCode, type CounterSnapshotLike, type DomPath, type ElementPath, ElementPathError, type ElementPathErrorCode, type ExtractFromPlanOptions, type ExtractOptions, type ExtractSchema, type ExtractSchemaField, type ExtractSchemaValue, type ExtractionFieldPlan, type ExtractionPlan, type ExtractionRunResult, type FieldSelector, type FileUploadOptions, type GotoOptions, type HoverOptions, type InputOptions, type LaunchOptions, LocalSelectorStorage, type MarkInteractivityOptions, type MatchClause, type MatchOperator, OPENSTEER_HIDDEN_ATTR, OPENSTEER_INTERACTIVE_ATTR, OPENSTEER_SCROLLABLE_ATTR, OS_BOUNDARY_ATTR, OS_IFRAME_BOUNDARY_TAG, OS_NODE_ID_ATTR, OS_SHADOW_BOUNDARY_TAG, OS_UNAVAILABLE_ATTR, Opensteer, OpensteerActionError, type OpensteerBrowserConfig, type OpensteerConfig, type OpensteerMode, OpensteerRemoteError, type OpensteerRemoteOptions, type OpensteerStorageConfig, type PathNode, type PathNodePosition, type PositionMatchClause, type PreparedSnapshot, type RegistryEntry, type RemoteActionFailure, type RemoteActionFailureDetails, type RemoteActionMethod, type RemoteActionRequest, type RemoteActionResponse, type RemoteActionSuccess, RemoteCdpClient, type RemoteCdpConnectArgs, type RemoteCdpConnection, type RemoteErrorCode, type RemoteSelectorCacheImportEntry, type RemoteSelectorCacheImportRequest, type RemoteSelectorCacheImportResponse, RemoteSessionClient, type RemoteSessionCreateRequest, type RemoteSessionCreateResponse, type ResolvedElementPath, type ScreenshotOptions, type ScrollOptions, type SelectOptions, type SelectorFile, type SelectorRegistry, type SerializeOptions, type SerializedNodeMeta, type SerializedPageHTML, type SnapshotMode, type SnapshotOptions, type StateResult, type TabInfo, buildElementPathFromHandle, buildElementPathFromSelector, buildPathSelectorHint, cleanForAction, cleanForClickable, cleanForExtraction, cleanForFull, cleanForScrollable, clearCookies, cloneElementPath, closeTab, collectLocalSelectorCacheEntries, countArrayItemsWithPath, createEmptyRegistry, createExtractCallback, createResolveCallback, createTab, ensureLiveCounters, exportCookies, extractArrayRowsWithPaths, extractArrayWithPaths, extractWithPaths, getCookies, getElementAttributes, getElementBoundingBox, getElementText, getElementValue, getModelProvider, getPageHtml, getPageTitle, importCookies, listTabs, markInteractiveElements, normalizeNamespace, performClick, performFileUpload, performHover, performInput, performScroll, performSelect, prepareSnapshot, pressKey, remoteNotLaunchedError, remoteUnsupportedMethodError, resolveCounterElement, resolveCountersBatch, resolveElementPath, resolveNamespaceDir, sanitizeElementPath, serializePageHTML, setCookie, switchTab, typeText, waitForVisualStability };