@mearl/native-host 2.22.0 → 3.0.0-beta.1

package/dist/agent/event-transport.d.ts

@@ -0,0 +1,3 @@
+import type { AgentChatEvent } from '@mearl/browser-core';
+export declare const MAX_AGENT_EVENT_BYTES: number;
+export declare function sanitizeAgentChatEvent(event: AgentChatEvent): AgentChatEvent;

package/dist/agent/manager.d.ts

@@ -0,0 +1,59 @@
+import type { AgentChatEvent, AgentChatEventsOptions, AgentChatEventsResult, AgentChatListSessionsOptions, AgentChatListSessionsResult, AgentChatOpenWorkspaceOptions, AgentChatPrepareOptions, AgentChatRefreshResult, AgentChatRunOptions, AgentChatRunResult, AgentChatRespondOptions, AgentChatSendOptions, AgentChatSession, AgentChatSessionTarget, AgentChatStartOptions, AgentChatStatus, AgentInstalledSkill, AgentSkillInstalledListOptions, AgentSkillReadOptions, AgentSkillReadResult } from '@mearl/browser-core';
+import { type ToolboxAgentRuntime } from '../toolbox-service.js';
+import type { AgentProvider, AgentProviderSessionOptions, AgentProviderTurnOptions } from '@mearl/agent-runtime';
+export interface AgentChatManagerDependencies {
+    resolveToolboxAgent?: (toolId: string) => ToolboxAgentRuntime;
+}
+interface AgentProviderLoader {
+    id: string;
+    load(): Promise<AgentProvider>;
+}
+export declare class AgentChatManager {
+    private readonly emit;
+    private readonly dependencies;
+    private readonly providers;
+    private readonly providerLoaders;
+    private readonly providerLoads;
+    private disposed;
+    private readonly sessions;
+    private readonly sessionByProviderThread;
+    private readonly pendingRequests;
+    private readonly completedTurns;
+    private readonly recentEvents;
+    private readonly recentEventBytes;
+    private readonly compactedEventCounts;
+    private readonly truncatedEventSessions;
+    private readonly unsubscribe;
+    private readonly taskListeners;
+    constructor(providers: Array<AgentProvider | AgentProviderLoader>, emit: (event: AgentChatEvent) => void, dependencies?: AgentChatManagerDependencies);
+    getStatus(): Promise<AgentChatStatus>;
+    prepare(options: AgentChatPrepareOptions): Promise<void>;
+    listSkills(options: AgentSkillInstalledListOptions): Promise<AgentInstalledSkill[]>;
+    readSkill(options: AgentSkillReadOptions): Promise<AgentSkillReadResult>;
+    listSessions(options: AgentChatListSessionsOptions): Promise<AgentChatListSessionsResult>;
+    startSession(options: AgentChatStartOptions, providerOptionsOverride?: Pick<AgentProviderSessionOptions, 'readOnly'>): Promise<AgentChatSession>;
+    sendMessage(options: AgentChatSendOptions, turnOptions?: AgentProviderTurnOptions): Promise<{
+        turnId: string;
+    }>;
+    runTask(options: AgentChatRunOptions): Promise<AgentChatRunResult>;
+    interrupt(options: AgentChatSessionTarget): Promise<void>;
+    openSession(options: AgentChatSessionTarget): Promise<void>;
+    openWorkspace(options: AgentChatOpenWorkspaceOptions): Promise<void>;
+    closeSession(options: AgentChatSessionTarget): Promise<void>;
+    getEvents(options: AgentChatEventsOptions): AgentChatEventsResult;
+    refreshSession(options: AgentChatEventsOptions): Promise<AgentChatRefreshResult>;
+    respondToRequest(options: AgentChatRespondOptions): void;
+    dispose(): void;
+    private handleProviderEvent;
+    private emitEvent;
+    private recordEvent;
+    private trimReplayBuffer;
+    private getProvider;
+    private registerProvider;
+    private loadProvider;
+    private getSession;
+    private providerThreadKey;
+    private providerRequestKey;
+    private sessionTurnKey;
+}
+export {};

package/dist/agent/skill-manager.d.ts

