@mearl/client 3.0.0-beta.0 → 3.0.0-beta.10

package/dist/scriptErrors.js

@@ -0,0 +1,21 @@
+import { serializePluginExecutionError } from './plugins/runtime/pluginExecutorProtocol.js';
+export function serializeScriptError(error, fallback = 'SCRIPT_ERROR') {
+    const value = error;
+    const diagnostic = serializePluginExecutionError({
+        message: typeof value?.message === 'string' ? value.message : String(error),
+        code: typeof value?.code === 'string' ? value.code : fallback,
+        details: {
+            ...value?.details,
+            ...(value?.attempt !== undefined ? { attempt: value.attempt } : {}),
+        },
+        ...(typeof value?.stage === 'string' ? { stage: value.stage } : {}),
+    });
+    return {
+        code: diagnostic.code ?? fallback,
+        message: diagnostic.message,
+        ...(diagnostic.details ? { details: diagnostic.details } : {}),
+        ...(typeof diagnostic.metadata?.stage === 'string' ? { stage: diagnostic.metadata.stage } : {}),
+        ...(diagnostic.details?.attempt !== undefined ? { attempt: diagnostic.details.attempt } : {}),
+        ...(typeof value?.stack === 'string' ? { stack: value.stack.slice(0, 16384) } : {}),
+    };
+}

package/dist/scriptWorker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/scriptWorker.js

@@ -0,0 +1,50 @@
+import { getStructure } from '@mearl/browser-core';
+import { serializeScriptError } from './scriptErrors.js';
+const pending = new Map();
+let sequence = 0;
+let session;
+const call = (method, args) => new Promise((resolve, reject) => {
+    const id = ++sequence;
+    pending.set(id, { resolve, reject });
+    process.send({ type: 'call', id, method, args });
+});
+process.on('disconnect', () => process.exit(1));
+process.on('message', async (message) => {
+    if (message.type === 'response') {
+        const entry = pending.get(message.id);
+        if (!entry)
+            return;
+        pending.delete(message.id);
+        session = message.session ?? session;
+        if (message.error)
+            entry.reject(Object.assign(new Error(message.error.message), message.error));
+        else
+            entry.resolve(message.result);
+        return;
+    }
+    if (message.type !== 'start')
+        return;
+    session = message.session;
+    const api = Object.fromEntries(message.methods.map((method) => [method, (...args) => call(method, args)]));
+    api.structure = getStructure;
+    Object.defineProperty(api, 'session', { get: () => session, enumerable: true });
+    Object.defineProperty(globalThis, 'mearl', { value: Object.freeze(api), configurable: true });
+    let failure;
+    try {
+        const AsyncFunction = Object.getPrototypeOf(async function () { }).constructor;
+        const fn = new AsyncFunction('mearl', '"use strict";\n' + message.code + '\n//# sourceURL=mearl-script.js');
+        await fn(api);
+        if (pending.size)
+            throw Object.assign(new Error('Script finished with unawaited SDK calls'), {
+                code: 'SCRIPT_PENDING_CALLS',
+            });
+    }
+    catch (error) {
+        failure = serializeScriptError(error);
+    }
+    await Promise.all([
+        new Promise(resolve => process.stdout.write('', resolve)),
+        new Promise(resolve => process.stderr.write('', resolve)),
+    ]);
+    process.send(failure ? { type: 'error', error: failure } : { type: 'done' });
+});

package/dist/sdkMethods.d.ts

@@ -0,0 +1,3 @@
+/** Method names and signature exceptions shared by script dispatch and command help. */
+export declare const SDK_METHOD_ACTIONS: Map<string, string>;
+export declare const SDK_OPTIONS_ONLY_METHODS: Set<string>;

package/dist/sdkMethods.js

