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

package/README.md

@@ -1,37 +1,39 @@
 # @mearl/provider
 
-`@mearl/provider` 是 Mearl 的统一浏览器 Provider 契约与运行时。内置 Local Chrome 和外部
-Provider 使用相同的 `BrowserProviderDefinition`；区别只在于运行时位于 Native Host 进程内，
-还是通过本地 Provider Socket 接入。
+[English](README.md) | [简体中文](README.zh-CN.md)
 
-action 清单直接复用 `@mearl/browser-core/browserActionProtocol` 的能力动作合同，不维护独立生成副本。
+`@mearl/provider` defines Mearl's unified browser Provider contracts and runtime. Built-in Local Chrome and external
+Providers share `BrowserProviderDefinition`; the runtime either runs inside Native Host
+or connects through a local Provider Socket.
 
-## 核心模型
+The action catalog directly reuses `@mearl/browser-core/browserActionProtocol`, without a separately generated copy.
 
-控制会话由 Mearl 管理。Provider 继续接收目标实例、页面与普通 action，无需处理控制会话 ID、资源归属或人工交接状态。带 `--session` 的释放只结束 Mearl 任务控制；实例关闭、退出接管与 Cookie 同步仍使用 Provider 的生命周期方法。上传与下载分别按 `capabilities.actions` 中的 `page_upload`、`page_download` 声明使用。
+## Core model
 
-普通 action 响应中的 `session` 由 Mearl 附加，只包含路由与控制状态；`browser_control` 交接时还包含会话页面清单。`page_snapshot` 的文本 ref 可直接用于后续操作，Provider 应在自身运行时保存其定位映射，不在响应中输出内部节点 ID 字典。
+Mearl manages control sessions by default. Providers receive target instances, pages, and ordinary actions, without handling session IDs, resource ownership, or human handoff state. Release with `--session` ends only Mearl task control; instance closure, detachment, and Cookie synchronization use Provider lifecycle methods. Upload and download require `page_upload` and `page_download`, respectively, in `capabilities.actions`.
 
-`page_upload` 接收执行宿主上的 `filePaths`，Mearl 负责中转调用方文件与浏览器产物。`page_download` 接收 `{ tabId, trigger, url?, timeout? }`；Provider 先监听下载，再执行点击，等待文件完成后返回 `ProviderDownloadResult`：`{ filename, filePath, action, owned? }`。`filePath` 是本地 Provider 进程宿主上的绝对路径，云端文件由 Provider 取回；`action` 是点击结果，`owned:true` 允许 Mearl 在导入后删除该中转文件。Mearl 将结果转为统一的浏览器产物，支持调用方保存、后续上传与会话清理。下载超时或来源不确定时返回错误，不重复点击。
+Mearl appends `session` to ordinary action responses with routing and control state only; `browser_control` handoff also includes session pages. Text refs from `page_snapshot` are directly actionable. Providers retain locator mappings in their runtime rather than exposing internal node-ID dictionaries.
 
-Provider v2 分开表达实例状态与控制方式：
+`page_upload` receives `filePaths` on the execution host; Mearl stages caller files and browser artifacts. `page_download` receives `{ tabId, trigger, url?, timeout? }`: listen for downloads before clicking, wait for completion, then return `ProviderDownloadResult`: `{ filename, filePath, action, owned? }`. `filePath` is absolute on the local Provider process host; Providers retrieve remote files. `action` is the click result; `owned:true` lets Mearl delete the staged file after import. Mearl converts it to a browser artifact for saving, later upload, and session cleanup. Return an error on timeout or uncertain provenance without clicking again.
 
-- `status`：实例处于 `connected`、`pairing`、`running_disconnected` 或 `stopped`。
-- `control`：页面操作由 Provider 自己处理、由宿主的 Extension/CDP 处理，或当前没有控制通道。
+Provider v2 separates instance status from control mode:
 
-实例还会声明 `ownership`、`persistence`、当前允许的资源 `operations`、稳定
-`references` 和可公开展示的 `details`。因此 Provider identity 不再等同于控制传输，持久化实例
-也不需要伪装成已连接浏览器。
+- `status`: `connected`, `pairing`, `running_disconnected`, or `stopped`.
+- `control`: Page actions are handled by the Provider, by the host's Extension/CDP, or have no current control channel.
 
-## 外部 Provider 安装
+Instances also declare `ownership`, `persistence`, currently permitted resource `operations`, stable
+`references`, and publicly displayable `details`. Provider identity is independent of control transport, and persistent instances
+need not pretend to be connected browsers.
 