@@ -0,0 +1,52 @@
+import type { AgentSkillCheckUpdatesResult, AgentSkillCheckUpdatesOptions, AgentSkillInstallOptions, AgentSkillMutationOptions, AgentSkillMutationResult, AgentSkillProviderId } from '@mearl/browser-core';
+import { checkTrackedSkillUpdates, readTrackedSkillSources, type SkillInstallationStatus } from '@mearl/setup/skill-sources';
+export type SkillCliRunner = (executable: string, args: string[], cwd?: string) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+export type SkillBackendBatchOptions = Omit<AgentSkillInstallOptions, 'name' | 'providerId'> & {
+    names: string[];
+    providerId?: AgentSkillProviderId;
+};
+/** A preset supplies CLI behavior; directory state and plugin registration stay in the host. */
+export interface AgentSkillBackend {
+    id: string;
+    install(data: AgentSkillInstallOptions): ReturnType<SkillCliRunner>;
+    installBatch?(data: SkillBackendBatchOptions): ReturnType<SkillCliRunner>;
+    normalizeSource?(source: string, sourceType?: string): string;
+    update(data: AgentSkillMutationOptions): ReturnType<SkillCliRunner>;
+    uninstall(data: AgentSkillMutationOptions): ReturnType<SkillCliRunner>;
+    checkUpdates(data: AgentSkillCheckUpdatesOptions): Promise<AgentSkillCheckUpdatesResult>;
+}
+export declare const runSkillCli: SkillCliRunner;
+export interface AgentSkillManagerOptions {
+    run?: SkillCliRunner;
+    checkUpdates?: typeof checkTrackedSkillUpdates;
+    readSources?: typeof readTrackedSkillSources;
+    backend?: () => AgentSkillBackend | undefined;
+}
+export type { SkillInstallationStatus } from '@mearl/setup/skill-sources';
+export declare class AgentSkillManager {
+    private readonly run;
+    private readonly check;
+    private readonly sources;
+    private readonly selectedBackend;
+    constructor(options?: AgentSkillManagerOptions);
+    private backend;
+    /** A preset batch keeps one accepted manager for all of its operations. */
+    capture(): AgentSkillManager;
+    inspectGlobal(source: string, name: string, version?: string): SkillInstallationStatus;
+    repairGlobalRegistration(name: string, options?: {
+        registrationManagedBy?: string;
+    }): Promise<void>;
+    install(data: AgentSkillInstallOptions): Promise<AgentSkillMutationResult>;
+    installGlobal(source: string, name: string): Promise<AgentSkillMutationResult>;
+    installGlobals(source: string, names: string[], options?: {
+        registrationManagedBy?: string;
+    }): Promise<AgentSkillMutationResult>;
+    private installAccepted;
+    checkUpdates(data: AgentSkillCheckUpdatesOptions): Promise<AgentSkillCheckUpdatesResult>;
+    update(data: AgentSkillMutationOptions): Promise<AgentSkillMutationResult>;
+    uninstall(data: AgentSkillMutationOptions): Promise<AgentSkillMutationResult>;
+    private mutationContext;
+}

package/dist/agent/workspace-directory.d.ts

@@ -0,0 +1,4 @@
+export type DirectoryPickerRunner = (command: string, args: string[]) => Promise<string | null>;
+export declare const runDirectoryPickerCommand: DirectoryPickerRunner;
+export declare function pickWorkspaceDirectory(platform?: NodeJS.Platform, run?: DirectoryPickerRunner): Promise<string | null>;
+export declare function resolveWorkspaceDirectory(directory: unknown): string;

package/dist/alipay-auth-code.d.ts

@@ -0,0 +1,13 @@
+export type AlipayAuthCodeProgress = 'installing' | 'connected' | 'authorizing';
+export interface AlipayAuthCodeParams {
+    appId: string;
+    scopeNicks: string[];
+    showErrorTip?: boolean;
+}
+export declare function validateAlipayAuthCodeParams(value: unknown): AlipayAuthCodeParams;
+export declare function startAlipayAuthCode(value: unknown, onProgress?: (phase: AlipayAuthCodeProgress) => void): Promise<{
+    browserId: string;
+    qrSvg: string;
+}>;
+export declare function waitAlipayAuthCode(browserId: string, value: unknown, onProgress?: (phase: AlipayAuthCodeProgress) => void): Promise<Record<string, unknown>>;
+export declare function closeAlipayAuthCode(browserId: string): Promise<void>;

