@mearl/client 2.5.1 → 2.6.0

package/dist/unified.js

@@ -0,0 +1,562 @@
+import WebSocket from 'ws';
+import { DEFAULT_CONNECT_TIMEOUT, DEFAULT_HEARTBEAT_INTERVAL, DEFAULT_REQUEST_TIMEOUT, MAX_BUFFER_SIZE, isHeartbeatMessage, resolveCloudConnectorSelector, } from '@mearl/cloud-types';
+import { resolveActionTimeoutSec } from './actionTimeouts.js';
+import { invoke as invokeLocalBrowser } from './socket.js';
+import { loadCloudServerConfig, loadLocalConnectorId } from './unifiedConfig.js';
+const RESPONSE_GRACE_MS = 1_000;
+const GLOBAL_BROWSER_PREFIX = 'mearl:';
+function encodeBrowserTarget(target) {
+    const browser = encodeURIComponent(target.browser);
+    return target.connector
+        ? `${GLOBAL_BROWSER_PREFIX}remote:${encodeURIComponent(target.connector)}:${browser}`
+        : `${GLOBAL_BROWSER_PREFIX}local:${browser}`;
+}
+function omitTransientBrowserSecrets(browser) {
+    const safeBrowser = { ...browser };
+    delete safeBrowser.agentbayAccessUrl;
+    delete safeBrowser.accessUrl;
+    return safeBrowser;
+}
+export function decodeBrowserTarget(selector) {
+    if (!selector?.startsWith(GLOBAL_BROWSER_PREFIX))
+        return undefined;
+    try {
+        const parts = selector.slice(GLOBAL_BROWSER_PREFIX.length).split(':');
+        if (parts[0] === 'local' && parts.length === 2) {
+            const browser = decodeURIComponent(parts[1]);
+            return browser ? { browser } : undefined;
+        }
+        if (parts[0] === 'remote' && parts.length === 3) {
+            const connector = decodeURIComponent(parts[1]);
+            const browser = decodeURIComponent(parts[2]);
+            return connector && browser ? { connector, browser } : undefined;
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+function decorateBrowser(browser, source) {
+    const safeBrowser = omitTransientBrowserSecrets(browser);
+    const originalBrowserId = String(browser.browserId);
+    const originalName = String(browser.name);
+    return {
+        ...safeBrowser,
+        browserId: encodeBrowserTarget({
+            browser: originalBrowserId,
+            ...(source.connectorId ? { connector: source.connectorId } : {}),
+        }),
+        name: source.kind === 'local'
+            ? `[this machine] ${originalName}`
+            : `[${source.connectorName}] ${originalName}`,
+        originalBrowserId,
+        originalName,
+        status: typeof browser.status === 'string' ? browser.status : 'disconnected',
+        source,
+    };
+}
+function browserMatches(browser, selector) {
+    const normalized = selector.trim().toLowerCase();
+    return (browser.browserId.toLowerCase() === normalized ||
+        browser.originalBrowserId?.toLowerCase() === normalized ||
+        browser.name.toLowerCase() === normalized ||
+        browser.originalName?.toLowerCase() === normalized);
+}
+function findBrowsers(browsers, selector, connectedOnly = true) {
+    const candidates = connectedOnly
+        ? browsers.filter(browser => browser.status === 'connected')
+        : browsers;
+    const exact = candidates.filter(browser => browserMatches(browser, selector));
+    if (exact.length > 0)
+        return exact;
+    const normalized = selector.trim().toLowerCase();
+    return candidates.filter(browser => browser.browserId.toLowerCase().includes(normalized) ||
+        browser.originalBrowserId?.toLowerCase().includes(normalized) ||
+        browser.name.toLowerCase().includes(normalized) ||
+        browser.originalName?.toLowerCase().includes(normalized));
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export class UnifiedClient {
+    options;
+    defaultBrowser;
+    defaultConnector;
+    ws = null;
+    connectPromise = null;
+    messageBuffer = '';
+    pendingRequests = new Map();
+    heartbeatTimer = null;
+    closing = false;
+    constructor(options = {}) {
+        this.options = {
+            ...(options.serverUrl ? { serverUrl: options.serverUrl } : {}),
+            connectTimeoutSec: options.connectTimeoutSec ?? DEFAULT_CONNECT_TIMEOUT,
+            requestTimeoutSec: options.requestTimeoutSec ?? DEFAULT_REQUEST_TIMEOUT,
+            heartbeatInterval: options.heartbeatInterval ?? DEFAULT_HEARTBEAT_INTERVAL,
+        };
+        this.defaultBrowser =
+            options.defaultBrowser ?? (process.env.MEARL_BROWSER?.trim() || undefined);
+        this.defaultConnector = options.defaultConnector;
+    }
+    disconnect() {
+        this.closing = true;
+        if (this.heartbeatTimer)
+            clearInterval(this.heartbeatTimer);
+        this.heartbeatTimer = null;
+        this.rejectAllPending(new Error('Connection closed by user'));
+        this.ws?.close();
+        this.ws = null;
+    }
+    async invoke(action, data = {}, options = {}) {
+        const timeoutSec = options.timeoutSec ?? resolveActionTimeoutSec(action, data, this.options.requestTimeoutSec);
+        if (action === 'connector_list')
+            return this.listConnectors(timeoutSec);
+        if (action === 'browser_list') {
+            if (options.local || options.transport === 'cdp') {
+                return this.listLocalBrowsers(timeoutSec, options.transport);
+            }
+            const connector = options.connector ?? this.defaultConnector;
+            return connector
+                ? this.listConnectorBrowsers(connector, timeoutSec)
+                : this.listAllBrowsers(timeoutSec);
+        }
+        if (action === 'browser_select_browser') {
+            return this.selectDefaultBrowser(data, options, timeoutSec);
+        }
+        if (options.local || options.transport === 'cdp') {
+            return this.invokeExplicitLocal(action, data, options, timeoutSec);
+        }
+        const optionTarget = decodeBrowserTarget(options.browser);
+        const defaultTarget = options.browser ? undefined : decodeBrowserTarget(this.defaultBrowser);
+        const closeTarget = action === 'browser_close' && typeof data.browser === 'string'
+            ? decodeBrowserTarget(data.browser)
+            : undefined;
+        const target = optionTarget ?? closeTarget ?? defaultTarget;
+        const connector = target?.connector ?? options.connector ?? this.defaultConnector;
+        const browser = optionTarget?.browser ??
+            defaultTarget?.browser ??
+            (options.browser && !optionTarget ? options.browser : undefined) ??
+            (this.defaultBrowser && !defaultTarget ? this.defaultBrowser : undefined);
+        const requestData = closeTarget ? { ...data, browser: closeTarget.browser } : data;
+        if (target && !target.connector) {
+            if (options.connector) {
+                throw new Error('A local browser cannot be used together with --connector.');
+            }
+            return this.invokeLocal(action, requestData, timeoutSec, target.browser);
+        }
+        if (connector) {
+            const selected = target?.connector && !options.connector && !this.defaultConnector
+                ? { connectorId: target.connector, name: target.connector }
+                : await this.resolveConnector(connector, timeoutSec);
+            if (target?.connector && selected.connectorId !== target.connector) {
+                throw new Error('The selected browser belongs to a different cloud connector.');
+            }
+            return this.invokeRemote(action, requestData, timeoutSec, browser, selected);
+        }
+        if (!this.options.serverUrl) {
+            return this.invokeLocal(action, requestData, timeoutSec, options.browser ?? this.defaultBrowser);
+        }
+        const selector = options.browser ??
+            this.defaultBrowser ??
+            (action === 'browser_close' && typeof data.browser === 'string' ? data.browser : undefined);
+        const resolved = await this.resolveUnifiedBrowser(selector, timeoutSec, action === 'browser_close');
+        if (resolved) {
+            if (action === 'browser_close') {
+                const nextOptions = { ...options };
+                delete nextOptions.browser;
+                return this.invoke(action, { ...data, browser: resolved }, nextOptions);
+            }
+            return this.invoke(action, data, { ...options, browser: resolved });
+        }
+        if (action === 'browser_launch') {
+            return this.invokeLaunchWithoutControlBrowser(data, timeoutSec);
+        }
+        throw new Error('No connected browser is available. Run `mearl browser_list` to inspect all sources.');
+    }
+    async invokeExplicitLocal(action, data, options, timeoutSec) {
+        const optionTarget = decodeBrowserTarget(options.browser);
+        const defaultTarget = options.browser ? undefined : decodeBrowserTarget(this.defaultBrowser);
+        const closeTarget = action === 'browser_close' && typeof data.browser === 'string'
+            ? decodeBrowserTarget(data.browser)
+            : undefined;
+        if (optionTarget?.connector || defaultTarget?.connector || closeTarget?.connector) {
+            throw new Error('A remote browser cannot be used together with --local or --cdp.');
+        }
+        const browser = optionTarget?.browser ?? defaultTarget?.browser ?? options.browser ?? this.defaultBrowser;
+        const requestData = closeTarget ? { ...data, browser: closeTarget.browser } : data;
+        return this.invokeLocal(action, requestData, timeoutSec, browser, options.transport);
+    }
+    async invokeLaunchWithoutControlBrowser(data, timeoutSec) {
+        const local = await this.tryLocalBrowserList(timeoutSec);
+        const discoveredConnectors = await this.listConnectors(timeoutSec).then(result => result.connectors);
+        const localAvailable = local !== null;
+        const localConnectorId = localAvailable ? loadLocalConnectorId() : null;
+        const connectors = localConnectorId
+            ? discoveredConnectors.filter(connector => connector.connectorId !== localConnectorId)
+            : discoveredConnectors;
+        if (localAvailable && connectors.length === 0) {
+            return this.invokeLocal('browser_launch', data, timeoutSec, undefined);
+        }
+        if (!localAvailable && connectors.length === 1) {
+            return this.invokeRemote('browser_launch', data, timeoutSec, undefined, connectors[0]);
+        }
+        if (!localAvailable && connectors.length === 0) {
+            throw new Error('No browser host is available. Install @mearl/native-host locally or connect a cloud connector.');
+        }
+        throw new Error('The browser host for browser_launch is ambiguous. Pass --local, --connector <id|name>, or --browser <global-id>.');
+    }
+    async selectDefaultBrowser(data, options, timeoutSec) {
+        const selector = typeof data.browser === 'string' ? data.browser.trim() : '';
+        if (!selector) {
+            this.defaultBrowser = undefined;
+            this.defaultConnector = undefined;
+            return { selected: null, note: 'Cleared the process-wide default browser.' };
+        }
+        const listing = (await this.invoke('browser_list', {}, {
+            timeoutSec,
+            ...(options.local ? { local: true } : {}),
+            ...(options.transport ? { transport: options.transport } : {}),
+            ...(options.connector ? { connector: options.connector } : {}),
+        }));
+        const matches = findBrowsers(listing.browsers, selector);
+        if (matches.length > 1) {
+            throw new Error(`Browser selector "${selector}" is ambiguous. Use an exact global browserId.`);
+        }
+        const match = matches[0];
+        if (!match)
+            throw new Error(`No connected browser matches "${selector}".`);
+        this.defaultBrowser = match.browserId;
+        this.defaultConnector = undefined;
+        return { selected: { browserId: match.browserId, name: match.name } };
+    }
+    async resolveUnifiedBrowser(selector, timeoutSec, includeDisconnected) {
+        const listing = await this.listAllBrowsers(timeoutSec);
+        if (selector) {
+            const matches = findBrowsers(listing.browsers, selector, !includeDisconnected);
+            if (matches.length > 1) {
+                throw new Error(`Browser selector "${selector}" is ambiguous. Use an exact global browserId from browser_list.`);
+            }
+            if (matches.length === 0) {
+                throw new Error(`No browser matches "${selector}". Run \`mearl browser_list\`.`);
+            }
+            return matches[0].browserId;
+        }
+        if (listing.defaultBrowserId)
+            return listing.defaultBrowserId;
+        const connected = listing.browsers.filter(browser => browser.status === 'connected');
+        if (connected.length === 1)
+            return connected[0].browserId;
+        if (connected.length > 1) {
+            throw new Error('Multiple browsers are connected and there is no unique default. Pass --browser <global-id>.');
+        }
+        return undefined;
+    }
+    async listConnectors(timeoutSec = this.options.requestTimeoutSec) {
+        if (!this.options.serverUrl)
+            return { count: 0, connectors: [] };
+        return this.requestRemote('connector_list', {}, timeoutSec, undefined, undefined);
+    }
+    async resolveConnector(selector, timeoutSec) {
+        const connectors = (await this.listConnectors(timeoutSec)).connectors;
+        const selection = resolveCloudConnectorSelector(connectors, selector);
+        if (selection.status === 'ambiguous') {
+            throw new Error(`Cloud connector selector "${selector}" is ambiguous. Use an exact connectorId.`);
+        }
+        if (selection.status !== 'matched') {
+            throw new Error(`No cloud connector matches "${selector}".`);
+        }
+        return selection.connector;
+    }
+    async listLocalBrowsers(timeoutSec, transport) {
+        const result = await invokeLocalBrowser('browser_list', {}, { timeoutSec, ...(transport ? { transport } : {}), controlSource: 'local' });
+        return this.applyConfiguredDefault(this.decorateListing(result, { kind: 'local' }));
+    }
+    async tryLocalBrowserList(timeoutSec) {
+        try {
+            return await invokeLocalBrowser('browser_list', {}, { timeoutSec, controlSource: 'local' });
+        }
+        catch {
+            return null;
+        }
+    }
+    decorateListing(result, source) {
+        const rawBrowsers = Array.isArray(result?.browsers)
+            ? result.browsers
+            : [];
+        const browsers = rawBrowsers.map(browser => decorateBrowser(browser, source));
+        return {
+            count: browsers.length,
+            connectedCount: browsers.filter(browser => browser.status === 'connected').length,
+            defaultBrowserId: typeof result?.defaultBrowserId === 'string'
+                ? encodeBrowserTarget({
+                    browser: result.defaultBrowserId,
+                    ...(source.connectorId ? { connector: source.connectorId } : {}),
+                })
+                : null,
+            browsers,
+        };
+    }
+    applyConfiguredDefault(listing) {
+        if (!this.defaultBrowser)
+            return listing;
+        const matches = findBrowsers(listing.browsers, this.defaultBrowser);
+        return {
+            ...listing,
+            defaultBrowserId: matches.length === 1 ? matches[0].browserId : null,
+        };
+    }
+    async listConnectorBrowsers(selector, timeoutSec) {
+        const connector = await this.resolveConnector(selector, timeoutSec);
+        const result = await this.requestRemote('browser_list', {}, timeoutSec, undefined, connector.connectorId);
+        return this.applyConfiguredDefault(this.decorateListing(result, {
+            kind: 'remote',
+            connectorId: connector.connectorId,
+            connectorName: connector.name,
+        }));
+    }
+    async listAllBrowsers(timeoutSec) {
+        const warnings = [];
+        const localPromise = this.tryLocalBrowserList(timeoutSec);
+        let connectors = [];
+        if (this.options.serverUrl) {
+            try {
+                connectors = (await this.listConnectors(timeoutSec)).connectors;
+            }
+            catch (error) {
+                warnings.push(`cloud-server: ${errorMessage(error)}`);
+            }
+        }
+        const localResult = await localPromise;
+        if (!localResult)
+            warnings.push('this machine: local browser runtime is unavailable');
+        const localConnectorId = localResult ? loadLocalConnectorId() : null;
+        const remoteConnectors = localConnectorId
+            ? connectors.filter(connector => connector.connectorId !== localConnectorId)
+            : connectors;
+        const settled = await Promise.allSettled(remoteConnectors.map(async (connector) => ({
+            connector,
+            listing: await this.requestRemote('browser_list', {}, timeoutSec, undefined, connector.connectorId),
+        })));
+        const remoteListings = [];
+        for (let index = 0; index < settled.length; index += 1) {
+            const result = settled[index];
+            const connector = remoteConnectors[index];
+            if (result.status === 'fulfilled')
+                remoteListings.push(result.value);
+            else
+                warnings.push(`${connector.name}: ${errorMessage(result.reason)}`);
+        }
+        const listings = [];
+        if (localResult)
+            listings.push(this.decorateListing(localResult, { kind: 'local' }));
+        for (const { connector, listing } of remoteListings) {
+            listings.push(this.decorateListing(listing, {
+                kind: 'remote',
+                connectorId: connector.connectorId,
+                connectorName: connector.name,
+            }));
+        }
+        const browsers = listings.flatMap(listing => listing.browsers);
+        const defaults = listings
+            .map(listing => listing.defaultBrowserId)
+            .filter((browserId) => typeof browserId === 'string');
+        let defaultBrowserId = null;
+        if (this.defaultBrowser &&
+            browsers.some(browser => browser.browserId === this.defaultBrowser)) {
+            defaultBrowserId = this.defaultBrowser;
+        }
+        else if (defaults.length === 1) {
+            defaultBrowserId = defaults[0];
+        }
+        return this.applyConfiguredDefault({
+            count: browsers.length,
+            connectedCount: browsers.filter(browser => browser.status === 'connected').length,
+            defaultBrowserId,
+            browsers,
+            ...(warnings.length > 0 ? { warnings } : {}),
+        });
+    }
+    async invokeLocal(action, data, timeoutSec, browser, transport) {
+        const result = await invokeLocalBrowser(action, data, {
+            timeoutSec,
+            ...(browser ? { browser } : {}),
+            ...(transport ? { transport } : {}),
+            controlSource: 'local',
+        });
+        return this.decorateActionResult(action, result, { kind: 'local' });
+    }
+    async invokeRemote(action, data, timeoutSec, browser, connector) {
+        const result = await this.requestRemote(action, data, timeoutSec, browser, connector.connectorId);
+        return this.decorateActionResult(action, result, {
+            kind: 'remote',
+            connectorId: connector.connectorId,
+            connectorName: connector.name,
+        });
+    }
+    decorateActionResult(action, result, source) {
+        if (action !== 'browser_launch' || typeof result?.browserId !== 'string')
+            return result;
+        const safeResult = omitTransientBrowserSecrets(result);
+        const originalBrowserId = result.browserId;
+        return {
+            ...safeResult,
+            browserId: encodeBrowserTarget({
+                browser: originalBrowserId,
+                ...(source.connectorId ? { connector: source.connectorId } : {}),
+            }),
+            originalBrowserId,
+            source,
+        };
+    }
+    async ensureConnected() {
+        if (this.ws?.readyState === WebSocket.OPEN)
+            return;
+        if (this.connectPromise)
+            return this.connectPromise;
+        this.closing = false;
+        this.connectPromise = this.connect();
+        try {
+            await this.connectPromise;
+        }
+        finally {
+            this.connectPromise = null;
+        }
+    }
+    connect() {
+        return new Promise((resolve, reject) => {
+            if (!this.options.serverUrl) {
+                reject(new Error('Cloud server URL is required. Start cloud-server, pass --server, or set MEARL_SERVER_URL.'));
+                return;
+            }
+            const ws = new WebSocket(this.options.serverUrl);
+            this.ws = ws;
+            let settled = false;
+            const timer = setTimeout(() => {
+                ws.close();
+                if (!settled)
+                    reject(new Error(`Connection timeout after ${this.options.connectTimeoutSec}s`));
+            }, this.options.connectTimeoutSec * 1_000);
+            ws.on('open', () => {
+                settled = true;
+                clearTimeout(timer);
+                ws.send(JSON.stringify({ type: 'agent_hello' }) + '\n');
+                this.startHeartbeat();
+                resolve();
+            });
+            ws.on('message', data => this.handleMessage(data));
+            ws.on('close', (code, reason) => {
+                clearTimeout(timer);
+                this.rejectAllPending(new Error(`Connection closed (${code}: ${reason.toString()})`));
+                if (!this.closing)
+                    this.ws = null;
+            });
+            ws.on('error', error => {
+                clearTimeout(timer);
+                if (!settled)
+                    reject(error);
+            });
+        });
+    }
+    startHeartbeat() {
+        if (this.heartbeatTimer)
+            clearInterval(this.heartbeatTimer);
+        this.heartbeatTimer = setInterval(() => {
+            if (this.ws?.readyState === WebSocket.OPEN) {
+                this.ws.send(JSON.stringify({ type: 'ping', timestamp: Date.now() }) + '\n');
+            }
+        }, this.options.heartbeatInterval * 1_000);
+    }
+    handleMessage(data) {
+        this.messageBuffer += data.toString('utf8');
+        if (this.messageBuffer.length > MAX_BUFFER_SIZE) {
+            this.disconnect();
+            return;
+        }
+        let newlineIndex;
+        while ((newlineIndex = this.messageBuffer.indexOf('\n')) !== -1) {
+            const line = this.messageBuffer.slice(0, newlineIndex);
+            this.messageBuffer = this.messageBuffer.slice(newlineIndex + 1);
+            if (!line.trim())
+                continue;
+            try {
+                const message = JSON.parse(line);
+                if (!isHeartbeatMessage(message))
+                    this.handleResponse(message);
+            }
+            catch {
+                // Ignore malformed or unrelated frames; pending requests retain their timeout.
+            }
+        }
+    }
+    handleResponse(response) {
+        const pending = this.pendingRequests.get(response.id);
+        if (!pending)
+            return;
+        this.pendingRequests.delete(response.id);
+        clearTimeout(pending.timer);
+        if (response.versionWarning)
+            console.warn(response.versionWarning);
+        if (response.success)
+            pending.resolve(response.data);
+        else
+            pending.reject(new Error(response.error || 'Unknown error from cloud-server'));
+    }
+    async requestRemote(action, data, timeoutSec, browser, connector) {
+        await this.ensureConnected();
+        const ws = this.ws;
+        if (!ws || ws.readyState !== WebSocket.OPEN)
+            throw new Error('Connection is not open');
+        const id = `${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+        const message = { id, action, data, timeoutSec };
+        if (browser)
+            message.browser = browser;
+        if (connector)
+            message.connector = connector;
+        const serialized = `${JSON.stringify(message)}\n`;
+        const bytes = Buffer.byteLength(serialized, 'utf8');
+        if (bytes > MAX_BUFFER_SIZE) {
+            throw new Error(`Cloud request exceeds ${MAX_BUFFER_SIZE} byte message limit (${bytes} bytes)`);
+        }
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pendingRequests.delete(id);
+                reject(new Error(`Request timeout after ${timeoutSec}s`));
+            }, timeoutSec * 1_000 + RESPONSE_GRACE_MS);
+            this.pendingRequests.set(id, { resolve, reject, timer });
+            ws.send(serialized);
+        });
+    }
+    rejectAllPending(error) {
+        for (const pending of this.pendingRequests.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(error);
+        }
+        this.pendingRequests.clear();
+    }
+}
+let defaultBrowser;
+let defaultConnector;
+export async function invoke(action, data = {}, options = {}) {
+    const serverUrl = process.env.MEARL_SERVER_URL ?? loadCloudServerConfig()?.server;
+    const client = new UnifiedClient({
+        ...(serverUrl ? { serverUrl } : {}),
+        defaultBrowser,
+        defaultConnector,
+    });
+    try {
+        const result = await client.invoke(action, data, options);
+        if (action === 'browser_select_browser') {
+            defaultBrowser = result?.selected?.browserId;
+            defaultConnector = undefined;
+        }
+        return result;
+    }
+    finally {
+        client.disconnect();
+    }
+}
+export function listCloudConnectors() {
+    return invoke('connector_list', {});
+}

package/dist/unifiedConfig.d.ts

@@ -0,0 +1,6 @@
+export interface CloudServerConfig {
+    server: string;
+}
+export declare function getCloudServerConfigPath(): string;
+export declare function loadCloudServerConfig(): CloudServerConfig | null;
+export declare function loadLocalConnectorId(): string | null;

package/dist/unifiedConfig.js

@@ -0,0 +1,35 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const MEARL_CONFIG_DIR = join(homedir(), '.mearl');
+export function getCloudServerConfigPath() {
+    return join(MEARL_CONFIG_DIR, 'cloud-server.json');
+}
+export function loadCloudServerConfig() {
+    try {
+        const configPath = getCloudServerConfigPath();
+        if (!existsSync(configPath))
+            return null;
+        const config = JSON.parse(readFileSync(configPath, 'utf8'));
+        return typeof config.server === 'string' && config.server.trim()
+            ? { server: config.server }
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function loadLocalConnectorId() {
+    const explicit = process.env.MEARL_CONNECTOR_ID?.trim();
+    if (explicit)
+        return explicit;
+    try {
+        const config = JSON.parse(readFileSync(join(MEARL_CONFIG_DIR, 'cloud-connector-identity.json'), 'utf8'));
+        return typeof config.connectorId === 'string' && config.connectorId.trim()
+            ? config.connectorId
+            : null;
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mearl/client",
-  "version": "2.5.1",
-  "description": "Client SDK & CLI for Mearl — communicate with Chrome Extension via Unix Socket",
+  "version": "2.6.0",
+  "description": "Unified Mearl SDK & CLI for local and remote browsers",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -10,9 +10,25 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./local": {
+      "types": "./dist/local.d.ts",
+      "import": "./dist/local.js"
+    },
     "./action-timeouts": {
       "types": "./dist/actionTimeouts.d.ts",
       "import": "./dist/actionTimeouts.js"
+    },
+    "./commands": {
+      "types": "./dist/commands.d.ts",
+      "import": "./dist/commands.js"
+    },
+    "./check": {
+      "types": "./dist/check.d.ts",
+      "import": "./dist/check.js"
+    },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "import": "./dist/cli.js"
     }
   },
   "bin": {
@@ -31,8 +47,13 @@
   "publishConfig": {
     "registry": "https://registry.npmjs.org"
   },
+  "dependencies": {
+    "ws": "^8.18.0",
+    "@mearl/cloud-types": "2.6.0"
+  },
   "devDependencies": {
     "@types/node": "^24.9.1",
+    "@types/ws": "^8.18.1",
     "typescript": "^5.8.3"
   },
   "scripts": {