@mearl/client 2.13.0 → 2.14.0

package/dist/browserRegistry.d.ts

@@ -8,7 +8,7 @@
  * registry directory and record shape; reading scans every *.json in the dir,
  * so it never needs to replicate daemon-core's filename hashing.
  */
-import type { BrowserCapabilities, BrowserPairingInfo, BrowserTransport } from './generated-browser-action-protocol.js';
+import type { BrowserCapabilities, BrowserDetails, BrowserPairingInfo, BrowserProviderIdentity, BrowserProviderOperation, BrowserReference, BrowserTransport } from './generated-browser-action-protocol.js';
 export interface LiveBrowser {
     pid: number;
     browserId: string;
@@ -18,13 +18,15 @@ export interface LiveBrowser {
     nativeHostVersion?: string;
     transport?: BrowserTransport;
     providerBrowserId?: string;
-    providerId?: string;
-    providerName?: string;
-    providerVersion?: string;
-    providerProtocolVersion?: number;
+    provider?: BrowserProviderIdentity;
     capabilities?: BrowserCapabilities;
-    status?: 'connected' | 'pairing';
+    status?: 'connected' | 'pairing' | 'running_disconnected' | 'stopped';
+    ownership?: 'owned' | 'attached';
+    persistence?: 'ephemeral' | 'persistent';
+    operations?: BrowserProviderOperation[];
     pairing?: BrowserPairingInfo;
+    references?: BrowserReference[];
+    details?: BrowserDetails;
     lastFocusedAt?: number;
     updatedAt?: number;
 }

package/dist/check.d.ts

@@ -1,5 +1,5 @@
 import type { CloudConnectorInfo } from '@mearl/cloud-types';
-import type { BrowserCapabilities } from './generated-browser-action-protocol.js';
+import type { BrowserCapabilities, BrowserProviderIdentity, BrowserProviderOperation } from './generated-browser-action-protocol.js';
 import { type UnifiedClientOptions, type UnifiedInvokeOptions } from './unified.js';
 export interface UnifiedCheckVersions {
     nativeHost?: string;
@@ -8,8 +8,9 @@ export interface UnifiedCheckVersions {
     provider?: ProviderVersionInfo;
 }
 export interface ProviderVersionInfo {
-    providerId: string;
+    id: string;
     name: string;
+    builtin: boolean;
     version: string;
     protocolVersion: number;
 }
@@ -19,6 +20,8 @@ export type BrowserAccessCapability = {
     kind: 'sandbox-novnc';
     environment: 'opensandbox' | 'aone';
     port: number;
+} | {
+    kind: string;
 };
 export type BrowserAccess = BrowserAccessCapability & {
     url: string;
@@ -32,11 +35,10 @@ interface BrowserInfo {
     originalName?: string;
     status: string;
     type?: string;
-    provider?: 'local' | 'agentbay';
-    providerId?: string;
-    providerName?: string;
-    providerVersion?: string;
-    providerProtocolVersion?: number;
+    provider?: BrowserProviderIdentity;
+    ownership?: 'owned' | 'attached';
+    persistence?: 'ephemeral' | 'persistent';
+    operations?: BrowserProviderOperation[];
     transport?: 'extension' | 'cdp' | 'provider';
 }
 interface CheckItem {

package/dist/check.js

@@ -5,13 +5,16 @@ function formatError(error) {
 function browserAccessLabel(access) {
     if (access.kind === 'agentbay')
         return 'AgentBay, temporary';
-    return access.environment === 'opensandbox' ? 'OpenSandbox noVNC' : 'AONE Sandbox noVNC';
+    if (access.kind === 'sandbox-novnc' && 'environment' in access) {
+        return access.environment === 'opensandbox' ? 'OpenSandbox noVNC' : 'AONE Sandbox noVNC';
+    }
+    return access.kind;
 }
 async function getBrowserAccess(client, browser, capability, timeoutSec) {
     const result = (await client.invoke('get_browser_access_url', {}, { timeoutSec, browser: browser.browserId }));
     if (!result.browserAccess?.url)
         throw new Error('Browser host did not return an access URL');
-    if (result.browserAccess.kind !== capability.kind) {
+    if (capability && result.browserAccess.kind !== capability.kind) {
         throw new Error('Browser host returned an unexpected access URL type');
     }
     return result.browserAccess;
@@ -57,7 +60,7 @@ function formatBrowser(browser, isDefault) {
         : browser.transport === 'extension'
             ? ' [Extension]'
             : browser.transport === 'provider'
-                ? ` [Provider: ${browser.providerName || browser.providerId || 'external'}]`
+                ? ` [Provider: ${browser.provider?.name || browser.provider?.id || 'external'}]`
                 : '';
     const type = browser.type === 'managed' ? ' [Managed]' : '';
     return `  ${isDefault ? '★' : ' '} ${browser.name} [${shortBrowserId(browser.browserId)}]${type}${transport}`;
@@ -250,9 +253,10 @@ export async function runUnifiedCheck(options, dependencies = {}) {
                 let browserAccess;
                 let accessUrlWarning;
                 const browserAccessCapability = versions.browserAccess;
-                if (browserAccessCapability && options.browser) {
+                const providerAccess = browser.operations?.includes('access') === true;
+                if ((providerAccess || browserAccessCapability) && options.browser) {
                     try {
-                        browserAccess = await getBrowserAccess(client, browser, browserAccessCapability, timeoutSec);
+                        browserAccess = await getBrowserAccess(client, browser, providerAccess ? undefined : browserAccessCapability, timeoutSec);
                         details.push(`Browser access URL (${browserAccessLabel(browserAccess)}; sensitive): ${browserAccess.url}`);
                     }
                     catch (error) {

package/dist/commands.d.ts

@@ -402,8 +402,8 @@ export declare const COMMANDS: readonly [{
         readonly description: "运行环境，默认 local；可传 agentbay 或 mearl --help 中展示的已注册 Provider ID";
     }, {
         readonly name: "providerOptions";
-        readonly type: "Record<string, string>";
-        readonly description: "外部 Provider 注册时声明的实例创建参数";
+        readonly type: "Record<string, JSON value>";
+        readonly description: "所选 Provider 声明的结构化启动参数；不能与顶层启动字段混用";
     }, {
         readonly name: "sessionId";
         readonly type: "string";

package/dist/commands.js

@@ -310,8 +310,8 @@ export const COMMANDS = [
             },
             {
                 name: 'providerOptions',
-                type: 'Record<string, string>',
-                description: '外部 Provider 注册时声明的实例创建参数',
+                type: 'Record<string, JSON value>',
+                description: '所选 Provider 声明的结构化启动参数；不能与顶层启动字段混用',
             },
             {
                 name: 'sessionId',

package/dist/generated-browser-action-protocol.d.ts

@@ -137,6 +137,38 @@ export interface BrowserSource {
     connectorId?: string;
     connectorName?: string;
 }
+export type BrowserJsonPrimitive = string | number | boolean | null;
+export type BrowserJsonValue = BrowserJsonPrimitive | BrowserJsonValue[] | {
+    [key: string]: BrowserJsonValue;
+};
+export type BrowserProviderOperation = 'start' | 'close' | 'detach' | 'deleteData' | 'access' | 'syncCookies';
+export interface BrowserProviderIdentity {
+    id: string;
+    name: string;
+    builtin: boolean;
+    version?: string;
+    protocolVersion?: number;
+}
+/** Common safe metadata; additional Provider-specific keys must also be non-secret JSON. */
+export type BrowserDetails = Record<string, BrowserJsonValue> & {
+    headless?: boolean;
+    createdAt?: string;
+    cdpPort?: number;
+    account?: {
+        nickname: string;
+        accountId?: string;
+        loginId?: string;
+    };
+    copiedCookies?: {
+        domains: string[];
+        count: number;
+    };
+};
+export interface BrowserReference {
+    kind: string;
+    id: string;
+    label?: string;
+}
 export interface BrowserInfoBase {
     browserId: string;
     name: string;
@@ -148,12 +180,14 @@ export interface BrowserInfoBase {
     extensionVersion?: string;
     nativeHostVersion?: string;
     transport?: BrowserTransport;
-    /** External control-provider identity. Present only when transport is provider. */
-    providerId?: string;
-    /** Human-readable Provider name; providerId remains the stable identity. */
-    providerName?: string;
-    providerVersion?: string;
-    providerProtocolVersion?: number;
+    /** Provider identity, independent from the browser control transport. */
+    provider?: BrowserProviderIdentity;
+    ownership?: 'owned' | 'attached';
+    persistence?: 'ephemeral' | 'persistent';
+    operations?: BrowserProviderOperation[];
+    references?: BrowserReference[];
+    /** Safe, non-secret metadata suitable for display and remote connectors. */
+    details?: BrowserDetails;
     /** Setup information exposed by a provider while it waits for an external device. */
     pairing?: BrowserPairingInfo;
 }
@@ -170,33 +204,12 @@ export interface RegularBrowserInfo extends BrowserInfoBase {
     type: 'regular';
     status: 'connected' | 'pairing';
 }
-export interface ManagedBrowserAccount {
-    accountId?: string;
-    loginId?: string;
-    nickname: string;
-}
 export interface ManagedBrowserInfo extends BrowserInfoBase {
     type: 'managed';
-    status: 'connected' | 'running_disconnected' | 'stopped';
-    provider?: 'local' | 'agentbay';
-    headless: boolean;
-    persistent: boolean;
-    cdpPort?: number;
-    agentbaySessionId?: string;
-    /** Whether this host owns the AgentBay session lifecycle or only attaches to it. */
-    agentbaySessionMode?: 'owned' | 'attached';
-    /** AgentBay image used to create the session. */
-    agentbayImageId?: string;
-    /** Persistent AgentBay browser context ID when enabled for this instance. */
-    agentbayContextId?: string;
-    /** Stable AgentBay browser context name derived from the managed browser name. */
-    agentbayContextName?: string;
-    createdAt: string;
-    account?: ManagedBrowserAccount;
-    copiedCookies?: {
-        domains: string[];
-        count: number;
-    };
+    status: 'connected' | 'pairing' | 'running_disconnected' | 'stopped';
+    provider: BrowserProviderIdentity;
+    persistence: 'ephemeral' | 'persistent';
+    operations: BrowserProviderOperation[];
 }
 export type BrowserInfo = RegularBrowserInfo | ManagedBrowserInfo;
 export interface BrowserListResult {
@@ -245,8 +258,8 @@ export interface BrowserLaunchParams {
     name?: string;
     /** Built-in runtime or the id of a registered external Provider. */
     provider?: string;
-    /** Creation parameters declared by a registered external Provider. */
-    providerOptions?: Record<string, string>;
+    /** Structured launch parameters declared by the selected Provider. Cannot be mixed with flat options. */
+    providerOptions?: Record<string, BrowserJsonValue>;
     /** Attach to an exact live AgentBay session without creating or owning it. */
     sessionId?: string;
     /** AgentBay running-session reuse policy. Defaults to never. */
@@ -272,6 +285,61 @@ export interface BrowserCloseParams {
     browser: string;
     deleteProfile?: boolean;
 }
+interface BrowserProviderSchemaBase {
+    title?: string;
+    description?: string;
+    default?: BrowserJsonValue;
+}
+export type BrowserProviderInputSchema = (BrowserProviderSchemaBase & {
+    type: 'string';
+    secret?: boolean;
+    enum?: readonly string[];
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    placeholder?: string;
+}) | (BrowserProviderSchemaBase & {
+    type: 'number';
+    integer?: boolean;
+    minimum?: number;
+    maximum?: number;
+}) | (BrowserProviderSchemaBase & {
+    type: 'boolean';
+}) | (BrowserProviderSchemaBase & {
+    type: 'array';
+    items: BrowserProviderInputSchema;
+    minItems?: number;
+    maxItems?: number;
+}) | BrowserProviderObjectSchema;
+export interface BrowserProviderObjectSchema extends BrowserProviderSchemaBase {
+    type: 'object';
+    properties: Record<string, BrowserProviderInputSchema>;
+    required?: readonly string[];
+    oneOf?: readonly BrowserProviderObjectSchema[];
+    not?: BrowserProviderObjectSchema;
+    additionalProperties?: boolean;
+}
+export interface BrowserProviderDefinition {
+    provider: BrowserProviderIdentity;
+    browserType: {
+        name: string;
+        documentationUrl?: string;
+        inputSchema: BrowserProviderObjectSchema;
+        configuration?: {
+            inputSchema: BrowserProviderObjectSchema;
+        };
+    };
+}
+export interface BrowserProviderListResult {
+    providers: BrowserProviderDefinition[];
+}
+export interface BrowserAccessResult {
+    browserAccess: {
+        kind: string;
+        url: string;
+        sensitive: true;
+    };
+}
 export interface SetRuleParams {
     actionType: 'redirect' | 'block' | 'allow' | 'upgradeScheme' | 'modifyHeaders';
     filter: string;
@@ -647,7 +715,7 @@ export interface BrowserActionMap {
     };
     browser_launch: {
         request: BrowserLaunchParams;
-        response: unknown;
+        response: ManagedBrowserInfo;
     };
     browser_close: {
         request: BrowserCloseParams;

package/dist/index.d.ts

@@ -7,7 +7,7 @@
 export { UnifiedClient, UnifiedClient as MearlClient, decodeBrowserTarget, invoke, listCloudConnectors, } from './unified.js';
 export type { UnifiedClientOptions, UnifiedInvokeOptions, UnifiedInvokeOptions as InvokeOptions, } from './unified.js';
 export { APP_PROFILE_NAMES, BROWSER_DEVICE_PRESET_NAMES, BROWSER_ACTIONS, BROWSER_COMMAND_ACTIONS, EXTENSION_BROWSER_ACTIONS, PAGE_ACT_ACTIONS, SEND_REQUEST_MAX_FILES, SEND_REQUEST_MAX_TOTAL_BASE64_FILE_BYTES, SEND_REQUEST_MAX_TOTAL_FILE_BYTES, isBrowserAction, isBrowserCapabilityAction, isBrowserCommandAction, isExtensionBrowserAction, } from './generated-browser-action-protocol.js';
-export type { ActionStep, AppProfileName, BrowserAction, BrowserActionMap, BrowserActionRequest, BrowserActionResponse, BrowserCapabilities, BrowserCapabilityAction, BrowserCloseParams, BrowserCommandAction, BrowserInfo, BrowserInfoBase, BrowserLaunchParams, BrowserListResult, BrowserPairingInfo, BrowserReleaseFailure, BrowserReleaseResult, BrowserSource, BrowserStatus, BrowserScreenshotKind, BrowserTransport, CaptureCheckpointParams, CaptureCheckpointResult, BrowserDevicePresetName, BrowserEmulationOptions, ExtensionBrowserAction, GetApiSchemaParams, GetCookieParams, GetCookieResult, GetEventsParams, GetLogsParams, GetMocksParams, GetRequestsParams, GetUserInfoParams, ManagedBrowserAccount, ManagedBrowserInfo, PageClickParams, PageDragEndpoint, PageDragParams, PageDragPoint, PageActAction, PageDiagnosticsOptions, PageDiagnosticsSetting, PageEvalParams, PageFramesParams, PageHoverParams, PageNavigateParams, PageObservationWaitOptions, PagePressParams, PageScreenshotParams, PageScrollParams, PageSelectedElementParams, PageSnapshotParams, PageSnapshotQuery, PageTypeParams, PageUploadParams, PageWaitParams, RecordParams, RegularBrowserInfo, RequestDomainPermissionParams, RulesResult, RunActionName, RunActionsParams, SelectBrowserParams, SelectBrowserResult, SendRequestFile, SendRequestFormValue, SendMtopRequestParams, SendRequestParams, SetAppProfileParams, SetCookieParams, SetCookieResult, SetDeviceEmulationParams, SetMockParams, SetRuleParams, SetTimezoneParams, SetTimezoneResult, TabCloseParams, TabOpenParams, TdbankAccountParams, } from './generated-browser-action-protocol.js';
+export type { ActionStep, AppProfileName, BrowserAction, BrowserActionMap, BrowserActionRequest, BrowserActionResponse, BrowserCapabilities, BrowserCapabilityAction, BrowserCloseParams, BrowserCommandAction, BrowserInfo, BrowserInfoBase, BrowserJsonValue, BrowserLaunchParams, BrowserProviderOperation, BrowserListResult, BrowserPairingInfo, BrowserReleaseFailure, BrowserReleaseResult, BrowserProviderDefinition, BrowserProviderIdentity, BrowserProviderInputSchema, BrowserProviderListResult, BrowserReference, BrowserDetails, BrowserSource, BrowserStatus, BrowserScreenshotKind, BrowserTransport, CaptureCheckpointParams, CaptureCheckpointResult, BrowserDevicePresetName, BrowserEmulationOptions, ExtensionBrowserAction, GetApiSchemaParams, GetCookieParams, GetCookieResult, GetEventsParams, GetLogsParams, GetMocksParams, GetRequestsParams, GetUserInfoParams, ManagedBrowserInfo, PageClickParams, PageDragEndpoint, PageDragParams, PageDragPoint, PageActAction, PageDiagnosticsOptions, PageDiagnosticsSetting, PageEvalParams, PageFramesParams, PageHoverParams, PageNavigateParams, PageObservationWaitOptions, PagePressParams, PageScreenshotParams, PageScrollParams, PageSelectedElementParams, PageSnapshotParams, PageSnapshotQuery, PageTypeParams, PageUploadParams, PageWaitParams, RecordParams, RegularBrowserInfo, RequestDomainPermissionParams, RulesResult, RunActionName, RunActionsParams, SelectBrowserParams, SelectBrowserResult, SendRequestFile, SendRequestFormValue, SendMtopRequestParams, SendRequestParams, SetAppProfileParams, SetCookieParams, SetCookieResult, SetDeviceEmulationParams, SetMockParams, SetRuleParams, SetTimezoneParams, SetTimezoneResult, TabCloseParams, TabOpenParams, TdbankAccountParams, } from './generated-browser-action-protocol.js';
 import { type UnifiedInvokeOptions } from './unified.js';
 import type * as Protocol from './generated-browser-action-protocol.js';
 export declare function tabCheckpoint(params?: Protocol.CaptureCheckpointParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'tab_checkpoint'>>;

package/dist/socket.js

@@ -77,14 +77,16 @@ function browserListFromProviderRecords(browsers) {
         .map(browser => ({
         browserId: browser.browserId,
         name: browser.browserName,
-        type: 'regular',
-        status: browser.status === 'pairing' ? 'pairing' : 'connected',
+        type: 'managed',
+        status: browser.status ?? 'running_disconnected',
         transport: 'provider',
-        providerId: browser.providerId,
-        providerName: browser.providerName,
-        providerVersion: browser.providerVersion,
-        providerProtocolVersion: browser.providerProtocolVersion,
+        provider: browser.provider,
+        ownership: browser.ownership,
+        persistence: browser.persistence,
+        operations: browser.operations,
         pairing: browser.pairing,
+        references: browser.references,
+        details: browser.details,
     }));
     return {
         count: providerBrowsers.length,
@@ -99,11 +101,23 @@ function mergeWarnings(result, warnings) {
     const merged = [...new Set([...resultWarnings, ...warnings])];
     return { ...result, ...(merged.length > 0 ? { warnings: merged } : {}) };
 }
-function supportsAction(browser, action) {
-    if (browser.transport === 'provider' &&
-        (action === 'get_versions' || action === 'browser_close')) {
+function isConnectedBrowser(browser) {
+    return browser.status === undefined || browser.status === 'connected';
+}
+function supportsAction(browser, action, data) {
+    if (action === 'get_versions')
         return true;
+    if (action === 'get_browser_access_url') {
+        return browser.transport !== 'provider' || browser.operations?.includes('access') === true;
+    }
+    if (action === 'browser_close') {
+        if (browser.transport !== 'provider')
+            return true;
+        const required = data.deleteProfile === true ? 'deleteData' : 'close';
+        return browser.operations?.includes(required) === true;
     }
+    if (!isConnectedBrowser(browser))
+        return false;
     return (browser.transport !== 'provider' ||
         browser.capabilities?.actions.some(capability => capability === action) === true);
 }
@@ -117,7 +131,7 @@ function selectBrowserResult(data) {
         };
     }
     const browsers = listLiveBrowsers();
-    const controllableBrowsers = browsers.filter(browser => browser.status !== 'pairing');
+    const controllableBrowsers = browsers.filter(isConnectedBrowser);
     const match = findBrowser(controllableBrowsers, selector);
     if (!match)
         throw new Error(formatNoMatchError(selector, browsers));
@@ -218,20 +232,20 @@ async function dispatchInvoke(action, data, timeoutSec, transport, selector, con
         }
     }
     const browsers = listLiveBrowsers();
-    const controllableBrowsers = browsers.filter(browser => browser.status !== 'pairing');
+    const controllableBrowsers = browsers.filter(isConnectedBrowser);
     // Explicit target: must match a live browser; do not silently fall back.
     if (selector) {
         const match = findBrowser(browsers, selector);
         if (!match) {
             throw new Error(formatNoMatchError(selector, browsers));
         }
-        if (match.status === 'pairing' && action !== 'get_versions' && action !== 'browser_close') {
-            throw new Error(`Browser ${describeBrowser(match)} is waiting for device pairing`);
-        }
         if (transport === 'cdp' && match.transport === 'provider') {
             throw new Error(`Browser ${describeBrowser(match)} does not support the CDP transport`);
         }
-        if (!supportsAction(match, action)) {
+        if (match.status === 'pairing' && action !== 'get_versions' && action !== 'browser_close') {
+            throw new Error(`Browser ${describeBrowser(match)} is waiting for device pairing`);
+        }
+        if (!supportsAction(match, action, data)) {
             throw new Error(`Browser ${describeBrowser(match)} does not support ${action}`);
         }
         try {
@@ -248,7 +262,8 @@ async function dispatchInvoke(action, data, timeoutSec, transport, selector, con
     }
     // No explicit target: prefer the most-recently-focused live browser; on a
     // stale socket, fall through to the legacy path + auto-spawn.
-    const routableBrowsers = controllableBrowsers.filter(browser => !(transport === 'cdp' && browser.transport === 'provider') && supportsAction(browser, action));
+    const routableBrowsers = controllableBrowsers.filter(browser => !(transport === 'cdp' && browser.transport === 'provider') &&
+        supportsAction(browser, action, data));
     if (routableBrowsers.length > 0) {
         const target = routableBrowsers[0];
         try {
@@ -288,9 +303,9 @@ async function invokeViaLegacy(action, data, timeoutSec, transport, controlSourc
                     /* isRetry */ true);
                 }
                 const browsers = listLiveBrowsers();
-                const target = browsers.find(browser => browser.status !== 'pairing' &&
+                const target = browsers.find(browser => isConnectedBrowser(browser) &&
                     !(transport === 'cdp' && browser.transport === 'provider') &&
-                    supportsAction(browser, action));
+                    supportsAction(browser, action, data));
                 if (target) {
                     return invokeOnce(action, data, timeoutSec, transport, target.socketPath, controlSource, target.providerBrowserId);
                 }

package/dist/unified.js

@@ -420,17 +420,7 @@ export class UnifiedClient {
     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,
-        };
+        return decorateBrowser(result, source);
     }
     async ensureConnected() {
         if (this.ws?.readyState === WebSocket.OPEN)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/client",
-  "version": "2.13.0",
+  "version": "2.14.0",
   "description": "Unified Mearl SDK & CLI for local and remote browsers",
   "type": "module",
   "main": "dist/index.js",
@@ -59,8 +59,8 @@
     "commander": "^15.0.0",
     "fastest-levenshtein": "^1.0.16",
     "ws": "^8.18.0",
-    "@mearl/cloud-types": "2.13.0",
-    "@mearl/provider": "2.13.0"
+    "@mearl/cloud-types": "2.14.0",
+    "@mearl/provider": "2.14.0"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",