package/dist/analytics.d.ts

@@ -0,0 +1,3 @@
+export declare function setAnalyticsClientId(value: unknown): boolean;
+export declare function classifyAnalyticsError(error: unknown): string;
+export declare function trackAction(action: string, params?: Record<string, string | number | boolean>): void;

package/dist/app-profile-catalog.d.ts

@@ -0,0 +1,11 @@
+import { type ResolveAppProfileOptions } from '@mearl/app-profiles';
+import { type AppProfileCatalogEntry } from '@mearl/browser-core';
+export declare function findCapabilityAppProfile(id: string): AppProfileCatalogEntry | undefined;
+export declare function listInstalledAppProfiles(): Promise<{
+    profiles: AppProfileCatalogEntry[];
+    errors: Array<{
+        plugin: string;
+        error: string;
+    }>;
+}>;
+export declare function resolveInstalledAppProfile(name: string, options?: ResolveAppProfileOptions): Promise<import("@mearl/app-profiles").ResolvedAppProfile>;

package/dist/browser-artifacts.d.ts

@@ -0,0 +1,26 @@
+import type { BrowserArtifact } from '@mearl/browser-core';
+export declare const ARTIFACT_CHUNK_BYTES: number;
+/** Opaque ids keep browser-host paths out of remote file requests. */
+export declare class BrowserArtifactStore {
+    private root;
+    private files;
+    private directory?;
+    private sweeper?;
+    constructor(root?: string);
+    create(filename: string, sessionId?: string): Promise<BrowserArtifact>;
+    importFile(filename: string, sourcePath: string, sessionId?: string): Promise<BrowserArtifact>;
+    private require;
+    private info;
+    write(id: string, offset: number, base64: string, sessionId?: string): Promise<BrowserArtifact>;
+    complete(id: string, bytes: number, sessionId?: string): BrowserArtifact;
+    resolve(id: string, sessionId?: string): string;
+    read(id: string, offset: number, sessionId?: string): Promise<{
+        base64: string;
+        bytes: number;
+        totalBytes: number;
+    }>;
+    remove(id: string, sessionId?: string): Promise<void>;
+    release(sessionId: string, keep?: string[]): Promise<void>;
+    disposeSync(): void;
+    dispose(): Promise<void>;
+}

package/dist/browser-inventory.d.ts

@@ -0,0 +1,22 @@
+import type { BrowserListResult, BrowserProviderIdentity, ManagedBrowserInfo } from '@mearl/browser-core';
+import type { ProviderBrowser, ProviderDescriptor, ProviderRuntime } from '@mearl/provider';
+import { type BrowserRecord } from './browser-registry.js';
+type BrowserInventoryResult = Omit<BrowserListResult, 'defaultBrowserId'>;
+export interface CdpBrowserDiscovery {
+    isPublished: () => boolean;
+    isAvailable: () => Promise<boolean>;
+    publish: () => boolean;
+    monitor: () => void;
+}
+export declare function providerIdentity(descriptor: ProviderDescriptor): BrowserProviderIdentity;
+export interface ProviderInventoryBrowser {
+    provider: BrowserProviderIdentity;
+    browser: ProviderBrowser;
+}
+/** Register the default CDP browser only after a live browser-level connection succeeds. */
+export declare function ensureDiscoverableCdpBrowser(discovery: CdpBrowserDiscovery): Promise<boolean>;
+export declare function providerBrowserInfo(entry: ProviderInventoryBrowser, route?: BrowserRecord): ManagedBrowserInfo;
+export declare function mergeBrowserInventory(routes: BrowserRecord[], providerBrowsers: ProviderInventoryBrowser[]): BrowserInventoryResult;
+export declare function providerInventory(runtimes: ProviderRuntime[]): Promise<ProviderInventoryBrowser[]>;
+export declare function listBrowserInventory(runtimes: ProviderRuntime[]): Promise<BrowserInventoryResult>;
+export {};

package/dist/browser-provider-coordinator.d.ts

