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

package/dist/app-resources.js

@@ -0,0 +1,55 @@
+import { createHash } from 'node:crypto';
+import { PROVIDER_APP_RESOURCE_PROTOCOL_VERSION, MAX_PROVIDER_APP_RESOURCE_MESSAGE_BYTES, appProfileRevision, validateAppProfileDefinition, requireReadyProviderEnhancementTarget, BROWSER_DEVICE_PRESET_NAMES, } from '@mearl/browser-core';
+import { providerBrowserKey } from './registry.js';
+import { requestProviderHost } from './control-rpc.js';
+/** Reads accepted installed resources. It never installs code in a page or runs host services. */
+export function createProviderAppResourceClient(providerId, providerBrowserId) {
+    if (!providerId || !providerBrowserId)
+        throw new Error('Provider and browser IDs are required');
+    const target = providerBrowserKey(providerId, providerBrowserId);
+    async function request(data, deadline = Date.now() + 60_000) {
+        const result = await requestProviderHost(target, '__provider_app_resources', data, {
+            deadline, maximumBytes: MAX_PROVIDER_APP_RESOURCE_MESSAGE_BYTES,
+            assertHost(host) {
+                if (host.appResourceProtocolVersion !== PROVIDER_APP_RESOURCE_PROTOCOL_VERSION)
+                    throw new Error('PROVIDER_APP_RESOURCES_UNSUPPORTED: update Mearl and restart the Provider control host');
+            },
+        });
+        for (const revision of [result.capabilityRevision, result.installationRevision])
+            if (revision !== null && (typeof revision !== 'string' || !/^[a-f0-9]{64}$/.test(revision)))
+                throw new Error('Invalid App resource revision');
+        return result;
+    }
+    return {
+        async catalog(params = {}, deadline) {
+            const result = await request({ operation: 'catalog', params }, deadline);
+            if (!('catalog' in result) || !result.catalog || !['available', 'partial', 'unsupported'].includes(result.catalog.status) ||
+                !Array.isArray(result.catalog.entries) || !Array.isArray(result.catalog.issues))
+                throw new Error('Invalid App resource catalog');
+            return result;
+        },
+        async resolve(data, deadline) {
+            if (!Number.isSafeInteger(data.providerTabId) || data.providerTabId < 0 || typeof data.profile !== 'string' || !data.profile || data.profile.length > 161)
+                throw new Error('Invalid App resource request');
+            const result = await request({ ...data, operation: 'resolve' }, deadline);
+            if (!('config' in result) || result.config?.binding?.version !== 1 || result.config.profile !== data.profile ||
+                typeof result.config.userAgent !== 'string' || !BROWSER_DEVICE_PRESET_NAMES.includes(result.recommendedPreset))
+                throw new Error('Invalid resolved App config');
+            const definition = validateAppProfileDefinition(result.config.binding.definition);
+            if (definition.name !== data.profile || result.config.binding.revision !== appProfileRevision(definition))
+                throw new Error('Invalid App definition revision');
+            requireReadyProviderEnhancementTarget(result.target, data.providerTabId);
+            const binding = result.config.pageRuntime;
+            if (binding?.id !== definition.pageRuntime?.id || binding?.sha256 !== definition.pageRuntime?.sha256)
+                throw new Error('App runtime binding mismatch');
+            if (binding) {
+                if (!result.runtime || result.runtime.binding.id !== binding.id || result.runtime.binding.sha256 !== binding.sha256 ||
+                    typeof result.runtime.source !== 'string' || createHash('sha256').update(result.runtime.source).digest('hex') !== binding.sha256)
+                    throw new Error('App runtime integrity check failed');
+            }
+            else if (result.runtime || definition.bridges.length || Object.keys(definition.globals).length)
+                throw new Error('Required App runtime is missing');
+            return result;
+        },
+    };
+}

package/dist/control-host.d.ts

