@mearl/native-host 2.0.0

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

@@ -0,0 +1,66 @@
+/**
+ * Shared utilities for CDP backend handlers.
+ *
+ * Contains: HTTP helper (nodeFetch), cookie utilities, page-load waiters,
+ * viewport helpers, and serialized function sources for page injection.
+ */
+import type { PageSession } from './cdp-session.js';
+import { type CdpTarget } from './discover.js';
+export declare const TYPE_INTO_ELEMENT_SRC: string;
+export declare const CLICK_ELEMENT_VIA_JS_SRC: string;
+export declare const GET_CLICK_COORDS_FROM_NODE_SRC: string;
+export interface CdpViewportMetrics {
+    cssLayoutViewport?: {
+        clientWidth?: number;
+        clientHeight?: number;
+    };
+    cssVisualViewport?: {
+        clientWidth?: number;
+        clientHeight?: number;
+        scale?: number;
+    };
+    layoutViewport?: {
+        clientWidth?: number;
+        clientHeight?: number;
+    };
+    visualViewport?: {
+        clientWidth?: number;
+        clientHeight?: number;
+        scale?: number;
+    };
+}
+export declare function nodeFetch(urlStr: string, options?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    timeoutMs?: number;
+}): Promise<{
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    body: string;
+}>;
+export declare function getCookiesForUrl(session: PageSession, targetUrl: string): Promise<Map<string, string>>;
+export declare function decodeTracknick(raw: string): string;
+export declare function buildMultipartFormBody(fields: Record<string, string>): {
+    contentType: string;
+    body: string;
+};
+export declare function waitForPageLoad(session: PageSession, timeoutMs: number): Promise<void>;
+export declare function waitForTargetLoad(session: {
+    port: number;
+}, targetId: string, timeoutMs: number): Promise<CdpTarget | null>;
+export declare function getPageViewportSize(session: PageSession): Promise<{
+    width: number;
+    height: number;
+} | null>;
+export declare function getCdpInputViewportSize(session: PageSession): Promise<{
+    width: number;
+    height: number;
+} | null>;
+export declare function toCdpInputPoint(session: PageSession, x: number, y: number): Promise<{
+    x: number;
+    y: number;
+}>;
+export declare function dispatchCdpClick(session: PageSession, x: number, y: number): Promise<void>;
+export declare function resolveBackendNodeObjectId(session: PageSession, backendNodeId: number): Promise<string>;

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

@@ -0,0 +1,47 @@
+/**
+ * Minimal WebSocket-based CDP client for native-host (no external deps).
+ * Uses node:http upgrade event + raw frame handling via node:net Socket.
+ */
+type EventCallback = (params: any) => void;
+/**
+ * A virtual client that routes CDP messages through a specific sessionId
+ * on a shared browser-level WebSocket connection.
+ *
+ * This is used for page-level commands when Chrome does not allow direct
+ * connections to /devtools/page/... (e.g., when enabled via chrome://inspect).
+ */
+export declare class CdpChildSession {
+    private readonly parent;
+    readonly sessionId: string;
+    constructor(parent: CdpClient, sessionId: string);
+    sendCommand(method: string, params?: Record<string, any>, timeoutMs?: number): Promise<any>;
+    on(method: string, callback: EventCallback): () => void;
+    get closed(): boolean;
+    close(): void;
+}
+export declare class CdpClient {
+    private socket;
+    private buffer;
+    private nextId;
+    private pending;
+    private eventHandlers;
+    /** sessionId → method → callbacks (for multiplexed page sessions) */
+    private sessionEventHandlers;
+    private _closed;
+    private constructor();
+    /** Create a child session client that routes through this connection via sessionId. */
+    createChildSession(sessionId: string): CdpChildSession;
+    /** Send a command within a specific CDP session (multiplexed on this connection). */
+    sendCommandInSession(sessionId: string, method: string, params?: Record<string, any>, timeoutMs?: number): Promise<any>;
+    /** Subscribe to events from a specific CDP session. */
+    onSession(sessionId: string, method: string, callback: EventCallback): () => void;
+    static connect(wsUrl: string): Promise<CdpClient>;
+    private consumeFrames;
+    private handleMessage;
+    sendCommand(method: string, params?: Record<string, any>, timeoutMs?: number): Promise<any>;
+    on(method: string, callback: EventCallback): () => void;
+    private sendText;
+    close(): void;
+    get closed(): boolean;
+}
+export {};

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

@@ -0,0 +1,19 @@
+/**
+ * CDP composite action handlers.
+ *
+ * Provides `run_actions` — sequential batch execution of multiple actions
+ * within a single request, sharing the same CDP session — and the observed
+ * page-action wrapper that gives page interaction actions their default
+ * built-in observation.
+ */
+import type { CdpSession } from './cdp-session.js';
+import { type PageActAction } from '@mearl/browser-core';
+export declare function cdpRunActions(session: CdpSession, data: any): Promise<any>;
+/**
+ * Runs a page interaction action with built-in observation: executes the raw
+ * handler inside `runPageAct` and reports resulting page changes / navigation
+ * in the same round trip. Callers opt out with `observe: false`, which
+ * dispatches the raw handler directly. `run_actions` steps never go through
+ * this wrapper — they use dispatchCdpAction and stay lightweight.
+ */
+export declare function cdpObservedPageAction(session: CdpSession, action: PageActAction, data: any): Promise<any>;

package/dist/cdp-backend/controlled-indicator.d.ts

@@ -0,0 +1,17 @@
+/**
+ * CDP 模式的受控页面视觉标识。
+ *
+ * 与扩展模式的 favicon 替换保持一致：agent 操作过的页面把 favicon 换成 Mearl
+ * 图标。CDP 模式拿不到扩展资源，图标以 data URL 内联在注入脚本里，不依赖任何
+ * 网络请求。
+ *
+ * 注入通过 Page.addScriptToEvaluateOnNewDocument + runImmediately 完成：每个
+ * PageSession 只注册一次，注册的脚本在 session 存续期内跨导航自动生效；
+ * session 断开重建后由下一次动作重新注册。
+ */
+import type { PageSession } from './cdp-session.js';
+/**
+ * 确保受控标识已注入到该 page session。幂等且 best-effort：
+ * 失败时撤销标记，下一次动作重试；任何异常都不阻断 agent 动作本身。
+ */
+export declare function ensureControlledIndicator(session: PageSession): Promise<void>;

package/dist/cdp-backend/cookie-transfer.d.ts

@@ -0,0 +1,25 @@
+/** Cookie export/import helpers for copying selected domains between CDP browsers. */
+import type { CdpSession } from './cdp-session.js';
+export interface TransferableCookie {
+    name: string;
+    value: string;
+    domain: string;
+    path: string;
+    secure?: boolean;
+    httpOnly?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+    expires?: number;
+    priority?: 'Low' | 'Medium' | 'High';
+    sameParty?: boolean;
+    sourceScheme?: 'Unset' | 'NonSecure' | 'Secure';
+    sourcePort?: number;
+    partitionKey?: {
+        topLevelSite: string;
+        hasCrossSiteAncestor?: boolean;
+    };
+}
+export declare function normalizeCookieDomain(input: string): string;
+export declare function normalizeCookieDomains(inputs: unknown): string[];
+export declare function cookieMatchesDomain(cookieDomain: string, requestedDomain: string): boolean;
+export declare function cdpExportCookies(session: CdpSession, domains: string[]): Promise<TransferableCookie[]>;
+export declare function cdpImportCookies(session: CdpSession, cookies: TransferableCookie[]): Promise<number>;

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

@@ -0,0 +1,28 @@
+/**
+ * CDP target discovery.
+ *
+ * Strategy (in order):
+ * 1. Read Chrome's DevToolsActivePort file — written by Chrome when remote
+ *    debugging is enabled (including via chrome://inspect/#remote-debugging).
+ *    Contains the actual port and browser WebSocket path.
+ * 2. Fall back to HTTP /json REST API on the given port (requires Chrome
+ *    launched with --remote-debugging-port).
+ */
+export interface CdpTarget {
+    id: string;
+    title: string;
+    type: string;
+    url: string;
+    webSocketDebuggerUrl: string;
+    faviconUrl?: string;
+}
+/**
+ * Read Chrome's DevToolsActivePort file.
+ * Returns { port, browserWsPath } or null if unavailable.
+ */
+export declare function readDevToolsActivePort(userDataDir?: string): {
+    port: number;
+    browserWsPath: string;
+} | null;
+export declare function discoverTargets(port?: number): Promise<CdpTarget[]>;
+export declare function isCdpAvailable(port?: number, userDataDir?: string): Promise<boolean>;

package/dist/cdp-backend/domain-manager.d.ts

@@ -0,0 +1,4 @@
+import type { CdpChildSession, CdpClient } from './client.js';
+type DomainClient = CdpClient | CdpChildSession;
+export declare function ensureCdpDomain(client: DomainClient, domain: string, params?: Record<string, unknown>): Promise<void>;
+export {};

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