@@ -0,0 +1,24 @@
+import type { BrowserAccessResult, BrowserLaunchParams, ManagedBrowserInfo, BrowserProviderListResult } from '@mearl/browser-core';
+import type { JsonObject, ProviderRuntime, ProviderLaunchFormRequest } from '@mearl/provider';
+import { type TransferableCookie } from './cdp-backend/cookie-transfer.js';
+export declare class BrowserProviderCoordinator {
+    private readonly runtimes;
+    private readonly hostServices?;
+    constructor(runtimes: ProviderRuntime[], hostServices?: {
+        exportCookies: (domains: string[]) => Promise<TransferableCookie[]>;
+        getBrowserUserAgent: () => Promise<string>;
+    } | undefined);
+    private hostContext;
+    definitions(): BrowserProviderListResult;
+    get providerRuntimes(): ProviderRuntime[];
+    launch(input: BrowserLaunchParams): Promise<ManagedBrowserInfo>;
+    close(selector: string, deleteProfile?: boolean): Promise<unknown>;
+    start(selector: string): Promise<ManagedBrowserInfo>;
+    syncCookies(selector: string, scope: JsonObject): Promise<unknown>;
+    access(selector: string): Promise<BrowserAccessResult>;
+    detach(selector: string): Promise<unknown>;
+    configure(providerId: string, options: JsonObject): Promise<unknown>;
+    getLaunchForm(providerId: string, request: ProviderLaunchFormRequest): Promise<import("@mearl/provider").ProviderLaunchForm>;
+    private findRuntimeBrowsers;
+    private requireOne;
+}

package/dist/browser-provider.d.ts

@@ -0,0 +1,30 @@
+import { type JsonObject, type ProviderAccess, type ProviderBrowser, type ProviderBrowserType, type ProviderHostContextData, type ProviderLaunchForm, type ProviderLaunchFormRequest } from '@mearl/provider';
+import { type BrowserRecord } from './browser-registry.js';
+export interface BrowserProviderSummary {
+    provider: {
+        id: string;
+        name: string;
+        builtin: false;
+        version: string;
+        protocolVersion: number;
+    };
+    browserType: ProviderBrowserType;
+}
+export declare function listExternalBrowserProviders(): BrowserProviderSummary[];
+export declare function getProviderLaunchForm(providerId: string, request: ProviderLaunchFormRequest): Promise<ProviderLaunchForm>;
+export declare function launchProviderBrowser(input: {
+    provider: string;
+    providerOptions: JsonObject;
+    host?: ProviderHostContextData;
+}): Promise<ProviderBrowser>;
+export declare function findProviderBrowser(selector: string): BrowserRecord | null;
+export declare function listProviderControlSessions(): Promise<any>;
+export declare function updateProviderControlSession(sessionId: string, operation: string): Promise<any>;
+export declare function closeProviderBrowser(browser: BrowserRecord, options?: {
+    deleteProfile?: boolean;
+}): Promise<unknown>;
+export declare function detachProviderBrowser(browser: BrowserRecord): Promise<unknown>;
+export declare function accessProviderBrowser(browser: BrowserRecord): Promise<ProviderAccess>;
+export declare function startProviderBrowser(browser: BrowserRecord): Promise<ProviderBrowser>;
+export declare function syncProviderBrowserCookies(browser: BrowserRecord, scope: JsonObject, host?: ProviderHostContextData): Promise<unknown>;
+export declare function configureProvider(providerId: string, options: JsonObject): Promise<unknown>;

