@mearl/provider 3.0.0-beta.5 → 3.0.0-beta.8

package/README.md

@@ -8,7 +8,7 @@ action 清单直接复用 `@mearl/browser-core/browserActionProtocol` 的能力
 
 ## 核心模型
 
-控制会话由 Mearl 管理。Provider 继续接收目标实例、页面与普通 action，无需处理控制会话 ID、资源归属或人工交接状态。带 `--session` 的释放只结束 Mearl 任务控制；实例关闭、退出接管与 Cookie 同步仍使用 Provider 的生命周期方法。上传与下载分别按 `capabilities.actions` 中的 `page_upload`、`page_download` 声明使用。
+默认由 Mearl 管理控制会话。Provider 继续接收目标实例、页面与普通 action，无需处理控制会话 ID、资源归属或人工交接状态。带 `--session` 的释放只结束 Mearl 任务控制；实例关闭、退出接管与 Cookie 同步仍使用 Provider 的生命周期方法。上传与下载分别按 `capabilities.actions` 中的 `page_upload`、`page_download` 声明使用。
 
 普通 action 响应中的 `session` 由 Mearl 附加，只包含路由与控制状态；`browser_control` 交接时还包含会话页面清单。`page_snapshot` 的文本 ref 可直接用于后续操作，Provider 应在自身运行时保存其定位映射，不在响应中输出内部节点 ID 字典。
 
