@mearl/provider 2.13.0 → 2.15.0

package/dist/registry.js

@@ -3,6 +3,7 @@ import { randomUUID } from 'node:crypto';
 import { isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { claimRecord, ensureDir, hashKey, isAlive, keyedConfigFile, keyedDir, listRecordFiles, readLiveRecords, readRecord, removeInvalidRecord, removeRecordIfPid, writeRecord, writeRecordIfPid, } from '@mearl/daemon-core';
 import { MEARL_PROVIDER_PROTOCOL_VERSION, } from './types.js';
+import { isProviderInputSchema } from './provider-runtime.js';
 export const INSTALLED_PROVIDERS_SUBDIR = 'providers/installed';
 export const LIVE_PROVIDERS_SUBDIR = 'providers/live';
 export const STARTING_PROVIDERS_SUBDIR = 'providers/starting';
@@ -10,8 +11,14 @@ export const PROVIDER_SOCKETS_SUBDIR = 'providers/sockets';
 export const PROVIDER_DATA_SUBDIR = 'providers/data';
 export const BROWSERS_SUBDIR = 'browsers';
 export const PROVIDER_START_TOKEN_ENV = 'MEARL_PROVIDER_START_TOKEN';
+const RESERVED_PROVIDER_IDS = new Set(['local']);
 export function providerBrowserKey(providerId, browserId) {
-    return `provider:${encodeURIComponent(providerId)}:${encodeURIComponent(browserId)}`;
+    const redundantPrefix = `managed:${providerId}:`;
+    const scopedBrowserId = browserId.toLowerCase().startsWith(redundantPrefix.toLowerCase())
+        ? browserId.slice(redundantPrefix.length)
+        : browserId;
+    const encodedBrowserId = encodeURIComponent(scopedBrowserId).replace(/%3A/gi, ':');
+    return `provider:${encodeURIComponent(providerId)}:${encodedBrowserId}`;
 }
 export function providerSocketPath(providerId) {
     const suffix = hashKey(providerId);
@@ -89,6 +96,9 @@ export function validateInstalledProviderManifest(manifest) {
     if (manifest.protocolVersion !== MEARL_PROVIDER_PROTOCOL_VERSION) {
         return `protocol ${manifest.protocolVersion} is unsupported`;
     }
+    if (RESERVED_PROVIDER_IDS.has(manifest.providerId)) {
+        return `providerId ${manifest.providerId} is reserved for a built-in Provider`;
+    }
     if (!isProviderBrowserType(manifest.browserType)) {
         return 'browserType is invalid';
     }
@@ -135,25 +145,23 @@ function isProviderBrowserType(value) {
     const browserType = value;
     if (typeof browserType.name !== 'string' || !browserType.name.trim())
         return false;
-    if (!Array.isArray(browserType.parameters))
+    if (browserType.documentationUrl !== undefined &&
+        (typeof browserType.documentationUrl !== 'string' ||
+            !/^https?:\/\//.test(browserType.documentationUrl)))
         return false;
-    const keys = new Set();
-    for (const parameter of browserType.parameters) {
-        if (!parameter ||
-            typeof parameter !== 'object' ||
-            typeof parameter.key !== 'string' ||
-            !/^[A-Za-z][A-Za-z0-9_]*$/.test(parameter.key) ||
-            typeof parameter.label !== 'string' ||
-            !parameter.label.trim() ||
-            (parameter.required !== undefined && typeof parameter.required !== 'boolean') ||
-            (parameter.placeholder !== undefined && typeof parameter.placeholder !== 'string') ||
-            (parameter.description !== undefined && typeof parameter.description !== 'string') ||
-            keys.has(parameter.key)) {
-            return false;
-        }
-        keys.add(parameter.key);
-    }
-    return true;
+    if (browserType.help !== undefined &&
+        (!Array.isArray(browserType.help) ||
+            browserType.help.some(item => typeof item !== 'string' || !item.trim())))
+        return false;
+    if (!isProviderObjectSchema(browserType.inputSchema))
+        return false;
+    return (browserType.configuration === undefined ||
+        (Boolean(browserType.configuration) &&
+            typeof browserType.configuration === 'object' &&
+            isProviderObjectSchema(browserType.configuration.inputSchema)));
+}
+function isProviderObjectSchema(value) {
+    return isProviderInputSchema(value) && value.type === 'object';
 }
 export function registerProviderPackage(packageRoot) {
     if (!isAbsolute(packageRoot))
@@ -290,13 +298,21 @@ export function publishProviderBrowsers(descriptor, socketPath, browsers, previo
             browserName: browser.name,
             socketPath,
             transport: 'provider',
-            providerId: descriptor.providerId,
-            providerName: descriptor.name,
-            providerVersion: descriptor.version,
-            providerProtocolVersion: descriptor.protocolVersion ?? MEARL_PROVIDER_PROTOCOL_VERSION,
-            capabilities: browser.capabilities,
-            status: browser.status ?? 'connected',
+            provider: {
+                id: descriptor.providerId,
+                name: descriptor.name,
+                builtin: descriptor.builtin === true,
+                version: descriptor.version,
+                protocolVersion: descriptor.protocolVersion ?? MEARL_PROVIDER_PROTOCOL_VERSION,
+            },
+            capabilities: browser.control.kind === 'provider' ? browser.control.capabilities : undefined,
+            status: browser.status,
+            ownership: browser.ownership,
+            persistence: browser.persistence,
+            operations: browser.operations,
             pairing: browser.pairing,
+            references: browser.references,
+            details: browser.details,
             startedAt: previous?.startedAt ?? startedAt,
             updatedAt: now,
             lastFocusedAt: Math.max(browser.lastFocusedAt ?? 0, previous?.lastFocusedAt ?? 0),

package/dist/runtime.d.ts

@@ -2,3 +2,4 @@
 export { ensureInstalledProvidersRunning } from './launcher.js';
 export { providerBrowserKey, readLiveProvider } from './registry.js';
 export type { LiveProviderRecord } from './registry.js';
+export { createProviderRuntime, validateProviderBrowser, validateProviderInput, } from './provider-runtime.js';

package/dist/runtime.js

@@ -1,3 +1,4 @@
 /** Mearl host integration; Provider implementations should use the package root API. */
 export { ensureInstalledProvidersRunning } from './launcher.js';
 export { providerBrowserKey, readLiveProvider } from './registry.js';
+export { createProviderRuntime, validateProviderBrowser, validateProviderInput, } from './provider-runtime.js';

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;
@@ -11,6 +12,15 @@ const activeProviderIds = new Set();
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
+function isProviderHostContextData(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const host = value;
+    return ((host.userAgent === undefined || typeof host.userAgent === 'string') &&
+        (host.cookies === undefined ||
+            (Array.isArray(host.cookies) &&
+                host.cookies.every(cookie => cookie && typeof cookie === 'object' && !Array.isArray(cookie)))));
+}
 function isProviderActionRequest(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         return false;
@@ -25,156 +35,116 @@ function isProviderActionRequest(value) {
                 !Array.isArray(request.data))) &&
         (request.browserId === undefined || typeof request.browserId === 'string') &&
         (request.version === undefined || typeof request.version === 'string') &&
-        (request.controlSource === undefined || typeof request.controlSource === 'string'));
+        (request.controlSource === undefined || typeof request.controlSource === 'string') &&
+        (request.host === undefined || isProviderHostContextData(request.host)));
+}
+function providerContext(request) {
+    const hostData = request.host;
+    return {
+        controlSource: request.controlSource,
+        ...(hostData
+            ? {
+                host: {
+                    async request(method) {
+                        if (method === 'export_cookies')
+                            return (hostData.cookies ?? []);
+                        if (method === 'get_browser_user_agent') {
+                            if (!hostData.userAgent)
+                                throw new Error('Host browser user agent is unavailable');
+                            return hostData.userAgent;
+                        }
+                        throw new Error(`Unsupported Provider host service: ${method}`);
+                    },
+                },
+            }
+            : {}),
+    };
 }
 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) {
+        const context = providerContext(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 ?? {}, context);
+        }
+        if (request.action === 'browser_provider_configure') {
+            if (request.browserId)
+                throw new Error('Provider configuration does not accept browserId');
+            return runtime.configure(request.data ?? {}, context);
+        }
+        if (request.action === 'browser_manager_start') {
+            return runtime.start({ browserId: await providerBrowserId(request.browserId) }, context);
+        }
+        if (request.action === 'browser_manager_sync_cookies') {
+            return runtime.syncCookies({
+                browserId: await providerBrowserId(request.browserId),
+                scope: request.data?.scope,
+            }, context);
         }
         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 }, context);
+        }
+        if (request.action === 'get_browser_access_url') {
+            return {
+                browserAccess: await runtime.getAccess({ browserId }, context),
+            };
         }
         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 }, context);
+            }
         }
-        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 +186,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 +226,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 +251,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 +261,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 +284,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';
             });