-外部 Provider 包将 `@mearl/provider` 声明为运行依赖：
+## External Provider installation
+
+External Provider packages declare `@mearl/provider` as a runtime dependency:
 
 ```bash
 pnpm add @mearl/provider
 ```
 
-包的 `package.json#mearl.provider` 声明协议入口、浏览器类型和结构化启动参数：
+`package.json#mearl.provider` declares the protocol entry, browser type, and structured launch arguments:
 
 ```json
 {
@@ -63,13 +65,13 @@ pnpm add @mearl/provider
 }
 ```
 
-Schema 支持 string、number、boolean、array 和递归 object；Provider 配置也可通过
-`browserType.configuration.inputSchema` 声明。`browserType.help` 由 `mearl <providerId>` 和
-`mearl <providerId> --help` 展示，让 Provider 的操作说明随独立包版本演进。同名 Skill 插件已注册时，
-CLI 会在其后自动追加插件命令摘要，Provider 不需要在 `browserType.help` 中重复维护命令清单。
-`local` 是内置保留 ID。
+Schemas support string, number, boolean, array, and recursive object. Provider configuration can use
+`browserType.configuration.inputSchema`. `mearl <providerId>` and
+`mearl <providerId> --help` display `browserType.help`, so operation guidance evolves with the package version. If a same-name Skill plugin is registered,
+the CLI appends a plugin command summary automatically; do not duplicate that list in `browserType.help`.
+`local` is a reserved built-in ID.
 
-## 最小外部运行时
+## Minimal external runtime
 
 ```ts
 import { createProviderServer, type BrowserProviderDefinition } from '@mearl/provider';
@@ -114,73 +116,73 @@ server.updateBrowsers([
 ]);
 ```
 
-配对中的设备使用 `status: "pairing"` 并提供 `pairing`；停止的持久化实例使用
-`status: "stopped"` 和 `control: { kind: "none" }`。运行但尚未接通控制链路时使用
+Pairing devices use `status: "pairing"` with `pairing`; stopped persistent instances use
+`status: "stopped"` and `control: { kind: "none" }`. Running instances without connected control use
 `status: "running_disconnected"`。
