@mearl/provider 2.13.0 → 2.14.0

package/dist/server.js

@@ -4,6 +4,7 @@ import { chmodSync, rmSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { ensureDir } from '@mearl/daemon-core';
 import { isProviderAction } from './generated-provider-actions.js';
+import { createProviderRuntime } from './provider-runtime.js';
 import { PROVIDER_START_TOKEN_ENV, claimProviderStart, providerBrowserKey, providerSocketPath, publishLiveProvider, publishProviderBrowsers, readLiveProvider, releaseProviderStart, removeStaleProviderSocket, touchProviderBrowser, unpublishLiveProvider, unpublishProviderBrowsers, } from './registry.js';
 import { MEARL_PROVIDER_PROTOCOL_VERSION } from './types.js';
 const MAX_REQUEST_BYTES = 16 * 1024 * 1024;
@@ -28,153 +29,89 @@ function isProviderActionRequest(value) {
         (request.controlSource === undefined || typeof request.controlSource === 'string'));
 }
 export function createProviderServer(options) {
-    const socketPath = options.socketPath ?? providerSocketPath(options.descriptor.providerId);
+    const runtime = createProviderRuntime(options.definition);
+    const descriptor = options.definition.descriptor;
+    const socketPath = options.socketPath ?? providerSocketPath(descriptor.providerId);
     let server = null;
     let browserIds = new Set();
     let browsers = [];
     let state = 'idle';
     let stopPromise = null;
     const connections = new Set();
-    function assertDescriptor() {
-        const { providerId, name, version, protocolVersion } = options.descriptor;
-        if (typeof providerId !== 'string' || !providerId.trim()) {
-            throw new Error('providerId is required');
-        }
-        if (typeof name !== 'string' || !name.trim())
-            throw new Error('provider name is required');
-        if (typeof version !== 'string' || !version.trim()) {
-            throw new Error('provider version is required');
-        }
-        if (protocolVersion !== undefined && protocolVersion !== MEARL_PROVIDER_PROTOCOL_VERSION) {
-            throw new Error(`Unsupported provider protocol ${protocolVersion}; expected ${MEARL_PROVIDER_PROTOCOL_VERSION}`);
-        }
-    }
-    function assertBrowsers(nextBrowsers) {
-        const seen = new Set();
-        for (const browser of nextBrowsers) {
-            if (typeof browser.browserId !== 'string' || !browser.browserId.trim()) {
-                throw new Error('provider browserId is required');
-            }
-            if (typeof browser.name !== 'string' || !browser.name.trim()) {
-                throw new Error(`Provider browser ${browser.browserId} needs a name`);
-            }
-            if (seen.has(browser.browserId)) {
-                throw new Error(`Duplicate provider browserId: ${browser.browserId}`);
-            }
-            seen.add(browser.browserId);
-            if (!Array.isArray(browser.capabilities?.actions)) {
-                throw new Error(`Provider browser ${browser.browserId} needs an actions capability list`);
-            }
-            for (const action of browser.capabilities.actions) {
-                if (!isProviderAction(action)) {
-                    throw new Error(`Unsupported provider capability action: ${String(action)}`);
-                }
-            }
-            if (new Set(browser.capabilities.actions).size !== browser.capabilities.actions.length) {
-                throw new Error(`Provider browser ${browser.browserId} has duplicate capability actions`);
-            }
-            if (!['native', 'reconstructed', 'none'].includes(browser.capabilities.screenshot)) {
-                throw new Error(`Unsupported screenshot capability: ${browser.capabilities.screenshot}`);
-            }
-            const supportsScreenshot = browser.capabilities.actions.includes('page_screenshot');
-            if (supportsScreenshot === (browser.capabilities.screenshot === 'none')) {
-                throw new Error(`Provider browser ${browser.browserId} has inconsistent screenshot capabilities`);
-            }
-            if (browser.status !== undefined && !['connected', 'pairing'].includes(browser.status)) {
-                throw new Error(`Unsupported provider browser status: ${String(browser.status)}`);
-            }
-            assertPairing(browser.status, browser.pairing, browser.browserId);
-            if (browser.lastFocusedAt !== undefined &&
-                (!Number.isFinite(browser.lastFocusedAt) || browser.lastFocusedAt < 0)) {
-                throw new Error(`Provider browser ${browser.browserId} has invalid lastFocusedAt`);
-            }
-        }
-    }
-    function providerBrowserId(requested) {
+    async function providerBrowserId(requested) {
         if (requested)
             return requested;
-        if (browsers.length === 1)
-            return browsers[0].browserId;
-        if (browsers.length === 0)
-            throw new Error('Provider has no connected browsers');
+        const available = await runtime.listBrowsers();
+        if (available.length === 1)
+            return available[0].browserId;
+        if (available.length === 0)
+            throw new Error('Provider has no browser instances');
         throw new Error('browserId is required when the provider has multiple browsers');
     }
     async function dispatch(request) {
         if (request.action === 'browser_launch') {
             if (request.browserId)
                 throw new Error('browser_launch does not accept browserId');
-            const parameters = request.data ?? {};
-            if (Object.values(parameters).some(value => typeof value !== 'string')) {
-                throw new Error('Provider browser parameters must be strings');
-            }
-            const created = await options.createBrowser(parameters);
-            if (!created ||
-                typeof created.browserId !== 'string' ||
-                !created.browserId.trim() ||
-                typeof created.name !== 'string' ||
-                !created.name.trim() ||
-                !['connected', 'pairing'].includes(created.status)) {
-                throw new Error('Provider returned an invalid browser creation result');
-            }
-            try {
-                assertPairing(created.status, created.pairing, created.browserId);
-            }
-            catch {
-                throw new Error('Provider returned an invalid browser creation result');
-            }
-            return created;
+            return runtime.launch(request.data ?? {}, { controlSource: request.controlSource });
+        }
+        if (request.action === 'browser_provider_configure') {
+            if (request.browserId)
+                throw new Error('Provider configuration does not accept browserId');
+            return runtime.configure(request.data ?? {}, { controlSource: request.controlSource });
+        }
+        if (request.action === 'browser_manager_start') {
+            return runtime.start({ browserId: await providerBrowserId(request.browserId) }, { controlSource: request.controlSource });
+        }
+        if (request.action === 'browser_manager_sync_cookies') {
+            return runtime.syncCookies({
+                browserId: await providerBrowserId(request.browserId),
+                scope: request.data?.scope,
+            }, { controlSource: request.controlSource });
         }
         if (request.action !== 'get_versions' &&
             request.action !== 'browser_close' &&
+            request.action !== 'get_browser_access_url' &&
             !isProviderAction(request.action)) {
             throw new Error(`Unsupported provider action: ${String(request.action)}`);
         }
-        const browserId = providerBrowserId(request.browserId);
-        const found = browsers.find(browser => browser.browserId === browserId);
-        if (!found)
-            throw new Error(`Provider browser not found: ${browserId}`);
+        const browserId = await providerBrowserId(request.browserId);
         if (request.action === 'browser_close') {
-            return options.deleteBrowser(browserId);
+            return runtime.close({ browserId, deleteData: request.data?.deleteProfile === true }, { controlSource: request.controlSource });
+        }
+        if (request.action === 'get_browser_access_url') {
+            return {
+                browserAccess: await runtime.getAccess({ browserId }, { controlSource: request.controlSource }),
+            };
         }
         if (request.action === 'get_versions') {
+            const found = (await runtime.listBrowsers()).find(browser => browser.browserId === browserId);
+            if (!found)
+                throw new Error(`Provider browser not found: ${browserId}`);
             return {
                 provider: {
-                    providerId: options.descriptor.providerId,
-                    name: options.descriptor.name,
-                    version: options.descriptor.version,
-                    protocolVersion: options.descriptor.protocolVersion ?? MEARL_PROVIDER_PROTOCOL_VERSION,
+                    id: descriptor.providerId,
+                    name: descriptor.name,
+                    builtin: descriptor.builtin === true,
+                    version: descriptor.version,
+                    protocolVersion: descriptor.protocolVersion ?? MEARL_PROVIDER_PROTOCOL_VERSION,
                 },
-                capabilities: found.capabilities,
+                capabilities: found.control.kind === 'provider' ? found.control.capabilities : undefined,
             };
         }
-        if (found.status === 'pairing') {
-            throw new Error(`Provider browser ${browserId} is waiting for device pairing`);
-        }
-        if (!found.capabilities.actions.includes(request.action)) {
-            throw new Error(`Provider browser ${browserId} does not support ${request.action}`);
+        if (request.action === 'browser_release') {
+            const found = (await runtime.listBrowsers()).find(browser => browser.browserId === browserId);
+            if (found?.operations.includes('detach')) {
+                return runtime.detach({ browserId }, { controlSource: request.controlSource });
+            }
         }
-        touchProviderBrowser(providerBrowserKey(options.descriptor.providerId, browserId));
-        return options.handleAction({
+        touchProviderBrowser(providerBrowserKey(descriptor.providerId, browserId));
+        return runtime.invokeAction({
             browserId,
             action: request.action,
             data: request.data ?? {},
             controlSource: request.controlSource,
         });
     }
-    function assertPairing(status, pairing, browserId) {
-        if (status === 'pairing' &&
-            (pairing?.kind !== 'qr' || typeof pairing.url !== 'string' || !pairing.url.trim())) {
-            throw new Error(`Pairing browser ${browserId} needs a pairing URL`);
-        }
-        if (status !== 'pairing' && pairing) {
-            throw new Error(`Pairing metadata requires status "pairing": ${browserId}`);
-        }
-        if (pairing &&
-            ((pairing.code !== undefined && typeof pairing.code !== 'string') ||
-                (pairing.label !== undefined && typeof pairing.label !== 'string'))) {
-            throw new Error(`Provider browser ${browserId} has invalid pairing metadata`);
-        }
-    }
     function handleConnection(socket) {
         connections.add(socket);
         socket.once('close', () => connections.delete(socket));
@@ -216,22 +153,22 @@ export function createProviderServer(options) {
     }
     return {
         socketPath,
+        runtime,
         async start() {
             if (state !== 'idle')
                 throw new Error(`Provider server is already ${state}`);
-            assertDescriptor();
-            const providerId = options.descriptor.providerId;
+            const providerId = descriptor.providerId;
             if (activeProviderIds.has(providerId)) {
                 throw new Error(`Provider ${providerId} is already running in this process`);
             }
             state = 'starting';
             activeProviderIds.add(providerId);
             const startToken = process.env[PROVIDER_START_TOKEN_ENV] || randomUUID();
-            const existing = readLiveProvider(options.descriptor.providerId);
+            const existing = readLiveProvider(descriptor.providerId);
             if (existing) {
                 state = 'idle';
                 activeProviderIds.delete(providerId);
-                throw new Error(`Provider ${options.descriptor.providerId} is already running (pid ${existing.pid})`);
+                throw new Error(`Provider ${descriptor.providerId} is already running (pid ${existing.pid})`);
             }
             if (!claimProviderStart(providerId, startToken)) {
                 state = 'idle';
@@ -256,7 +193,7 @@ export function createProviderServer(options) {
                 });
                 if (process.platform !== 'win32')
                     chmodSync(socketPath, 0o600);
-                publishLiveProvider(options.descriptor, socketPath);
+                publishLiveProvider(descriptor, socketPath);
                 releaseProviderStart(providerId, startToken);
                 state = 'running';
             }
@@ -281,9 +218,9 @@ export function createProviderServer(options) {
         updateBrowsers(nextBrowsers) {
             if (state !== 'running')
                 throw new Error('Provider server is not running');
-            assertBrowsers(nextBrowsers);
+            runtime.updateBrowsers(nextBrowsers);
             browsers = [...nextBrowsers];
-            browserIds = publishProviderBrowsers(options.descriptor, socketPath, browsers, browserIds);
+            browserIds = publishProviderBrowsers(descriptor, socketPath, browsers, browserIds);
         },
         touchBrowser(browserId) {
             if (state !== 'running')
@@ -291,7 +228,7 @@ export function createProviderServer(options) {
             if (!browsers.some(browser => browser.browserId === browserId)) {
                 throw new Error(`Provider browser not found: ${browserId}`);
             }
-            touchProviderBrowser(providerBrowserKey(options.descriptor.providerId, browserId));
+            touchProviderBrowser(providerBrowserKey(descriptor.providerId, browserId));
         },
         async stop() {
             if (state === 'idle')
@@ -314,9 +251,9 @@ export function createProviderServer(options) {
                 browsers = [];
                 if (process.platform !== 'win32')
                     rmSync(socketPath, { force: true });
-                unpublishLiveProvider(options.descriptor.providerId);
+                unpublishLiveProvider(descriptor.providerId);
             })().finally(() => {
-                activeProviderIds.delete(options.descriptor.providerId);
+                activeProviderIds.delete(descriptor.providerId);
                 stopPromise = null;
                 state = 'idle';
             });

package/dist/types.d.ts

@@ -1,6 +1,11 @@
 import type { ProviderAction } from './generated-provider-actions.js';
-export declare const MEARL_PROVIDER_PROTOCOL_VERSION = 1;
+export declare const MEARL_PROVIDER_PROTOCOL_VERSION = 2;
 export type { ProviderAction } from './generated-provider-actions.js';
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | JsonObject;
+export interface JsonObject {
+    [key: string]: JsonValue;
+}
 export type ProviderScreenshotKind = 'native' | 'reconstructed' | 'none';
 export interface ProviderCapabilities {
     actions: ProviderAction[];
@@ -17,27 +22,104 @@ export interface ProviderDescriptor {
     name: string;
     version: string;
     protocolVersion?: number;
+    builtin?: boolean;
 }
-export interface ProviderBrowserParameter {
-    key: string;
-    label: string;
-    required?: boolean;
-    placeholder?: string;
+interface ProviderSchemaBase {
+    title?: string;
     description?: string;
+    default?: JsonValue;
+}
+export interface ProviderStringSchema extends ProviderSchemaBase {
+    type: 'string';
+    secret?: boolean;
+    enum?: readonly string[];
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    placeholder?: string;
+}
+export interface ProviderNumberSchema extends ProviderSchemaBase {
+    type: 'number';
+    integer?: boolean;
+    minimum?: number;
+    maximum?: number;
+}
+export interface ProviderBooleanSchema extends ProviderSchemaBase {
+    type: 'boolean';
+}
+export interface ProviderArraySchema extends ProviderSchemaBase {
+    type: 'array';
+    items: ProviderInputSchema;
+    minItems?: number;
+    maxItems?: number;
+}
+export interface ProviderObjectSchema extends ProviderSchemaBase {
+    type: 'object';
+    properties: Record<string, ProviderInputSchema>;
+    required?: readonly string[];
+    oneOf?: readonly ProviderObjectSchema[];
+    not?: ProviderObjectSchema;
+    additionalProperties?: boolean;
+}
+export type ProviderInputSchema = ProviderStringSchema | ProviderNumberSchema | ProviderBooleanSchema | ProviderArraySchema | ProviderObjectSchema;
+export interface ProviderConfigurationDefinition {
+    inputSchema: ProviderObjectSchema;
 }
 export interface ProviderBrowserType {
     name: string;
-    parameters: ProviderBrowserParameter[];
+    documentationUrl?: string;
+    inputSchema: ProviderObjectSchema;
+    configuration?: ProviderConfigurationDefinition;
+}
+export type ProviderBrowserStatus = 'connected' | 'pairing' | 'running_disconnected' | 'stopped';
+export type ProviderOwnership = 'owned' | 'attached';
+export type ProviderPersistence = 'ephemeral' | 'persistent';
+export type ProviderBrowserOperation = 'start' | 'close' | 'detach' | 'deleteData' | 'access' | 'syncCookies';
+export type ProviderBrowserControl = {
+    kind: 'provider';
+    capabilities: ProviderCapabilities;
+} | {
+    kind: 'host';
+    transport: 'extension' | 'cdp';
+    browserId: string;
+    capabilities?: ProviderCapabilities;
+} | {
+    kind: 'none';
+};
+/** Common safe metadata; additional Provider-specific keys must also be non-secret JSON. */
+export type ProviderBrowserDetails = JsonObject & {
+    headless?: boolean;
+    createdAt?: string;
+    cdpPort?: number;
+    account?: {
+        nickname: string;
+        accountId?: string;
+        loginId?: string;
+    };
+    copiedCookies?: {
+        domains: string[];
+        count: number;
+    };
+};
+export interface ProviderBrowserReference {
+    kind: string;
+    id: string;
+    label?: string;
 }
 export interface ProviderBrowser {
-    /** Stable within this provider. Mearl prefixes it with the provider id globally. */
+    /** Stable within this provider. Mearl adds the Provider namespace globally. */
     browserId: string;
     name: string;
-    status?: 'connected' | 'pairing';
+    status: ProviderBrowserStatus;
+    control: ProviderBrowserControl;
+    ownership?: ProviderOwnership;
+    persistence: ProviderPersistence;
+    operations: ProviderBrowserOperation[];
     lastFocusedAt?: number;
-    capabilities: ProviderCapabilities;
-    /** Pairing metadata is valid only while status is pairing. */
     pairing?: ProviderPairingInfo;
+    references?: ProviderBrowserReference[];
+    /** Safe, non-secret metadata suitable for browser_list and remote connectors. */
+    details?: ProviderBrowserDetails;
 }
 export interface InstalledProviderManifest extends ProviderDescriptor {
     protocolVersion: number;
@@ -56,7 +138,7 @@ export interface ProviderPackageMetadata {
 export interface ProviderActionRequest {
     id: string;
     action: string;
-    data?: Record<string, unknown>;
+    data?: JsonObject;
     /** Provider-local browser id selected by the Mearl client. */
     browserId?: string;
     version?: string;
@@ -65,32 +147,63 @@ export interface ProviderActionRequest {
 export interface ProviderActionContext {
     browserId: string;
     action: ProviderAction;
-    data: Record<string, unknown>;
+    data: JsonObject;
     controlSource?: string;
 }
-export type ProviderActionHandler = (context: ProviderActionContext) => Promise<unknown>;
-interface ProviderBrowserCreateResultBase {
+export interface ProviderHostServices {
+    request<T = JsonValue>(method: string, data?: JsonObject): Promise<T>;
+}
+export interface ProviderContext {
+    host?: ProviderHostServices;
+    controlSource?: string;
+}
+export interface ProviderInstanceRequest {
     browserId: string;
-    name: string;
 }
-export type ProviderBrowserCreateResult = (ProviderBrowserCreateResultBase & {
-    status: 'connected';
-    pairing?: never;
-}) | (ProviderBrowserCreateResultBase & {
-    status: 'pairing';
-    pairing: ProviderPairingInfo;
-});
-export type ProviderBrowserCreateHandler = (parameters: Record<string, string>) => Promise<ProviderBrowserCreateResult>;
-export type ProviderBrowserDeleteHandler = (browserId: string) => Promise<unknown>;
-export interface ProviderServerOptions {
+export interface ProviderCloseRequest extends ProviderInstanceRequest {
+    deleteData?: boolean;
+}
+export interface ProviderSyncCookiesRequest extends ProviderInstanceRequest {
+    scope: JsonObject;
+}
+export interface ProviderAccess {
+    kind: string;
+    url: string;
+    sensitive: true;
+}
+export interface BrowserProviderDefinition {
     descriptor: ProviderDescriptor;
-    handleAction: ProviderActionHandler;
-    createBrowser: ProviderBrowserCreateHandler;
-    deleteBrowser: ProviderBrowserDeleteHandler;
+    browserType: ProviderBrowserType;
+    listBrowsers?: (context: ProviderContext) => ProviderBrowser[] | Promise<ProviderBrowser[]>;
+    launch: (options: JsonObject, context: ProviderContext) => Promise<ProviderBrowser>;
+    start?: (request: ProviderInstanceRequest, context: ProviderContext) => Promise<ProviderBrowser>;
+    close: (request: ProviderCloseRequest, context: ProviderContext) => Promise<unknown>;
+    detach?: (request: ProviderInstanceRequest, context: ProviderContext) => Promise<unknown>;
+    syncCookies?: (request: ProviderSyncCookiesRequest, context: ProviderContext) => Promise<unknown>;
+    getAccess?: (request: ProviderInstanceRequest, context: ProviderContext) => Promise<ProviderAccess>;
+    configure?: (options: JsonObject, context: ProviderContext) => Promise<unknown>;
+    handleAction?: (context: ProviderActionContext) => Promise<unknown>;
+}
+export interface ProviderRuntime {
+    readonly definition: BrowserProviderDefinition;
+    listBrowsers(context?: ProviderContext): Promise<ProviderBrowser[]>;
+    updateBrowsers(browsers: ProviderBrowser[]): void;
+    launch(options: JsonObject, context?: ProviderContext): Promise<ProviderBrowser>;
+    start(request: ProviderInstanceRequest, context?: ProviderContext): Promise<ProviderBrowser>;
+    close(request: ProviderCloseRequest, context?: ProviderContext): Promise<unknown>;
+    detach(request: ProviderInstanceRequest, context?: ProviderContext): Promise<unknown>;
+    syncCookies(request: ProviderSyncCookiesRequest, context?: ProviderContext): Promise<unknown>;
+    getAccess(request: ProviderInstanceRequest, context?: ProviderContext): Promise<ProviderAccess>;
+    configure(options: JsonObject, context?: ProviderContext): Promise<unknown>;
+    invokeAction(context: ProviderActionContext): Promise<unknown>;
+}
+export interface ProviderServerOptions {
+    definition: BrowserProviderDefinition;
     socketPath?: string;
 }
 export interface ProviderServer {
     readonly socketPath: string;
+    readonly runtime: ProviderRuntime;
     start(): Promise<void>;
     updateBrowsers(browsers: ProviderBrowser[]): void;
     touchBrowser(browserId: string): void;

package/dist/types.js

@@ -1 +1 @@
-export const MEARL_PROVIDER_PROTOCOL_VERSION = 1;
+export const MEARL_PROVIDER_PROTOCOL_VERSION = 2;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mearl/provider",
-  "version": "2.13.0",
-  "description": "Contracts and runtime utilities for external Mearl browser-control providers",
+  "version": "2.14.0",
+  "description": "Unified contracts and runtime utilities for built-in and external Mearl browser providers",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -35,7 +35,7 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "@mearl/daemon-core": "2.13.0"
+    "@mearl/daemon-core": "2.14.0"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",