@@ -120,7 +120,7 @@ server.updateBrowsers([
 Runtime 会统一校验 schema、状态机、操作能力和页面 action capability，校验通过后才调用实现。
 `capabilities.actions` 应明确列出适配器已经实现并验证的动作，避免通过全量动作减排除项生成清单，使 SDK 新增动作被误报为可用。适配器转发请求时，只有能证明请求尚未发送的连接失败才可自动重连重试；已经发送、响应丢失或业务执行失败的动作不应自动重放。
 `start`、`detach`、`getAccess`、`syncCookies` 等可选实现必须与实例声明的 operation 对应；
-这些是 Provider runtime 的内部能力，不会要求 Mearl 公共协议增加一一对应的 action。
+这些生命周期方法由 Provider runtime 协调，浏览器动作使用统一的 Mearl 协议。
 
 公共 `browser_launch` 对所有 Provider 接收 `{ provider, providerOptions }`，返回与
 `browser_list.browsers[]` 相同的 `ManagedBrowserInfo`（对象形式的 Provider identity、状态、
@@ -201,3 +201,46 @@ npx @mearl/setup provider uninstall <provider-id>
 SDK 负责将 Socket 请求分发到 `configure/getLaunchForm/start/detach/syncCookies` 等方法。
 `browser_release` 普通 action 不承担实例解绑；公开 CLI 的无会话释放由 Mearl 转换为 `detach`。
 打包 SDK 的 Provider 必须更新 SDK 并重新构建，修改安装元数据不能替换运行中的旧代码。
+
+## 外部任务控制与页面增强
+
+已自行管理任务归属、人工交接的 Provider，可在 `browserType.controlSessionModes` 中声明
+`["external"]`，并在实例的 `control.capabilities` 中返回 `controlSessionMode: "external"`。
+SDK 在服务启动和操作前确认 Mearl 控制宿主支持此模式；旧宿主会明确拒绝。
+同一运行时内实例的控制模式固定。该模式不接受 Mearl `--session`，页面归属和交接仍由外部工具负责。
+未声明该字段的 Provider 保持原有行为。
+
+外部 Provider 可用 `createProviderEnhancementClient(providerId, browserId)` 为已获准页面绑定 Mearl
+Extension 的环境增强，依次调用 `bind`、`invoke`、`release`。这条通道只允许设备、App、时区类增强，
+具体范围取决于 Extension 返回的能力；当前 Extension 实现仅开放时区。
+它沿用域授权和现有页面控制冲突检查，不登记自动化页面，不提供普通页面操作、任意代码执行或关闭权限。
+独立 Provider 包使用 `@mearl/provider-<id>` 命名。EgoLite 已有原生 Space 管理和人工交接，通过 [mearl-ego Skill](../../skills/mearl-ego/SKILL.md) 配合 Mearl 扩展进行端模拟与调试；该流程直接调用现有工具，不使用本节的 Provider 增强通道。
+
+实现必须提供只读的 `getEnhancementTarget({ browserId, tabId }, context)`：外部用户控制时返回
+`{ tabId, ready: false }`；确认 Agent 可操作时返回
+`{ tabId, ready: true, mainFrameId, url }`，也可用当前物理 `targetId` 代替 `mainFrameId`。
+身份必须来自当前浏览器目标；提供两项时，当前宿主同时核验两项。仅提供 target ID 时，需要宿主具备相应的目标核验能力。
+URL 仅用于缩小候选范围，不能单独证明双方是同一页面。
+此回调和 `listBrowsers` 必须能在 `handleAction` 等待增强结果期间重入，不应获取该操作持有的锁或认领用户页面。
+
+调用可传入原请求的绝对 `deadline`，它不属于业务 payload。绑定句柄有页面、连接代次和动作范围限制；
+进程重启或页面身份变化后需要重新核验。变更响应丢失后，后续写入会被隔离，不能自动重放或改走普通 action。
+显式重新绑定只完成核验；无法确认的环境仍须由执行宿主处理恢复冲突。
+
+## 已安装 App 资源
+
+外部控制 Provider 可通过 `createProviderAppResourceClient(providerId, browserId)` 读取本机已接受的
+App 定义与运行时。`catalog(params?, deadline?)` 只返回目录摘要；
+`resolve({providerTabId, profile, options?}, deadline?)` 在重新核验页面控制和身份后返回编译配置、
+能力/安装 revision，以及必要运行时的确切 binding 与源码。它不执行页面安装或业务宿主服务。
+
+资源由完整 Native 能力服务解析，Skill 目录读取已注册快照；不会为发现目录重新执行 Skill 源文件。
+资源协议声明只表示读取口存在；显式读取时才刷新和校验安装，能力模块的慢初始化或失败不阻塞普通 Provider 控制宿主启动。
+含桥或全局变量且未显式指定运行时的档案，沿用已安装的 `app.defaultPageRuntime`；缺少运行时直接拒绝，
+不将其降级为已完整准备的 UA 配置。SDK 会再次核验定义 revision、页面证明和源码 SHA-256。
+独立的资源消息上限为 16 MiB，以容纳合法运行时的 JSON 编码；普通增强通道仍限 1 MiB。
+
+Provider 应在自己的实例/页面范围中保存并引用已核验代码，保持原有资源配额与清理规则；
+Space 清单不等于整个物理浏览器的目标清单，不能据此回收别人的资源。
+获得资源不代表后端已支持其根容器、桥回调或真实授权，只有逐项验证后才声明对应 App 能力。
+旧宿主缺少资源协议声明时明确拒绝，不回退到普通 action 或任意 Node 执行。

package/dist/app-resources.d.ts

@@ -0,0 +1,15 @@
+import { type ProviderAppResourceRequest, type ProviderAppResourceResponse } from '@mearl/browser-core';
+export interface ProviderAppResourceClient {
+    catalog(params?: Extract<ProviderAppResourceRequest, {
+        operation: 'catalog';
+    }>['params'], deadline?: number): Promise<Extract<ProviderAppResourceResponse, {
+        catalog: unknown;
+    }>>;
+    resolve(request: Omit<Extract<ProviderAppResourceRequest, {
+        operation: 'resolve';
+    }>, 'operation'>, deadline?: number): Promise<Extract<ProviderAppResourceResponse, {
+        config: unknown;
+    }>>;
+}
+/** Reads accepted installed resources. It never installs code in a page or runs host services. */
+export declare function createProviderAppResourceClient(providerId: string, providerBrowserId: string): ProviderAppResourceClient;

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)))

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.5",
+  "version": "3.0.0-beta.8",
   "description": "Unified contracts and runtime utilities for built-in and external Mearl browser providers",
   "type": "module",
   "main": "dist/index.js",
@@ -29,14 +29,14 @@
   ],
   "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.5",
-    "@mearl/browser-core": "3.0.0-beta.5"
+    "@mearl/daemon-core": "3.0.0-beta.8",
+    "@mearl/browser-core": "3.0.0-beta.8"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",
@@ -44,7 +44,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/F-loat/mearl.git",
+    "url": "git+https://github.com/mearlhq/mearl.git",
     "directory": "packages/provider"
   },
   "scripts": {