-Runtime 会统一校验 schema、状态机、操作能力和页面 action capability，校验通过后才调用实现。
-`capabilities.actions` 应明确列出适配器已经实现并验证的动作，避免通过全量动作减排除项生成清单，使 SDK 新增动作被误报为可用。适配器转发请求时，只有能证明请求尚未发送的连接失败才可自动重连重试；已经发送、响应丢失或业务执行失败的动作不应自动重放。
-`start`、`detach`、`getAccess`、`syncCookies` 等可选实现必须与实例声明的 operation 对应；
-这些是 Provider runtime 的内部能力，不会要求 Mearl 公共协议增加一一对应的 action。
-
-公共 `browser_launch` 对所有 Provider 接收 `{ provider, providerOptions }`，返回与
-`browser_list.browsers[]` 相同的 `ManagedBrowserInfo`（对象形式的 Provider identity、状态、
-持久化策略、操作和安全元数据）。管理器内部字段、控制连接和临时访问地址不进入该结果。
-Local 的 CLI 顶层参数是便捷输入；外部 Provider 参数必须放在 `providerOptions`，两者不得混用。
-
-内置浏览器保留本地启动交互；外部 Provider 根据 `browserType.inputSchema` 生成输入项。
-两者提交同一结构的 `providerOptions`。
-Schema 的顶层 `oneOf` 可声明多个完整对象约束，
-例如创建与接管会话；每个分支用 `title` 命名，Runtime 要求输入恰好匹配一个分支，
-`not` 可排除不允许的字段组合。`default` 是表单初始值，不会隐式修改调用方参数。
-对象字段 `copyCookieDomains` 约定使用 `{ presets?, domains? }` Cookie 范围结构。
-为这个字段声明 `component: "cookie-sync"` 后，Mearl 浏览器管理器会使用统一的 Cookie
-范围选择组件，并在提交前申请所选站点权限；未声明组件时仍按普通 object 字段渲染。
-Provider 可用 `component: "switch"` 渲染紧凑布尔开关；`formHidden` 隐藏仅供 CLI/API
-使用的高级字段，`formWidth` 控制字段宽度，`formDefault` 设置不影响运行时默认值的表单初值，
-`formHideOptional` 只隐藏可选标识而不改变校验，`formVisibleWhen` 根据另一个字段是否为空控制显示与提交。
-`browserType.documentationUrl` 声明 HTTP(S) 文档地址；`configuration.inputSchema` 声明配置参数，
-配置只传给所选 Provider 的 `configure`，不存入页面本地存储。
-
-Provider 需要查询设备池、已有会话或动态候选项时，声明 `browserType.dynamicLaunchForm: true`
-并实现只读的 `getLaunchForm({ variant?, values }, context)`。
-`browserType.launchForm` 可提供无网络依赖的初始表单，弹窗立即渲染其字段和模式；
-各 `variants[]` 可用 `inputSchema/values/refreshOn/dynamicFields` 覆盖该模式的初值。
-`dynamicFields` 指定异步查询期间需要禁用的字段，其余字段与模式选择保持可操作；加载状态在表单状态行显示。
-初次查询携带静态表单默认值；查询只传入可解析的字段，最终启动仍严格校验全部输入。
-用户在等待期间输入的内容会保留，切换模式或环境会使旧请求失效。
-管理器通过内部
-`browser_providers` 的 `launch_form` operation 获取 `ProviderLaunchForm`，不识别 Provider ID 或业务字段：
-
-- `inputSchema` 描述当前模式的用户输入，`required` 决定必填标识与提交校验。
-- `variants` 的 `id/title/description` 描述连接方式，`variant` 指定当前方式。
-- `values` 是 Provider 给出的固定启动参数，提交时与用户输入合并；只包含非敏感参数。
-- 字符串字段的 `options` 使用 `{ value, label, description?, disabled? }` 描述候选项。
-  禁用项只供展示；运行时的最终资源状态由 Provider 的 `launch` 再次核验。
-- `refreshOn` 指定需要重新查询表单的字段；字段变化会清空其他选项字段的选择。
-  刷新时保留已有输入，选项字段仅保留仍有效的选择；切换模式重新使用该模式默认值。
-- `message` 展示查询结果，`blocked` 阻止无资源、无有效会话等情况下的提交。
-
-查询过程不得创建或租用资源，也不得返回凭据。Runtime 会校验返回的 schema、候选项、
-模式与固定参数。最终 `launch` 仍使用 `browserType.inputSchema` 校验，动态表单不改变 CLI/API
-参数契约。未声明动态表单的 Provider 继续使用静态 schema。
-开发联调时，Provider 应链接包含该公开契约的本地 `@mearl/provider` 构建；分发时需配套发布
-包含动态表单能力的 SDK、Mearl 宿主与 Provider。
-
-`details` 中的通用键具有固定类型：`headless` 为布尔值，`createdAt` 为可解析时间字符串，
-`cdpPort` 为有效端口，`account` 包含 `nickname` 和可选的字符串 `accountId/loginId`，
-`copiedCookies` 包含字符串数组 `domains` 和非负整数 `count`。其余键允许非敏感 JSON，界面同样展示。
-`references` 的 `kind` 表示资源类别，`id` 为不透明标识，`label` 为展示名；
-通用类别包括 `profile/session/image/context/context-name`，也允许 Provider 自定义类别。
-
-## 内置运行时
-
-Native Host 使用 `createProviderRuntime(definition)` 直接运行内置 Local Provider，不需要创建 Socket
-或注册安装记录。内置与外部实现共享同一份 schema 校验、状态机和生命周期派发逻辑；需要宿主服务的进程内调用可通过 `ProviderContext.host` 注入，Provider 合同本身不依赖 Extension、Native Messaging 或
-具体浏览器服务 SDK。
-
-指定 Provider 的启动、配置和动态表单查询只启动该 Provider；完整浏览器发现仍检查所有已安装 Provider。Mearl 的 Provider 控制宿主按调用方绝对期限管理排队及后续动作，旧调用方使用按动作推导的等待时间，持久化关闭和长时间等待不受固定两分钟限制。适配器自己的转发链路也应覆盖对应动作的时间预算，并在等待失败时保留执行结果不确定的语义。
-
-外部 Provider 的安装、发现与启动仍由 `@mearl/setup` 管理：
+The runtime validates schemas, state machines, operations, and page-action capabilities before calling implementations.
+`capabilities.actions` must explicitly list implemented and verified actions. Do not derive it from all actions minus exclusions, which could falsely advertise new SDK actions. Forwarding adapters may automatically reconnect and retry only if a connection failure proves the request was never sent. Sent requests with missing responses and business execution failures must not be replayed automatically.
+Optional implementations such as `start`, `detach`, `getAccess`, and `syncCookies` must match declared instance operations;
+the Provider runtime coordinates these lifecycle methods while browser actions use the unified Mearl protocol.
+
+Public `browser_launch` accepts `{ provider, providerOptions }` for all Providers and returns
+the same `ManagedBrowserInfo` as `browser_list.browsers[]`: object-form Provider identity, state,
+persistence policy, operations, and security metadata. Internal manager fields, control connections, and temporary access URLs are excluded.
+Local top-level CLI arguments are convenience inputs. External Provider arguments must use `providerOptions`; the two cannot be mixed.
+
+Built-in browsers retain local launch interactions; external Provider inputs are generated from `browserType.inputSchema`.
+Both submit the same `providerOptions` structure.
+Top-level schema `oneOf` can declare multiple complete object constraints,
+such as creating or attaching sessions. Each branch has a `title`; the runtime requires input to match exactly one branch.
+`not` excludes forbidden combinations. `default` initializes forms without implicitly modifying caller arguments.
+Object field `copyCookieDomains` uses the `{ presets?, domains? }` Cookie scope convention.
+With `component: "cookie-sync"`, the browser manager uses the shared Cookie
+scope selector and requests selected-site permissions before submission. Without it, the field renders as an ordinary object.
+`component: "switch"` renders compact boolean switches. `formHidden` hides advanced CLI/API-only
+fields; `formWidth` controls width; `formDefault` initializes forms without changing runtime defaults;
+`formHideOptional` hides only the optional marker, not validation; `formVisibleWhen` controls display and submission based on another field's emptiness.
+`browserType.documentationUrl` declares an HTTP(S) documentation URL. `configuration.inputSchema` declares configuration inputs,
+passed only to the selected Provider's `configure`, without page-local persistence.
+
+Providers querying device pools, existing sessions, or dynamic options declare `browserType.dynamicLaunchForm: true`
+and implement read-only `getLaunchForm({ variant?, values }, context)`.
+`browserType.launchForm` can supply an initial form without network access, rendering fields and modes immediately.
+Each `variants[]` entry can override mode defaults through `inputSchema/values/refreshOn/dynamicFields`.
+`dynamicFields` identifies fields disabled during asynchronous queries; other fields and mode selection remain usable. A form status row shows loading.
+The initial query carries static defaults and sends only parseable fields; final launch still validates all inputs strictly.
+Input entered while waiting is retained. Mode or environment changes invalidate previous requests.
+The manager uses the internal
+`browser_providers` `launch_form` operation to obtain `ProviderLaunchForm`, without recognizing Provider IDs or business fields:
+
+- `inputSchema` describes user inputs for the current mode; `required` controls required markers and submission validation.
+- `variants` uses `id/title/description` for connection modes, with `variant` selecting the current mode.
+- `values` contains fixed, non-sensitive Provider launch arguments, merged with user inputs on submission.
+- String-field `options` use `{ value, label, description?, disabled? }`.
+  Disabled options are display-only. Provider `launch` revalidates final resource state.
+- `refreshOn` identifies fields requiring a form query; changes clear selections in other option fields.
+  Refresh retains inputs and still-valid option selections; switching modes reapplies that mode's defaults.
+- `message` displays query results; `blocked` prevents submission without resources or valid sessions.
+
+Queries must not create or rent resources or return credentials. The runtime validates returned schemas, options,
+modes, and fixed arguments. Final `launch` still validates against `browserType.inputSchema`; dynamic forms do not change CLI/API
+argument contracts. Providers without dynamic forms use static schemas.
+For local integration, link a local `@mearl/provider` build containing this public contract. Distribution requires matching releases
+of the SDK, Mearl host, and Provider supporting dynamic forms.
+
+Common `details` keys have fixed types: `headless` is boolean, `createdAt` is a parseable timestamp,
+`cdpPort` is a valid port, `account` contains `nickname` and optional string `accountId/loginId`,
+and `copiedCookies` contains string-array `domains` and nonnegative integer `count`. Other keys may contain non-sensitive JSON and are also displayed.
+`references.kind` identifies resource categories, `id` is opaque, and `label` is the display name.
+Common categories include `profile/session/image/context/context-name`; Providers may define others.
+
+## Built-in runtime
+
+Native Host runs Local directly with `createProviderRuntime(definition)`, without a Socket
+or installation record. Built-in and external implementations share schema validation, state machines, and lifecycle dispatch. In-process host services can use `ProviderContext.host`; Provider contracts do not depend on Extension, Native Messaging, or
+specific browser service SDKs.
+
+Launching, configuring, or querying dynamic forms for a specific Provider starts only that Provider; full discovery checks all installed Providers. Mearl's control host manages queues and actions against caller absolute deadlines. Callers without deadlines use action-derived waits; persistent closure and long waits have no fixed two-minute limit. Adapter forwarding must cover the action's time budget and preserve uncertain-execution semantics when waiting fails.
+
+setup manages external Provider installation, discovery, and startup:
 
 ```bash
 npx @mearl/setup provider install <package>
@@ -188,16 +190,59 @@ npx @mearl/setup provider update <provider-id>
 npx @mearl/setup provider uninstall <provider-id>
 ```
 