@@ -0,0 +1,9 @@
+import { BROWSER_COMMAND_ACTIONS } from '@mearl/browser-core/browserActionProtocol';
+/** Method names and signature exceptions shared by script dispatch and command help. */
+export const SDK_METHOD_ACTIONS = new Map(Object.keys(BROWSER_COMMAND_ACTIONS).map(action => [
+    action.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase()),
+    action,
+]));
+SDK_METHOD_ACTIONS.set('selectBrowser', 'browser_select_browser');
+SDK_METHOD_ACTIONS.set('captureCheckpoint', 'tab_checkpoint');
+export const SDK_OPTIONS_ONLY_METHODS = new Set(['browserList', 'tabList', 'getRules']);

package/dist/socket.js

@@ -13,13 +13,13 @@ import os from 'node:os';
 import path from 'node:path';
 import { CLIENT_VERSION } from './runtimePaths.js';
 import { StringDecoder } from 'node:string_decoder';
-import { ensureProviderControlHost, listInstalledProviders } from '@mearl/provider/host';
-import { MEARL_PROVIDER_PROTOCOL_VERSION } from '@mearl/provider';
-import { readLiveProvider } from '@mearl/provider/runtime';
+import { assertProviderControlSessionMode, ensureProviderControlHost, listInstalledProviders } from '@mearl/provider/host';
+import { MEARL_PROVIDER_PROTOCOL_VERSION, assertProviderProtocolVersion, validateProviderLaunchForm } from '@mearl/provider';
+import { readLiveProvider, ensureInstalledProvidersRunning } from '@mearl/provider/runtime';
 import { resolveFileRefs } from './fileRefs.js';
 import { listLiveBrowsers, findBrowser, describeBrowser, } from './browserRegistry.js';
 import { resolveActionTimeoutSec } from './actionTimeouts.js';
-import { isBrowserCapabilityAction } from '@mearl/browser-core';
+import { isBrowserCapabilityAction, parseBrowserListParams } from '@mearl/browser-core';
 export { CLIENT_VERSION };
 const MAX_SOCKET_BUFFER_SIZE = 64 * 1024 * 1024;
 /**
@@ -133,6 +133,7 @@ function isOrdinaryLocalBrowser(browser) {
 function supportsAction(browser, action, data) {
     if (browser.transport === 'provider') {
         if (action === 'browser_control' ||
+            (action === 'get_capabilities' && isConnectedBrowser(browser)) ||
             (action === 'browser_release' && data[SESSION_OPTION]))
             return true;
         if (action.startsWith('__artifact_'))
@@ -375,6 +376,29 @@ export function invoke(action, data = {}, options = {}) {
     const resolvedData = resolveFileRefs(data);
     Object.defineProperty(resolvedData, SESSION_OPTION, { value: options.controlSessionId });
     if (action === 'browser_list') {
+        const discovery = parseBrowserListParams(resolvedData);
+        if (discovery) {
+            return (async () => {
+                if (transport || options.socketPath || controlSource !== 'local' || options.controlSessionId)
+                    throw new Error('Provider discovery requires the local source without a transport, socket or session override');
+                const provider = listInstalledProviders().find(provider => provider.providerId === discovery.provider);
+                if (!provider?.browserType.dynamicLaunchForm)
+                    throw new Error(`Provider does not support dynamic launch forms: ${discovery.provider}`);
+                const warnings = await ensureInstalledProvidersRunning([discovery.provider]);
+                if (warnings.length)
+                    throw new Error(warnings.join('; '));
+                const live = readLiveProvider(discovery.provider);
+                if (!live)
+                    throw new Error(`Provider did not start: ${discovery.provider}`);
+                assertProviderProtocolVersion(live.providerProtocolVersion, discovery.provider);
+                const form = await invokeOnce('browser_providers', { operation: 'launch_form', ...discovery.launchForm }, timeoutSec, undefined, live.socketPath, 'local');
+                validateProviderLaunchForm(form);
+                return decorateBrowserListResult({
+                    ...browserListFromProviderRecords(listLiveBrowsers().filter(browser => browser.provider?.id === discovery.provider)),
+                    discovery: { provider: discovery.provider, launchForm: form },
+                });
+            })();
+        }
         return dispatchInvoke(action, resolvedData, timeoutSec, transport, undefined, controlSource, options.socketPath).then(result => decorateBrowserListResult(transport === 'cdp' ? cdpOnlyBrowserList(result) : result));
     }
     const selector = browser ?? defaultBrowser ?? process.env.MEARL_BROWSER ?? undefined;
@@ -509,7 +533,7 @@ async function dispatchInvoke(action, data, timeoutSec, transport, selector, con
             throw new Error(`Browser ${describeBrowser(match)} does not support ${action}`);
         }
         try {
-            return await invokeOnce(action, data, timeoutSec, transport, match.socketPath, controlSource, match.transport === 'provider' ? match.browserId : undefined);
+            return await invokeOnce(action, data, timeoutSec, transport, match.socketPath, controlSource, match.transport === 'provider' ? match.browserId : undefined, match.capabilities?.controlSessionMode);
         }
         catch (error) {
             if (isConnError(error) || isSocketSandboxError(error)) {
@@ -526,7 +550,7 @@ async function dispatchInvoke(action, data, timeoutSec, transport, selector, con
     if (candidates.length > 0) {
         const target = candidates[0];
         try {
-            return await invokeOnce(action, data, timeoutSec, transport, target.socketPath, controlSource, target.transport === 'provider' ? target.browserId : undefined);
+            return await invokeOnce(action, data, timeoutSec, transport, target.socketPath, controlSource, target.transport === 'provider' ? target.browserId : undefined, target.capabilities?.controlSessionMode);
         }
         catch (error) {
             if (isSocketSandboxError(error)) {
@@ -574,7 +598,7 @@ async function invokeViaLegacy(action, data, timeoutSec, transport, controlSourc
                     !(transport === 'cdp' && browser.transport === 'provider') &&
                     supportsAction(browser, action, data));
                 if (target) {
-                    return invokeOnce(action, data, timeoutSec, transport, target.socketPath, controlSource, target.transport === 'provider' ? target.browserId : undefined);
+                    return invokeOnce(action, data, timeoutSec, transport, target.socketPath, controlSource, target.transport === 'provider' ? target.browserId : undefined, target.capabilities?.controlSessionMode);
                 }
                 return invokeViaLegacy(action, data, timeoutSec, transport, controlSource, 
                 /* isRetry */ true, localOnly);