@@ -0,0 +1,29 @@
+/**
+ * CDP backend action handlers — re-export hub.
+ *
+ * All handler implementations live in dedicated sub-modules.
+ * Importing this file triggers side-effect registrations in the action registry.
+ */
+import './request-handlers.js';
+import './mock-handlers.js';
+import './http-handlers.js';
+import './browser-handlers.js';
+import './tdbank-handlers.js';
+import './tab-handlers.js';
+import './interaction-handlers.js';
+import './timezone-handlers.js';
+import './snapshot-handlers.js';
+import './recording-handlers.js';
+import './composite-handlers.js';
+export { dispatchCdpAction, getRegisteredActionNames } from './action-registry.js';
+export { cdpGetRequests, cdpGetLogs, cdpGetEvents } from './request-handlers.js';
+export { cdpSetMock, cdpGetMocks } from './mock-handlers.js';
+export { cdpSendRequest, cdpSendMtopRequest, cdpGetApiSchema } from './http-handlers.js';
+export { cdpPageScreenshot, cdpPageSelectedElement, cdpGetUserInfo } from './browser-handlers.js';
+export { cdpTdbankAccount } from './tdbank-handlers.js';
+export { cdpTabOpen, cdpTabClose, cdpTabList } from './tab-handlers.js';
+export { cdpPageClick, cdpPageType, cdpPageScroll, cdpPageEval, cdpPagePress, cdpPageWait, cdpPageNavigate, cdpPageUpload, cdpSetDeviceEmulation, } from './interaction-handlers.js';
+export { cdpPageSnapshot, cdpPageFrames } from './snapshot-handlers.js';
+export { cdpRecordStart, cdpRecordStop } from './recording-handlers.js';
+export { cdpRunActions, cdpObservedPageAction } from './composite-handlers.js';
+export { cdpSetTimezone } from './timezone-handlers.js';

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

@@ -0,0 +1,7 @@
+/**
+ * CDP HTTP proxy / MTOP request / API schema handlers.
+ */
+import type { PageSession } from './cdp-session.js';
+export declare function cdpSendRequest(session: PageSession, data: any): Promise<any>;
+export declare function cdpSendMtopRequest(session: PageSession, data: any): Promise<any>;
+export declare function cdpGetApiSchema(session: PageSession, data: any): Promise<any>;

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

@@ -0,0 +1,16 @@
+/**
+ * CDP page interaction handlers.
+ *
+ * Covers: click, type, scroll, eval, press, wait, navigate, upload, device emulation.
+ */
+import type { PageSession } from './cdp-session.js';
+export declare function cdpPageClick(session: PageSession, data: any): Promise<any>;
+export declare function cdpPageType(session: PageSession, data: any): Promise<any>;
+export declare function cdpPageScroll(session: PageSession, data: any): Promise<any>;
+export declare function cdpPageEval(session: PageSession, data: any): Promise<any>;
+export declare function cdpPagePress(session: PageSession, data: any): Promise<any>;
+export declare function cdpPageWait(session: PageSession, data: any): Promise<any>;
+export declare function cdpPageNavigate(session: PageSession, data: any): Promise<any>;
+export declare function cdpPageUpload(session: PageSession, data: any): Promise<any>;
+export declare function cdpSetDeviceEmulation(session: PageSession, data: any): Promise<any>;
+export declare function cdpPageHover(session: PageSession, data: any): Promise<any>;

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

@@ -0,0 +1,6 @@
+/**
+ * CDP mock interception handlers.
+ */
+import type { PageSession } from './cdp-session.js';
+export declare function cdpSetMock(session: PageSession, data: any): Promise<any>;
+export declare function cdpGetMocks(_session: PageSession, _data: any): any;

package/dist/cdp-backend/navigation-observer.d.ts

@@ -0,0 +1,7 @@
+import { type PageActNavigationObserver } from '@mearl/browser-core';
+import type { PageSession } from './cdp-session.js';
+export declare function startCdpNavigationObserver(session: PageSession, urlBefore: string, options?: {
+    trackNetwork?: boolean;
+    networkIdleMs?: number;
+    contentReadyAfterMs?: number;
+}): Promise<PageActNavigationObserver>;

package/dist/cdp-backend/page-observer.d.ts

@@ -0,0 +1,5 @@
+import { type PageChangeSet, type PageObservationCheckpoint, type PageObservationWaitOptions } from '@mearl/browser-core';
+import type { PageSession } from './cdp-session.js';
+export declare function startPageObservation(session: PageSession): Promise<PageObservationCheckpoint>;
+export declare function finishPageObservation(session: PageSession, checkpoint: PageObservationCheckpoint, options?: PageObservationWaitOptions): Promise<PageChangeSet>;
+export declare function disposePageObservation(session: PageSession): Promise<void>;

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

@@ -0,0 +1,9 @@
+/**
+ * CDP recording session handlers.
+ *
+ * Manages browser-side action recording via Runtime.addBinding +
+ * Page.addScriptToEvaluateOnNewDocument.
+ */
+import type { PageSession } from './cdp-session.js';
+export declare function cdpRecordStart(session: PageSession, _data: any): Promise<any>;
+export declare function cdpRecordStop(session: PageSession, _data: any): Promise<any>;

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

