Turn an external browser platform or control SDK into an installable, observable, and verifiable Mearl Browser Provider. The user only needs to provide the target platform or code, the usage scenarios they want supported, and how the necessary credentials will be supplied; the Agent is responsible for completing the contract design, implementation, and verification.
Before creating or substantially modifying a Provider, read Provider contract. Then confirm the current contract from the @mearl/provider package actually installed in the target project, its exported types, and the documentation shipped with the package; if the user provides a workspace containing Mearl Provider source code, locate the corresponding package via the package manifest or module resolution, and do not assume it is in some fixed directory. When the public contract actually depended on differs from the reference, the actually depended-on version takes precedence, and avoid using internal interfaces that exist only in unreleased source code.
Inputs and artifacts
Derive the Provider ID, package name, target directory, lifecycle semantics, control method, supported actions, and input schema from the SDK, API documentation, existing package, or Provider directory. Modify an existing Provider incrementally in its real directory. When creating a new one, prioritize the location specified by the user; otherwise, choose a non-conflicting directory based on the workspace configuration and package layout already present in the current workspace, and only ask for the output directory if no unique location can be determined from them. Do not assume the project is a monorepo, and do not presuppose packages/、providers/ or any other parent directory.
By default, produce a standalone npm package containing package.json#mearl.provider, the Provider runtime, the necessary SDK adapter, and tests. Create only the files actually needed for operation; do not add placeholder implementations or documentation unrelated to Provider distribution.
Workflow
- Inspect the package structure, version, lifecycle API, identity, and credential sources of the target SDK or existing Provider. Do not claim capabilities that cannot be confirmed from code or official documentation.
- First determine the browser instance's state, control method, ownership, persistence strategy, and allowed operations, then implement the manifest and runtime. Do not hide pairing, stopped, or disconnected states behind a single
connectedboolean value. - Make
browserType.inputSchemaconsistent with the real creation parameters; Provider-specific configuration usesbrowserType.configuration.inputSchema. Write the pairing, billing, login-state, and cleanup rules that users need to understand intobrowserType.help。 - Use
BrowserProviderDefinitionto implementlistBrowsers、launch、closeand the optional lifecycle methods that are actually needed. Only implementcontrol.kind: "provider"forhandleAction, and declare only capabilities that have been verified end to end. - Use the Provider instance list as the single source of truth, and publish a complete snapshot via
server.updateBrowsers()after the server starts and after every observable state change.definition.listBrowsersis only for the Provider runtime to query and validate; it will not automatically update the Mearl host'sbrowser_list; both polling and SDK events must land in the same snapshot before being published. - Prefer reading the runtime descriptor from
package.json#mearl.providerto avoid manually writing the IDs, protocol, version, and schema twice. Verify that the build artifacts can independently resolve all runtime dependencies and that the manifest'sentryis actually packaged, then run the package-level tests, typecheck, and build. Do not hide contract errors by disabling validation or widening types. - First run the Provider runtime directly to verify the schema, instance creation and listing, one real action, and the shutdown flow. Once the package has been published to a registry source accessible to the current user, install it through Mearl and verify the Provider help,
browser_launchandbrowser_list; do not publish the package on your own just to complete installation verification. If verification requires creating billable resources, scan-code pairing, deleting data, or providing credentials, stop before that action and ask the user to intervene.
Implementation constraints
providerIdUse a stable kebab-case identifier that does not conflict with the built-inlocal; the instancebrowserIdonly needs to be stable within that Provider.operationsDeclare only the operations that the current instance genuinely allows and the Provider has implemented, and map them to the corresponding methods per the Runtime:start、detach、syncCookiescorrespond respectively to the methods of the same name,accesscorresponds togetAccess,closeanddeleteDataare both handled byclose. A stopped persistent instance may declarestart; ephemeral instances should not masquerade as recoverable resources.detailsandreferencesreturn only presentable, non-sensitive JSON. Credentials do not enter the Provider list; temporary access addresses are returned only throughgetAccessand markedsensitive: true。- Shutdown, release, data deletion, and Cookie sync are distinct semantics. Choose the implementation based on the user request and platform contract; do not incidentally delete persistent data during an ordinary shutdown.
- External CLIs, system services, or non-npm runtime environments are explicitly prepared by a companion installation entry point; the Provider's load and help phases must not silently install anything. When missing, return an error containing an executable remediation command; a companion Skill or plugin may provide idempotent
setupand read-onlydoctor。 - When the Provider process exits, close the local server, connections, and timers; unless the platform contract explicitly defines process exit as resource shutdown, do not secretly equate signal handling with
close, releasing leases, or deleting remote resources. - When upgrading an existing Provider, preserve the user-visible Provider ID, input fields, and instance semantics; make breaking changes only when a real platform contract or user goal requires it.
Verification and delivery
Unit tests cover at least schema validation, creation and listing consistency, status and control combinations,server.updateBrowsers() publication timing, operation-to-implementation mapping, rejection of undeclared actions, and sensitive metadata boundaries. Use the package manager, test, typecheck, and build commands already declared by the Provider package and its workspace; when no scripts exist, run equivalent checks based on the actual toolchain, and do not assume pnpm, fixed package names, or repository-level test projects exist.
When delivering, state the Provider path, control method, implemented lifecycle and actions, installation and invocation examples, verification results, and any end-to-end steps not yet completed due to credentials, pairing, billing, or the external environment. Do not present "compiles successfully" as "platform integration verified".