@@ -1,10 +1,20 @@
+import type { BrowserControlSessionMode } from '@mearl/browser-core';
 import { type DaemonRecord } from '@mearl/daemon-core';
 export interface ProviderControlHostRecord extends DaemonRecord {
     socketPath: string;
     token: string;
     ready: boolean;
     protocolVersion: number;
+    /** Missing on older hosts, which only support Mearl sessions. */
+    controlSessionModes?: readonly BrowserControlSessionMode[];
+    enhancementProtocolVersion?: number;
+    enhancementNavigationOriginVersion?: number;
+    enhancementPreparationVersion?: number;
+    enhancementHostEnvironmentVersion?: number;
+    /** RPC support only; each read still prepares and validates the accepted App resources. */
+    appResourceProtocolVersion?: number;
 }
+export declare function assertProviderControlSessionMode(host: Pick<ProviderControlHostRecord, 'controlSessionModes'> | null, mode?: BrowserControlSessionMode): void;
 export declare function providerControlHostFile(): string;
 export declare function providerControlSocketPath(pid: number): string;
 export declare function readProviderControlHost(): ProviderControlHostRecord | null;

package/dist/control-host.js

@@ -4,6 +4,11 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { assertProviderProtocolVersion, MEARL_PROVIDER_PROTOCOL_VERSION } from './protocol.js';
 import { isAlive, keyedConfigFile, claimRecord, readRecord, removeInvalidRecord, removeRecordIfPid, writeRecordIfPid, } from '@mearl/daemon-core';
+export function assertProviderControlSessionMode(host, mode = 'mearl') {
+    if (mode === 'external' && (!Array.isArray(host?.controlSessionModes) || !host.controlSessionModes.includes('external'))) {
+        throw new Error('CONTROL_SESSION_MODE_UNSUPPORTED: the Provider requires external task control. Update Mearl and restart the Provider control host.');
+    }
+}
 export function providerControlHostFile() {
     return keyedConfigFile('control', 'providers');
 }

package/dist/control-rpc.d.ts

@@ -0,0 +1,7 @@
+import { type ProviderControlHostRecord } from './control-host.js';
+/** Package-private transport shared by the two closed Provider host services. */
+export declare function requestProviderHost<T>(providerTarget: string, action: '__provider_enhancement' | '__provider_app_resources', data: unknown, options: {
+    deadline: number;
+    maximumBytes: number;
+    assertHost(host: ProviderControlHostRecord): void;
+}): Promise<T>;

package/dist/control-rpc.js

@@ -0,0 +1,66 @@
+import net from 'node:net';
+import { randomUUID } from 'node:crypto';
+import { ensureProviderControlHost } from './control-host.js';
+import { MEARL_PROVIDER_PROTOCOL_VERSION } from './protocol.js';
+/** Package-private transport shared by the two closed Provider host services. */
+export async function requestProviderHost(providerTarget, action, data, options) {
+    const remaining = () => {
+        const ms = options.deadline - Date.now();
+        if (!Number.isSafeInteger(options.deadline) || ms < 1 || ms > 2_147_483_647)
+            throw new Error('Provider host deadline exceeded or invalid');
+        return ms;
+    };
+    const host = await ensureProviderControlHost(Math.min(remaining(), 10_000));
+    options.assertHost(host);
+    const id = randomUUID();
+    const line = JSON.stringify({ id, action, providerTarget, protocolVersion: MEARL_PROVIDER_PROTOCOL_VERSION,
+        controlSource: 'local', deadline: options.deadline, data }) + '\n';
+    if (Buffer.byteLength(line) > options.maximumBytes)
+        throw new Error('Provider host request exceeded its byte limit');
+    const waitMs = remaining();
+    return new Promise((resolve, reject) => {
+        const socket = net.createConnection(host.socketPath);
+        socket.setEncoding('utf8');
+        let buffer = '', settled = false;
+        const finish = (error, result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            socket.removeAllListeners();
+            socket.destroy();
+            if (error)
+                reject(error);
+            else
+                resolve(result);
+        };
+        const timer = setTimeout(() => finish(new Error('Provider host request timed out; any dispatched effect is unconfirmed')), waitMs);
+        socket.on('connect', () => socket.write(line));
+        socket.on('data', chunk => {
+            buffer += chunk;
+            if (Buffer.byteLength(buffer) > options.maximumBytes)
+                return finish(new Error('Provider host response exceeded its byte limit'));
+            while (buffer.includes('\n')) {
+                const index = buffer.indexOf('\n'), line = buffer.slice(0, index);
+                buffer = buffer.slice(index + 1);
+                let response;
+                try {
+                    response = JSON.parse(line);
+                }
+                catch {
+                    return finish(new Error('Invalid Provider host response'));
+                }
+                if (response?.id !== id)
+                    continue;
+                if (response.success !== true)
+                    return finish(new Error(response.error ?? 'Provider host request failed'));
+                if (!response.data || typeof response.data !== 'object')
+                    return finish(new Error('Invalid Provider host response'));
+                return finish(undefined, response.data);
+            }
+        });
+        socket.on('error', error => finish(error));
+        socket.on('end', () => finish(new Error('Provider host connection closed before its response')));
+        socket.on('close', () => finish(new Error('Provider host connection closed before its response')));
+    });
+}