package/dist/browser-registry.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Browser registry — advertises this native-host's connection in a shared,
+ * on-disk registry so clients can discover and address multiple browsers at
+ * once (multiple Chrome profiles / Chromium-based browsers, each with the
+ * extension, each launching its own native-host).
+ *
+ * Why a registry instead of the old single well-known socket
+ * ----------------------------------------------------------
+ * Historically every native-host fought over one fixed socket; the last one to
+ * start kicked the others off, so at most one browser was reachable and the two
+ * flapped on every reconnect. Here each native-host listens on its own unique
+ * per-process socket and publishes a record; the client reads the registry and
+ * connects to the socket of whichever browser it wants (default: most-recently
+ * focused). No contention, N browsers reachable simultaneously.
+ *
+ * Ownership
+ * ---------
+ * The record is keyed by the browser's stable installation id, so a browser
+ * that reconnects (extension reload → new native-host pid → new socket) simply
+ * overwrites its own record. To avoid a briefly-overlapping predecessor wiping
+ * the successor's record during a reload, every mutation first checks that the
+ * on-disk record still belongs to this process (or is stale) before writing.
+ */
+import { type DaemonRecord } from '@mearl/daemon-core';
+import type { BrowserCapabilities, BrowserDetails, BrowserPairingInfo, BrowserProviderOperation, BrowserProviderIdentity, BrowserReference, BrowserTransport } from '@mearl/browser-core';
+export interface BrowserRecord extends DaemonRecord {
+    /** native-host pid — used for liveness pruning. */
+    pid: number;
+    /** Stable per-installation id reported by the extension (or 'cdp' for daemon mode). */
+    browserId: string;
+    /** Absolute path of the per-process socket this native-host listens on. */
+    socketPath: string;
+    /** Human-readable browser name, e.g. "Chrome", "Edge". */
+    browserName: string;
+    extensionVersion?: string;
+    nativeHostVersion?: string;
+    transport: BrowserTransport;
+    providerBrowserId?: string;
+    provider?: BrowserProviderIdentity;
+    capabilities?: BrowserCapabilities;
+    status?: 'connected' | 'pairing' | 'running_disconnected' | 'stopped';
+    ownership?: 'owned' | 'attached';
+    persistence?: 'ephemeral' | 'persistent';
+    operations?: BrowserProviderOperation[];
+    references?: BrowserReference[];
+    details?: BrowserDetails;
+    pairing?: BrowserPairingInfo;
+    /** Epoch ms when this browser window last gained focus; drives default target selection. */
+    lastFocusedAt?: number;
+    startedAt: string;
+    /** Epoch ms of the last record write; latest-wins tiebreak. */
+    updatedAt: number;
+}
+export declare function initBrowserRegistry(deps: {
+    log: (...args: any[]) => void;
+}): void;
+/** Retire a CDP record whose process remains alive but its instance socket no longer accepts connections. */
+export declare function retireUnreachableBrowserRecord(browserId: string, canConnect: (socketPath: string) => Promise<boolean>): Promise<boolean>;
+/**
+ * Publish (or refresh) this native-host's registry record. Called once the
+ * browser identity is known — from the extension handshake, or immediately with
+ * a synthetic identity in CDP daemon mode.
+ */
+export declare function registerBrowser(info: {
+    browserId: string;
+    socketPath: string;
+    browserName: string;
+    nativeHostVersion: string;
+    transport: 'extension' | 'cdp';
+    extensionVersion?: string;
+    /** Initial focus rank. Managed headless browsers use 0 so they do not steal the default target. */
+    lastFocusedAt?: number;
+    /** Keep a previous focus rank when this browser reconnects. */
+    preserveFocus?: boolean;
+}): boolean;
+/**
+ * Mark this browser as most-recently focused, so it becomes the default target.
+ * Focus can change in rapid bursts (fast window switching), so writes are
+ * throttled: the first change in an interval writes immediately, further changes
+ * schedule a single trailing write rather than one write each.
+ */
+export declare function touchFocus(): void;
+/** Remove our record on shutdown — but only if it is still ours. */
+export declare function unregisterBrowser(): void;
+/**
+ * Reap registry records left behind by native-hosts that exited without
+ * cleanup (crashes). Live records are kept; a dead record is kept until it is
+ * older than STALE_RECORD_TTL_MS so a quickly-reconnecting browser can still
+ * inherit its own last-focus time. Meant to run once at startup.
+ */
+export declare function pruneDeadBrowsers(): void;
+/** Live browser connections, ordered by the same focus rank used for default routing. */
+export declare function listRegisteredBrowsers(): BrowserRecord[];

package/dist/browser-socket-request.d.ts

@@ -0,0 +1,5 @@
+import { type ProviderHostContextData } from '@mearl/provider';
+export declare function requestBrowserSocket(socketPath: string, action: string, data: Record<string, any>, version: string, timeoutMs?: number, browserId?: string, host?: ProviderHostContextData, routing?: {
+    providerTarget?: string;
+    controlSource?: string;
+}): Promise<any>;

package/dist/builtin-browser-providers.d.ts