-## Socket 协议
-
-当前 Provider 协议版本为 **3**，请求 envelope 携带 `protocolVersion`。安装元数据、
-运行时 descriptor、运行中进程与调用方必须使用相同协议；不匹配时更新相关包并重启进程。
-
-- `browser_providers`：`operation: "configure"` 携带 `options`，`operation: "launch_form"` 携带 `variant?` 和 `values`。
-- `browser_instances`：`operation: "start" | "detach" | "sync_cookies"`；同步携带 `scope`，目标实例由 envelope 的 `browserId` 选择。
-- `browser_launch`、`browser_close`、`get_browser_access_url` 保留各自职责。
-- `browser_sessions` 由 Mearl 控制进程处理，不转交外部 Provider；会话释放与实例 `detach` 分开执行。
-
-SDK 负责将 Socket 请求分发到 `configure/getLaunchForm/start/detach/syncCookies` 等方法。
-`browser_release` 普通 action 不承担实例解绑；公开 CLI 的无会话释放由 Mearl 转换为 `detach`。
-打包 SDK 的 Provider 必须更新 SDK 并重新构建，修改安装元数据不能替换运行中的旧代码。
+## Socket protocol
+
+The current Provider protocol version is **3**; request envelopes carry `protocolVersion`. Installation metadata,
+runtime descriptors, running processes, and callers must match. Update the relevant packages and restart processes on mismatch.
+
+- `browser_providers`: `operation: "configure"` carries `options`; `operation: "launch_form"` carries `variant?` and `values`.
+- `browser_instances`: `operation: "start" | "detach" | "sync_cookies"`; synchronization carries `scope`, and envelope `browserId` selects the instance.
+- `browser_launch`, `browser_close`, and `get_browser_access_url` retain their separate responsibilities.
+- Mearl's control process handles `browser_sessions`, without forwarding to external Providers. Session release and instance `detach` are separate.
+
+The SDK dispatches Socket requests to methods such as `configure/getLaunchForm/start/detach/syncCookies`.
+The ordinary `browser_release` action does not detach instances; Mearl converts public CLI release without a session to `detach`.
+Providers bundling the SDK must update it and rebuild. Editing installation metadata cannot replace running code.
+
+## External task control and page enhancement
+
+Providers managing their own task ownership and human handoffs can declare
+`["external"]` in `browserType.controlSessionModes` and return `controlSessionMode: "external"` in instance `control.capabilities`.
+The SDK checks Mearl host support at startup and before operations; unsupported hosts reject explicitly.
+An instance's control mode is fixed within a runtime. External mode rejects Mearl `--session`; external tools own page ownership and handoff.
+Providers omitting this field retain default behavior.
+
+External Providers can bind Mearl Extension environment enhancement to authorized pages through
+`createProviderEnhancementClient(providerId, browserId)`, calling `bind`, `invoke`, and `release`. Only device, App, and time-zone enhancement is allowed,
+as advertised by the Extension. The current Extension exposes only time zones.
+The channel applies domain authorization and page-control conflict checks without registering automation pages or granting ordinary page actions, arbitrary code execution, or closure.
+Independent packages use `@mearl/provider-<id>`. EgoLite has native Space management and human handoff. The [mearl-ego Skill](../../skills/mearl-ego/SKILL.md) uses existing tools with the Mearl extension for simulation and debugging, without this Provider enhancement channel.
+
+Implement read-only `getEnhancementTarget({ browserId, tabId }, context)`. Under external user control, return
+`{ tabId, ready: false }`; when Agent control is confirmed, return
+`{ tabId, ready: true, mainFrameId, url }`. A current physical `targetId` may replace `mainFrameId`.
+Identity must come from the current browser target. When both are given, the host verifies both. Target-ID-only mode requires host target verification support.
+URL narrows candidates but cannot alone prove page identity.
+This callback and `listBrowsers` must be reentrant while `handleAction` awaits enhancement, without acquiring that operation's lock or claiming user pages.
+
+Calls may carry the original request's absolute `deadline`, outside the business payload. Binding handles are scoped to pages, connection generations, and allowed actions;
+process restarts or page identity changes require revalidation. After a mutation response is lost, later writes are isolated and cannot be replayed or rerouted through ordinary actions.
+Explicit rebinding only revalidates identity; the execution host must resolve environment recovery conflicts that remain unconfirmed.
+
+## Installed App resources
+
+External-control Providers can read locally accepted App definitions and runtimes using
+`createProviderAppResourceClient(providerId, browserId)`. `catalog(params?, deadline?)` returns catalog summaries only;
+`resolve({providerTabId, profile, options?}, deadline?)` revalidates page control and identity, then returns compiled configuration,
+capability/installation revisions, and exact runtime bindings and source. It does not install pages or execute business host services.
+
+The full Native capability service resolves resources; Skill catalogs read registered snapshots without re-executing source files for discovery.
+A resource protocol declaration only indicates an available reader. Explicit reads refresh and validate installation; slow or failed module initialization does not block ordinary Provider control-host startup.
+Profiles containing bridges or globals without an explicit runtime use installed `app.defaultPageRuntime`. Missing runtimes are rejected,
+without downgrading the profile into a fully prepared UA configuration. The SDK rechecks definition revisions, page proof, and source SHA-256.
+The separate resource message limit is 16 MiB to accommodate JSON-encoded runtimes; ordinary enhancement remains limited to 1 MiB.
+
+Providers store and reference verified code within their own instance/page scopes, preserving existing quotas and cleanup rules.
+A Space listing is not the full physical browser target list and cannot justify reclaiming others' resources.
+Obtaining resources does not establish backend support for root containers, bridge callbacks, or real authorization. Advertise App capabilities only after individual verification.
+Hosts without the resource protocol declaration reject explicitly, without falling back to ordinary actions or arbitrary Node execution.