package/dist/enhancements.d.ts

@@ -0,0 +1,19 @@
+import { type BrowserEnhancementInvocation, type ProviderEnhancementBinding, type ProviderEnhancementPreparation, type ProviderEnhancementRequest } from '@mearl/browser-core';
+export interface ProviderEnhancementClient {
+    inspect(request: Omit<Extract<ProviderEnhancementRequest, {
+        operation: 'inspect';
+    }>, 'operation'>, deadline?: number): Promise<ProviderEnhancementPreparation>;
+    bind(request: Omit<Extract<ProviderEnhancementRequest, {
+        operation: 'bind';
+    }>, 'operation'>, deadline?: number): Promise<ProviderEnhancementBinding>;
+    invoke(binding: ProviderEnhancementBinding, invocation: BrowserEnhancementInvocation, deadline?: number): Promise<unknown>;
+    release(binding: ProviderEnhancementBinding, deadline?: number): Promise<{
+        released: boolean;
+        conflicts?: string[];
+    }>;
+}
+/** Uses the accepted instance's narrow control-host gateway; never forwards ordinary actions. */
+export declare function createProviderEnhancementClient(providerId: string, providerBrowserId: string, options?: {
+    timeoutMs?: number;
+    requireHostEnvironment?: boolean;
+}): ProviderEnhancementClient;

package/dist/enhancements.js