@@ -0,0 +1,8 @@
+import { type ProviderRuntime } from '@mearl/provider';
+import type { TransferableCookie } from './cdp-backend/cookie-transfer.js';
+export interface BuiltinProviderDependencies {
+    nativeHostScript: string;
+    exportCookies: (domains: string[]) => Promise<TransferableCookie[]>;
+    log: (...args: any[]) => void;
+}
+export declare function createBuiltinBrowserProviders(deps: BuiltinProviderDependencies): ProviderRuntime[];

package/dist/builtin-provider-options.d.ts

@@ -0,0 +1,11 @@
+import type { CookieCopyScope } from '@mearl/browser-core';
+/** Launch values understood by the built-in local Provider. */
+export interface BuiltinBrowserLaunchOptions {
+    name?: string;
+    headless?: boolean;
+    userAgentMode?: 'default' | 'desktop';
+    persistent?: boolean;
+    executablePath?: string;
+    url?: string;
+    copyCookieDomains?: string[] | string | CookieCopyScope;
+}

package/dist/capability-contracts.d.ts

@@ -0,0 +1,73 @@
+import type { MtopRequest, ParsedSseEvent, RumEvent, SendMtopRequestParams } from '@mearl/browser-core';
+export interface ResolvedMtopRequest {
+    api: string;
+    requestData: unknown;
+    dataStr: string;
+    version: string;
+    normalizedMethod: 'GET' | 'POST';
+    appKey: string;
+    gatewayUrl: URL;
+    customHeaders: Record<string, string>;
+    ttid?: string;
+    timeout: number;
+    isMopen: boolean;
+}
+export interface PreparedSignedMtopRequest extends ResolvedMtopRequest {
+    targetUrl: URL;
+    requestHeaders: Record<string, string>;
+    cookieHeader: string;
+    body?: string;
+}
+export interface MtopStreamCapture {
+    request: MtopRequest;
+    startTimeMs: number;
+    lastMessageTimeMs?: number;
+}
+export interface MtopStreamCaptureStart {
+    id: number;
+    api: string;
+    url?: string;
+    method: string;
+    requestHeaders?: Array<{
+        name: string;
+        value: string;
+    }>;
+    requestData?: unknown;
+    timestampMs?: number;
+    tabId?: number;
+    captureSequence: number;
+}
+export interface MtopStreamCaptureResponse {
+    status: number;
+    statusText: string;
+    responseHeaders: Array<{
+        name: string;
+        value: string;
+    }>;
+}
+export interface MtopCapability {
+    resolveRequest(data: SendMtopRequestParams): ResolvedMtopRequest;
+    prepareRequest(resolved: ResolvedMtopRequest, cookies: Map<string, string>, stream?: boolean): PreparedSignedMtopRequest;
+    parseResponse(text: string): unknown;
+    consumeResponse(response: Response, onReceive: (event: ParsedSseEvent) => void | Promise<void>): Promise<unknown>;
+    createCapture(data: MtopStreamCaptureStart): MtopStreamCapture;
+    updateCapture(capture: MtopStreamCapture, response: MtopStreamCaptureResponse): void;
+    appendCapture(capture: MtopStreamCapture, data: unknown, timestampMs?: number): boolean;
+    finishCapture(capture: MtopStreamCapture, options?: {
+        timestampMs?: number;
+        error?: string;
+    }): void;
+    gateways: Array<{
+        prod: string;
+        pre: string;
+    }>;
+}
+export interface TrackingCapability {
+    matches(url: string): boolean;
+    parse(url: string, postData?: string, options?: {
+        sequence?: number;
+        now?: number;
+    }): RumEvent[];
+}
+export declare function getMtopCapability(): MtopCapability;
+export declare function getTrackingCapability(): TrackingCapability | undefined;

package/dist/cdp-backend/action-registry.d.ts