@@ -585,9 +609,10 @@ async function invokeViaLegacy(action, data, timeoutSec, transport, controlSourc
         throw new Error(formatConnectError(err, SOCKET_PATH), { cause: error });
     }
 }
-async function invokeOnce(action, data, timeoutSec, transport, socketPath, controlSource, providerTarget) {
+async function invokeOnce(action, data, timeoutSec, transport, socketPath, controlSource, providerTarget, controlSessionMode) {
     if (providerTarget) {
         const host = await ensureProviderControlHost(Math.min(timeoutSec * 1000, 10_000));
+        assertProviderControlSessionMode(host, controlSessionMode);
         socketPath = host.socketPath;
     }
     const id = `${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;

package/dist/unified.js

@@ -3,7 +3,7 @@ import { stageFile, exportArtifact } from './artifacts.js';
 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 { validateRequiredActionTabId, } from '@mearl/browser-core';
+import { validateRequiredActionTabId, parseBrowserListParams, } from '@mearl/browser-core';
 import { invoke as invokeLocalBrowser, resolveLocalActionTarget } from './socket.js';
 import { loadCloudServerConfig, loadLocalConnectorId } from './unifiedConfig.js';
 const RESPONSE_GRACE_MS = 1_000;
@@ -146,6 +146,9 @@ export class UnifiedClient {
         }, options);
     }
     async invoke(action, data = {}, options = {}) {
+        const discovery = action === 'browser_list' ? parseBrowserListParams(data) : undefined;
+        if (discovery && (!options.local || options.connector || options.transport || options.session || options.controlSessionId))
+            throw new Error('Provider discovery requires explicit --local without connector, transport, socket or session overrides');
         if (action === 'plugin_state') {
             const { PluginStateClient } = await import('./plugins/clients/pluginState.js');
             const state = new PluginStateClient();
@@ -350,6 +353,12 @@ export class UnifiedClient {
         if (action === 'connector_list')
             return this.listConnectors(timeoutSec);
         if (action === 'browser_list') {
+            if (parseBrowserListParams(data)) {
+                const result = await invokeLocalBrowser('browser_list', data, { timeoutSec, controlSource: 'local' });
+                if (!result?.discovery)
+                    throw new Error('Provider launch-form discovery is not supported by this host');
+                return this.applyConfiguredDefault(this.decorateListing(result, { kind: 'local' }));
+            }
             if (options.local || options.transport === 'cdp') {
                 return this.listLocalBrowsers(timeoutSec, options.transport);
             }
@@ -543,6 +552,7 @@ export class UnifiedClient {
                 })
                 : null,
             browsers,
+            ...(result?.discovery ? { discovery: result.discovery } : {}),
             ...(resultWarnings.length > 0 ? { warnings: resultWarnings } : {}),
         };
     }

package/dist/unifiedConfig.d.ts

@@ -6,3 +6,7 @@ export declare function loadCliAutoUpdateIntervalDays(configPath?: string): numb
 export declare function getCloudServerConfigPath(): string;
 export declare function loadCloudServerConfig(): CloudServerConfig | null;
 export declare function loadLocalConnectorId(): string | null;
+export declare function resolveServer(explicit?: string): {
+    serverUrl?: string;
+    serverUrlSource?: string;
+};

package/dist/unifiedConfig.js

@@ -56,3 +56,14 @@ export function loadLocalConnectorId() {
         return null;
     }
 }
+export function resolveServer(explicit) {
+    if (explicit)
+        return { serverUrl: explicit, serverUrlSource: '--server' };
+    if (process.env.MEARL_SERVER_URL) {
+        return { serverUrl: process.env.MEARL_SERVER_URL, serverUrlSource: 'MEARL_SERVER_URL' };
+    }
+    const config = loadCloudServerConfig();
+    return config?.server
+        ? { serverUrl: config.server, serverUrlSource: getCloudServerConfigPath() }
+        : {};
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/client",
-  "version": "3.0.0-beta.0",
+  "version": "3.0.0-beta.10",
   "description": "Unified Mearl SDK & CLI for local and remote browsers",
   "type": "module",
   "main": "dist/index.js",
@@ -37,6 +37,10 @@
     "./plugin": {
       "types": "./dist/plugin.d.ts",
       "import": "./dist/plugin.js"
+    },
+    "./script": {
+      "types": "./dist/script.d.ts",
+      "import": "./dist/script.js"
     }
   },
   "bin": {
@@ -54,30 +58,33 @@
   ],
   "license": "Apache-2.0",
   "engines": {
-    "node": ">=22.12.0"
+    "node": ">=20.18.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "acorn": "^8.16.0",
-    "ajv": "^8.18.0",
-    "commander": "^15.0.0",
+    "commander": "^14.0.3",
     "fastest-levenshtein": "^1.0.16",
     "ws": "^8.18.0",
-    "@mearl/daemon-core": "3.0.0-beta.0",
-    "@mearl/cloud-types": "3.0.0-beta.0",
-    "@mearl/provider": "3.0.0-beta.0",
-    "@mearl/agent-runtime": "3.0.0-beta.0",
-    "@mearl/browser-core": "3.0.0-beta.0"
+    "@mearl/cloud-types": "3.0.0-beta.10",
+    "@mearl/provider": "3.0.0-beta.10",
+    "@mearl/daemon-core": "3.0.0-beta.10",
+    "@mearl/agent-runtime": "3.0.0-beta.10",
+    "@mearl/browser-core": "3.0.0-beta.10"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",
     "@types/ws": "^8.18.1",
     "typescript": "^5.8.3"
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mearlhq/mearl.git",
+    "directory": "packages/client"
+  },
   "scripts": {
-    "build": "rm -rf dist/ && tsc && chmod +x dist/bin.js",
+    "build": "rm -rf dist/ && tsc && node build-guides.mjs && chmod +x dist/bin.js",
     "dev": "tsc --watch",
     "typecheck": "tsc --noEmit",
     "test": "vitest run"