@@ -0,0 +1,100 @@
+import { BROWSER_ENHANCEMENT_PROTOCOL_VERSION, BROWSER_ENHANCEMENT_NAVIGATION_ORIGIN_VERSION, BROWSER_ENHANCEMENT_PREPARATION_VERSION, isBrowserEnhancementPreparationUrl, BROWSER_ENHANCEMENT_HOST_ENVIRONMENT_VERSION, isBrowserEnhancementAction, isEnhancementNavigationOrigin, requiredBrowserEnhancementActions, } from '@mearl/browser-core';
+import { requestProviderHost } from './control-rpc.js';
+import { providerBrowserKey } from './registry.js';
+/** Uses the accepted instance's narrow control-host gateway; never forwards ordinary actions. */
+export function createProviderEnhancementClient(providerId, providerBrowserId, options = {}) {
+    if (!providerId || !providerBrowserId)
+        throw new Error('Provider and browser IDs are required');
+    const timeoutMs = options.timeoutMs ?? 60_000;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 300_000)
+        throw new Error('Enhancement timeout must be between 1 and 300000 milliseconds');
+    const providerTarget = providerBrowserKey(providerId, providerBrowserId);
+    const uncertain = new Set();
+    async function request(data, callerDeadline) {
+        return requestProviderHost(providerTarget, '__provider_enhancement', data, {
+            deadline: callerDeadline ?? Date.now() + timeoutMs, maximumBytes: 1024 * 1024,
+            assertHost(host) {
+                if (host.enhancementProtocolVersion !== BROWSER_ENHANCEMENT_PROTOCOL_VERSION)
+                    throw new Error('BROWSER_ENHANCEMENT_UNSUPPORTED: update Mearl and restart the Provider control host');
+                // Support negotiation only. The Creator's verified initial environment decides the policy.
+                if (options.requireHostEnvironment && host.enhancementHostEnvironmentVersion !== BROWSER_ENHANCEMENT_HOST_ENVIRONMENT_VERSION)
+                    throw new Error('BROWSER_ENHANCEMENT_UNSUPPORTED: the control host cannot preserve the captured host environment');
+                if (data.operation === 'inspect' && host.enhancementPreparationVersion !== BROWSER_ENHANCEMENT_PREPARATION_VERSION)
+                    throw new Error('BROWSER_ENHANCEMENT_UNSUPPORTED: the control host cannot negotiate a preparation page');
+                if ((data.operation === 'bind' || data.operation === 'inspect') && data.navigationOrigin !== undefined &&
+                    host.enhancementNavigationOriginVersion !== BROWSER_ENHANCEMENT_NAVIGATION_ORIGIN_VERSION)
+                    throw new Error('BROWSER_ENHANCEMENT_UNSUPPORTED: the control host cannot authorize a first navigation origin');
+            },
+        });
+    }
+    function assertConfirmed(binding) {
+        if (uncertain.has(binding.bindingId))
+            throw new Error('ENVIRONMENT_UNCONFIRMED: reverify and rebind before another mutation');
+    }
+    return {
+        async inspect(data, deadline) {
+            if (!Number.isSafeInteger(data.providerTabId) || data.providerTabId < 0 || !isEnhancementNavigationOrigin(data.navigationOrigin) ||
+                !Array.isArray(data.actions) || !data.actions.length || data.actions.some(action => !isBrowserEnhancementAction(action)))
+                throw new Error('Invalid enhancement inspection request');
+            const result = await request({ ...data, operation: 'inspect' }, deadline);
+            if (!('preparation' in result) || result.preparation.providerTabId !== data.providerTabId ||
+                !Number.isSafeInteger(result.preparation.tabId) || result.preparation.tabId < 0 ||
+                typeof result.preparation.targetId !== 'string' || !result.preparation.targetId || result.preparation.targetId.length > 256 ||
+                typeof result.preparation.nativeBrowserId !== 'string' || !result.preparation.nativeBrowserId ||
+                (data.nativeBrowserId !== undefined && result.preparation.nativeBrowserId !== data.nativeBrowserId) ||
+                !isBrowserEnhancementPreparationUrl(result.preparation.url) ||
+                result.preparation.capabilities?.protocolVersion !== BROWSER_ENHANCEMENT_PROTOCOL_VERSION ||
+                result.preparation.capabilities?.preparationVersion !== BROWSER_ENHANCEMENT_PREPARATION_VERSION ||
+                !Array.isArray(result.preparation.capabilities.actions) || data.actions.some(action => !result.preparation.capabilities.actions.includes(action)))
+                throw new Error('Invalid enhancement preparation response');
+            return result.preparation;
+        },
+        async bind(data, deadline) {
+            if (!Number.isSafeInteger(data.providerTabId) || data.providerTabId < 0 || !Array.isArray(data.actions) ||
+                (data.navigationOrigin !== undefined && !isEnhancementNavigationOrigin(data.navigationOrigin)) ||
+                !data.actions.length || data.actions.some(action => !isBrowserEnhancementAction(action)))
+                throw new Error('Invalid enhancement binding request');
+            const result = await request({ ...data, operation: 'bind' }, deadline);
+            if (!('binding' in result) || typeof result.binding?.bindingId !== 'string' || !result.binding.bindingId ||
+                !Number.isSafeInteger(result.binding.generation) || result.binding.generation < 1 ||
+                !Number.isSafeInteger(result.binding.tabId) || result.binding.tabId < 0 ||
+                typeof result.binding.mainFrameId !== 'string' || !result.binding.mainFrameId ||
+                (result.binding.targetId !== undefined && (typeof result.binding.targetId !== 'string' || !result.binding.targetId || result.binding.targetId.length > 256)) ||
+                typeof result.binding.nativeBrowserId !== 'string' || !result.binding.nativeBrowserId ||
+                (data.nativeBrowserId !== undefined && result.binding.nativeBrowserId !== data.nativeBrowserId) ||
+                result.binding.providerTabId !== data.providerTabId || !Array.isArray(result.binding.actions) ||
+                data.actions.some(action => !result.binding.actions.includes(action)))
+                throw new Error('Invalid enhancement binding response');
+            uncertain.delete(result.binding.bindingId);
+            return result.binding;
+        },
+        async invoke(binding, invocation, deadline) {
+            assertConfirmed(binding);
+            if (!isBrowserEnhancementAction(invocation.action) || requiredBrowserEnhancementActions(invocation).some(action => !binding.actions.includes(action)))
+                throw new Error('BROWSER_ENHANCEMENT_SCOPE_MISMATCH');
+            try {
+                const result = await request({ ...invocation, operation: 'invoke', bindingId: binding.bindingId, generation: binding.generation }, deadline);
+                if (!('result' in result))
+                    throw new Error('Invalid enhancement invocation response');
+                return result.result;
+            }
+            catch (error) {
+                uncertain.add(binding.bindingId);
+                throw error;
+            }
+        },
+        async release(binding, deadline) {
+            assertConfirmed(binding);
+            try {
+                const result = await request({ operation: 'release', bindingId: binding.bindingId, generation: binding.generation }, deadline);
+                if (!('released' in result) || typeof result.released !== 'boolean')
+                    throw new Error('Invalid enhancement release response');
+                return result;
+            }
+            catch (error) {
+                uncertain.add(binding.bindingId);
+                throw error;
+            }
+        },
+    };
+}