@@ -0,0 +1,36 @@
+/**
+ * CDP action registry.
+ *
+ * Each handler sub-module registers its actions here. The registry replaces
+ * the giant switch/case in handleViaCdp with a data-driven lookup.
+ *
+ * Two session levels:
+ * - `browser`: handler receives CdpSession for tab and page management
+ * - `page`:    handler receives PageSession (for most page-level actions)
+ */
+import { type BrowserCommandAction, type ControlSource } from '@mearl/browser-core';
+import type { CdpSession, PageSession } from './cdp-session.js';
+export interface BrowserAction {
+    name: BrowserCommandAction;
+    session: 'browser';
+    handler: (session: CdpSession, data: any, controlSource: ControlSource) => Promise<any>;
+}
+export interface PageAction {
+    name: BrowserCommandAction;
+    session: 'page';
+    handler: (session: PageSession, data: any, controlSource: ControlSource) => Promise<any>;
+}
+export type CdpAction = BrowserAction | PageAction;
+/** Register one or more CDP actions. Called by each handler sub-module. */
+export declare function registerActions(actions: CdpAction[]): void;
+/** Look up a registered action by name. Returns undefined if not found. */
+export declare function getAction(name: string): CdpAction | undefined;
+/** Get all registered action names (useful for diagnostics). */
+export declare function getRegisteredActionNames(): string[];
+/**
+ * Dispatch an action by name.
+ *
+ * Resolves the appropriate session level and calls the handler.
+ * Throws if the action is unknown or CDP is not available.
+ */
+export declare function dispatchCdpAction(cdpSession: CdpSession, action: string, data: any, controlSource?: ControlSource): Promise<any>;

package/dist/cdp-backend/app-profile-handlers.d.ts

@@ -0,0 +1,62 @@
+/** CDP App environment and JSBridge injection. */
+import { type ResolvedAppProfile } from '@mearl/app-profiles';
+import { type AppProfileBinding, type AppProfileDefinition, type BrowserDevicePresetName, type InjectedAppProfileConfig, type ResolvedEmulationConfig, type SetAppProfileParams } from '@mearl/browser-core';
+import type { PageSession } from './cdp-session.js';
+declare const APP_PROFILE_RESTORE_VERSION = 1;
+interface CdpAppProfileRestoreOptions {
+    lockDefinition?: boolean;
+    os: 'ios' | 'android';
+    appVersion: string;
+    language?: SetAppProfileParams['language'];
+    deviceModel: string;
+    devicePreset?: BrowserDevicePresetName;
+    orientation?: 'portrait' | 'landscape';
+    bridgeConfig?: ResolveCdpAppProfileOptions['bridgeConfig'];
+}
+interface CdpAppProfileRestoreEmulation {
+    preset?: BrowserDevicePresetName;
+    width: number;
+    height: number;
+    deviceScaleFactor: number;
+    scale: number;
+    mobile: boolean;
+    userAgent: string;
+    orientation: 'portrait' | 'landscape';
+    touch: boolean;
+    deviceShell: boolean;
+    splitScreen?: boolean;
+}
+interface CdpAppProfileRestoreState {
+    version: typeof APP_PROFILE_RESTORE_VERSION;
+    profile: string;
+    binding: Omit<AppProfileBinding, 'options'>;
+    options: CdpAppProfileRestoreOptions;
+    emulation?: CdpAppProfileRestoreEmulation;
+    activeDocument: boolean;
+}
+export interface ResolvedCdpAppProfile {
+    profile: ResolvedAppProfile;
+    restoreState: Omit<CdpAppProfileRestoreState, 'activeDocument'>;
+}
+interface ResolveCdpAppProfileOptions extends Omit<SetAppProfileParams, 'enabled' | 'profile' | 'tabId' | 'reload'> {
+    devicePreset?: BrowserDevicePresetName;
+    orientation?: 'portrait' | 'landscape';
+}
+export declare function resolveCdpAppProfile(profile: string, options?: ResolveCdpAppProfileOptions, definition?: AppProfileDefinition, current?: InjectedAppProfileConfig): ResolvedCdpAppProfile;
+/** Reconnect daemon-owned CDP listeners for an App profile already installed in this target. */
+export declare function restoreCdpAppProfile(session: PageSession): Promise<boolean>;
+export declare function applyResolvedCdpAppProfile(session: PageSession, resolved: ResolvedCdpAppProfile): Promise<void>;
+/** Update future-document scripts without replacing the active runtime or its bridge listeners. */
+export declare function refreshCdpAppProfileForNavigation(session: PageSession, beforeApply?: () => Promise<void>): Promise<string | undefined>;
+export declare function updateCdpAppProfileDeviceEmulation(session: PageSession, emulation: ResolvedEmulationConfig | null, deviceShell?: boolean, splitScreen?: boolean): Promise<{
+    userAgent: string;
+    platform: string;
+} | undefined>;
+export declare function isCdpAppProfileActive(session: PageSession): boolean;
+export declare function waitForCdpAppProfileLoad(session: PageSession, timeoutMs?: number): Promise<void>;
+export declare function clearCdpAppProfile(session: PageSession, reload?: boolean): Promise<{
+    enabled: false;
+    reloaded: boolean;
+}>;
+export declare function cdpSetAppProfile(session: PageSession, data: SetAppProfileParams): Promise<any>;
+export {};