package/README.zh-CN.md

@@ -0,0 +1,248 @@
+# @mearl/provider
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+`@mearl/provider` 是 Mearl 的统一浏览器 Provider 契约与运行时。内置 Local Chrome 和外部
+Provider 使用相同的 `BrowserProviderDefinition`；区别只在于运行时位于 Native Host 进程内，
+还是通过本地 Provider Socket 接入。
+
+action 清单直接复用 `@mearl/browser-core/browserActionProtocol` 的能力动作合同，不维护独立生成副本。
+
+## 核心模型
+
+默认由 Mearl 管理控制会话。Provider 继续接收目标实例、页面与普通 action，无需处理控制会话 ID、资源归属或人工交接状态。带 `--session` 的释放只结束 Mearl 任务控制；实例关闭、退出接管与 Cookie 同步仍使用 Provider 的生命周期方法。上传与下载分别按 `capabilities.actions` 中的 `page_upload`、`page_download` 声明使用。
+
+普通 action 响应中的 `session` 由 Mearl 附加，只包含路由与控制状态；`browser_control` 交接时还包含会话页面清单。`page_snapshot` 的文本 ref 可直接用于后续操作，Provider 应在自身运行时保存其定位映射，不在响应中输出内部节点 ID 字典。
+
+`page_upload` 接收执行宿主上的 `filePaths`，Mearl 负责中转调用方文件与浏览器产物。`page_download` 接收 `{ tabId, trigger, url?, timeout? }`；Provider 先监听下载，再执行点击，等待文件完成后返回 `ProviderDownloadResult`：`{ filename, filePath, action, owned? }`。`filePath` 是本地 Provider 进程宿主上的绝对路径，云端文件由 Provider 取回；`action` 是点击结果，`owned:true` 允许 Mearl 在导入后删除该中转文件。Mearl 将结果转为统一的浏览器产物，支持调用方保存、后续上传与会话清理。下载超时或来源不确定时返回错误，不重复点击。
+
+Provider v2 分开表达实例状态与控制方式：
+
+- `status`：实例处于 `connected`、`pairing`、`running_disconnected` 或 `stopped`。
+- `control`：页面操作由 Provider 自己处理、由宿主的 Extension/CDP 处理，或当前没有控制通道。
+
+实例还会声明 `ownership`、`persistence`、当前允许的资源 `operations`、稳定
+`references` 和可公开展示的 `details`。因此 Provider identity 不再等同于控制传输，持久化实例
+也不需要伪装成已连接浏览器。
+
+## 外部 Provider 安装
+
+外部 Provider 包将 `@mearl/provider` 声明为运行依赖：
+
+```bash
+pnpm add @mearl/provider
+```
+
+包的 `package.json#mearl.provider` 声明协议入口、浏览器类型和结构化启动参数：
+
+```json
+{
+  "name": "@example/mearl-provider-device",
+  "version": "1.0.0",
+  "type": "module",
+  "mearl": {
+    "provider": {
+      "providerId": "example-device",
+      "name": "Example device provider",
+      "protocolVersion": 3,
+      "entry": "./dist/runtime.js",
+      "browserType": {
+        "name": "Device",
+        "help": ["Pair a device, then use its browserId with Mearl actions."],
+        "inputSchema": {
+          "type": "object",
+          "properties": {
+            "code": {
+              "type": "string",
+              "title": "Pairing code",
+              "placeholder": "Generated by default"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Schema 支持 string、number、boolean、array 和递归 object；Provider 配置也可通过
+`browserType.configuration.inputSchema` 声明。`browserType.help` 由 `mearl <providerId>` 和
+`mearl <providerId> --help` 展示，让 Provider 的操作说明随独立包版本演进。同名 Skill 插件已注册时，
+CLI 会在其后自动追加插件命令摘要，Provider 不需要在 `browserType.help` 中重复维护命令清单。
+`local` 是内置保留 ID。
+
+## 最小外部运行时
+
+```ts
+import { createProviderServer, type BrowserProviderDefinition } from '@mearl/provider';
+
+const definition: BrowserProviderDefinition = {
+  descriptor: {
+    providerId: 'example-device',
+    name: 'Example device provider',
+    version: '1.0.0',
+  },
+  browserType: {
+    name: 'Device',
+    inputSchema: {
+      type: 'object',
+      properties: { code: { type: 'string', title: 'Pairing code' } },
+    },
+  },
+  launch: async options => createDevice(String(options.code ?? '')),
+  close: async ({ browserId }) => removeDevice(browserId),
+  handleAction: async ({ browserId, action, data }) =>
+    dispatchDeviceAction(browserId, action, data),
+};
+
+const server = createProviderServer({ definition });
+await server.start();
+server.updateBrowsers([
+  {
+    browserId: 'device-1',
+    name: 'Example device',
+    status: 'connected',
+    control: {
+      kind: 'provider',
+      capabilities: {
+        actions: ['tab_list', 'page_snapshot', 'page_click'],
+        screenshot: 'none',
+      },
+    },
+    ownership: 'owned',
+    persistence: 'persistent',
+    operations: ['close'],
+  },
+]);
+```
+
+配对中的设备使用 `status: "pairing"` 并提供 `pairing`；停止的持久化实例使用
+`status: "stopped"` 和 `control: { kind: "none" }`。运行但尚未接通控制链路时使用
+`status: "running_disconnected"`。
+Runtime 会统一校验 schema、状态机、操作能力和页面 action capability，校验通过后才调用实现。
+`capabilities.actions` 应明确列出适配器已经实现并验证的动作，避免通过全量动作减排除项生成清单，使 SDK 新增动作被误报为可用。适配器转发请求时，只有能证明请求尚未发送的连接失败才可自动重连重试；已经发送、响应丢失或业务执行失败的动作不应自动重放。
+`start`、`detach`、`getAccess`、`syncCookies` 等可选实现必须与实例声明的 operation 对应；
+这些生命周期方法由 Provider runtime 协调，浏览器动作使用统一的 Mearl 协议。
+
+公共 `browser_launch` 对所有 Provider 接收 `{ provider, providerOptions }`，返回与
+`browser_list.browsers[]` 相同的 `ManagedBrowserInfo`（对象形式的 Provider identity、状态、
+持久化策略、操作和安全元数据）。管理器内部字段、控制连接和临时访问地址不进入该结果。
+Local 的 CLI 顶层参数是便捷输入；外部 Provider 参数必须放在 `providerOptions`，两者不得混用。
+
+内置浏览器保留本地启动交互；外部 Provider 根据 `browserType.inputSchema` 生成输入项。
+两者提交同一结构的 `providerOptions`。
+Schema 的顶层 `oneOf` 可声明多个完整对象约束，
+例如创建与接管会话；每个分支用 `title` 命名，Runtime 要求输入恰好匹配一个分支，
+`not` 可排除不允许的字段组合。`default` 是表单初始值，不会隐式修改调用方参数。
+对象字段 `copyCookieDomains` 约定使用 `{ presets?, domains? }` Cookie 范围结构。
+为这个字段声明 `component: "cookie-sync"` 后，Mearl 浏览器管理器会使用统一的 Cookie
+范围选择组件，并在提交前申请所选站点权限；未声明组件时仍按普通 object 字段渲染。
+Provider 可用 `component: "switch"` 渲染紧凑布尔开关；`formHidden` 隐藏仅供 CLI/API
+使用的高级字段，`formWidth` 控制字段宽度，`formDefault` 设置不影响运行时默认值的表单初值，
+`formHideOptional` 只隐藏可选标识而不改变校验，`formVisibleWhen` 根据另一个字段是否为空控制显示与提交。
+`browserType.documentationUrl` 声明 HTTP(S) 文档地址；`configuration.inputSchema` 声明配置参数，
+配置只传给所选 Provider 的 `configure`，不存入页面本地存储。
+
+Provider 需要查询设备池、已有会话或动态候选项时，声明 `browserType.dynamicLaunchForm: true`
+并实现只读的 `getLaunchForm({ variant?, values }, context)`。
+`browserType.launchForm` 可提供无网络依赖的初始表单，弹窗立即渲染其字段和模式；
+各 `variants[]` 可用 `inputSchema/values/refreshOn/dynamicFields` 覆盖该模式的初值。
+`dynamicFields` 指定异步查询期间需要禁用的字段，其余字段与模式选择保持可操作；加载状态在表单状态行显示。
+初次查询携带静态表单默认值；查询只传入可解析的字段，最终启动仍严格校验全部输入。
+用户在等待期间输入的内容会保留，切换模式或环境会使旧请求失效。
+管理器通过内部
+`browser_providers` 的 `launch_form` operation 获取 `ProviderLaunchForm`，不识别 Provider ID 或业务字段：
+
+- `inputSchema` 描述当前模式的用户输入，`required` 决定必填标识与提交校验。
+- `variants` 的 `id/title/description` 描述连接方式，`variant` 指定当前方式。
+- `values` 是 Provider 给出的固定启动参数，提交时与用户输入合并；只包含非敏感参数。
+- 字符串字段的 `options` 使用 `{ value, label, description?, disabled? }` 描述候选项。
+  禁用项只供展示；运行时的最终资源状态由 Provider 的 `launch` 再次核验。
+- `refreshOn` 指定需要重新查询表单的字段；字段变化会清空其他选项字段的选择。
+  刷新时保留已有输入，选项字段仅保留仍有效的选择；切换模式重新使用该模式默认值。
+- `message` 展示查询结果，`blocked` 阻止无资源、无有效会话等情况下的提交。
+
+查询过程不得创建或租用资源，也不得返回凭据。Runtime 会校验返回的 schema、候选项、
+模式与固定参数。最终 `launch` 仍使用 `browserType.inputSchema` 校验，动态表单不改变 CLI/API
+参数契约。未声明动态表单的 Provider 继续使用静态 schema。
+开发联调时，Provider 应链接包含该公开契约的本地 `@mearl/provider` 构建；分发时需配套发布
+包含动态表单能力的 SDK、Mearl 宿主与 Provider。
+
+`details` 中的通用键具有固定类型：`headless` 为布尔值，`createdAt` 为可解析时间字符串，
+`cdpPort` 为有效端口，`account` 包含 `nickname` 和可选的字符串 `accountId/loginId`，
+`copiedCookies` 包含字符串数组 `domains` 和非负整数 `count`。其余键允许非敏感 JSON，界面同样展示。
+`references` 的 `kind` 表示资源类别，`id` 为不透明标识，`label` 为展示名；
+通用类别包括 `profile/session/image/context/context-name`，也允许 Provider 自定义类别。
+
+## 内置运行时
+
+Native Host 使用 `createProviderRuntime(definition)` 直接运行内置 Local Provider，不需要创建 Socket
+或注册安装记录。内置与外部实现共享同一份 schema 校验、状态机和生命周期派发逻辑；需要宿主服务的进程内调用可通过 `ProviderContext.host` 注入，Provider 合同本身不依赖 Extension、Native Messaging 或
+具体浏览器服务 SDK。
+
+指定 Provider 的启动、配置和动态表单查询只启动该 Provider；完整浏览器发现仍检查所有已安装 Provider。Mearl 的 Provider 控制宿主按调用方绝对期限管理排队及后续动作，旧调用方使用按动作推导的等待时间，持久化关闭和长时间等待不受固定两分钟限制。适配器自己的转发链路也应覆盖对应动作的时间预算，并在等待失败时保留执行结果不确定的语义。
+
+外部 Provider 的安装、发现与启动仍由 `@mearl/setup` 管理：
+
+```bash
+npx @mearl/setup provider install <package>
+npx @mearl/setup provider update <provider-id>
+npx @mearl/setup provider uninstall <provider-id>
+```
+
+## Socket 协议
+
+当前 Provider 协议版本为 **3**，请求 envelope 携带 `protocolVersion`。安装元数据、
+运行时 descriptor、运行中进程与调用方必须使用相同协议；不匹配时更新相关包并重启进程。
+
+- `browser_providers`：`operation: "configure"` 携带 `options`，`operation: "launch_form"` 携带 `variant?` 和 `values`。
+- `browser_instances`：`operation: "start" | "detach" | "sync_cookies"`；同步携带 `scope`，目标实例由 envelope 的 `browserId` 选择。
+- `browser_launch`、`browser_close`、`get_browser_access_url` 保留各自职责。
+- `browser_sessions` 由 Mearl 控制进程处理，不转交外部 Provider；会话释放与实例 `detach` 分开执行。
+
+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;