package/dist/host.d.ts

@@ -1,4 +1,4 @@
 export { listInstalledProviders, validateInstalledProviderManifest, registerProviderPackage, stopProvider, readLiveProvider, readProviderStart, uninstallProvider, } from './registry.js';
 export type { InstalledProviderManifest, ProviderPackageMetadata } from './types.js';
-export { ensureProviderControlHost, readProviderControlHost, providerControlHostFile, providerControlSocketPath, } from './control-host.js';
+export { ensureProviderControlHost, assertProviderControlSessionMode, readProviderControlHost, providerControlHostFile, providerControlSocketPath, } from './control-host.js';
 export type { ProviderControlHostRecord } from './control-host.js';

package/dist/host.js

@@ -1,2 +1,2 @@
 export { listInstalledProviders, validateInstalledProviderManifest, registerProviderPackage, stopProvider, readLiveProvider, readProviderStart, uninstallProvider, } from './registry.js';
-export { ensureProviderControlHost, readProviderControlHost, providerControlHostFile, providerControlSocketPath, } from './control-host.js';
+export { ensureProviderControlHost, assertProviderControlSessionMode, readProviderControlHost, providerControlHostFile, providerControlSocketPath, } from './control-host.js';

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export * from './types.js';
+export { createProviderEnhancementClient, type ProviderEnhancementClient } from './enhancements.js';
+export { createProviderAppResourceClient, type ProviderAppResourceClient } from './app-resources.js';
 export { assertProviderProtocolVersion } from './protocol.js';
 export { PROVIDER_ACTIONS, isProviderAction } from './actions.js';
 export { providerDataDir } from './registry.js';

package/dist/index.js

@@ -1,4 +1,6 @@
 export * from './types.js';
+export { createProviderEnhancementClient } from './enhancements.js';
+export { createProviderAppResourceClient } from './app-resources.js';
 export { assertProviderProtocolVersion } from './protocol.js';
 export { PROVIDER_ACTIONS, isProviderAction } from './actions.js';
 export { providerDataDir } from './registry.js';

package/dist/launcher.js

@@ -95,17 +95,28 @@ export async function ensureInstalledProvidersRunning(providerIds) {
     }
     if (starting.size === 0)
         return warnings;
