Skip to content

refactor(provider-webdriver): ship BrowserStack as the @agent-device/browserstack plugin #3309

Closed

Description

@thymikee

Purpose and evidence

0.22 stops bundling hosted device providers with the default installation. BrowserStack already presents the plugin factory shape inside core: packages/provider-webdriver/src/browserstack-provider.ts returns { webDriver, connection } next to a manifest-shaped declaration (CLOUD_WEBDRIVER_PROVIDER_DECLARATIONS in providers.ts), composed through the same route an installed WebDriver plugin uses (PR #3312). TestMu (packages/provider-testmu, #3118) is the packaging template: bundled ESM, agentDevicePlugin manifest, ./connection-verification subpath, test/package-smoke.mjs, release through scripts/release-workspace.mjs.

Final 0.22 delivery contract

For BrowserStack (@agent-device/browserstack), follow the maintainer decision and shared acceptance in #4591. Core may retain only declarative help/docs/schema/catalog and installation-guidance metadata. Do not ship the plugin factory, executable implementation, plugin-only workers or dedicated runtime dependencies in the core npm package. Lazy-loading code that remains in the tarball is not extraction.

Plugin code is installed separately, on demand, by the existing agent-device plugin manager. T3 Code and e2e must use that shared installation/selection lifecycle and machine-readable inventory/recovery, rather than bespoke npm commands or private-store manipulation. Keep current v2 factories and ./agent-device; older manifest/static-registration examples below describe historical preparation and do not override this final distribution contract. Preserve independently required core contracts and local-device code.

Required behavior and boundary

  • New workspace package packages/provider-browserstack publishing @agent-device/browserstack, versioned with core, built with tsdown like TestMu. Its default export is (host: ProviderPluginHost) => { webDriver, connection }; the manifest declares provider: "browserstack", the connection capabilities and credentialVariables: ["BROWSERSTACK_USERNAME", "BROWSERSTACK_ACCESS_KEY"] exactly as CLOUD_WEBDRIVER_PROVIDER_DECLARATIONS does today.
  • Move the BrowserStack modules out of provider-webdriver (browserstack.ts, browserstack-provider.ts, browserstack-connection.ts, browserstack-connection-verification.ts, browserstack-device-features.ts, their tests, and the bs:// helpers from providers.ts). provider-webdriver keeps the shared engine and the ./plugin surface only.
  • Core drops browserstack from BUNDLED_CLOUD_WEBDRIVER_PROVIDERS and from RESERVED_PLUGIN_PROVIDERS; the connect route, credential fingerprint, and daemon composition keep working through the plugin manifest with no provider-name branch left in src/.
  • agent-device connect browserstack without the plugin fails with the existing unknown-provider error naming plugins add @agent-device/browserstack; help, website/docs/docs/browserstack.md, device-clouds.md, plugins.md ("remain bundled"), and the README move the provider to the plugin install flow.
agent-device plugins add @agent-device/browserstack
export BROWSERSTACK_USERNAME=... BROWSERSTACK_ACCESS_KEY=...
agent-device connect browserstack --platform android --device "Google Pixel 8" --provider-os-version 14.0 --provider-app bs://app-id

Completion and validation

  • node scripts/check-provider-plugin.mjs packages/provider-browserstack passes (packed install, host-recognized errors, CLI connect).
  • The published name drops the provider- prefix and the directory keeps it. packages/provider-browserstack/package.json declares "name": "@agent-device/browserstack". The provider plugin catalog (src/commands/provider-plugin-catalog.ts), help, docs, and every plugins add example use that name. This is the convention that packages/provider-testmu (@agent-device/testmu) and packages/provider-revyl (@agent-device/revyl) follow.
  • Provider-scenario integration tests that today build the BrowserStack runtime through createBundledCloudWebDriverRuntimes run the plugin factory through createCloudWebDriverRuntime the way the TestMu scenarios do.
  • pnpm check:affected --run passes; the Size report shows the default install shrinking by the BrowserStack modules; eager-closure budgets need no approval row.
  • One live BrowserStack session (connect, open, snapshot, close, artifacts) with the packed plugin, recorded in the PR.

Dependencies and readiness

Blocked by: #3312 landing on main. Sibling: the AWS Device Farm and Limrun extractions in this milestone; land this one first, it needs no plugin-host change.

Effort: M. Risk: low (shape already proven by TestMu; user-visible change is the install step).

Activity

  1. added this to the 0.22 milestone on Oct 7, 2026
  2. thymikee commented on Nov 16, 2026

    @thymikee
    MemberAuthor

    Decision: plugin distribution: final 0.22 extraction means separate agent-device-managed installation, not merely lazy loading. Core retains declarative help/docs/catalog metadata, with no shipped plugin implementation or dedicated dependency closure. T3 Code and e2e use the same management owner and observable install/selection/recovery contract. The issue body now states this explicitly; #4591 owns shared consumer acceptance and the approximately 3 MB unpacked-core target. Earlier seam-only/static-registration or v1 manifest wording is historical preparation, not the final requirement. Existing extraction owners, sequencing, host/session ownership and publication prerequisites remain in force.

  3. apex-sentinel-staging commented on Nov 16, 2026

    @apex-sentinel-staging

    Apex Sentinel · Issue review

    Suggested label: feature

    The issue describes a concrete packaging refactor to extract BrowserStack from provider-webdriver into a separate @​agent-device/browserstack plugin and update the core/plugin lifecycle, docs, and tests. It has specific implementation requirements and validation steps, making it an actionable enhancement rather than a bug report or question.

    Possible duplicates

  4. thymikee commented on Nov 20, 2026

    @thymikee
    MemberAuthor

    Done on 0.22: #4579 extracted BrowserStack as the @agent-device/browserstack plugin and removed the bundled provider. Live evidence is in the PR body (packed install through the plugin manager, connect, open and a snapshot on a physical iPhone 15). The published nightly was installed and activated by a clean consumer (see the #4591 status comment of 2026-11-18). Final publication with the 0.22 release is tracked in #4591.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions