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

package/dist/server.js

@@ -4,12 +4,19 @@ import { chmodSync, rmSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { ensureDir } from '@mearl/daemon-core';
 import { isProviderAction } from './actions.js';
-import { createProviderRuntime } from './provider-runtime.js';
+import { createProviderRuntime, validateProviderBrowser } 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';
 import { assertProviderProtocolVersion } from './protocol.js';
+import { assertProviderControlSessionMode, ensureProviderControlHost, readProviderControlHost } from './control-host.js';
 const MAX_REQUEST_BYTES = 16 * 1024 * 1024;
 const activeProviderIds = new Set();
+function assertControlHost(browser) {
+    validateProviderBrowser(browser);
+    if (browser.control.kind === 'provider' && browser.control.capabilities.controlSessionMode === 'external') {
+        assertProviderControlSessionMode(readProviderControlHost(), 'external');
+    }
+}
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
@@ -31,6 +38,7 @@ function isProviderActionRequest(value) {
         typeof request.action === 'string' &&
         request.action.length > 0 &&
         typeof request.protocolVersion === 'number' &&
+        (request.deadline === undefined || (Number.isSafeInteger(request.deadline) && request.deadline > 0)) &&
         (request.data === undefined ||
             (request.data !== null &&
                 typeof request.data === 'object' &&
@@ -44,6 +52,7 @@ function providerContext(request) {
     const hostData = request.host;
     return {
         controlSource: request.controlSource,
+        ...(request.deadline !== undefined ? { deadline: request.deadline } : {}),
         ...(hostData
             ? {
                 host: {
@@ -65,6 +74,7 @@ function providerContext(request) {
 export function createProviderServer(options) {
     const runtime = createProviderRuntime(options.definition);
     const descriptor = options.definition.descriptor;
+    const requiresExternalControl = options.definition.browserType.controlSessionModes?.includes('external') === true;
     const socketPath = options.socketPath ?? providerSocketPath(descriptor.providerId);
     let server = null;
     let browserIds = new Set();
@@ -72,20 +82,43 @@ export function createProviderServer(options) {
     let state = 'idle';
     let stopPromise = null;
     const connections = new Set();
+    async function prepareControlHost() {
+        if (requiresExternalControl) {
+            assertProviderControlSessionMode(await ensureProviderControlHost(), 'external');
+        }
+    }
     async function providerBrowserId(requested) {
-        if (requested)
-            return requested;
         const available = await runtime.listBrowsers();
-        if (available.length === 1)
-            return available[0].browserId;
+        const selected = requested
+            ? available.find(browser => browser.browserId === requested)
+            : available.length === 1 ? available[0] : undefined;
+        if (selected) {
+            assertControlHost(selected);
+            return selected.browserId;
+        }
+        if (requested)
+            throw new Error(`Provider browser not found: ${requested}`);
         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 assertDeadline = () => {
+            if (request.deadline !== undefined && Date.now() >= request.deadline)
+                throw new Error('Provider request deadline exceeded');
+        };
+        assertDeadline();
         if (request.controlSessionId)
             throw new Error('CONTROL_SESSION_UNSUPPORTED: this Provider does not implement control sessions');
+        await prepareControlHost();
+        assertDeadline();
         const context = providerContext(request);
+        if (request.action === '__provider_enhancement_target') {
+            const browserId = await providerBrowserId(request.browserId);
+            if (!runtime.getEnhancementTarget)
+                throw new Error('BROWSER_ENHANCEMENT_TARGET_UNSUPPORTED');
+            return runtime.getEnhancementTarget({ browserId, tabId: request.data?.tabId }, context);
+        }
         if (request.action === 'browser_providers') {
             if (request.browserId)
                 throw new Error('Provider management does not accept browserId');
@@ -104,7 +137,9 @@ export function createProviderServer(options) {
         if (request.action === 'browser_launch') {
             if (request.browserId)
                 throw new Error('browser_launch does not accept browserId');
-            return runtime.launch(request.data ?? {}, context);
+            const browser = await runtime.launch(request.data ?? {}, context);
+            assertControlHost(browser);
+            return browser;
         }
         if (request.action === 'browser_instances') {
             if (!['start', 'detach', 'sync_cookies'].includes(String(request.data?.operation))) {
@@ -156,6 +191,7 @@ export function createProviderServer(options) {
             action: request.action,
             data: request.data ?? {},
             controlSource: request.controlSource,
+            ...(request.deadline !== undefined ? { deadline: request.deadline } : {}),
         });
     }
     function handleConnection(socket) {
@@ -229,6 +265,7 @@ export function createProviderServer(options) {
                 throw new Error(`Provider ${providerId} start is already in progress`);
             }
             try {
+                await prepareControlHost();
                 const competing = readLiveProvider(providerId);
                 if (competing) {
                     throw new Error(`Provider ${providerId} is already running (pid ${competing.pid})`);
@@ -271,6 +308,7 @@ export function createProviderServer(options) {
         updateBrowsers(nextBrowsers) {
             if (state !== 'running')
                 throw new Error('Provider server is not running');
+            nextBrowsers.forEach(assertControlHost);
             runtime.updateBrowsers(nextBrowsers);
             browsers = [...nextBrowsers];
             browserIds = publishProviderBrowsers(descriptor, socketPath, browsers, browserIds);

package/dist/types.d.ts

@@ -1,15 +1,15 @@
 import type { ProviderAction } from './actions.js';
+import type { BrowserCapabilities, BrowserControlSessionMode, ProviderEnhancementTarget } from '@mearl/browser-core';
 export { MEARL_PROVIDER_PROTOCOL_VERSION } from './protocol.js';
 export type { ProviderAction } from './actions.js';
+export type { BrowserEnhancementInvocation, ProviderEnhancementBinding, ProviderEnhancementTarget } from '@mearl/browser-core';
 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[];
-    screenshot: ProviderScreenshotKind;
+export interface ProviderCapabilities extends BrowserCapabilities {
 }
 /** Completed download staged on the local Provider process host for Mearl transfer. */
 export interface ProviderDownloadResult {
@@ -123,6 +123,8 @@ export interface ProviderConfigurationDefinition {
 }
 export interface ProviderBrowserType {
     name: string;
+    /** Host must support every listed mode before launch. Omitted means Mearl only. */
+    controlSessionModes?: readonly BrowserControlSessionMode[];
     documentationUrl?: string;
     /** Provider-owned usage guidance rendered by `mearl <providerId>`. */
     help?: readonly string[];
@@ -198,6 +200,8 @@ export interface ProviderActionRequest {
     browserId?: string;
     version?: string;
     protocolVersion: number;
+    /** Absolute caller deadline, outside Provider business options. */
+    deadline?: number;
     controlSource?: string;
     host?: ProviderHostContextData;
 }
@@ -206,6 +210,7 @@ export interface ProviderActionContext {
     action: ProviderAction;
     data: JsonObject;
     controlSource?: string;
+    deadline?: number;
 }
 export interface ProviderHostServices {
     request<T = JsonValue>(method: string, data?: JsonObject): Promise<T>;
@@ -218,6 +223,7 @@ export interface ProviderHostContextData {
 export interface ProviderContext {
     host?: ProviderHostServices;
     controlSource?: string;
+    deadline?: number;
 }
 export interface ProviderInstanceRequest {
     browserId: string;
@@ -245,6 +251,10 @@ export interface BrowserProviderDefinition {
     getAccess?: (request: ProviderInstanceRequest, context: ProviderContext) => Promise<ProviderAccess>;
     configure?: (options: JsonObject, context: ProviderContext) => Promise<unknown>;
     getLaunchForm?: (request: ProviderLaunchFormRequest, context: ProviderContext) => Promise<ProviderLaunchForm>;
+    /** Reentrant read-only preflight: must reflect current control and identity without claiming a page. */
+    getEnhancementTarget?: (request: ProviderInstanceRequest & {
+        tabId: number;
+    }, context: ProviderContext) => Promise<ProviderEnhancementTarget>;
     handleAction?: (context: ProviderActionContext) => Promise<unknown>;
 }
 export interface ProviderRuntime {
@@ -260,6 +270,9 @@ export interface ProviderRuntime {
     configure(options: JsonObject, context?: ProviderContext): Promise<unknown>;
     getLaunchForm(request: ProviderLaunchFormRequest, context?: ProviderContext): Promise<ProviderLaunchForm>;
     invokeAction(context: ProviderActionContext): Promise<unknown>;
+    getEnhancementTarget?(request: ProviderInstanceRequest & {
+        tabId: number;
+    }, context?: ProviderContext): Promise<ProviderEnhancementTarget>;
 }
 export interface ProviderServerOptions {
     definition: BrowserProviderDefinition;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/provider",
-  "version": "3.0.0-beta.0",
+  "version": "3.0.0-beta.10",
   "description": "Unified contracts and runtime utilities for built-in and external Mearl browser providers",
   "type": "module",
   "main": "dist/index.js",
@@ -29,19 +29,24 @@
   ],
   "license": "Apache-2.0",
   "engines": {
-    "node": ">=22.12.0"
+    "node": ">=20.18.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "@mearl/daemon-core": "3.0.0-beta.0",
-    "@mearl/browser-core": "3.0.0-beta.0"
+    "@mearl/daemon-core": "3.0.0-beta.10",
+    "@mearl/browser-core": "3.0.0-beta.10"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",
     "typescript": "^5.8.3"
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mearlhq/mearl.git",
+    "directory": "packages/provider"
+  },
   "scripts": {
     "build": "rm -rf dist/ && tsc",
     "typecheck": "tsc --noEmit",