-    const deadline = Date.now() + 2_000;
-    let remaining = [...starting.keys()];
-    while (remaining.length > 0 && Date.now() < deadline) {
+    const startupTimeout = (providerId) => installed.find(manifest => manifest.providerId === providerId)?.browserType.controlSessionModes?.includes('external')
+        ? 12_000 : 2_000;
+    const deadlines = new Map([...starting.keys()].map(id => [id, Date.now() + startupTimeout(id)]));
+    const remaining = new Set(starting.keys());
+    const waiting = new Set(starting.keys());
+    while (waiting.size > 0) {
         await delay(100);
         const current = new Set(listLiveProviders().map(record => record.providerId));
-        remaining = remaining.filter(providerId => !current.has(providerId));
+        for (const providerId of waiting) {
+            if (current.has(providerId)) {
+                waiting.delete(providerId);
+                remaining.delete(providerId);
+            }
+            else if (Date.now() >= deadlines.get(providerId)) {
+                waiting.delete(providerId);
+            }
+        }
     }
     for (const [providerId, token] of starting) {
-        if (!remaining.includes(providerId) && token)
+        if (!remaining.has(providerId) && token)
             releaseProviderStart(providerId, token);
-        if (!remaining.includes(providerId)) {
+        if (!remaining.has(providerId)) {
             try {
                 hasCompatibleLiveProvider(providerId);
             }
@@ -116,7 +127,7 @@ export async function ensureInstalledProvidersRunning(providerIds) {
     }
     for (const providerId of remaining) {
         const logFile = providerLogFile(providerId);
-        warnings.push(`provider ${providerId}: did not become ready within 2s${existsSync(logFile) ? `; see ${logFile}` : ''}`);
+        warnings.push(`provider ${providerId}: did not become ready within ${startupTimeout(providerId) / 1000}s${existsSync(logFile) ? `; see ${logFile}` : ''}`);
     }
     // A ready provider may still be publishing its first browser inventory.
     await delay(100);

package/dist/protocol.d.ts

@@ -1,2 +1,4 @@
+import type { BrowserControlSessionMode } from '@mearl/browser-core';
 export declare const MEARL_PROVIDER_PROTOCOL_VERSION = 3;
+export declare function isProviderControlSessionModes(value: unknown): value is BrowserControlSessionMode[];
 export declare function assertProviderProtocolVersion(actual: unknown, peer?: string): void;

package/dist/protocol.js

@@ -1,4 +1,9 @@
 export const MEARL_PROVIDER_PROTOCOL_VERSION = 3;
+export function isProviderControlSessionModes(value) {
+    return Array.isArray(value) && value.length > 0 &&
+        value.every(mode => mode === 'mearl' || mode === 'external') &&
+        new Set(value).size === value.length;
+}
 export function assertProviderProtocolVersion(actual, peer = 'Provider') {
     if (actual !== MEARL_PROVIDER_PROTOCOL_VERSION) {
         throw new Error(`PROVIDER_PROTOCOL_MISMATCH: ${peer} uses protocol ${String(actual ?? 'unknown')}; expected ${MEARL_PROVIDER_PROTOCOL_VERSION}. Update Mearl and the Provider package, then restart the services.`);

package/dist/provider-runtime.js

@@ -1,5 +1,7 @@
 import { MEARL_PROVIDER_PROTOCOL_VERSION } from './types.js';
 import { isProviderAction } from './actions.js';
+import { isProviderControlSessionModes } from './protocol.js';
+import { isProviderEnhancementTarget } from '@mearl/browser-core';
 const LIFECYCLE_OPERATIONS = new Set([
     'start',
     'close',
@@ -8,6 +10,10 @@ const LIFECYCLE_OPERATIONS = new Set([
     'access',
     'syncCookies',
 ]);
+function assertDeadline(context) {
+    if (context.deadline !== undefined && (!Number.isSafeInteger(context.deadline) || Date.now() >= context.deadline))
+        throw new Error('Provider request deadline exceeded');
+}
 function isJsonValue(value, depth = 0) {
     if (depth > 32)
         return false;
@@ -329,6 +335,13 @@ export function validateProviderBrowser(browser) {
         if (!['native', 'reconstructed', 'none'].includes(capabilities.screenshot)) {
             throw new Error(`Provider browser ${browser.browserId} has invalid screenshot capabilities`);
         }
+        if (capabilities.controlSessionMode !== undefined &&
+            !['mearl', 'external'].includes(capabilities.controlSessionMode)) {
+            throw new Error(`Provider browser ${browser.browserId} has invalid control session mode`);
+        }
+        if (browser.control.kind === 'host' && capabilities.controlSessionMode === 'external') {
+            throw new Error('External control sessions require Provider control');
+        }
         const supportsScreenshot = capabilities.actions.includes('page_screenshot');
         if (supportsScreenshot === (capabilities.screenshot === 'none')) {
             throw new Error(`Provider browser ${browser.browserId} has inconsistent screenshot capabilities`);
@@ -390,6 +403,9 @@ function validateDefinition(definition) {
     }
     if (!definition.browserType.name?.trim())
         throw new Error('provider browser type name is required');
+    if (definition.browserType.controlSessionModes !== undefined &&
+        !isProviderControlSessionModes(definition.browserType.controlSessionModes))
+        throw new Error('Provider control session modes are invalid');
     if (!isProviderInputSchema(definition.browserType.inputSchema) ||
         definition.browserType.inputSchema.type !== 'object') {
         throw new Error('Provider input schema is invalid');
@@ -454,8 +470,24 @@ export function validateProviderLaunchForm(form) {
 export function createProviderRuntime(definition) {
     validateDefinition(definition);
     let publishedBrowsers = [];
+    const declaredModes = new Set(definition.browserType.controlSessionModes ?? ['mearl']);
+    const controlModes = new Map();
+    const rememberControlMode = (browser) => {
+        if (browser.control.kind !== 'none') {
+            controlModes.set(browser.browserId, browser.control.capabilities?.controlSessionMode ?? 'mearl');
+        }
+    };
     const validateRuntimeBrowser = (browser) => {
         validateProviderBrowser(browser);
+        if (browser.control.kind !== 'none') {
+            const previous = controlModes.get(browser.browserId);
+            const mode = browser.control.capabilities?.controlSessionMode ?? 'mearl';
+            if (!declaredModes.has(mode))
+                throw new Error(`Provider did not declare control session mode: ${mode}`);
+            if (previous !== undefined && previous !== mode) {
+                throw new Error('CONTROL_SESSION_MODE_CHANGED: use a new browserId to change task control mode');
+            }
+        }
         const implementations = {
             start: definition.start,
             detach: definition.detach,
@@ -470,6 +502,7 @@ export function createProviderRuntime(definition) {
         }
     };
     const listBrowsers = async (context = {}) => {
+        assertDeadline(context);
         const browsers = definition.listBrowsers
             ? await definition.listBrowsers(context)
             : publishedBrowsers;
@@ -481,6 +514,7 @@ export function createProviderRuntime(definition) {
             }
             seen.add(browser.browserId);
         }
+        browsers.forEach(rememberControlMode);
         return browsers;
     };
     const requireBrowser = async (browserId, operation, context) => {
@@ -490,6 +524,7 @@ export function createProviderRuntime(definition) {
         if (!browser.operations.includes(operation)) {
             throw new Error(`Provider browser ${browserId} does not support ${operation}`);
         }
+        assertDeadline(context);
         return browser;
     };
     return {
@@ -500,9 +535,11 @@ export function createProviderRuntime(definition) {
             if (new Set(browsers.map(browser => browser.browserId)).size !== browsers.length) {
                 throw new Error('Provider browser ids must be unique');
             }
+            browsers.forEach(rememberControlMode);
             publishedBrowsers = [...browsers];
         },
         async getLaunchForm(request, context = {}) {
+            assertDeadline(context);
             if (!definition.browserType.dynamicLaunchForm || !definition.getLaunchForm)
                 throw new Error('Provider does not support dynamic launch forms');
             if (!request ||
@@ -523,9 +560,11 @@ export function createProviderRuntime(definition) {
             return form;
         },
         async launch(options, context = {}) {
+            assertDeadline(context);
             validateProviderInput(definition.browserType.inputSchema, options);
             const browser = await definition.launch(options, context);
             validateRuntimeBrowser(browser);
+            rememberControlMode(browser);
             return browser;
         },
         async start(request, context = {}) {
@@ -534,6 +573,7 @@ export function createProviderRuntime(definition) {
                 throw new Error('Provider does not implement start');
             const browser = await definition.start(request, context);
             validateRuntimeBrowser(browser);
+            rememberControlMode(browser);
             return browser;
         },
         async close(request, context = {}) {
@@ -581,6 +621,7 @@ export function createProviderRuntime(definition) {
             return { ...access, url: url.toString() };
         },
         async configure(options, context = {}) {
+            assertDeadline(context);
             const configuration = definition.browserType.configuration;
             if (!configuration || !definition.configure) {
                 throw new Error('Provider does not support configuration');
@@ -588,8 +629,32 @@ export function createProviderRuntime(definition) {
             validateProviderInput(configuration.inputSchema, options);
             return definition.configure(options, context);
         },
+        async getEnhancementTarget(request, context = {}) {
+            assertDeadline(context);
+            if (!definition.getEnhancementTarget)
+                throw new Error('BROWSER_ENHANCEMENT_TARGET_UNSUPPORTED');
+            if (!Number.isSafeInteger(request.tabId) || request.tabId < 0)
+                throw new Error('A valid Provider tabId is required');
+            const browser = (await listBrowsers(context)).find(item => item.browserId === request.browserId);
+            if (browser?.status !== 'connected' || browser.control.kind !== 'provider' ||
+                browser.control.capabilities.controlSessionMode !== 'external')
+                throw new Error('BROWSER_ENHANCEMENT_OWNER_UNAVAILABLE');
+            assertDeadline(context);
+            const target = await definition.getEnhancementTarget(request, context);
+            if (!isProviderEnhancementTarget(target) || target.tabId !== request.tabId)
+                throw new Error('Invalid Provider enhancement target');
+            assertDeadline(context);
+            return target.ready
+                ? { tabId: target.tabId, ready: true, ...(target.mainFrameId ? { mainFrameId: target.mainFrameId } : {}),
+                    ...(target.targetId ? { targetId: target.targetId } : {}), url: target.url,
+                    ...(target.initialEnvironment ? { initialEnvironment: structuredClone(target.initialEnvironment) } : {}),
+                }
+                : { tabId: target.tabId, ready: false };
+        },
         async invokeAction(actionContext) {
-            const browser = (await listBrowsers({ controlSource: actionContext.controlSource })).find(item => item.browserId === actionContext.browserId);
+            const browser = (await listBrowsers({ controlSource: actionContext.controlSource,
+                ...(actionContext.deadline !== undefined ? { deadline: actionContext.deadline } : {}),
+            })).find(item => item.browserId === actionContext.browserId);
             if (!browser)
                 throw new Error(`Provider browser not found: ${actionContext.browserId}`);
             if (browser.status !== 'connected') {
@@ -603,6 +668,7 @@ export function createProviderRuntime(definition) {
             }
             if (!definition.handleAction)
                 throw new Error('Provider does not implement browser actions');
+            assertDeadline(actionContext);
             return definition.handleAction(actionContext);
         },
     };

package/dist/registry.js

@@ -4,7 +4,7 @@ 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 { validateProviderLaunchForm, isProviderInputSchema } from './provider-runtime.js';
-import { assertProviderProtocolVersion } from './protocol.js';
+import { assertProviderProtocolVersion, isProviderControlSessionModes } from './protocol.js';
 export const INSTALLED_PROVIDERS_SUBDIR = 'providers/installed';
 export const LIVE_PROVIDERS_SUBDIR = 'providers/live';
 export const STARTING_PROVIDERS_SUBDIR = 'providers/starting';
@@ -149,6 +149,8 @@ function isProviderBrowserType(value) {
     const browserType = value;
     if (typeof browserType.name !== 'string' || !browserType.name.trim())
         return false;
+    if (browserType.controlSessionModes !== undefined && !isProviderControlSessionModes(browserType.controlSessionModes))
+        return false;
     if (browserType.documentationUrl !== undefined &&
         (typeof browserType.documentationUrl !== 'string' ||
             !/^https?:\/\//.test(browserType.documentationUrl)))