package/dist/cdp-backend/browser-handlers.d.ts

@@ -0,0 +1,6 @@
+/**
+ * CDP browser-level handlers: screenshots.
+ */
+import type { PageScreenshotParams } from '@mearl/browser-core';
+import type { PageSession } from './cdp-session.js';
+export declare function cdpPageScreenshot(session: PageSession, data: PageScreenshotParams): Promise<any>;

package/dist/cdp-backend/buffers.d.ts

@@ -0,0 +1,72 @@
+import { type MtopStreamCapture, type MtopStreamCaptureResponse, type MtopStreamCaptureStart } from '../capability-contracts.js';
+/**
+ * In-memory circular buffers for CDP network requests, console logs, and
+ * RUM/tracking events. A single CdpSession subscribes to CDP events and
+ * fills these buffers; callers read from them without CDP interaction.
+ */
+import { TextDecoder } from 'node:util';
+import type { MtopRequest, RumEvent, ConsoleLog, RequestBufferAccounting } from '@mearl/browser-core';
+import { type CaptureSequenceState, type SseEventParser } from '@mearl/browser-core';
+import type { CdpClient, CdpChildSession } from './client.js';
+interface PartialRequest extends MtopRequest {
+    id: number;
+    requestId: string;
+    timestamp: string;
+    timestampMs: number;
+    method: string;
+    url: string;
+    apiName: string;
+    headers: Array<{
+        name: string;
+        value: string;
+    }>;
+    postData: any;
+    queryString: Array<{
+        name: string;
+        value: string;
+    }>;
+    status: number;
+    statusText: string;
+    responseHeaders: Array<{
+        name: string;
+        value: string;
+    }>;
+    responseBody: any;
+    isProxy: boolean;
+    proxyRequestUrl: string | null;
+    proxyData: any;
+    startTs?: number;
+}
+interface CdpSseStream {
+    parser: SseEventParser;
+    decoder: TextDecoder;
+    mode: 'eventsource' | 'resource' | 'fallback';
+    lastMessageTimeMs?: number;
+}
+export type CdpMtopStreamCapture = MtopStreamCapture;
+export type CdpMtopStreamStart = Omit<MtopStreamCaptureStart, 'id' | 'tabId' | 'captureSequence'>;
+export type CdpMtopStreamResponse = MtopStreamCaptureResponse;
+export interface CdpBuffers {
+    requests: MtopRequest[];
+    logs: ConsoleLog[];
+    events: RumEvent[];
+    pending: Map<string, PartialRequest>;
+    sseStreams: Map<string, CdpSseStream>;
+    requestCounter: number;
+    requestBufferAccounting: RequestBufferAccounting;
+    capture: CaptureSequenceState & {
+        droppedRequestsThroughSequence: number;
+        droppedLogsThroughSequence: number;
+        droppedEventsThroughSequence: number;
+    };
+}
+export declare function createBuffers(tabId?: number): CdpBuffers;
+export declare function recordCdpMtopStreamStart(buffers: CdpBuffers, data: CdpMtopStreamStart): CdpMtopStreamCapture;
+export declare function recordCdpMtopStreamResponse(buffers: CdpBuffers, capture: CdpMtopStreamCapture, response: CdpMtopStreamResponse): void;
+export declare function recordCdpMtopStreamChunk(buffers: CdpBuffers, capture: CdpMtopStreamCapture, data: unknown, timestampMs?: number): void;
+export declare function recordCdpMtopStreamEnd(buffers: CdpBuffers, capture: CdpMtopStreamCapture, options?: {
+    timestampMs?: number;
+    error?: string;
+}): void;
+export declare function setupBufferListeners(client: CdpClient | CdpChildSession, buffers: CdpBuffers): Promise<void>;
+export {};