@@ -0,0 +1,7 @@
+/**
+ * CDP request/log/event buffer query handlers.
+ */
+import type { PageSession } from './cdp-session.js';
+export declare function cdpGetRequests(session: PageSession, data: any): Promise<any>;
+export declare function cdpGetLogs(session: PageSession, data: any): Promise<any>;
+export declare function cdpGetEvents(session: PageSession, data: any): Promise<any>;

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

@@ -0,0 +1,6 @@
+/**
+ * CDP accessibility tree snapshot and frame handlers.
+ */
+import type { PageSession } from './cdp-session.js';
+export declare function cdpPageSnapshot(session: PageSession, data: any): Promise<any>;
+export declare function cdpPageFrames(session: PageSession, _data: any): Promise<any>;

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

@@ -0,0 +1,7 @@
+/**
+ * CDP tab management handlers.
+ */
+import type { CdpSession } from './cdp-session.js';
+export declare function cdpTabOpen(session: CdpSession, data: any): Promise<any>;
+export declare function cdpTabClose(session: CdpSession, data: any): Promise<any>;
+export declare function cdpTabList(session: CdpSession, _data: any): Promise<any>;

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

@@ -0,0 +1,13 @@
+/**
+ * CDP TDBank account handlers.
+ *
+ * Manages TDBank account listing, switching, borrowing via CDP cookie-based auth.
+ */
+import type { CdpSession } from './cdp-session.js';
+/** Prepare a TDBank SSO ticket without changing the controller browser account. */
+export declare function cdpPrepareTdbankSso(cdpSession: CdpSession, data: any): Promise<any>;
+/** Consume a TDBank SSO ticket inside an isolated managed browser. */
+export declare function cdpConsumeTdbankSso(cdpSession: CdpSession, ssoUrl: string, expectedLoginId?: string): Promise<{
+    nickname: string;
+}>;
+export declare function cdpTdbankAccount(cdpSession: CdpSession, data: any): Promise<any>;

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

@@ -0,0 +1,3 @@
+/** CDP timezone override handler. */
+import type { PageSession } from './cdp-session.js';
+export declare function cdpSetTimezone(session: PageSession, data: any): Promise<any>;

package/dist/cloud-connector.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Cloud connector process management — start/stop/list cloud-connector
+ * child processes that bridge the local native-host to remote cloud servers.
+ *
+ * Lifecycle design
+ * ----------------
+ * cloud-connector processes are spawned `detached` and intentionally OUTLIVE
+ * the native-host that started them. The native-host is an ephemeral broker:
+ * Chrome kills it whenever the extension reloads / updates (stdin EOF). If a
+ * connector were a normal child it would die with that broker, tearing down the
+ * cloud bridge on every extension reload.
+ *
+ * Shared registry & ownership
+ * ---------------------------
+ * Connectors are also self-manageable from the terminal (`cloud-connector start
+ * <url>`), so the host-managed and self-managed modes must not fight over the
+ * same connector. They interoperate through a single shared registry under
+ * ~/.mearl/connectors/ (one JSON record per serverUrl), with paths
+ * derived via @mearl/daemon-core so both sides agree on locations.
+ *
+ * The CONNECTOR PROCESS is the sole writer of its own record (it writes on
+ * connect, removes on graceful exit). This native-host only READS the registry
+ * to adopt/list connectors, and best-effort removes a record when it stops or
+ * reaps one. A freshly started native-host reads the registry, verifies the
+ * recorded pids are still alive, and ADOPTS them instead of spawning duplicates.
+ * Starting a connector is therefore idempotent: if a healthy one already exists
+ * for the serverUrl (started by us, a previous host, or the daemon CLI) we reuse
+ * it. Connectors die only when explicitly stopped, when they exit on their own,
+ * or when the machine reboots — never merely because the broker restarted.
+ */
+export interface CloudConnectorListResult {
+    connectors: Array<{
+        serverUrl: string;
+        pid: number;
+    }>;
+}
+/**
+ * Initialise module-level dependencies. Must be called before any other export.
+ */
+export declare function initCloudConnector(deps: {
+    log: (...args: any[]) => void;
+    isDaemonMode: boolean;
+    sendToExtension: (message: Record<string, any>) => void;
+    version: string;
+}): void;
+export declare function startCloudConnector(serverUrl: string): Promise<{
+    success: boolean;
+    pid?: number;
+    reused?: boolean;
+    error?: string;
+}>;
+export declare function stopCloudConnector(serverUrl: string): {
+    success: boolean;
+    error?: string;
+};
+export declare function listCloudConnectors(): CloudConnectorListResult;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};