From b1bc37bc8c452bceea35c9c81a48166eaa11356c Mon Sep 17 00:00:00 2001 From: Thymikee Tweseling Date: Fri, 13 Nov 2026 10:57:22 +0000 Subject: [PATCH 1/3] refactor(plugins): remove the version 1 provider plugin contract (#3759) Drop the v1 loader adapter, the manifest-driven discovery and store branches, the manifest credential and connection fallbacks, and the install-time provider collision checks. A store package is discovered through its exports only, and everything it declares comes from the object its factory returns. The registry settles a duplicate provider id by first claim. Remove the v1 entries and manifest declarations from TestMu AI and Revyl, and document the migration to an AgentDevicePluginFactory in ./agent-device. --- .changeset/remove-provider-plugin-v1.md | 9 + .fallowrc.json | 7 +- docs/adr/0034-provider-plugin-registry.md | 17 +- packages/plugins/package.json | 4 - packages/plugins/src/connection.ts | 19 +- packages/plugins/src/contract.ts | 3 + .../plugins/src/credential-fingerprint.ts | 14 +- packages/plugins/src/discovery.test.ts | 67 ++++++- packages/plugins/src/discovery.ts | 48 +++-- packages/plugins/src/legacy.ts | 90 --------- packages/plugins/src/load.test.ts | 122 +++++------- packages/plugins/src/manifest.test.ts | 90 --------- packages/plugins/src/manifest.ts | 118 ------------ packages/plugins/src/registry.ts | 6 +- packages/plugins/src/store-legacy.ts | 83 -------- packages/plugins/src/store.test.ts | 178 +++++++++++------- packages/plugins/src/store.ts | 113 ++++++----- packages/plugins/src/validate.ts | 47 ++++- packages/provider-revyl/package.json | 19 -- packages/provider-revyl/src/plugin.ts | 21 --- packages/provider-revyl/tsdown.config.ts | 2 +- packages/provider-testmu/package.json | 18 -- packages/provider-testmu/src/index.test.ts | 21 ++- packages/provider-testmu/src/plugin.test.ts | 68 ------- packages/provider-testmu/src/plugin.ts | 8 - packages/provider-testmu/tsdown.config.ts | 2 +- packages/provider-webdriver/src/providers.ts | 4 +- packages/test-kit/src/index.ts | 4 - packages/test-kit/src/plugin.fixtures.ts | 156 +++++---------- scripts/release-workspace.mjs | 5 +- src/__tests__/cloud-connect-testmu.test.ts | 21 +-- .../provider-device-runtimes.test.ts | 30 ++- src/builtin-provider-ids.ts | 2 +- .../__tests__/connection-revyl.test.ts | 31 +-- src/cli/commands/__tests__/plugins.test.ts | 26 ++- src/cli/commands/plugins.ts | 7 +- src/cli/connection/provider-policy.test.ts | 87 ++++----- src/provider-credential-fingerprint.test.ts | 139 +++++++++----- src/provider-plugin-policy.test.ts | 12 +- website/docs/docs/plugins.md | 27 ++- 40 files changed, 676 insertions(+), 1069 deletions(-) create mode 100644 .changeset/remove-provider-plugin-v1.md delete mode 100644 packages/plugins/src/legacy.ts delete mode 100644 packages/plugins/src/manifest.test.ts delete mode 100644 packages/plugins/src/manifest.ts delete mode 100644 packages/plugins/src/store-legacy.ts delete mode 100644 packages/provider-revyl/src/plugin.ts delete mode 100644 packages/provider-testmu/src/plugin.test.ts delete mode 100644 packages/provider-testmu/src/plugin.ts diff --git a/.changeset/remove-provider-plugin-v1.md b/.changeset/remove-provider-plugin-v1.md new file mode 100644 index 0000000000..70d52b3993 --- /dev/null +++ b/.changeset/remove-provider-plugin-v1.md @@ -0,0 +1,9 @@ +--- +'agent-device': minor +'@agent-device/testmu': minor +'@agent-device/revyl': minor +--- + +Remove the version 1 provider plugin contract. A store package is now discovered only through its exports: `./agent-device`, or the package root when that subpath is absent. The host no longer reads an `agentDevicePlugin` manifest to choose an entry or to declare a provider, connection capabilities, or credential variables, and `agent-device plugins add` no longer refuses a package for a provider another manifest claims — the registry settles a duplicate provider id when the daemon next composes its plugins, as the first claim wins. + +Migrate a plugin by exporting its factory from `./agent-device` and returning the manifest's values from the factory: `provider`, `credentials: { variables: [...] }`, an optional `connection`, and `setup(host)` that returns `{ runtime, platformModule }` or `{ webDriver }`, with `apiVersion: 2`. See [Provider plugins](/docs/plugins) for the full migration. A package whose default export is not a version 2 plugin is listed as `failed` with `incompatible_plugin` and the daemon starts without it. diff --git a/.fallowrc.json b/.fallowrc.json index c1d92c5396..fb4d7c381d 100644 --- a/.fallowrc.json +++ b/.fallowrc.json @@ -152,15 +152,10 @@ "exports": ["*"] }, { - // A published provider package's default export is its plugin contract; packages/plugins/src/load.ts imports the package by name at runtime and reads `default`. + // A published provider package's default export is its plugin contract; the plugin loader imports the installed package's resolved entry at runtime and reads `default`. "file": "packages/provider-*/src/index.ts", "exports": ["default"] }, - { - // The version 1 entry a provider package's `agentDevicePlugin.entry` names; hosts without the version 2 contract import the built file and read `default`. - "file": "packages/provider-*/src/plugin.ts", - "exports": ["default"] - }, { // packages/platform-apple/src/lifecycle.ts loads this module on demand and reads the member off the memoized import() promise, which Fallow cannot follow. "file": "packages/platform-apple/src/expo-dev-client-launch.ts", diff --git a/docs/adr/0034-provider-plugin-registry.md b/docs/adr/0034-provider-plugin-registry.md index 6c3d1bc277..52a0d539de 100644 --- a/docs/adr/0034-provider-plugin-registry.md +++ b/docs/adr/0034-provider-plugin-registry.md @@ -23,10 +23,9 @@ Status: accepted. Umbrella #3747; contract and registry #3755. - `daemon.json` has one reader. Its states are `absent`, `unreadable`, and `invalid`. A missing or stale record reads as a stopped daemon; an unreadable or invalid one never does. - The plugin set is fixed for a daemon's lifetime. A plugin change takes effect on the next daemon. -- v1 plugins (`agentDevicePlugin.apiVersion: 1`) without a `./agent-device` export are dispatched by - their manifest before any code runs and load through an adapter until 0.22 removes them (#3759). - A package that keeps the manifest and also exports `./agent-device` loads as v2; hosts without - v2 still read the manifest. +- A store package is discovered only through its exports: `./agent-device`, or the package root when + that subpath is absent. Nothing is read from `package.json` to choose an entry or to declare a + provider, connection capabilities, or credential variables (#3759). ## Context @@ -44,17 +43,15 @@ had to fake the store to load a plugin from its own dependencies (#3747). fingerprint. - **A package exports its entry as `./agent-device`.** The host resolves it with import conditions and falls back to the package root only when the subpath is absent. A subpath whose - import or setup throws never falls back. A v2 package needs no manifest. + import or setup throws never falls back. A plugin package needs no manifest. - **The registry owns identity, not the retired lists.** Duplicate ids and bundled ids are one question answered by claim order. Credential variables, per-backend narrowing and connect - capabilities are read from the registry's plugins, not from manifests. A v1 manifest still - supplies them for a v1 plugin. + capabilities are read from the registry's plugins, not from manifests. - **Failure is data.** A failed plugin is an inventory entry, not an exception. Behavior keys on `error.reason`, never on the message. - **A client reads a daemon's inventory from `daemon.json`.** The client credential fingerprint - takes variable names from it and falls back to v1 manifests. A v2 plugin declares its connect - capabilities in code, so a client loads the store, without setting up a runtime, before it reads - them. + takes variable names from it. A v2 plugin declares its connect capabilities in code, so a client + loads the store, without setting up a runtime, before it reads them. ## Daemon ownership diff --git a/packages/plugins/package.json b/packages/plugins/package.json index 319a6e2fb0..a5d803b8fc 100644 --- a/packages/plugins/package.json +++ b/packages/plugins/package.json @@ -30,10 +30,6 @@ "types": "./src/load.ts", "default": "./src/load.ts" }, - "./manifest": { - "types": "./src/manifest.ts", - "default": "./src/manifest.ts" - }, "./registry": { "types": "./src/registry.ts", "default": "./src/registry.ts" diff --git a/packages/plugins/src/connection.ts b/packages/plugins/src/connection.ts index 021c297ce0..7012d89711 100644 --- a/packages/plugins/src/connection.ts +++ b/packages/plugins/src/connection.ts @@ -2,7 +2,7 @@ import type { ConnectionProviderCapabilities } from '@agent-device/contracts/rem import { resolveUserConfigPath } from '@agent-device/host-kit/file'; import type { PluginInventoryEntry } from '@agent-device/contracts/plugin-inventory'; import type { PluginConnection, PluginConnectionContext } from './contract.ts'; -import { legacyStoreManifests, storePluginCandidates } from './store.ts'; +import { storePluginCandidates } from './store.ts'; /** A plugin's connection as the client calls it: the registry adds the `host` to each context. */ export type PluginConnectionCallbacks = Readonly<{ @@ -15,10 +15,9 @@ export type PluginConnectionCallbacks = Readonly<{ export type RegisteredConnection = PluginConnectionCallbacks & Readonly<{ capabilities: PluginConnection['capabilities'] }>; -// Capabilities live in the plugin, so a v2 store plugin answers only once its package has loaded. -// A client loads the store once per process through primePluginConnections; every synchronous -// reader below then answers from that registry alone. Before the store is primed, a v1 plugin -// answers from its manifest. +// A plugin declares its connection capabilities in code, so a store plugin answers only once its +// package has loaded. A client loads the store once per process through primePluginConnections; +// every synchronous reader below then answers from that registry alone. export type FailedPlugin = Extract; type PrimedStore = Readonly<{ @@ -69,16 +68,10 @@ export function pluginConnectionCapabilities( env: NodeJS.ProcessEnv, ): ConnectionProviderCapabilities | undefined { if (provider === undefined) return undefined; - const store = primed.get(resolveUserConfigPath(env)); - if (store) return store.connections.get(provider)?.capabilities; - return legacyStoreManifests(env).find((plugin) => plugin.agentDevicePlugin.provider === provider) - ?.agentDevicePlugin.connection; + return primed.get(resolveUserConfigPath(env))?.connections.get(provider)?.capabilities; } export function pluginConnectionNames(env: NodeJS.ProcessEnv): string[] { const store = primed.get(resolveUserConfigPath(env)); - if (store) return [...store.connections.keys()]; - return legacyStoreManifests(env) - .filter((plugin) => plugin.agentDevicePlugin.connection) - .map((plugin) => plugin.agentDevicePlugin.provider); + return store ? [...store.connections.keys()] : []; } diff --git a/packages/plugins/src/contract.ts b/packages/plugins/src/contract.ts index 956645453a..99037cddae 100644 --- a/packages/plugins/src/contract.ts +++ b/packages/plugins/src/contract.ts @@ -9,6 +9,9 @@ import type { ProviderPluginHost } from './host.ts'; /** The provider plugin contract version this module defines. */ export const PROVIDER_PLUGIN_API_VERSION = 2; +/** Provider ids that name daemon routing; no plugin can claim either of them. */ +export const ROUTING_PROVIDER_IDENTITIES: readonly string[] = ['cloud', 'proxy']; + /** * The environment variables a plugin reads credentials from. The host fingerprints their values to * refuse a lease when the shell holds different credentials than the daemon started with. List diff --git a/packages/plugins/src/credential-fingerprint.ts b/packages/plugins/src/credential-fingerprint.ts index f2797cd046..3249ecaf56 100644 --- a/packages/plugins/src/credential-fingerprint.ts +++ b/packages/plugins/src/credential-fingerprint.ts @@ -4,7 +4,6 @@ import { type PluginInventoryEntry, } from '@agent-device/contracts/plugin-inventory'; import type { EnvMap } from '@agent-device/kernel/source-value'; -import { legacyStoreManifests } from './store-legacy.ts'; type CredentialValues = Readonly>; @@ -12,7 +11,7 @@ type CredentialValues = Readonly>; * A versioned, non-reversible digest of the credentials a lease on `leaseBackend` reads from `env`, * or undefined when `env` holds none of them or the provider's credentials do not come from the * environment. Provider names are trimmed before lookup. Variable names come from the daemon's - * plugin inventory, then from v1 manifests. + * plugin inventory. */ export function providerCredentialFingerprint( provider: string, @@ -20,7 +19,7 @@ export function providerCredentialFingerprint( leaseBackend?: string, inventory?: readonly PluginInventoryEntry[], ): string | undefined { - const variables = declaredCredentialVariables(provider.trim(), env, leaseBackend, inventory); + const variables = declaredCredentialVariables(provider.trim(), leaseBackend, inventory); // Whitespace-only counts as unset and other values are kept as is, as the provider's requireEnv does. return variables ? digest( @@ -31,17 +30,14 @@ export function providerCredentialFingerprint( : undefined; } -// Read from the inventory or manifest, so neither the client nor the daemon evaluates provider code. +// Read from the inventory the daemon published, so neither the client nor the daemon evaluates +// provider code. function declaredCredentialVariables( provider: string, - env: EnvMap, leaseBackend: string | undefined, inventory: readonly PluginInventoryEntry[] | undefined, ): readonly string[] | undefined { - const published = inventory && pluginCredentialVariables(inventory, provider, leaseBackend); - if (published) return published; - return legacyStoreManifests(env).find((plugin) => plugin.agentDevicePlugin.provider === provider) - ?.agentDevicePlugin.credentialVariables; + return inventory && pluginCredentialVariables(inventory, provider, leaseBackend); } function digest(values: CredentialValues): string | undefined { diff --git a/packages/plugins/src/discovery.test.ts b/packages/plugins/src/discovery.test.ts index ff2299bb0c..2109021ffb 100644 --- a/packages/plugins/src/discovery.test.ts +++ b/packages/plugins/src/discovery.test.ts @@ -120,11 +120,68 @@ test('package export resolution agrees with Node for each shape a plugin package entry.name, ); } else { - assert.deepEqual( - discoverPluginEntry(directory), - { kind: 'v2', file: path.join(directory, entry.loads) }, - entry.name, - ); + assert.equal(discoverPluginEntry(directory), path.join(directory, entry.loads), entry.name); } } }); + +test('a manifest entry never selects the loaded file', () => { + const root = fs.realpathSync(mkdtempForTestSync('agent-device-manifest-entry-')); + const directory = path.join(root, 'node_modules', 'declared'); + fs.mkdirSync(directory, { recursive: true }); + fs.writeFileSync( + path.join(directory, 'package.json'), + JSON.stringify({ + name: 'declared', + version: '1.0.0', + type: 'module', + main: './main.js', + agentDevicePlugin: { apiVersion: 1, provider: 'declared', entry: './legacy.js' }, + }), + ); + for (const file of ['main.js', 'legacy.js']) + fs.writeFileSync(path.join(directory, file), 'export {};'); + + assert.equal(discoverPluginEntry(directory), path.join(directory, 'main.js')); +}); + +test('an entry outside the installed package is refused', () => { + const root = mkdtempForTestSync('agent-device-entry-containment-'); + const outside = path.join(root, 'outside.js'); + fs.writeFileSync(outside, 'export {};'); + + const escaped = path.join(root, 'node_modules', 'traversal'); + fs.mkdirSync(escaped, { recursive: true }); + fs.writeFileSync( + path.join(escaped, 'package.json'), + JSON.stringify({ + name: 'traversal', + version: '1.0.0', + type: 'module', + exports: { './agent-device': './../outside.js' }, + }), + ); + assert.throws( + () => discoverPluginEntry(escaped), + (error: unknown) => + (error as { details?: { reason?: string } }).details?.reason === 'plugin_load_failed', + ); + + const linked = path.join(root, 'node_modules', 'symlinked'); + fs.mkdirSync(linked, { recursive: true }); + fs.writeFileSync( + path.join(linked, 'package.json'), + JSON.stringify({ + name: 'symlinked', + version: '1.0.0', + type: 'module', + exports: { './agent-device': './plugin.js' }, + }), + ); + fs.symlinkSync(outside, path.join(linked, 'plugin.js')); + assert.throws( + () => discoverPluginEntry(linked), + (error: unknown) => + (error as { details?: { reason?: string } }).details?.reason === 'plugin_load_failed', + ); +}); diff --git a/packages/plugins/src/discovery.ts b/packages/plugins/src/discovery.ts index d052660a03..b6df3d27ec 100644 --- a/packages/plugins/src/discovery.ts +++ b/packages/plugins/src/discovery.ts @@ -2,7 +2,6 @@ import fs from 'node:fs'; import path from 'node:path'; import { AppError } from '@agent-device/kernel/errors'; import { isRecord } from '@agent-device/kernel/record'; -import { readPluginManifest, resolvePluginEntry, type PluginManifest } from './manifest.ts'; const PROVIDER_ID = /^[a-z][a-z0-9-]*$/; @@ -10,29 +9,19 @@ export function isProviderId(value: unknown): value is string { return typeof value === 'string' && PROVIDER_ID.test(value); } -/** The subpath a v2 plugin package exports; its default export is the plugin factory. */ +/** The subpath a plugin package exports; its default export is the plugin factory. */ const PLUGIN_ENTRY_SUBPATH = './agent-device'; -export type PluginPackageEntry = - | Readonly<{ kind: 'v2'; file: string }> - | Readonly<{ kind: 'v1'; manifest: PluginManifest }>; - /** - * Chooses how an installed package loads, without evaluating it. The `./agent-device` export wins; - * a package that lacks that subpath and declares `agentDevicePlugin` is a v1 plugin dispatched by - * its manifest; any other package falls back to its root export. A subpath that exists but does - * not resolve is an error, never a reason to fall back. + * Chooses the file an installed package loads, without evaluating it. The `./agent-device` export + * wins; a package that lacks that subpath falls back to its root export. A subpath that exists but + * does not resolve is an error, never a reason to fall back. */ -export function discoverPluginEntry(directory: string): PluginPackageEntry { +export function discoverPluginEntry(directory: string): string { const manifest = readPackageJson(directory); const subpath = resolveExport(manifest.exports, PLUGIN_ENTRY_SUBPATH); - if (subpath.status === 'resolved') { - return { kind: 'v2', file: resolvePluginEntry(directory, subpath.target) }; - } + if (subpath.status === 'resolved') return resolvePluginEntry(directory, subpath.target); if (subpath.status === 'blocked') throw unresolvableEntry(directory, PLUGIN_ENTRY_SUBPATH); - if (manifest.agentDevicePlugin !== undefined) { - return { kind: 'v1', manifest: readPluginManifest(directory) }; - } const root = resolveExport(manifest.exports, '.'); if (root.status === 'blocked') throw unresolvableEntry(directory, '.'); const target = @@ -43,7 +32,30 @@ export function discoverPluginEntry(directory: string): PluginPackageEntry { ? `./${path.posix.normalize(manifest.main)}` : undefined; if (target === undefined) throw missingEntry(directory, PLUGIN_ENTRY_SUBPATH); - return { kind: 'v2', file: resolvePluginEntry(directory, target) }; + return resolvePluginEntry(directory, target); +} + +/** + * The entry a plugin package names: a readable file inside the package directory it is installed + * in. Traversal and a symlink out of that directory are refused. + */ +export function resolvePluginEntry(directory: string, target: string): string { + try { + const root = fs.realpathSync(directory); + const resolved = fs.realpathSync(path.resolve(directory, target)); + if ( + target.startsWith('./') && + resolved.startsWith(`${root}${path.sep}`) && + fs.statSync(resolved).isFile() + ) { + return resolved; + } + } catch {} + throw new AppError('INVALID_ARGS', 'Plugin entry must be a readable file inside its package', { + reason: 'plugin_load_failed', + directory, + entry: target, + }); } export function readPackageJson(directory: string): Record { diff --git a/packages/plugins/src/legacy.ts b/packages/plugins/src/legacy.ts deleted file mode 100644 index 2a61fddea4..0000000000 --- a/packages/plugins/src/legacy.ts +++ /dev/null @@ -1,90 +0,0 @@ -import { pathToFileURL } from 'node:url'; -import { AppError } from '@agent-device/kernel/errors'; -import { isRecord } from '@agent-device/kernel/record'; -import type { EnvMap } from '@agent-device/kernel/source-value'; -import type { ProviderDeviceRuntime } from '@agent-device/contracts/device'; -import { - PROVIDER_PLUGIN_API_VERSION, - type AgentDevicePlugin, - type PluginConnection, - type PluginSetupResult, -} from './contract.ts'; -import { createPluginHost, type ProviderPluginHost } from './host.ts'; -import { resolvePluginEntry, type PluginManifest } from './manifest.ts'; - -type LegacyConnection = Pick; - -/** - * Presents a v1 plugin as a v2 plugin until 0.22 removes v1. The manifest still declares the - * provider, connection capabilities and credential variables, and the v1 factory still runs with - * the host and returns `{ runtime, platformModule }` or `{ webDriver }`, so no v1 plugin changes. - */ -export function adaptLegacyPlugin( - manifest: PluginManifest, - directory: string, - options: Record | undefined, -): AgentDevicePlugin { - const declaration = manifest.agentDevicePlugin; - const runFactory = async (host: ProviderPluginHost): Promise => { - const module = await import( - pathToFileURL(resolvePluginEntry(directory, declaration.entry)).href - ); - if (typeof module.default !== 'function') - throw new AppError('INVALID_ARGS', `Plugin must export a default factory: ${manifest.name}`, { - reason: 'invalid_plugin', - }); - return await (module.default as (host: ProviderPluginHost) => unknown)(host); - }; - const withConnection = async ( - env: EnvMap, - run: (connection: LegacyConnection) => Promise | T, - ): Promise => { - const result = await runFactory(createPluginHost(env, options)); - try { - const connection = isRecord(result) ? result.connection : undefined; - if ( - !isRecord(connection) || - !isFunction(connection.resolve) || - !isFunction(connection.verify) - ) { - throw new AppError( - 'INVALID_ARGS', - `Plugin connection must provide resolve and verify: ${manifest.name}`, - { reason: 'invalid_plugin' }, - ); - } - return await run(connection as LegacyConnection); - } finally { - const runtime = isRecord(result) - ? (result.runtime as ProviderDeviceRuntime | undefined) - : undefined; - if (isFunction(runtime?.shutdown)) await Promise.allSettled([runtime.shutdown()]); - } - }; - return { - apiVersion: PROVIDER_PLUGIN_API_VERSION, - provider: declaration.provider, - credentials: { variables: declaration.credentialVariables ?? [] }, - ...(declaration.connection - ? { - connection: { - capabilities: declaration.connection, - resolve: async (context) => - await withConnection(context.env, (connection) => connection.resolve(context)), - verify: async (context) => - await withConnection(context.env, (connection) => connection.verify(context)), - }, - } - : {}), - setup: async (host) => { - const result = await runFactory(host); - return ( - isRecord(result) && 'webDriver' in result ? { webDriver: result.webDriver } : result - ) as PluginSetupResult; - }, - }; -} - -function isFunction(value: unknown): value is (...args: never[]) => unknown { - return typeof value === 'function'; -} diff --git a/packages/plugins/src/load.test.ts b/packages/plugins/src/load.test.ts index 1da14a14eb..d18fca5ce5 100644 --- a/packages/plugins/src/load.test.ts +++ b/packages/plugins/src/load.test.ts @@ -5,14 +5,11 @@ import { test } from 'vitest'; import { withPluginConnection } from './load.ts'; import { pluginHome, - registrationSource, - selectPlugin, selectV2Plugin, v2RegistrationSource, webDriverPluginSource, } from '@agent-device/test-kit'; import { AppError } from '@agent-device/kernel/errors'; -import type { ProviderPluginHost } from './host.ts'; import type { PluginRegistryPolicy } from './registry.ts'; import type { ProviderDeviceRuntime } from '@agent-device/contracts/device'; @@ -51,17 +48,27 @@ async function startStore(env: NodeJS.ProcessEnv, builtin: readonly string[] = [ return await startProviderRegistry(resolved, env, FAKE_POLICY); } -test('a v1 store plugin loads through the adapter with options and the host error constructor', async () => { +test('a store plugin loads its factory with the selection options and the host error constructor', async () => { const { home, env } = pluginHome(); - selectPlugin(home, 'example', 'example', registrationSource('example')); + selectV2Plugin( + home, + '@example/v2', + v2RegistrationSource('example').replace( + 'options, hostEnv: host.env }', + 'options, hostEnv: host.env, createError: host.createError }', + ), + ); const registry = await startStore(env); - const runtime = registry.registrations[0]!.runtime as ProviderDeviceRuntime & ProviderPluginHost; + const runtime = registry.registrations[0]!.runtime as ProviderDeviceRuntime & { + options: unknown; + createError: (code: 'INVALID_ARGS', message: string) => unknown; + }; assert.deepEqual(runtime.options, { region: 'eu' }); assert.ok(runtime.createError('INVALID_ARGS', 'bad profile') instanceof AppError); await registry.close(); }); -test('a v2 store plugin loads its factory with the selection options', async () => { +test('a plugin package loads its factory with the selection options', async () => { const { home, env } = pluginHome(); selectV2Plugin(home, '@example/v2', v2RegistrationSource('example')); const registry = await startStore(env); @@ -84,10 +91,10 @@ test('a v2 store plugin loads its factory with the selection options', async () await registry.close(); }); -test('v1 and v2 store plugins register in package-name order whichever version they are', async () => { +test('store plugins register in package-name order', async () => { const { home, env } = pluginHome(); selectV2Plugin(home, 'b-plugin', v2RegistrationSource('second')); - selectPlugin(home, 'a-plugin', 'first', registrationSource('first')); + selectV2Plugin(home, 'a-plugin', v2RegistrationSource('first')); const registry = await startStore(env); assert.deepEqual( registry.inventory.map(({ provider, source, package: name }) => [provider, source, name]), @@ -118,7 +125,17 @@ test('a broken plugin is listed as failed while its working neighbor registers', 'e-setup-fails', `export default () => ({ apiVersion: 2, provider: 'setup-fails', credentials: { variables: [] }, setup: async () => { throw new Error('setup failed'); } });`, ); - selectPlugin(home, 'f-bad-owner', 'bad-owner', registrationSource('other-id')); + selectV2Plugin( + home, + 'f-bad-owner', + `export default () => ({ + apiVersion: 2, provider: 'declared-id', credentials: { variables: [] }, + setup: async () => ({ + runtime: { provider: 'other-id', ownsDevice: () => false, getInteractor: () => undefined, + deviceInventoryProvider: async () => [], leaseLifecycle: {}, shutdown: async () => {} }, + platformModule: { owner: { kind: 'provider-runtime', provider: 'other-id', instance: 'test' }, loadRuntime: async () => { throw new Error('lazy'); } } }) + });`, + ); const registry = await startStore(env); assert.deepEqual( @@ -167,16 +184,16 @@ test('the first plugin to name a provider claims it even when it fails, and late await registry.close(); }); -test('a v1 manifest is dispatched before any factory runs and an incompatible one is only listed', async () => { +test('a package whose factory returns the v1 shape is listed as incompatible', async () => { const { home, env } = pluginHome(); - const marker = path.join(home, 'evaluated'); - selectPlugin( + selectV2Plugin( home, - 'one', - 'one', - `import fs from 'node:fs'; fs.writeFileSync(${JSON.stringify(marker)}, 'yes');`, + 'v1-factory', + `export default () => ({ + runtime: { provider: 'v1-factory', ownsDevice: () => false, getInteractor: () => undefined, + deviceInventoryProvider: async () => [], leaseLifecycle: {}, shutdown: async () => {} }, + platformModule: { owner: { kind: 'provider-runtime', provider: 'v1-factory', instance: 'test' }, loadRuntime: async () => { throw new Error('lazy'); } } });`, ); - selectPlugin(home, 'two', 'other', 'throw new Error("evaluated");', 2); const { resolveProviderPlugins, claimProviderIds } = await import('./registry.ts'); const { storePluginCandidates } = await import('./store.ts'); const resolved = await resolveProviderPlugins([ @@ -184,13 +201,11 @@ test('a v1 manifest is dispatched before any factory runs and an incompatible on ...(await storePluginCandidates(env)), ]); - assert.ok(!fs.existsSync(marker)); + // A v1 package used to be dispatched from its manifest and registered; the contract version is + // now the only way in, so it is listed and skipped like any other incompatible plugin. assert.deepEqual( resolved.inventory().map(({ package: name, state, error }) => [name, state, error?.reason]), - [ - ['one', 'active', undefined], - ['two', 'failed', 'incompatible_plugin'], - ], + [['v1-factory', 'failed', 'incompatible_plugin']], ); }); @@ -231,16 +246,16 @@ test('entry discovery prefers ./agent-device and falls back to the root export o }); test('startup failure of one plugin cleans up its constructed runtime and keeps the others', async () => { - for (const instance of ["'test'", 'undefined', '42', '" "']) { + for (const instance of ['null', 'undefined', '42', '" "']) { const { home, env } = pluginHome(); const first = path.join(home, 'first-shutdown'); const invalid = path.join(home, 'invalid-shutdown'); - selectPlugin(home, 'one', 'one', registrationSource('one', first)); - const source = registrationSource(instance === "'test'" ? 'wrong' : 'two', invalid).replace( + selectV2Plugin(home, 'one', v2RegistrationSource('one', { shutdownFile: first })); + const source = v2RegistrationSource('two', { shutdownFile: invalid }).replace( "instance: 'test'", `instance: ${instance}`, ); - selectPlugin(home, 'two', 'two', source); + selectV2Plugin(home, 'two', source); const registry = await startStore(env); assert.deepEqual( registry.registrations.map(({ provider }) => provider), @@ -307,49 +322,7 @@ test('a frozen runtime registers untouched, serves its facets, and is shut down assert.equal(fs.readFileSync(log, 'utf8'), 'runtime;dispose;'); }); -test('connection callbacks run from a v1 plugin and always release its runtime', async () => { - const { home, env } = pluginHome(); - const marker = path.join(home, 'shutdown'); - const source = registrationSource('example', marker).replace( - 'platformModule:', - "connection: { resolve: () => ({ profile: { leaseProvider: 'example', platform: 'android' } }), verify: async () => { throw host.createError('COMMAND_FAILED', 'verification failed'); } }, platformModule:", - ); - selectPlugin(home, 'example', 'example', source); - selectPlugin(home, 'unrelated', 'unrelated', 'throw new Error("unrelated plugin evaluated");'); - const manifestPath = path.join( - home, - 'plugins', - JSON.parse(fs.readFileSync(path.join(home, 'config.json'), 'utf8')).plugins.example - .installation, - 'node_modules/example/package.json', - ); - const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')); - manifest.agentDevicePlugin.connection = LOCAL_CONNECTION; - fs.writeFileSync(manifestPath, JSON.stringify(manifest)); - const flags = { json: false, help: false, version: false }; - - const profile = await withPluginConnection( - 'example', - ['limrun'], - env, - async (connection) => await connection.resolve({ flags, stateDir: home, cwd: home, env }), - ); - assert.equal(profile.profile.platform, 'android'); - assert.ok(fs.existsSync(marker)); - fs.unlinkSync(marker); - await assert.rejects( - withPluginConnection( - 'example', - ['limrun'], - env, - async (connection) => await connection.verify({ flags, env }), - ), - { code: 'COMMAND_FAILED' }, - ); - assert.ok(fs.existsSync(marker)); -}); - -test('a v2 plugin connection runs without setting up any runtime', async () => { +test('a plugin connection runs without setting up any runtime', async () => { const { home, env } = pluginHome(); const marker = path.join(home, 'setup-ran'); selectV2Plugin( @@ -397,7 +370,7 @@ const LOCAL_CONNECTION = { test('a WebDriver descriptor is adapted by the policy, and a mismatched provider never reaches it', async () => { const { home, env } = pluginHome(); const source = webDriverPluginSource('example'); - selectPlugin(home, 'example', 'example', source); + selectV2Plugin(home, 'example', source); const registry = await startStore(env, []); assert.deepEqual( registry.registrations.map(({ provider, runtime }) => [provider, runtime.provider]), @@ -408,7 +381,12 @@ test('a WebDriver descriptor is adapted by the policy, and a mismatched provider adaptedDescriptors.length = 0; const other = pluginHome(); - selectPlugin(other.home, 'example', 'wrong', source); + selectV2Plugin( + other.home, + 'example', + // The descriptor names a provider the plugin did not declare. + source.replace('"provider":"example","endpoint"', '"provider":"wrong","endpoint"'), + ); const mismatched = await startStore(other.env, []); assert.deepEqual(mismatched.registrations, []); assert.equal(mismatched.inventory[0]!.error?.reason, 'invalid_plugin'); @@ -418,7 +396,7 @@ test('a WebDriver descriptor is adapted by the policy, and a mismatched provider test('a factory returning a primitive is listed as an invalid plugin', async () => { for (const value of ['42', '"runtime"', 'true']) { const { home, env } = pluginHome(); - selectPlugin(home, 'example', 'example', `export default () => ${value};`); + selectV2Plugin(home, 'example', `export default () => ${value};`); const registry = await startStore(env, []); assert.deepEqual(registry.registrations, []); assert.equal(registry.inventory[0]!.state, 'failed'); diff --git a/packages/plugins/src/manifest.test.ts b/packages/plugins/src/manifest.test.ts deleted file mode 100644 index e676087558..0000000000 --- a/packages/plugins/src/manifest.test.ts +++ /dev/null @@ -1,90 +0,0 @@ -import assert from 'node:assert/strict'; -import fs from 'node:fs'; -import path from 'node:path'; -import { test } from 'vitest'; -import { readPluginManifest } from './manifest.ts'; -import { pluginHome, writePlugin } from '@agent-device/test-kit'; - -test('manifest compatibility is checked without evaluating plugin code', () => { - const { home } = pluginHome(); - const directory = writePlugin(home); - assert.equal(readPluginManifest(directory).agentDevicePlugin.provider, 'example'); - writePlugin(home, '@example/provider', 2); - assert.throws(() => readPluginManifest(directory), { - code: 'INVALID_ARGS', - details: { - reason: 'incompatible_plugin', - apiVersion: 1, - hint: 'Install a plugin release supporting agentDevicePlugin.apiVersion 1.', - }, - }); -}); - -test('manifest refuses traversal and symlink entries outside the installed package', () => { - const { home } = pluginHome(); - const directory = writePlugin(home); - const outside = path.join(home, 'outside.js'); - fs.writeFileSync(outside, 'throw new Error("outside");'); - fs.unlinkSync(path.join(directory, 'plugin.js')); - fs.symlinkSync(outside, path.join(directory, 'plugin.js')); - assert.throws(() => readPluginManifest(directory), { code: 'INVALID_ARGS' }); - const manifest = JSON.parse(fs.readFileSync(path.join(directory, 'package.json'), 'utf8')); - manifest.agentDevicePlugin.entry = '../../../outside.js'; - fs.writeFileSync(path.join(directory, 'package.json'), JSON.stringify(manifest)); - assert.throws(() => readPluginManifest(directory), { code: 'INVALID_ARGS' }); -}); - -test('connection metadata admits local providers and rejects malformed or remote policies', () => { - const { home } = pluginHome(); - const directory = writePlugin(home); - const file = path.join(directory, 'package.json'); - const manifest = JSON.parse(fs.readFileSync(file, 'utf8')); - const connection = { - leaseKind: 'direct-device-provider', - requiresAppAttachment: true, - requiresRemoteDaemon: false, - supportsArtifacts: true, - supportsDeferredAppSelection: false, - supportsDirectPortReverse: false, - usesCloudWebDriverLease: true, - }; - const read = (policy: unknown) => { - manifest.agentDevicePlugin.connection = policy; - fs.writeFileSync(file, JSON.stringify(manifest)); - return readPluginManifest(directory); - }; - assert.deepEqual(read(connection).agentDevicePlugin.connection, connection); - const cloud = { ...connection, holdsCloudDevice: true, forgetsEndedConnectionLease: true }; - assert.deepEqual(read(cloud).agentDevicePlugin.connection, cloud); - for (const invalid of [ - null, - {}, - { ...connection, leaseKind: 'remote-daemon' }, - { ...connection, requiresRemoteDaemon: true }, - { ...connection, supportsArtifacts: 'true' }, - { ...connection, supportsDeferredAppSelection: undefined }, - { ...connection, holdsCloudDevice: 'false' }, - { ...connection, forgetsEndedConnectionLease: 'false' }, - ]) { - assert.throws(() => read(invalid), { code: 'INVALID_ARGS' }); - } -}); - -test('credential variables are optional environment variable names', () => { - const { home } = pluginHome(); - const directory = writePlugin(home); - const file = path.join(directory, 'package.json'); - const manifest = JSON.parse(fs.readFileSync(file, 'utf8')); - const read = (credentialVariables: unknown) => { - manifest.agentDevicePlugin.credentialVariables = credentialVariables; - fs.writeFileSync(file, JSON.stringify(manifest)); - return readPluginManifest(directory); - }; - assert.equal(read(undefined).agentDevicePlugin.credentialVariables, undefined); - assert.deepEqual(read(['EXAMPLE_USER', '_KEY_2']).agentDevicePlugin.credentialVariables, [ - 'EXAMPLE_USER', - '_KEY_2', - ]); - for (const invalid of [null, 'EXAMPLE_USER', {}, [''], ['example_user'], ['2KEY'], ['A-B'], [1]]) - assert.throws(() => read(invalid), { code: 'INVALID_ARGS' }, JSON.stringify(invalid)); -}); diff --git a/packages/plugins/src/manifest.ts b/packages/plugins/src/manifest.ts deleted file mode 100644 index 0422c38cee..0000000000 --- a/packages/plugins/src/manifest.ts +++ /dev/null @@ -1,118 +0,0 @@ -import fs from 'node:fs'; -import path from 'node:path'; -import { AppError } from '@agent-device/kernel/errors'; -import type { ConnectionProviderCapabilities } from '@agent-device/contracts/remote'; - -/** Provider ids that name daemon routing, not a runtime a plugin can supply. */ -export const ROUTING_PROVIDER_IDENTITIES: readonly string[] = ['cloud', 'proxy']; - -const V1_PLUGIN_API_VERSION = 1; - -/** A v1 plugin package: the manifest declares what the host reads before any plugin code runs. */ -export type PluginManifest = { - name: string; - version: string; - agentDevicePlugin: { - apiVersion: number; - provider: string; - entry: string; - connection?: ConnectionProviderCapabilities; - credentialVariables?: string[]; - }; -}; - -const ENVIRONMENT_VARIABLE = /^[A-Z_][A-Z0-9_]*$/; - -function invalidManifest(message: string): AppError { - return new AppError('INVALID_ARGS', message, { reason: 'invalid_plugin' }); -} - -export function assertLocalConnectionCapabilities( - policy: ConnectionProviderCapabilities | undefined, -): void { - if (policy === undefined) return; - if ( - !policy || - typeof policy !== 'object' || - policy.leaseKind !== 'direct-device-provider' || - [ - 'requiresAppAttachment', - 'requiresRemoteDaemon', - 'supportsArtifacts', - 'supportsDeferredAppSelection', - 'supportsDirectPortReverse', - 'usesCloudWebDriverLease', - ].some((key) => typeof policy[key as keyof ConnectionProviderCapabilities] !== 'boolean') || - (policy.holdsCloudDevice !== undefined && typeof policy.holdsCloudDevice !== 'boolean') || - (policy.forgetsEndedConnectionLease !== undefined && - typeof policy.forgetsEndedConnectionLease !== 'boolean') || - policy.requiresRemoteDaemon - ) { - throw invalidManifest('Plugin connection must declare local provider capabilities'); - } -} - -export function assertCredentialVariables(variables: unknown): void { - if ( - variables !== undefined && - (!Array.isArray(variables) || - !variables.every((name) => typeof name === 'string' && ENVIRONMENT_VARIABLE.test(name))) - ) { - throw invalidManifest('Plugin credential variables must list environment variable names'); - } -} - -export function readPluginManifest(directory: string): PluginManifest { - let manifest: PluginManifest; - try { - const file = path.join(directory, 'package.json'); - manifest = JSON.parse(fs.readFileSync(file, 'utf8')) as PluginManifest; - } catch (error) { - throw new AppError( - 'INVALID_ARGS', - `Cannot read plugin manifest: ${directory}`, - {}, - error as Error, - ); - } - const declaration = manifest?.agentDevicePlugin; - if ( - typeof manifest?.name !== 'string' || - typeof manifest?.version !== 'string' || - !declaration || - declaration.apiVersion !== V1_PLUGIN_API_VERSION || - typeof declaration.provider !== 'string' || - !/^[a-z][a-z0-9-]*$/.test(declaration.provider) || - typeof declaration.entry !== 'string' || - !declaration.entry.startsWith('./') - ) { - throw new AppError('INVALID_ARGS', 'Package does not declare a compatible provider plugin', { - reason: 'incompatible_plugin', - apiVersion: V1_PLUGIN_API_VERSION, - hint: `Install a plugin release supporting agentDevicePlugin.apiVersion ${V1_PLUGIN_API_VERSION}.`, - }); - } - resolvePluginEntry(directory, declaration.entry); - assertLocalConnectionCapabilities(declaration.connection); - assertCredentialVariables(declaration.credentialVariables); - return manifest as PluginManifest; -} - -export function resolvePluginEntry(directory: string, target: string): string { - try { - const root = fs.realpathSync(directory); - const resolved = fs.realpathSync(path.resolve(directory, target)); - if ( - target.startsWith('./') && - resolved.startsWith(`${root}${path.sep}`) && - fs.statSync(resolved).isFile() - ) { - return resolved; - } - } catch {} - throw new AppError('INVALID_ARGS', 'Plugin entry must be a readable file inside its package', { - reason: 'plugin_load_failed', - directory, - entry: target, - }); -} diff --git a/packages/plugins/src/registry.ts b/packages/plugins/src/registry.ts index e5b2e9cb90..ffbbd9cf71 100644 --- a/packages/plugins/src/registry.ts +++ b/packages/plugins/src/registry.ts @@ -20,7 +20,7 @@ import { } from '@agent-device/contracts/plugin-inventory'; import { describePluginFailure } from './inventory.ts'; import { isProviderId } from './discovery.ts'; -import { ROUTING_PROVIDER_IDENTITIES } from './manifest.ts'; +import { ROUTING_PROVIDER_IDENTITIES } from './contract.ts'; import { assertProviderRuntime, invalidPlugin, validateAgentDevicePlugin } from './validate.ts'; /** @@ -31,11 +31,11 @@ export type PluginCandidate = Readonly<{ source: PluginSource; package?: string; version?: string; - /** Known before the plugin loads, such as a v1 manifest; a load failure still claims it. */ + /** Claims `provider` without loading it, so a later candidate with that id is a duplicate. */ provider?: string; /** Claims `provider` without registering or listing: a built-in that is not configured. */ dormant?: boolean; - /** The `options` the store passes to the host, which a v1 plugin reads. */ + /** The `options` the store passes to the host when it calls the factory. */ hostOptions?: Record; /** Returns the unvalidated plugin, or throws the reason it cannot load. */ load(): Promise | unknown; diff --git a/packages/plugins/src/store-legacy.ts b/packages/plugins/src/store-legacy.ts deleted file mode 100644 index 8d82695809..0000000000 --- a/packages/plugins/src/store-legacy.ts +++ /dev/null @@ -1,83 +0,0 @@ -import fs from 'node:fs'; -import path from 'node:path'; -import { AppError } from '@agent-device/kernel/errors'; -import { isRecord } from '@agent-device/kernel/record'; -import { resolveUserConfigPath } from '@agent-device/host-kit/file'; -import { readPluginManifest, type PluginManifest } from './manifest.ts'; - -export type PluginSelection = { - installation: string; - version?: string; - options?: Record; -}; -type PluginConfig = Record & { plugins?: Record }; -export function readPluginConfig(env: NodeJS.ProcessEnv): PluginConfig { - const configPath = resolveUserConfigPath(env); - try { - const config = JSON.parse(fs.readFileSync(configPath, 'utf8')) as PluginConfig; - if (!isRecord(config) || (config.plugins !== undefined && !isRecord(config.plugins))) - throw new AppError('INVALID_ARGS', 'Plugin config must contain an object'); - return config; - } catch (error) { - if ((error as NodeJS.ErrnoException).code === 'ENOENT') return {}; - if (error instanceof SyntaxError) - throw new AppError('INVALID_ARGS', `Invalid plugin JSON: ${configPath}`, {}, error); - throw error; - } -} - -export function validatePluginSelection(name: string, selection: PluginSelection): void { - if ( - !isPackageName(name) || - !isRecord(selection) || - typeof selection.installation !== 'string' || - !/^[a-f0-9-]{36}$/.test(selection.installation) || - (selection.version !== undefined && !isVersionSelector(selection.version)) || - (selection.options !== undefined && !isRecord(selection.options)) - ) { - throw new AppError('INVALID_ARGS', `Invalid plugin selection: ${name}`); - } -} - -export function storeHome(env: NodeJS.ProcessEnv): string { - return path.dirname(resolveUserConfigPath(env)); -} - -export function installationDirectory(home: string, name: string, installation: string): string { - return path.join(home, 'plugins', installation, 'node_modules', name); -} - -/** - * The v1 manifests in the store, read without executing anything, including those of a package - * that also exports `./agent-device`; unreadable selections are skipped. - */ -export function legacyStoreManifests(env: NodeJS.ProcessEnv): PluginManifest[] { - const home = storeHome(env); - let selections: [string, PluginSelection][]; - try { - selections = Object.entries(readPluginConfig(env).plugins ?? {}); - } catch { - return []; - } - return selections.flatMap(([name, selection]) => { - try { - validatePluginSelection(name, selection); - const manifest = readPluginManifest( - installationDirectory(home, name, selection.installation), - ); - return manifest.name === name ? [manifest] : []; - } catch { - return []; - } - }); -} - -function isPackageName(value: string): boolean { - return /^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(value); -} - -export function isVersionSelector(value: unknown): value is string { - return ( - typeof value === 'string' && /^[a-zA-Z0-9*^~<>=| .+-]+$/.test(value) && value.trim().length > 0 - ); -} diff --git a/packages/plugins/src/store.test.ts b/packages/plugins/src/store.test.ts index 0a46f95f82..2c6224678c 100644 --- a/packages/plugins/src/store.test.ts +++ b/packages/plugins/src/store.test.ts @@ -3,14 +3,8 @@ import fs from 'node:fs'; import path from 'node:path'; import { afterEach, test, vi } from 'vitest'; import { runCmd } from '@agent-device/host-kit/command'; -import { changePlugin, legacyStoreManifests, listPlugins } from './store.ts'; -import { - pluginHome, - selectPlugin, - selectV2Plugin, - v2RegistrationSource, - writePlugin, -} from '@agent-device/test-kit'; +import { changePlugin, listPlugins } from './store.ts'; +import { pluginHome, selectV2Plugin, v2RegistrationSource } from '@agent-device/test-kit'; vi.mock('@agent-device/host-kit/command', () => ({ runCmd: vi.fn() })); afterEach(() => vi.mocked(runCmd).mockReset()); @@ -33,7 +27,8 @@ function installedPlugins(env: NodeJS.ProcessEnv) { }); } -function installFixture(name = packageName, apiVersion = 1, provider = 'example') { +/** Stands in for `npm install`: writes a v2 plugin package into the staged project. */ +function installFixture(name = packageName, provider = 'example') { vi.mocked(runCmd).mockImplementation(async (command, argv, options) => { assert.equal(command, 'npm'); assert.equal(argv[argv.indexOf('--prefix') + 1], options!.cwd); @@ -41,7 +36,18 @@ function installFixture(name = packageName, apiVersion = 1, provider = 'example' assert.ok(argv.includes('--ignore-scripts')); assert.ok(argv.includes('--workspaces=false')); assert.ok(argv.includes('--package-lock=true')); - writePlugin(options!.cwd!, name, apiVersion, provider); + const directory = path.join(options!.cwd!, 'node_modules', name); + fs.mkdirSync(directory, { recursive: true }); + fs.writeFileSync( + path.join(directory, 'package.json'), + JSON.stringify({ + name, + version: '1.2.3', + type: 'module', + exports: { './agent-device': { import: './plugin.mjs' } }, + }), + ); + fs.writeFileSync(path.join(directory, 'plugin.mjs'), v2RegistrationSource(provider)); return { stdout: '', stderr: '', exitCode: 0 }; }); } @@ -50,13 +56,13 @@ test('add, pinned update and remove preserve flags, options and old installation const { home, env } = pluginHome(); fs.writeFileSync(path.join(home, 'config.json'), JSON.stringify({ platform: 'android' })); installFixture(); - await changePlugin('add', `${packageName}@1.2.3`, env, []); + await changePlugin('add', `${packageName}@1.2.3`, env); const [first] = installedPlugins(env); const config = readPluginConfig(env); config.plugins![packageName]!.options = { region: 'eu' }; config.plugins![packageName]!.installation = '../damaged'; fs.writeFileSync(path.join(home, 'config.json'), JSON.stringify(config)); - await changePlugin('update', packageName, env, []); + await changePlugin('update', packageName, env); const [second] = installedPlugins(env); assert.notEqual(first!.directory, second!.directory); assert.deepEqual(second!.selection.options, { region: 'eu' }); @@ -66,7 +72,7 @@ test('add, pinned update and remove preserve flags, options and old installation { [packageName]: '1.2.3' }, ); assert.equal(readPluginConfig(env).platform, 'android'); - await changePlugin('remove', packageName, env, []); + await changePlugin('remove', packageName, env); assert.deepEqual(installedPlugins(env), []); assert.ok(fs.existsSync(first!.directory)); assert.ok(fs.existsSync(second!.directory)); @@ -75,31 +81,83 @@ test('add, pinned update and remove preserve flags, options and old installation test('failed npm install and incompatible replacement preserve the active selection', async () => { const { home, env } = pluginHome(); installFixture(); - await changePlugin('add', packageName, env, []); + await changePlugin('add', packageName, env); const before = fs.readFileSync(path.join(home, 'config.json'), 'utf8'); vi.mocked(runCmd).mockRejectedValue(new Error('npm failed')); - await assert.rejects(changePlugin('update', packageName, env, []), /npm failed/); + await assert.rejects(changePlugin('update', packageName, env), /npm failed/); assert.equal(fs.readFileSync(path.join(home, 'config.json'), 'utf8'), before); - installFixture(packageName, 2); - await assert.rejects(changePlugin('update', packageName, env, []), { code: 'INVALID_ARGS' }); + // The replacement exports neither ./agent-device nor a root entry, so it is not a plugin package. + vi.mocked(runCmd).mockImplementation(async (_command, _argv, options) => { + const directory = path.join(options!.cwd!, 'node_modules', packageName); + fs.mkdirSync(directory, { recursive: true }); + fs.writeFileSync( + path.join(directory, 'package.json'), + JSON.stringify({ + name: packageName, + version: '2.0.0', + type: 'module', + exports: { './tools': './tools.js' }, + }), + ); + fs.writeFileSync(path.join(directory, 'tools.js'), 'export {};'); + return { stdout: '', stderr: '', exitCode: 0 }; + }); + await assert.rejects(changePlugin('update', packageName, env), { code: 'INVALID_ARGS' }); assert.equal(fs.readFileSync(path.join(home, 'config.json'), 'utf8'), before); assert.equal(fs.readdirSync(path.join(home, 'plugins')).length, 1); }); +test('a factory shaped for the removed v1 contract still installs', async () => { + const { env } = pluginHome(); + vi.mocked(runCmd).mockImplementation(async (_command, _argv, options) => { + const directory = path.join(options!.cwd!, 'node_modules', packageName); + fs.mkdirSync(directory, { recursive: true }); + fs.writeFileSync( + path.join(directory, 'package.json'), + JSON.stringify({ + name: packageName, + version: '1.2.3', + type: 'module', + exports: { './agent-device': { import: './plugin.mjs' } }, + }), + ); + fs.writeFileSync(path.join(directory, 'plugin.mjs'), 'export default () => ({ register: 1 });'); + return { stdout: '', stderr: '', exitCode: 0 }; + }); + // Installation only needs a loadable default export; the registry rejects the shape later. + await changePlugin('add', packageName, env); + const [listed] = await listPlugins(env, []); + assert.deepEqual( + { name: listed?.name, compatible: listed?.compatible }, + { name: packageName, compatible: false }, + ); +}); + test('concurrent additions serialize without dropping the other package', async () => { const { env } = pluginHome(); vi.mocked(runCmd).mockImplementation(async (_, __, options) => { const { dependencies } = JSON.parse( fs.readFileSync(path.join(options!.cwd!, 'package.json'), 'utf8'), ); - const name = Object.keys(dependencies)[0]!; - writePlugin(options!.cwd!, name, 1, name); + const name: string = Object.keys(dependencies)[0]!; + const directory = path.join(options!.cwd!, 'node_modules', name); + fs.mkdirSync(directory, { recursive: true }); + fs.writeFileSync( + path.join(directory, 'package.json'), + JSON.stringify({ + name, + version: '1.2.3', + type: 'module', + exports: { './agent-device': { import: './plugin.mjs' } }, + }), + ); + fs.writeFileSync( + path.join(directory, 'plugin.mjs'), + v2RegistrationSource(name.toLowerCase().replaceAll(/[^a-z0-9-]/g, '-')), + ); return { stdout: '', stderr: '', exitCode: 0 }; }); - await Promise.all([ - changePlugin('add', 'constructor', env, []), - changePlugin('add', 'two', env, []), - ]); + await Promise.all([changePlugin('add', 'constructor', env), changePlugin('add', 'two', env)]); assert.deepEqual( installedPlugins(env) .map(({ name }) => name) @@ -117,43 +175,52 @@ test('invalid package sources and damaged selections fail before invoking npm', 'plugin@npm:other', 'https://example.com/plugin', ]) { - await assert.rejects(changePlugin('add', name, env, []), { code: 'INVALID_ARGS' }); + await assert.rejects(changePlugin('add', name, env), { code: 'INVALID_ARGS' }); } fs.writeFileSync( path.join(home, 'config.json'), JSON.stringify({ plugins: { one: { installation: '../other' } } }), ); assert.equal((await listPlugins(env, []))[0]?.compatible, false); - await changePlugin('remove', 'one', env, []); + await changePlugin('remove', 'one', env); assert.deepEqual(await listPlugins(env, []), []); fs.writeFileSync( path.join(home, 'config.json'), JSON.stringify({ plugins: { UPPERCASE: null } }), ); - await changePlugin('remove', 'UPPERCASE', env, []); + await changePlugin('remove', 'UPPERCASE', env); assert.deepEqual(await listPlugins(env, []), []); assert.equal(vi.mocked(runCmd).mock.calls.length, 0); }); -test('provider collisions refuse activation and preserve existing selections', async () => { - const { env } = pluginHome(); - installFixture(); - await assert.rejects(changePlugin('add', packageName, env, ['example']), { - code: 'INVALID_ARGS', - }); - assert.deepEqual(installedPlugins(env), []); - await changePlugin('add', packageName, env, []); - installFixture('other'); - await assert.rejects(changePlugin('add', 'other', env, []), { code: 'INVALID_ARGS' }); - assert.equal(installedPlugins(env).length, 1); +test('a duplicate provider id is settled by the registry when the store composes', async () => { + const { home, env } = pluginHome(); + selectV2Plugin(home, 'first', v2RegistrationSource('example')); + selectV2Plugin(home, 'second', v2RegistrationSource('example')); + const listed = await listPlugins(env, []); + assert.deepEqual( + listed.map(({ name, compatible, error }) => [name, compatible, error?.reason]), + [ + ['first', true, undefined], + ['second', false, 'duplicate_provider'], + ], + ); + // A built-in identity claims the id first, so a store package cannot take it either. + const { home: otherHome, env: otherEnv } = pluginHome(); + selectV2Plugin(otherHome, 'cloud', v2RegistrationSource('cloud')); + const cloud = await listPlugins(otherEnv, ['cloud']); + assert.deepEqual( + cloud.map(({ name, compatible, error }) => [name, compatible, error?.reason]), + [['cloud', false, 'reserved_provider']], + ); }); test('broken siblings do not block pinned updates or unrelated additions', async () => { - for (const damage of ['missing', 'json', 'abi']) { + for (const damage of ['missing', 'json', 'load']) { const { home, env } = pluginHome(); installFixture(); - await changePlugin('add', `${packageName}@1.2.3`, env, []); - selectPlugin(home, 'broken', 'broken', 'throw new Error("must not evaluate");', 2); + await changePlugin('add', `${packageName}@1.2.3`, env); + selectV2Plugin(home, 'broken', 'throw new Error("must not evaluate");'); const config = readPluginConfig(env); config.plugins![packageName]!.options = { region: 'eu' }; fs.writeFileSync(path.join(home, 'config.json'), JSON.stringify(config)); @@ -161,13 +228,13 @@ test('broken siblings do not block pinned updates or unrelated additions', async if (damage === 'missing') fs.rmSync(directory, { recursive: true }); if (damage === 'json') fs.writeFileSync(path.join(directory, 'node_modules/broken/package.json'), '{'); - await changePlugin('update', packageName, env, []); + await changePlugin('update', packageName, env); const repaired = readPluginConfig(env).plugins![packageName]!; assert.deepEqual(repaired.options, { region: 'eu' }); assert.equal(repaired.version, '1.2.3'); assert.deepEqual(readPluginConfig(env).plugins!.broken, config.plugins!.broken); - installFixture('other', 1, 'other'); - await changePlugin('add', 'other', env, []); + installFixture('other', 'other'); + await changePlugin('add', 'other', env); const listed = await listPlugins(env, []); assert.deepEqual( listed.map(({ name, compatible }) => [name, compatible]), @@ -179,28 +246,3 @@ test('broken siblings do not block pinned updates or unrelated additions', async ); } }); - -test('a package that declares the v1 manifest and exports ./agent-device still supplies its manifest', () => { - const { home, env } = pluginHome(); - const directory = selectV2Plugin(home, 'dual', v2RegistrationSource('dual'), { - manifest: { - agentDevicePlugin: { - apiVersion: 1, - provider: 'dual', - entry: './plugin.mjs', - credentialVariables: ['DUAL_KEY'], - }, - }, - }); - selectV2Plugin(home, 'v2-only', v2RegistrationSource('v2-only')); - assert.deepEqual( - legacyStoreManifests(env).map((manifest) => manifest.agentDevicePlugin.credentialVariables), - [['DUAL_KEY']], - ); - - // An installation that holds another package supplies nothing under this selection's name. - const manifestPath = path.join(directory, 'package.json'); - const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')); - fs.writeFileSync(manifestPath, JSON.stringify({ ...manifest, name: 'someone-else' })); - assert.deepEqual(legacyStoreManifests(env), []); -}); diff --git a/packages/plugins/src/store.ts b/packages/plugins/src/store.ts index db1dcd0af3..bd58308f4d 100644 --- a/packages/plugins/src/store.ts +++ b/packages/plugins/src/store.ts @@ -1,12 +1,3 @@ -import { - legacyStoreManifests, - readPluginConfig, - validatePluginSelection, - storeHome, - installationDirectory, - isVersionSelector, - type PluginSelection, -} from './store-legacy.ts'; import crypto from 'node:crypto'; import fs from 'node:fs'; import path from 'node:path'; @@ -20,18 +11,67 @@ import { resolveUserConfigPath, } from '@agent-device/host-kit/file'; import { readCurrentOwnerIdentity } from '@agent-device/host-kit/process'; -import type { PluginPackageEntry } from './discovery.ts'; -import { ROUTING_PROVIDER_IDENTITIES, type PluginManifest } from './manifest.ts'; import type { PluginCandidate } from './registry.ts'; -export { legacyStoreManifests }; +export type PluginSelection = { + installation: string; + version?: string; + options?: Record; +}; +type PluginConfig = Record & { plugins?: Record }; + +function readPluginConfig(env: NodeJS.ProcessEnv): PluginConfig { + const configPath = resolveUserConfigPath(env); + try { + const config = JSON.parse(fs.readFileSync(configPath, 'utf8')) as PluginConfig; + if (!isRecord(config) || (config.plugins !== undefined && !isRecord(config.plugins))) + throw new AppError('INVALID_ARGS', 'Plugin config must contain an object'); + return config; + } catch (error) { + if ((error as NodeJS.ErrnoException).code === 'ENOENT') return {}; + if (error instanceof SyntaxError) + throw new AppError('INVALID_ARGS', `Invalid plugin JSON: ${configPath}`, {}, error); + throw error; + } +} + +function validatePluginSelection(name: string, selection: PluginSelection): void { + if ( + !isPackageName(name) || + !isRecord(selection) || + typeof selection.installation !== 'string' || + !/^[a-f0-9-]{36}$/.test(selection.installation) || + (selection.version !== undefined && !isVersionSelector(selection.version)) || + (selection.options !== undefined && !isRecord(selection.options)) + ) { + throw new AppError('INVALID_ARGS', `Invalid plugin selection: ${name}`); + } +} + +function storeHome(env: NodeJS.ProcessEnv): string { + return path.dirname(resolveUserConfigPath(env)); +} + +function installationDirectory(home: string, name: string, installation: string): string { + return path.join(home, 'plugins', installation, 'node_modules', name); +} + +function isPackageName(value: string): boolean { + return /^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(value); +} + +export function isVersionSelector(value: unknown): value is string { + return ( + typeof value === 'string' && /^[a-zA-Z0-9*^~<>=| .+-]+$/.test(value) && value.trim().length > 0 + ); +} type StoreInstallation = { name: string; version: string; directory: string; selection: PluginSelection; - entry: PluginPackageEntry; + entry: string; }; async function describeInstallation( @@ -61,12 +101,8 @@ async function readInstallation(home: string, name: string, selection: PluginSel ); } -async function loadInstallation({ name, directory, selection, entry }: StoreInstallation) { - if (entry.kind === 'v1') { - const { adaptLegacyPlugin } = await import('./legacy.ts'); - return adaptLegacyPlugin(entry.manifest, directory, selection.options); - } - const module = await import(pathToFileURL(entry.file).href); +async function loadInstallation({ name, entry, selection }: StoreInstallation) { + const module = await import(pathToFileURL(entry).href); if (typeof module.default !== 'function') throw new AppError('INVALID_ARGS', `Plugin must export a default factory: ${name}`, { reason: 'invalid_plugin', @@ -77,7 +113,8 @@ async function loadInstallation({ name, directory, selection, entry }: StoreInst /** * The store's contribution to the provider registry, in package-name order. Nothing here runs * plugin code: a selection or package that cannot be read becomes a candidate that fails when - * loaded, so one damaged installation never hides the others. + * loaded, so one damaged installation never hides the others. A store package names its provider + * only once its factory runs, and the registry settles a duplicate then. */ export async function storePluginCandidates(env: NodeJS.ProcessEnv): Promise { const home = storeHome(env); @@ -96,9 +133,6 @@ export async function storePluginCandidates(env: NodeJS.ProcessEnv): Promise loadInstallation(installation), }; @@ -207,11 +241,15 @@ async function stagePlugin( } } +/** + * Installs, updates or removes one plugin selection. A package is accepted when its entry loads as + * a plugin; a provider-id clash with another plugin or a built-in is the registry's to settle when + * the daemon next composes its plugins. + */ export async function changePlugin( action: PluginAction, input: string, env: NodeJS.ProcessEnv, - reservedProviders: readonly string[], ): Promise { const { name, version } = parsePluginRequest(action, input); const configPath = resolveUserConfigPath(env); @@ -234,13 +272,6 @@ export async function changePlugin( const requested = action === 'update' && isVersionSelector(previous?.version) ? previous.version : version; staged = await stagePlugin(home, name, requested, env); - assertUniqueLegacyProviders( - [ - ...legacyStoreManifests(env).filter((manifest) => manifest.name !== name), - ...(staged.entry.kind === 'v1' ? [staged.entry.manifest] : []), - ], - reservedProviders, - ); selections[name] = { installation: staged.installation, version: requested, @@ -259,23 +290,3 @@ export async function changePlugin( await release(); } } - -// A v1 manifest names its provider before any code runs, so a clash is refused at install time. A -// v2 package names its provider only once loaded; the registry records a clash then. -function assertUniqueLegacyProviders( - manifests: readonly PluginManifest[], - reserved: readonly string[], -): void { - const providers = new Set([...ROUTING_PROVIDER_IDENTITIES, ...reserved]); - for (const { agentDevicePlugin } of manifests) { - if (providers.has(agentDevicePlugin.provider)) - throw new AppError( - 'INVALID_ARGS', - `Duplicate provider plugin: ${agentDevicePlugin.provider}`, - { - reason: 'duplicate_provider', - }, - ); - providers.add(agentDevicePlugin.provider); - } -} diff --git a/packages/plugins/src/validate.ts b/packages/plugins/src/validate.ts index 9c573d495a..6fe6008f84 100644 --- a/packages/plugins/src/validate.ts +++ b/packages/plugins/src/validate.ts @@ -1,15 +1,16 @@ import { AppError } from '@agent-device/kernel/errors'; import { isRecord } from '@agent-device/kernel/record'; import { isProviderId } from './discovery.ts'; -import { - assertCredentialVariables, - assertLocalConnectionCapabilities, - ROUTING_PROVIDER_IDENTITIES, -} from './manifest.ts'; import type { ConnectionProviderCapabilities } from '@agent-device/contracts/remote'; import type { ProviderDeviceRuntime } from '@agent-device/contracts/device'; import type { PlatformRuntimeProviderModule } from '@agent-device/contracts/platform-runtime-operations'; -import { PROVIDER_PLUGIN_API_VERSION, type AgentDevicePlugin } from './contract.ts'; +import { + PROVIDER_PLUGIN_API_VERSION, + ROUTING_PROVIDER_IDENTITIES, + type AgentDevicePlugin, +} from './contract.ts'; + +const ENVIRONMENT_VARIABLE = /^[A-Z_][A-Z0-9_]*$/; /** The one validation of what a plugin factory returned, whichever source produced it. */ export function validateAgentDevicePlugin(value: unknown): AgentDevicePlugin { @@ -53,6 +54,15 @@ function assertCredentials(credentials: unknown): void { } } +function assertCredentialVariables(variables: unknown): void { + if ( + !Array.isArray(variables) || + !variables.every((name) => typeof name === 'string' && ENVIRONMENT_VARIABLE.test(name)) + ) { + throw invalidPlugin('Plugin credential variables must list environment variable names'); + } +} + function assertConnection(connection: unknown): void { if ( !isRecord(connection) || @@ -65,6 +75,31 @@ function assertConnection(connection: unknown): void { assertLocalConnectionCapabilities(connection.capabilities as ConnectionProviderCapabilities); } +function assertLocalConnectionCapabilities( + policy: ConnectionProviderCapabilities | undefined, +): void { + if (policy === undefined) return; + if ( + !policy || + typeof policy !== 'object' || + policy.leaseKind !== 'direct-device-provider' || + [ + 'requiresAppAttachment', + 'requiresRemoteDaemon', + 'supportsArtifacts', + 'supportsDeferredAppSelection', + 'supportsDirectPortReverse', + 'usesCloudWebDriverLease', + ].some((key) => typeof policy[key as keyof ConnectionProviderCapabilities] !== 'boolean') || + (policy.holdsCloudDevice !== undefined && typeof policy.holdsCloudDevice !== 'boolean') || + (policy.forgetsEndedConnectionLease !== undefined && + typeof policy.forgetsEndedConnectionLease !== 'boolean') || + policy.requiresRemoteDaemon + ) { + throw invalidPlugin('Plugin connection must declare local provider capabilities'); + } +} + /** The runtime a plugin built must answer to the provider id it registered. */ export function assertProviderRuntime( provider: string, diff --git a/packages/provider-revyl/package.json b/packages/provider-revyl/package.json index 8fbb597a4f..f00dc546ed 100644 --- a/packages/provider-revyl/package.json +++ b/packages/provider-revyl/package.json @@ -30,25 +30,6 @@ "@agent-device/test-kit": "workspace:*", "agent-device": "workspace:*" }, - "agentDevicePlugin": { - "apiVersion": 1, - "provider": "revyl", - "entry": "./dist/plugin.mjs", - "connection": { - "leaseKind": "direct-device-provider", - "requiresAppAttachment": false, - "requiresRemoteDaemon": false, - "supportsArtifacts": false, - "supportsDeferredAppSelection": false, - "supportsDirectPortReverse": false, - "usesCloudWebDriverLease": false, - "holdsCloudDevice": true - }, - "credentialVariables": [ - "REVYL_API_KEY", - "REVYL_API_URL" - ] - }, "publishConfig": { "exports": { ".": { diff --git a/packages/provider-revyl/src/plugin.ts b/packages/provider-revyl/src/plugin.ts deleted file mode 100644 index 71e65786f2..0000000000 --- a/packages/provider-revyl/src/plugin.ts +++ /dev/null @@ -1,21 +0,0 @@ -import type { ProviderPluginHost } from 'agent-device/plugins'; -import type { RevylConnection } from './connection.ts'; -import type { RevylRuntimeRegistration } from './runtime.ts'; - -/** What the version 1 host reads out of this entry: the runtime pair, plus the connect half. */ -export type RevylPluginEntryResult = RevylRuntimeRegistration & { - connection: RevylConnection; -}; - -/** - * The version 1 plugin entry, kept so hosts without the version 2 contract still load this package. - * The runtime is built by the same setup the version 2 declaration runs. - */ -export default async function revylPlugin( - host: ProviderPluginHost, -): Promise { - const { setupRevylPlugin } = await import('./plugin-setup.ts'); - const { createRevylConnection } = await import('./connection.ts'); - const registration = await setupRevylPlugin(host); - return { ...registration, connection: createRevylConnection(host) }; -} diff --git a/packages/provider-revyl/tsdown.config.ts b/packages/provider-revyl/tsdown.config.ts index 6173fbf90a..b0e02a7587 100644 --- a/packages/provider-revyl/tsdown.config.ts +++ b/packages/provider-revyl/tsdown.config.ts @@ -1,7 +1,7 @@ import { defineConfig } from 'tsdown'; export default defineConfig({ - entry: { plugin: 'src/plugin.ts', 'agent-device': 'src/index.ts' }, + entry: { 'agent-device': 'src/index.ts' }, outDir: 'dist', format: 'esm', platform: 'node', diff --git a/packages/provider-testmu/package.json b/packages/provider-testmu/package.json index fba7b447fe..d2e80e65c5 100644 --- a/packages/provider-testmu/package.json +++ b/packages/provider-testmu/package.json @@ -31,24 +31,6 @@ "@agent-device/provider-webdriver": "workspace:*", "agent-device": "workspace:*" }, - "agentDevicePlugin": { - "apiVersion": 1, - "provider": "testmu", - "entry": "./dist/plugin.mjs", - "connection": { - "leaseKind": "direct-device-provider", - "requiresAppAttachment": false, - "requiresRemoteDaemon": false, - "supportsArtifacts": true, - "supportsDeferredAppSelection": false, - "supportsDirectPortReverse": false, - "usesCloudWebDriverLease": true - }, - "credentialVariables": [ - "LT_USERNAME", - "LT_ACCESS_KEY" - ] - }, "publishConfig": { "exports": { ".": { diff --git a/packages/provider-testmu/src/index.test.ts b/packages/provider-testmu/src/index.test.ts index 924457b2fd..005a4182fb 100644 --- a/packages/provider-testmu/src/index.test.ts +++ b/packages/provider-testmu/src/index.test.ts @@ -4,7 +4,6 @@ import type { ProviderPluginHost } from 'agent-device/plugins'; import { AppError } from '@agent-device/kernel/errors'; import testmu from './index.ts'; import { verifyTestMuConnection } from './testmu-connection-verification.ts'; -import manifest from '../package.json' with { type: 'json' }; vi.mock('./testmu-connection-verification.ts', () => ({ verifyTestMuConnection: vi.fn() })); @@ -119,12 +118,20 @@ test('connect uses the option credentials without an environment and verifies wi ); }); -test('the v2 declaration matches the v1 manifest that hosts without the v2 contract read', () => { - const v1 = manifest.agentDevicePlugin; - assert.equal(testmu().provider, v1.provider); - assert.deepEqual(testmu().connection?.capabilities, v1.connection); - assert.deepEqual(testmu().credentials.variables, v1.credentialVariables); - assert.equal(v1.apiVersion, 1); +test('the plugin declares its provider, capabilities and credential variables', () => { + const plugin = testmu(); + assert.equal(plugin.apiVersion, 2); + assert.equal(plugin.provider, 'testmu'); + assert.deepEqual(plugin.credentials, { variables: ['LT_USERNAME', 'LT_ACCESS_KEY'] }); + assert.deepEqual(plugin.connection?.capabilities, { + leaseKind: 'direct-device-provider', + requiresAppAttachment: false, + requiresRemoteDaemon: false, + supportsArtifacts: true, + supportsDeferredAppSelection: false, + supportsDirectPortReverse: false, + usesCloudWebDriverLease: true, + }); }); test('a credentials object missing one key falls back to the environment for that key', async () => { diff --git a/packages/provider-testmu/src/plugin.test.ts b/packages/provider-testmu/src/plugin.test.ts deleted file mode 100644 index 29621ae951..0000000000 --- a/packages/provider-testmu/src/plugin.test.ts +++ /dev/null @@ -1,68 +0,0 @@ -import assert from 'node:assert/strict'; -import { afterEach, test, vi } from 'vitest'; -import type { ProviderPluginHost } from 'agent-device/plugins'; -import { AppError } from '@agent-device/kernel/errors'; -import testMuPlugin from './plugin.ts'; -import { verifyTestMuConnection } from './testmu-connection-verification.ts'; - -vi.mock('./testmu-connection-verification.ts', () => ({ verifyTestMuConnection: vi.fn() })); - -const realFetch = globalThis.fetch; - -afterEach(() => { - globalThis.fetch = realFetch; - vi.clearAllMocks(); -}); - -function host(env: Record): ProviderPluginHost { - return { - env, - options: {}, - clientVersion: '0.0.0-test', - createError: (code, message, details) => new AppError(code, message, details), - }; -} - -test('whitespace-only credentials are missing, not a provider authentication failure', async () => { - globalThis.fetch = async () => { - throw new Error('a missing credential must not reach TestMu AI'); - }; - for (const env of [ - { LT_USERNAME: ' ', LT_ACCESS_KEY: 'key' }, - { LT_USERNAME: 'user', LT_ACCESS_KEY: '\t' }, - ]) { - await assert.rejects( - testMuPlugin(host(env)).webDriver.listArtifacts!({ - provider: 'testmu', - providerSessionId: 'SESSION1', - }), - (error: unknown) => - error instanceof AppError && - error.code === 'INVALID_ARGS' && - /requires LT_(USERNAME|ACCESS_KEY) in the environment/.test(error.message), - ); - } -}); - -test('verification of a hand-authored profile canonicalizes an upper-case app scheme', async () => { - vi.mocked(verifyTestMuConnection).mockResolvedValue({ - provider: 'testmu', - service: 'TestMu AI', - verificationMessage: 'verified', - device: { status: 'verified', name: 'iPhone 16', platform: 'ios', osVersion: '18.0' }, - app: { status: 'verified', reference: 'lt://APP1' }, - }); - const env = { LT_USERNAME: 'user', LT_ACCESS_KEY: 'key' }; - await testMuPlugin(host(env)).connection.verify({ - flags: { - json: false, - help: false, - version: false, - platform: 'ios', - device: 'iPhone 16', - providerOsVersion: '18.0', - providerApp: 'LT://APP1', - }, - }); - assert.equal(vi.mocked(verifyTestMuConnection).mock.calls[0]?.[0].app, 'lt://APP1'); -}); diff --git a/packages/provider-testmu/src/plugin.ts b/packages/provider-testmu/src/plugin.ts deleted file mode 100644 index 6303af5632..0000000000 --- a/packages/provider-testmu/src/plugin.ts +++ /dev/null @@ -1,8 +0,0 @@ -import type { ProviderPluginHost } from 'agent-device/plugins'; -import { createTestMuConnection } from './connection.ts'; -import { createTestMuWebDriver } from './testmu-webdriver.ts'; - -/** The version 1 plugin entry, kept so hosts without the version 2 contract still load this package. */ -export default function testMuPlugin(host: ProviderPluginHost) { - return { webDriver: createTestMuWebDriver(host), connection: createTestMuConnection(host) }; -} diff --git a/packages/provider-testmu/tsdown.config.ts b/packages/provider-testmu/tsdown.config.ts index 6173fbf90a..b0e02a7587 100644 --- a/packages/provider-testmu/tsdown.config.ts +++ b/packages/provider-testmu/tsdown.config.ts @@ -1,7 +1,7 @@ import { defineConfig } from 'tsdown'; export default defineConfig({ - entry: { plugin: 'src/plugin.ts', 'agent-device': 'src/index.ts' }, + entry: { 'agent-device': 'src/index.ts' }, outDir: 'dist', format: 'esm', platform: 'node', diff --git a/packages/provider-webdriver/src/providers.ts b/packages/provider-webdriver/src/providers.ts index dd0e6c5a46..7768dd8e3a 100644 --- a/packages/provider-webdriver/src/providers.ts +++ b/packages/provider-webdriver/src/providers.ts @@ -16,8 +16,8 @@ export const BROWSERSTACK_CREDENTIAL_VARIABLES = { /** * What a bundled provider declares before any of its code runs: the same fields an installed - * plugin publishes under `agentDevicePlugin` in its manifest. Connect policy and the credential - * fingerprint read this, never the provider implementation. + * plugin returns from its factory. Connect policy and the credential fingerprint read this, never + * the provider implementation. */ export type CloudWebDriverProviderDeclaration = Readonly<{ provider: CloudWebDriverKnownProviderName; diff --git a/packages/test-kit/src/index.ts b/packages/test-kit/src/index.ts index 5d74593d59..6a78bd476c 100644 --- a/packages/test-kit/src/index.ts +++ b/packages/test-kit/src/index.ts @@ -101,13 +101,9 @@ export { } from './loopback.ts'; export { pluginHome, - registrationSource, - selectPlugin, - selectPluginManifest, selectV2Plugin, v2RegistrationSource, webDriverPluginSource, - writePlugin, } from './plugin.fixtures.ts'; export { formatRef, diff --git a/packages/test-kit/src/plugin.fixtures.ts b/packages/test-kit/src/plugin.fixtures.ts index 7b65aa248b..d402e0b116 100644 --- a/packages/test-kit/src/plugin.fixtures.ts +++ b/packages/test-kit/src/plugin.fixtures.ts @@ -9,58 +9,44 @@ export function pluginHome() { return { home, env: { AGENT_DEVICE_HOME: home } }; } -export function writePlugin( - project: string, - name = '@example/provider', - apiVersion = 1, - provider = 'example', - source = 'throw new Error("evaluated");', +/** + * Installs a plugin package: no `agentDevicePlugin` manifest, an `./agent-device` export, options + * recorded. `exports` and `manifest` override the package.json fields, `files` adds extra files. + */ +export function selectV2Plugin( + home: string, + name: string, + source: string, + options: { + exports?: unknown; + manifest?: Record; + files?: Record; + selectionOptions?: unknown; + } = {}, ) { - const directory = path.join(project, 'node_modules', name); + const installation = crypto.randomUUID(); + const directory = path.join(home, 'plugins', installation, 'node_modules', name); fs.mkdirSync(directory, { recursive: true }); fs.writeFileSync( path.join(directory, 'package.json'), JSON.stringify({ name, - version: '1.2.3', + version: '2.0.0', type: 'module', - agentDevicePlugin: { apiVersion, provider, entry: './plugin.js' }, + exports: + 'exports' in options ? options.exports : { './agent-device': { import: './plugin.mjs' } }, + ...options.manifest, }), ); - fs.writeFileSync(path.join(directory, 'plugin.js'), source); + fs.writeFileSync(path.join(directory, 'plugin.mjs'), source); + for (const [file, contents] of Object.entries(options.files ?? {})) { + fs.mkdirSync(path.dirname(path.join(directory, file)), { recursive: true }); + fs.writeFileSync(path.join(directory, file), contents); + } + recordSelection(home, name, installation, options.selectionOptions); return directory; } -export function selectPlugin( - home: string, - name: string, - provider: string, - source: string, - apiVersion = 1, -) { - const installation = crypto.randomUUID(); - writePlugin(path.join(home, 'plugins', installation), name, apiVersion, provider, source); - recordSelection(home, name, installation); -} - -/** Installs `manifest` as-is, with an entry file that throws if evaluated. */ -export function selectPluginManifest( - home: string, - manifest: { - name: string; - version: string; - agentDevicePlugin: Record & { entry: string }; - }, -) { - const installation = crypto.randomUUID(); - const directory = path.join(home, 'plugins', installation, 'node_modules', manifest.name); - const entry = path.join(directory, manifest.agentDevicePlugin.entry); - fs.mkdirSync(path.dirname(entry), { recursive: true }); - fs.writeFileSync(path.join(directory, 'package.json'), JSON.stringify(manifest)); - fs.writeFileSync(entry, 'throw new Error("evaluated");'); - recordSelection(home, manifest.name, installation); -} - function recordSelection( home: string, name: string, @@ -74,19 +60,6 @@ function recordSelection( fs.writeFileSync(configPath, JSON.stringify(config)); } -export function registrationSource(provider: string, shutdownFile?: string) { - return `import fs from 'node:fs'; - export default host => ({ - runtime: { provider: ${JSON.stringify(provider)}, - ownsDevice: () => false, getInteractor: () => undefined, - deviceInventoryProvider: async () => [], leaseLifecycle: {}, - shutdown: async () => { ${shutdownFile ? `fs.writeFileSync(${JSON.stringify(shutdownFile)}, 'shutdown');` : ''} }, - options: host.options, env: host.env, createError: host.createError }, - platformModule: { owner: { kind: 'provider-runtime', provider: ${JSON.stringify(provider)}, instance: 'test' }, - loadRuntime: async () => { throw new Error('lazy'); } } - });`; -} - const CONSUMED_PROFILE_FIELDS: Record = { providerApp: 'consumed', providerOsVersion: 'consumed', @@ -112,31 +85,8 @@ const CONSUMED_PROFILE_FIELDS: Record = { awsInteractionMode: 'consumed', }; -/** A `{ webDriver }` factory with a total field declaration; `connection` is a JS expression. */ -export function webDriverPluginSource( - provider: string, - refused: readonly ProviderProfileField[] = [], - connection?: string, -) { - const fields = { - ...CONSUMED_PROFILE_FIELDS, - ...Object.fromEntries(refused.map((field) => [field, 'refused'])), - }; - const webDriver = { - provider, - endpoint: 'https://webdriver.test/wd/hub/', - platform: 'android', - deviceName: provider, - profileFields: { provider, label: provider, fields }, - requestPolicy: { retryAttempts: 0 }, - }; - return `export default (host) => ({ webDriver: ${JSON.stringify(webDriver)}${ - connection ? `, connection: ${connection}` : '' - } });`; -} - /** - * A v2 plugin factory module. `extra` is spliced into the returned plugin object, so a test can add + * A plugin factory module. `extra` is spliced into the returned plugin object, so a test can add * `connection` or override `credentials`; `shutdownFile` is written when the runtime shuts down. */ export function v2RegistrationSource( @@ -161,37 +111,25 @@ export function v2RegistrationSource( });`; } -/** Installs a v2 package: no `agentDevicePlugin` manifest, an `./agent-device` export, options recorded. */ -export function selectV2Plugin( - home: string, - name: string, - source: string, - options: { - exports?: unknown; - manifest?: Record; - files?: Record; - selectionOptions?: unknown; - } = {}, +/** A `{ webDriver }` factory with a total field declaration; `refused` fields the engine must refuse. */ +export function webDriverPluginSource( + provider: string, + refused: readonly ProviderProfileField[] = [], ) { - const installation = crypto.randomUUID(); - const directory = path.join(home, 'plugins', installation, 'node_modules', name); - fs.mkdirSync(directory, { recursive: true }); - fs.writeFileSync( - path.join(directory, 'package.json'), - JSON.stringify({ - name, - version: '2.0.0', - type: 'module', - exports: - 'exports' in options ? options.exports : { './agent-device': { import: './plugin.mjs' } }, - ...options.manifest, - }), - ); - fs.writeFileSync(path.join(directory, 'plugin.mjs'), source); - for (const [file, contents] of Object.entries(options.files ?? {})) { - fs.mkdirSync(path.dirname(path.join(directory, file)), { recursive: true }); - fs.writeFileSync(path.join(directory, file), contents); - } - recordSelection(home, name, installation, options.selectionOptions); - return directory; + const fields = { + ...CONSUMED_PROFILE_FIELDS, + ...Object.fromEntries(refused.map((field) => [field, 'refused'])), + }; + const webDriver = { + provider, + endpoint: 'https://webdriver.test/wd/hub/', + platform: 'android', + deviceName: provider, + profileFields: { provider, label: provider, fields }, + requestPolicy: { retryAttempts: 0 }, + }; + return `export default () => ({ + apiVersion: 2, provider: ${JSON.stringify(provider)}, credentials: { variables: [] }, + setup: async () => ({ webDriver: ${JSON.stringify(webDriver)} }), + });`; } diff --git a/scripts/release-workspace.mjs b/scripts/release-workspace.mjs index d526775a92..448108a94f 100644 --- a/scripts/release-workspace.mjs +++ b/scripts/release-workspace.mjs @@ -69,7 +69,10 @@ function checkPublishedDependencies(packed) { const unpublishableNames = new Set( packages.filter((pkg) => pkg.manifest.private === true).map((pkg) => pkg.manifest.name), ); - if (packed.agentDevicePlugin) unpublishableNames.add(rootPackage.manifest.name); + // A provider plugin exports its factory as `./agent-device` and imports only types from + // agent-device, so it must never carry the core as a runtime dependency. + if (packed.exports && Object.hasOwn(packed.exports, './agent-device')) + unpublishableNames.add(rootPackage.manifest.name); for (const field of ['dependencies', 'optionalDependencies', 'peerDependencies']) { checkDependencyField(field, packed[field] ?? {}, unpublishableNames); } diff --git a/src/__tests__/cloud-connect-testmu.test.ts b/src/__tests__/cloud-connect-testmu.test.ts index ddb3b18311..b3682dca87 100644 --- a/src/__tests__/cloud-connect-testmu.test.ts +++ b/src/__tests__/cloud-connect-testmu.test.ts @@ -15,7 +15,8 @@ import { resolveConnectProviderProfile } from '../cli/connection/connect-provide import { mkdtempForTestSync, pluginHome, - selectPlugin, + selectV2Plugin, + v2RegistrationSource, bindTestCommandHost, } from '@agent-device/test-kit'; import manifest from '@agent-device/testmu/package.json' with { type: 'json' }; @@ -50,20 +51,16 @@ const mockedVerifyWebDriverConnection = vi.mocked(verifyTestMuConnection); beforeEach(() => { const { home } = pluginHome(); - selectPlugin(home, manifest.name, 'testmu', 'export default () => {};'); - const { installation } = JSON.parse(fs.readFileSync(path.join(home, 'config.json'), 'utf8')) - .plugins[manifest.name]; - const manifestPath = path.join( + // The store declares the plugin installed with TestMu's capabilities; the mocked loader above + // supplies the workspace factory those assertions exercise. + selectV2Plugin( home, - 'plugins', - installation, - 'node_modules', manifest.name, - 'package.json', + v2RegistrationSource('testmu', { + extra: `connection: { capabilities: ${JSON.stringify(testmu().connection?.capabilities)}, resolve() {}, verify() {} },`, + credentials: '{ variables: ["LT_USERNAME", "LT_ACCESS_KEY"] }', + }), ); - const declared = JSON.parse(fs.readFileSync(manifestPath, 'utf8')); - declared.agentDevicePlugin.connection = manifest.agentDevicePlugin.connection; - fs.writeFileSync(manifestPath, JSON.stringify(declared)); vi.stubEnv('AGENT_DEVICE_HOME', home); mockedVerifyWebDriverConnection.mockImplementation(async (options) => { assert.equal(options.provider, 'testmu'); diff --git a/src/__tests__/provider-device-runtimes.test.ts b/src/__tests__/provider-device-runtimes.test.ts index 0b15653879..17f980167b 100644 --- a/src/__tests__/provider-device-runtimes.test.ts +++ b/src/__tests__/provider-device-runtimes.test.ts @@ -3,16 +3,11 @@ import { test } from 'vitest'; import { createDaemonProviderRuntimeComposition } from '../provider-device-runtimes.ts'; import fs from 'node:fs'; import path from 'node:path'; -import { - pluginHome, - registrationSource, - selectPlugin, - selectV2Plugin, -} from '@agent-device/test-kit'; +import { pluginHome, selectV2Plugin, v2RegistrationSource } from '@agent-device/test-kit'; test('daemon composition registers installed provider runtimes and their lazy platform modules', async () => { const { home, env } = pluginHome(); - selectPlugin(home, 'example', 'example', registrationSource('example')); + selectV2Plugin(home, 'example', v2RegistrationSource('example')); const composition = await createDaemonProviderRuntimeComposition({ env: env, cwd: process.cwd(), @@ -28,7 +23,7 @@ test('daemon composition registers installed provider runtimes and their lazy pl test('built-in providers register ahead of the store and an unconfigured Limrun still claims its id', async () => { const { home, env } = pluginHome(); - selectPlugin(home, 'example', 'example', registrationSource('example')); + selectV2Plugin(home, 'example', v2RegistrationSource('example')); const composition = await createDaemonProviderRuntimeComposition({ env: env, cwd: process.cwd(), @@ -51,7 +46,7 @@ test('built-in providers register ahead of the store and an unconfigured Limrun test('daemon composition records Limrun as failed for a partial instance set and still loads every other provider', async () => { const { home, env } = pluginHome(); - selectPlugin(home, 'example', 'example', registrationSource('example')); + selectV2Plugin(home, 'example', v2RegistrationSource('example')); const composition = await createDaemonProviderRuntimeComposition({ env: { ...env, @@ -76,7 +71,7 @@ test('daemon composition records Limrun as failed for a partial instance set and test('a plugin claiming a built-in provider ID is recorded as failed and the built-in keeps the ID', async () => { for (const provider of ['limrun', 'browserstack', 'aws-device-farm']) { const { home, env } = pluginHome(); - selectPlugin(home, 'example', provider, 'throw new Error("must not evaluate");'); + selectV2Plugin(home, 'example', v2RegistrationSource(provider)); const composition = await createDaemonProviderRuntimeComposition({ env: env, cwd: process.cwd(), @@ -93,6 +88,21 @@ test('a plugin claiming a built-in provider ID is recorded as failed and the bui } }); +test('a plugin claiming a routing identity is refused before the registry settles claims', async () => { + for (const provider of ['cloud', 'proxy']) { + const { home, env } = pluginHome(); + selectV2Plugin(home, 'example', v2RegistrationSource(provider)); + const composition = await createDaemonProviderRuntimeComposition({ + env: env, + cwd: process.cwd(), + }); + const plugin = composition.inventory.find(({ package: name }) => name === 'example'); + assert.equal(plugin?.state, 'failed'); + assert.equal(plugin?.error?.reason, 'reserved_provider'); + await composition.shutdown(); + } +}); + test('Limrun stays unregistered when only the removed API key alias is configured', async () => { const { env } = pluginHome(); const { runtimes, platformModules, inventory, shutdown } = diff --git a/src/builtin-provider-ids.ts b/src/builtin-provider-ids.ts index b2e542a59e..a9d2d79827 100644 --- a/src/builtin-provider-ids.ts +++ b/src/builtin-provider-ids.ts @@ -1,5 +1,5 @@ import type { ConnectionProviderCapabilities } from '@agent-device/contracts/remote'; -import { ROUTING_PROVIDER_IDENTITIES } from '@agent-device/plugins/manifest'; +import { ROUTING_PROVIDER_IDENTITIES } from '@agent-device/plugins/contract'; import { CLOUD_WEBDRIVER_PROVIDER_DECLARATIONS } from '@agent-device/provider-webdriver/providers'; export const LIMRUN_ID = 'limrun'; diff --git a/src/cli/commands/__tests__/connection-revyl.test.ts b/src/cli/commands/__tests__/connection-revyl.test.ts index ba9a563eaf..45330a3d7a 100644 --- a/src/cli/commands/__tests__/connection-revyl.test.ts +++ b/src/cli/commands/__tests__/connection-revyl.test.ts @@ -4,7 +4,12 @@ import http from 'node:http'; import type { AddressInfo } from 'node:net'; import path from 'node:path'; import { afterEach, beforeEach, test, vi } from 'vitest'; -import { mkdtempForTestSync, pluginHome, selectPlugin } from '@agent-device/test-kit'; +import { + mkdtempForTestSync, + pluginHome, + selectV2Plugin, + v2RegistrationSource, +} from '@agent-device/test-kit'; import type { CliFlags } from '@agent-device/contracts/command'; import { AppError } from '@agent-device/kernel/errors'; import { readActiveConnectionState } from '@agent-device/remote/remote-connection-state'; @@ -15,9 +20,9 @@ import manifest from '@agent-device/revyl/package.json' with { type: 'json' }; import { resolveConnectProviderProfile } from '../../connection/connect-provider-adapters.ts'; import { connectWithGeneratedProviderProfile } from '../../../__tests__/test-utils/connect-command.ts'; -// Mirrors src/__tests__/cloud-connect-testmu.test.ts: the plugin store is told the Revyl plugin is -// installed and its connection callbacks are loaded from the workspace source, so the assertions read -// the HTTP the plugin really sends rather than a mock of it. +// Mirrors src/__tests__/cloud-connect-testmu.test.ts: the store declares the Revyl plugin installed +// and its connection callbacks are loaded from the workspace source, so the assertions read the HTTP +// the plugin really sends rather than a mock of it. const mockedWithPluginConnection = vi.hoisted(() => vi.fn()); vi.mock('@agent-device/plugins/load', () => ({ @@ -81,20 +86,16 @@ afterEach(async () => { beforeEach(() => { const { home } = pluginHome(); - selectPlugin(home, manifest.name, 'revyl', 'export default () => {};'); - const { installation } = JSON.parse(fs.readFileSync(path.join(home, 'config.json'), 'utf8')) - .plugins[manifest.name]; - const manifestPath = path.join( + // The store declares the plugin installed with Revyl's capabilities; the mocked loader below + // supplies the workspace factory those assertions exercise. + selectV2Plugin( home, - 'plugins', - installation, - 'node_modules', manifest.name, - 'package.json', + v2RegistrationSource('revyl', { + extra: `connection: { capabilities: ${JSON.stringify(revyl().connection?.capabilities)}, resolve() {}, verify() {} },`, + credentials: '{ variables: ["REVYL_API_KEY"] }', + }), ); - const declared = JSON.parse(fs.readFileSync(manifestPath, 'utf8')); - declared.agentDevicePlugin.connection = manifest.agentDevicePlugin.connection; - fs.writeFileSync(manifestPath, JSON.stringify(declared)); vi.stubEnv('AGENT_DEVICE_HOME', home); vi.stubEnv('REVYL_API_KEY', 'rk_test'); vi.stubEnv('REVYL_API_URL', ''); diff --git a/src/cli/commands/__tests__/plugins.test.ts b/src/cli/commands/__tests__/plugins.test.ts index b6b8ac5db7..207589a32d 100644 --- a/src/cli/commands/__tests__/plugins.test.ts +++ b/src/cli/commands/__tests__/plugins.test.ts @@ -4,7 +4,12 @@ import path from 'node:path'; import { afterEach, test, vi } from 'vitest'; import { runCli } from '../../../cli.ts'; import { readCurrentOwnerIdentity } from '@agent-device/host-kit/process'; -import { pluginHome, selectPlugin, beginStdoutCapture } from '@agent-device/test-kit'; +import { + pluginHome, + selectV2Plugin, + v2RegistrationSource, + beginStdoutCapture, +} from '@agent-device/test-kit'; import { parseArgs, parseRawArgs, usageForCommand } from '../../parser/args.ts'; vi.mock('../../../provider-device-runtimes.ts', () => { @@ -15,17 +20,20 @@ afterEach(() => { vi.restoreAllMocks(); }); -test('plugins list and remove route through the CLI and emits JSON without daemon access or plugin evaluation', async () => { +test('plugins list and remove route through the CLI and emits JSON without daemon access or setup', async () => { const { home } = pluginHome(); vi.stubEnv('AGENT_DEVICE_HOME', home); vi.stubEnv('AGENT_DEVICE_STATE_DIR', path.join(home, 'state')); vi.stubEnv('AGENT_DEVICE_NO_UPDATE_NOTIFIER', '1'); - const marker = path.join(home, 'evaluated'); - selectPlugin( + const marker = path.join(home, 'setup'); + selectV2Plugin( home, 'example', - 'example', - `import fs from 'node:fs'; fs.writeFileSync(${JSON.stringify(marker)}, 'yes');`, + `import fs from 'node:fs'; + export default () => ({ + apiVersion: 2, provider: 'example', credentials: { variables: [] }, + setup: async () => { fs.writeFileSync(${JSON.stringify(marker)}, 'yes'); throw new Error('must not set up'); }, + });`, ); const sendToDaemon = vi.fn(async () => { throw new Error('unexpected daemon access'); @@ -40,7 +48,7 @@ test('plugins list and remove route through the CLI and emits JSON without daemo const result = JSON.parse(stdout); assert.equal(result.success, true); assert.deepEqual(result.data.plugins, [ - { name: 'example', version: '1.2.3', provider: 'example', compatible: true }, + { name: 'example', version: '2.0.0', provider: 'example', compatible: true }, ]); assert.equal(sendToDaemon.mock.calls.length, 0); await runCli(['plugins', 'remove', 'example', '--json'], { sendToDaemon }); @@ -87,7 +95,7 @@ test('plugins list reports the running daemon inventory next to the store select plugins: [failed], }), ); - selectPlugin(home, 'example', 'example', 'export default () => {};'); + selectV2Plugin(home, 'example', v2RegistrationSource('example')); const stdoutCapture = beginStdoutCapture(); try { await runCli(['plugins', 'list', '--json'], { @@ -161,7 +169,7 @@ test('plugins list names a plugin the running daemon did not register', async () ], }), ); - selectPlugin(home, 'example', 'example', 'export default () => {};'); + selectV2Plugin(home, 'example', v2RegistrationSource('example')); const text = await listPluginsAsText(home, stateDir); assert.match(text, /example@.* \(example\)/); assert.match(text, /The running daemon did not register example: bad plugin/); diff --git a/src/cli/commands/plugins.ts b/src/cli/commands/plugins.ts index 284a0f840f..9b40e6d65a 100644 --- a/src/cli/commands/plugins.ts +++ b/src/cli/commands/plugins.ts @@ -23,12 +23,7 @@ export const pluginsCommand: ClientCommandHandler = async ({ positionals, flags ); } if (action !== 'list' && name) { - await changePlugin( - action as 'add' | 'update' | 'remove', - name, - process.env, - BUILTIN_PROVIDER_IDS, - ); + await changePlugin(action as 'add' | 'update' | 'remove', name, process.env); } const plugins = await listPlugins(process.env, BUILTIN_PROVIDER_IDS); const daemon = readDaemonStatus(resolveDaemonPaths(flags.stateDir)); diff --git a/src/cli/connection/provider-policy.test.ts b/src/cli/connection/provider-policy.test.ts index b708979f2d..eb2f0fc785 100644 --- a/src/cli/connection/provider-policy.test.ts +++ b/src/cli/connection/provider-policy.test.ts @@ -1,20 +1,17 @@ import assert from 'node:assert/strict'; -import fs from 'node:fs'; -import path from 'node:path'; import { expect, test } from 'vitest'; -import { pluginConnectionNames, primePluginConnections } from '@agent-device/plugins/connection'; +import { + pluginConnectionNames, + pluginLoadFailures, + primePluginConnections, +} from '@agent-device/plugins/connection'; import { connectionProviderCapabilities, connectProviderNamesForError, isConnectProviderName, primeProviderConnection, } from './provider-policy.ts'; -import { - pluginHome, - selectPlugin, - selectV2Plugin, - v2RegistrationSource, -} from '@agent-device/test-kit'; +import { pluginHome, selectV2Plugin, v2RegistrationSource } from '@agent-device/test-kit'; test('provider policy projects provider identity into semantic capabilities', () => { assert.deepEqual(connectionProviderCapabilities('limrun'), { @@ -35,32 +32,32 @@ test('provider policy projects provider identity into semantic capabilities', () assert.equal(connectionProviderCapabilities('proxy').leaseKind, 'proxy'); }); -test('plugin capabilities come from the same environment as the provider name check', () => { +test('a manifest connection on a store package supplies no capabilities', async () => { const { home, env } = pluginHome(); - selectPlugin(home, 'example', 'example', 'export default () => {};'); - const { installation } = JSON.parse(fs.readFileSync(path.join(home, 'config.json'), 'utf8')) - .plugins.example; - const manifestPath = path.join( - home, - 'plugins', - installation, - 'node_modules/example/package.json', - ); - const declared = JSON.parse(fs.readFileSync(manifestPath, 'utf8')); - const connection = { - leaseKind: 'direct-device-provider', - requiresAppAttachment: true, - requiresRemoteDaemon: false, - supportsArtifacts: true, - supportsDeferredAppSelection: false, - supportsDirectPortReverse: false, - usesCloudWebDriverLease: true, - } as const; - declared.agentDevicePlugin.connection = connection; - fs.writeFileSync(manifestPath, JSON.stringify(declared)); + selectV2Plugin(home, 'example', v2RegistrationSource('example'), { + manifest: { + agentDevicePlugin: { + apiVersion: 1, + provider: 'example', + entry: './plugin.mjs', + connection: { + leaseKind: 'direct-device-provider', + requiresAppAttachment: true, + requiresRemoteDaemon: false, + supportsArtifacts: true, + supportsDeferredAppSelection: false, + supportsDirectPortReverse: false, + usesCloudWebDriverLease: true, + }, + }, + }, + }); - assert.equal(isConnectProviderName('example', env), true); - assert.deepEqual(connectionProviderCapabilities('example', env), connection); + assert.equal(isConnectProviderName('example', env), false); + await primeProviderConnection('example', env); + // The factory declares no connection, so the manifest never fills the gap. + assert.equal(isConnectProviderName('example', env), false); + assert.deepEqual(pluginConnectionNames(env), []); }); test('a v2 plugin declares its capabilities in code, so they are read once the store is primed', async () => { @@ -97,25 +94,13 @@ test('a store plugin that fails to load is named where an unknown connect provid ); }); -test('once the store is primed a duplicate v1 manifest no longer supplies capabilities', async () => { +test('a plugin that fails to load supplies no connection name even after priming', async () => { const { home, env } = pluginHome(); - selectPlugin(home, 'dup', 'browserstack', 'export default () => {};'); - const { installation } = JSON.parse(fs.readFileSync(path.join(home, 'config.json'), 'utf8')) - .plugins.dup; - const manifestPath = path.join(home, 'plugins', installation, 'node_modules/dup/package.json'); - const declared = JSON.parse(fs.readFileSync(manifestPath, 'utf8')); - declared.agentDevicePlugin.connection = { - leaseKind: 'direct-device-provider', - requiresAppAttachment: true, - requiresRemoteDaemon: false, - supportsArtifacts: true, - supportsDeferredAppSelection: false, - supportsDirectPortReverse: false, - usesCloudWebDriverLease: true, - }; - fs.writeFileSync(manifestPath, JSON.stringify(declared)); - - expect(pluginConnectionNames(env)).toEqual(['browserstack']); + selectV2Plugin(home, 'dup', v2RegistrationSource('browserstack')); await primePluginConnections(env, ['browserstack']); + // The built-in claimed the id first, so the store package registers nothing. expect(pluginConnectionNames(env)).toEqual([]); + expect(pluginLoadFailures(env).map(({ package: name, error }) => [name, error.reason])).toEqual([ + ['dup', 'duplicate_provider'], + ]); }); diff --git a/src/provider-credential-fingerprint.test.ts b/src/provider-credential-fingerprint.test.ts index 6ef316818d..1c0ffa6508 100644 --- a/src/provider-credential-fingerprint.test.ts +++ b/src/provider-credential-fingerprint.test.ts @@ -1,15 +1,19 @@ -import fs from 'node:fs'; -import path from 'node:path'; import { expect, test } from 'vitest'; import { providerCredentialFingerprint as fingerprintFor } from '@agent-device/plugins/credential-fingerprint'; import { readDaemonProviderCredentials as daemonCredentialsFor } from './provider-credential-fingerprint.ts'; +import type { PluginInventoryEntry } from '@agent-device/contracts/plugin-inventory'; import type { EnvMap } from '@agent-device/kernel/source-value'; import { builtinPluginInventory } from './__tests__/test-utils/builtin-plugin-inventory.ts'; -import { pluginHome, selectPluginManifest } from '@agent-device/test-kit'; +import { pluginHome, selectV2Plugin, v2RegistrationSource } from '@agent-device/test-kit'; +import { BUILTIN_PROVIDER_IDS } from './builtin-provider-ids.ts'; const inventory = await builtinPluginInventory(); -const providerCredentialFingerprint = (provider: string, env: EnvMap, leaseBackend?: string) => - fingerprintFor(provider, env, leaseBackend, inventory); +const providerCredentialFingerprint = ( + provider: string, + env: EnvMap, + leaseBackend?: string, + inventoryOverride?: readonly PluginInventoryEntry[], +) => fingerprintFor(provider, env, leaseBackend, inventoryOverride ?? inventory); const readDaemonProviderCredentials = (env: EnvMap, stateDir: string) => daemonCredentialsFor(env, stateDir, inventory); @@ -127,65 +131,100 @@ test('a Limrun lease fingerprint covers only the leased platform and the account ).toBe(ios(rotatedAndroid)); }); +/** The inventory the daemon publishes: the built-ins claim their ids, then the store loads. */ +async function storeInventory(env: Record) { + const { claimProviderIds, resolveProviderPlugins } = + await import('@agent-device/plugins/registry'); + const { storePluginCandidates } = await import('@agent-device/plugins/store'); + const resolved = await resolveProviderPlugins([ + ...claimProviderIds(BUILTIN_PROVIDER_IDS), + ...(await storePluginCandidates(env)), + ]); + return resolved.inventory(); +} + function pluginWithCredentialVariables(credentialVariables?: string[], provider = 'example') { const { home, env } = pluginHome(); - selectPluginManifest(home, { - name: '@example/provider', - version: '1.2.3', - agentDevicePlugin: { apiVersion: 1, provider, entry: './plugin.js', credentialVariables }, - }); - return env; + selectV2Plugin( + home, + '@example/provider', + v2RegistrationSource(provider, { + credentials: `{ variables: ${JSON.stringify(credentialVariables ?? [])} }`, + }), + ); + return { env: env as Record, home }; } -test('a plugin provider fingerprint hashes the variables its manifest declares', () => { - const home = pluginWithCredentialVariables(['EXAMPLE_USER', 'EXAMPLE_KEY']); +test('a plugin provider fingerprint hashes the variables its factory declares', async () => { + const { env: home } = pluginWithCredentialVariables(['EXAMPLE_USER', 'EXAMPLE_KEY']); + const inventory = await storeInventory(home); const env = { ...home, EXAMPLE_USER: 'user', EXAMPLE_KEY: 'key-1' }; - const fingerprint = providerCredentialFingerprint('example', env); + const fingerprint = providerCredentialFingerprint('example', env, undefined, inventory); expect(fingerprint).toMatch(/^v1:[0-9a-f]{16}$/); - expect(providerCredentialFingerprint('example', { ...env, UNRELATED: 'x' })).toBe(fingerprint); - expect(providerCredentialFingerprint('example', { ...env, EXAMPLE_KEY: 'key-2' })).not.toBe( - fingerprint, - ); - expect(providerCredentialFingerprint('example', { ...env, EXAMPLE_KEY: 'key-1 ' })).not.toBe( - fingerprint, - ); - expect(providerCredentialFingerprint('example', { ...home, EXAMPLE_USER: ' ' })).toBe(undefined); - expect(readDaemonProviderCredentials(env, '/state').fingerprint('example')).toBe(fingerprint); + expect( + providerCredentialFingerprint('example', { ...env, UNRELATED: 'x' }, undefined, inventory), + ).toBe(fingerprint); + expect( + providerCredentialFingerprint( + 'example', + { ...env, EXAMPLE_KEY: 'key-2' }, + undefined, + inventory, + ), + ).not.toBe(fingerprint); + expect( + providerCredentialFingerprint( + 'example', + { ...env, EXAMPLE_KEY: 'key-1 ' }, + undefined, + inventory, + ), + ).not.toBe(fingerprint); + expect( + providerCredentialFingerprint('example', { ...home, EXAMPLE_USER: ' ' }, undefined, inventory), + ).toBe(undefined); }); -test('a plugin provider without declared credential variables has no fingerprint', () => { - const env = { ...pluginWithCredentialVariables(), EXAMPLE_USER: 'user' }; - expect(providerCredentialFingerprint('example', env)).toBe(undefined); - expect(providerCredentialFingerprint('other', env)).toBe(undefined); +test('a plugin provider without declared credential variables has no fingerprint', async () => { + const { env: home } = pluginWithCredentialVariables(); + const inventory = await storeInventory(home); + const env = { ...home, EXAMPLE_USER: 'user' }; + expect(providerCredentialFingerprint('example', env, undefined, inventory)).toBe(undefined); + expect(providerCredentialFingerprint('other', env, undefined, inventory)).toBe(undefined); }); -test('a plugin declaration never adds a fingerprint to a bundled provider', () => { - const env = { - ...pluginWithCredentialVariables(['AWS_ACCESS_KEY_ID'], 'aws-device-farm'), - AWS_ACCESS_KEY_ID: 'id', - }; +test('a plugin declaration never adds a fingerprint to a bundled provider', async () => { + const { env: home } = pluginWithCredentialVariables(['AWS_ACCESS_KEY_ID'], 'aws-device-farm'); + const inventory = await storeInventory(home); + const env = { ...home, AWS_ACCESS_KEY_ID: 'id' }; + expect(providerCredentialFingerprint('aws-device-farm', env, undefined, inventory)).toBe( + undefined, + ); + // The built-in's own answer is unchanged by the store package that claims its id. expect(providerCredentialFingerprint('aws-device-farm', env)).toBe(undefined); }); -function testMuPluginEnv(): Record { - const manifest = path.resolve(import.meta.dirname, '../packages/provider-testmu/package.json'); +test('a store plugin declares per-backend credential variables in code', async () => { const { home, env } = pluginHome(); - selectPluginManifest(home, JSON.parse(fs.readFileSync(manifest, 'utf8'))); - return env; -} - -test('the bundled TestMu AI plugin manifest fingerprints its LT credentials', () => { - const home = testMuPluginEnv(); - const env = { ...home, LT_USERNAME: 'user', LT_ACCESS_KEY: 'key-1' }; - const fingerprint = providerCredentialFingerprint('testmu', env); - - expect(fingerprint).toMatch(/^v1:[0-9a-f]{16}$/); - expect(providerCredentialFingerprint('testmu', { ...env })).toBe(fingerprint); - expect(providerCredentialFingerprint('testmu', { ...env, LT_ACCESS_KEY: 'key-2' })).not.toBe( - fingerprint, + selectV2Plugin( + home, + '@example/backend', + v2RegistrationSource('example', { + credentials: + '{ variables: ["EXAMPLE_ACCOUNT"], byBackend: { "shared-session": ["EXAMPLE_POOL"] } }', + }), + ); + const inventory = await storeInventory(env as Record); + const envMap = { ...env, EXAMPLE_ACCOUNT: 'acct', EXAMPLE_POOL: 'pool-1' }; + const fingerprint = (values: Record, leaseBackend?: string) => + providerCredentialFingerprint('example', values, leaseBackend, inventory); + + // Without a backend the common variables answer; the pool belongs to one backend only. + expect(fingerprint(envMap)).toMatch(/^v1:[0-9a-f]{16}$/); + expect(fingerprint({ ...envMap, EXAMPLE_POOL: 'pool-2' })).toBe(fingerprint(envMap)); + expect(fingerprint({ ...envMap, EXAMPLE_POOL: 'pool-2' }, 'shared-session')).not.toBe( + fingerprint(envMap, 'shared-session'), ); - expect(providerCredentialFingerprint('testmu', home)).toBe(undefined); - expect(readDaemonProviderCredentials(env, '/state').fingerprint('testmu')).toBe(fingerprint); - expect(readDaemonProviderCredentials(home, '/state').fingerprint('testmu')).toBe(undefined); + expect(fingerprint({ EXAMPLE_ACCOUNT: 'acct' }, 'shared-session')).toBe(undefined); }); diff --git a/src/provider-plugin-policy.test.ts b/src/provider-plugin-policy.test.ts index 8e0c4f8776..7112f36bb2 100644 --- a/src/provider-plugin-policy.test.ts +++ b/src/provider-plugin-policy.test.ts @@ -8,7 +8,7 @@ import { startProviderRegistry, } from '@agent-device/plugins/registry'; import { storePluginCandidates } from '@agent-device/plugins/store'; -import { pluginHome, selectPlugin, webDriverPluginSource } from '@agent-device/test-kit'; +import { pluginHome, selectV2Plugin, webDriverPluginSource } from '@agent-device/test-kit'; import { PROVIDER_PLUGIN_POLICY } from './provider-plugin-policy.ts'; const realFetch = globalThis.fetch; @@ -39,7 +39,7 @@ afterEach(() => { test('a WebDriver plugin allocates through the shared engine under the process policy', async () => { const { home, env } = pluginHome(); - selectPlugin(home, 'example', 'example', webDriverPluginSource('example', ['awsProjectArn'])); + selectV2Plugin(home, 'example', webDriverPluginSource('example', ['awsProjectArn'])); const registry = await startStoreRegistry(env); const { runtime, platformModule } = registry.registrations[0]!; assert.equal(runtime.provider, 'example'); @@ -71,11 +71,13 @@ test('a WebDriver plugin allocates through the shared engine under the process p test('a WebDriver descriptor missing what the engine needs is listed as an invalid plugin', async () => { const { home, env } = pluginHome(); - selectPlugin( + selectV2Plugin( home, 'example', - 'example', - "export default () => ({ webDriver: { provider: 'example' } });", + `export default () => ({ + apiVersion: 2, provider: 'example', credentials: { variables: [] }, + setup: async () => ({ webDriver: { provider: 'example' } }), + });`, ); const registry = await startStoreRegistry(env); assert.deepEqual(registry.registrations, []); diff --git a/website/docs/docs/plugins.md b/website/docs/docs/plugins.md index d98f2cd4d1..df8523a6e5 100644 --- a/website/docs/docs/plugins.md +++ b/website/docs/docs/plugins.md @@ -134,12 +134,29 @@ connection: { Bundle the plugin implementation and ship ready-to-run ESM: installation disables lifecycle scripts. Bundle shared helpers with the plugin; `AppError` carries a shared brand so the host preserves its code and details across package copies. Import types with `import type` to keep them out of the runtime dependency graph. -## Version 1 plugins +## Migrating from a version 1 manifest -Packages that declare `agentDevicePlugin` with `apiVersion: 1` in `package.json` keep working. The host reads the manifest's `provider`, `entry`, `connection`, and `credentialVariables` before running any plugin code, then calls the default export with `ProviderPluginHost` and registers the `{ runtime, platformModule }` or `{ webDriver, connection? }` it returns. Support for this form ends in a later release; move to the `./agent-device` factory. +Earlier plugin packages declared `agentDevicePlugin` with `apiVersion: 1` in `package.json`, and the host read `provider`, `entry`, `connection`, and `credentialVariables` from it before loading any code. That form is no longer supported: a store package is loaded only through its exports, and everything it declares comes from the object its factory returns. -```json -{"agentDevicePlugin": {"apiVersion": 1, "provider": "example", "entry": "./dist/plugin.mjs"}} +To move a package: + +1. Export the factory from `./agent-device` instead of naming an entry file in the manifest, and drop `agentDevicePlugin` from `package.json`. +2. Return the manifest's values from the factory: `provider` stays `provider`, `credentialVariables` becomes `credentials: { variables: [...] }`, and the `connection` object goes on the plugin next to `setup`. +3. Return `apiVersion: 2` and keep the default export a function; the host calls it with the selection's options and `setup` receives the `ProviderPluginHost` the v1 entry used to receive first. + +```diff +-{"agentDevicePlugin": {"apiVersion": 1, "provider": "example", "entry": "./dist/plugin.mjs"}} ++{"exports": {"./agent-device": { "import": "./dist/plugin.mjs" }}} +``` + +```diff +-export default async (host) => ({ runtime, platformModule }); ++export default () => ({ ++ apiVersion: 2, ++ provider: 'example', ++ credentials: { variables: ['EXAMPLE_API_KEY'] }, ++ setup: async (host) => ({ runtime, platformModule }), ++}); ``` -A package that exports `./agent-device` is loaded as a version 2 plugin even if it also keeps the manifest, so one package can serve both old and new hosts. +A package that still ships the old manifest loads when it also exports `./agent-device`, and the manifest is then ignored. A package whose default export isn't a v2 plugin is listed as `failed` with `incompatible_plugin` and the daemon starts without it. From 246cac4a645122fe1e3053446ade8590074bc38b Mon Sep 17 00:00:00 2001 From: Thymikee Tweseling Date: Fri, 13 Nov 2026 11:05:44 +0000 Subject: [PATCH 2/3] refactor(plugins): keep entry resolution module-private after the v1 removal discoverPluginEntry is the only caller of resolvePluginEntry, and the store's version-selector check lost its second caller with the manifest branches, so both become module-local. Drop the deleted v1 entries from the Fallow entry list. Removes the dead-export findings the fallow audit raised at head. --- .fallowrc.json | 2 -- packages/plugins/src/discovery.ts | 2 +- packages/plugins/src/store.ts | 2 +- 3 files changed, 2 insertions(+), 4 deletions(-) diff --git a/.fallowrc.json b/.fallowrc.json index fb4d7c381d..1daaeb3098 100644 --- a/.fallowrc.json +++ b/.fallowrc.json @@ -7,10 +7,8 @@ "scripts/check-affected/command.ts", "packages/provider-testmu/test/package-smoke.mjs", "packages/provider-testmu/tsdown.config.ts", - "packages/provider-testmu/src/plugin.ts", "packages/provider-revyl/test/package-smoke.mjs", "packages/provider-revyl/tsdown.config.ts", - "packages/provider-revyl/src/plugin.ts", "packages/provider-webos/test/package-smoke.mjs", "packages/provider-webos/tsdown.config.ts", "packages/provider-tizen/test/package-smoke.mjs", diff --git a/packages/plugins/src/discovery.ts b/packages/plugins/src/discovery.ts index b6df3d27ec..b44c4ef0c3 100644 --- a/packages/plugins/src/discovery.ts +++ b/packages/plugins/src/discovery.ts @@ -39,7 +39,7 @@ export function discoverPluginEntry(directory: string): string { * The entry a plugin package names: a readable file inside the package directory it is installed * in. Traversal and a symlink out of that directory are refused. */ -export function resolvePluginEntry(directory: string, target: string): string { +function resolvePluginEntry(directory: string, target: string): string { try { const root = fs.realpathSync(directory); const resolved = fs.realpathSync(path.resolve(directory, target)); diff --git a/packages/plugins/src/store.ts b/packages/plugins/src/store.ts index bd58308f4d..2cf2ca5ac0 100644 --- a/packages/plugins/src/store.ts +++ b/packages/plugins/src/store.ts @@ -60,7 +60,7 @@ function isPackageName(value: string): boolean { return /^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(value); } -export function isVersionSelector(value: unknown): value is string { +function isVersionSelector(value: unknown): value is string { return ( typeof value === 'string' && /^[a-zA-Z0-9*^~<>=| .+-]+$/.test(value) && value.trim().length > 0 ); From f27396742f2d0d0e6bb00b8ce22bf2d21be15788 Mon Sep 17 00:00:00 2001 From: Thymikee Tweseling Date: Fri, 13 Nov 2026 11:21:27 +0000 Subject: [PATCH 3/3] refactor(plugins): answer the review findings on the v1 removal Point the traversal fixture at the file that exists outside the package, say the entry contract as it is (root export, which is main without exports), move the v1 manifest's connection to connection.capabilities in the migration note and separate the incompatible_plugin and invalid_plugin cases, claim the built-in id with a non-routing provider in the store test, and state what install checks. --- .changeset/remove-provider-plugin-v1.md | 2 +- docs/adr/0034-provider-plugin-registry.md | 6 +++--- packages/plugins/src/discovery.test.ts | 2 +- packages/plugins/src/registry.ts | 2 +- packages/plugins/src/store.test.ts | 10 +++++----- packages/plugins/src/store.ts | 7 ++++--- scripts/release-workspace.mjs | 3 ++- website/docs/docs/plugins.md | 6 +++--- 8 files changed, 20 insertions(+), 18 deletions(-) diff --git a/.changeset/remove-provider-plugin-v1.md b/.changeset/remove-provider-plugin-v1.md index 70d52b3993..a18f09fb30 100644 --- a/.changeset/remove-provider-plugin-v1.md +++ b/.changeset/remove-provider-plugin-v1.md @@ -6,4 +6,4 @@ Remove the version 1 provider plugin contract. A store package is now discovered only through its exports: `./agent-device`, or the package root when that subpath is absent. The host no longer reads an `agentDevicePlugin` manifest to choose an entry or to declare a provider, connection capabilities, or credential variables, and `agent-device plugins add` no longer refuses a package for a provider another manifest claims — the registry settles a duplicate provider id when the daemon next composes its plugins, as the first claim wins. -Migrate a plugin by exporting its factory from `./agent-device` and returning the manifest's values from the factory: `provider`, `credentials: { variables: [...] }`, an optional `connection`, and `setup(host)` that returns `{ runtime, platformModule }` or `{ webDriver }`, with `apiVersion: 2`. See [Provider plugins](/docs/plugins) for the full migration. A package whose default export is not a version 2 plugin is listed as `failed` with `incompatible_plugin` and the daemon starts without it. +Migrate a plugin by exporting its factory from `./agent-device` and returning the manifest's values from the factory: `provider`, `credentials: { variables: [...] }`, an optional `connection`, and `setup(host)` that returns `{ runtime, platformModule }` or `{ webDriver }`, with `apiVersion: 2`. See [Provider plugins](/docs/plugins) for the full migration. A plugin object with an `apiVersion` other than 2 is listed as `failed` with `incompatible_plugin`, and a default export that is not a plugin factory with `invalid_plugin`; the daemon starts without either. diff --git a/docs/adr/0034-provider-plugin-registry.md b/docs/adr/0034-provider-plugin-registry.md index 52a0d539de..5b97037db5 100644 --- a/docs/adr/0034-provider-plugin-registry.md +++ b/docs/adr/0034-provider-plugin-registry.md @@ -23,9 +23,9 @@ Status: accepted. Umbrella #3747; contract and registry #3755. - `daemon.json` has one reader. Its states are `absent`, `unreadable`, and `invalid`. A missing or stale record reads as a stopped daemon; an unreadable or invalid one never does. - The plugin set is fixed for a daemon's lifetime. A plugin change takes effect on the next daemon. -- A store package is discovered only through its exports: `./agent-device`, or the package root when - that subpath is absent. Nothing is read from `package.json` to choose an entry or to declare a - provider, connection capabilities, or credential variables (#3759). +- A store package is discovered through its package targets: the `./agent-device` export, else the + root export, which is `main` for a package that declares no `exports`. Nothing is read from + `package.json` to declare a provider, connection capabilities, or credential variables (#3759). ## Context diff --git a/packages/plugins/src/discovery.test.ts b/packages/plugins/src/discovery.test.ts index 2109021ffb..31ea661dd9 100644 --- a/packages/plugins/src/discovery.test.ts +++ b/packages/plugins/src/discovery.test.ts @@ -158,7 +158,7 @@ test('an entry outside the installed package is refused', () => { name: 'traversal', version: '1.0.0', type: 'module', - exports: { './agent-device': './../outside.js' }, + exports: { './agent-device': './../../outside.js' }, }), ); assert.throws( diff --git a/packages/plugins/src/registry.ts b/packages/plugins/src/registry.ts index ffbbd9cf71..00acf6328f 100644 --- a/packages/plugins/src/registry.ts +++ b/packages/plugins/src/registry.ts @@ -31,7 +31,7 @@ export type PluginCandidate = Readonly<{ source: PluginSource; package?: string; version?: string; - /** Claims `provider` without loading it, so a later candidate with that id is a duplicate. */ + /** Claims `provider` before its load settles, so a later candidate with that id is a duplicate. Dormant candidates claim it without loading. */ provider?: string; /** Claims `provider` without registering or listing: a built-in that is not configured. */ dormant?: boolean; diff --git a/packages/plugins/src/store.test.ts b/packages/plugins/src/store.test.ts index 2c6224678c..6e30bbcf85 100644 --- a/packages/plugins/src/store.test.ts +++ b/packages/plugins/src/store.test.ts @@ -205,13 +205,13 @@ test('a duplicate provider id is settled by the registry when the store composes ['second', false, 'duplicate_provider'], ], ); - // A built-in identity claims the id first, so a store package cannot take it either. + // A dormant built-in claims the id first, so a store package cannot take it either. const { home: otherHome, env: otherEnv } = pluginHome(); - selectV2Plugin(otherHome, 'cloud', v2RegistrationSource('cloud')); - const cloud = await listPlugins(otherEnv, ['cloud']); + selectV2Plugin(otherHome, 'limrun-plugin', v2RegistrationSource('limrun')); + const limrun = await listPlugins(otherEnv, ['limrun']); assert.deepEqual( - cloud.map(({ name, compatible, error }) => [name, compatible, error?.reason]), - [['cloud', false, 'reserved_provider']], + limrun.map(({ name, compatible, error }) => [name, compatible, error?.reason]), + [['limrun-plugin', false, 'duplicate_provider']], ); }); diff --git a/packages/plugins/src/store.ts b/packages/plugins/src/store.ts index 2cf2ca5ac0..8faf7ec77b 100644 --- a/packages/plugins/src/store.ts +++ b/packages/plugins/src/store.ts @@ -242,9 +242,10 @@ async function stagePlugin( } /** - * Installs, updates or removes one plugin selection. A package is accepted when its entry loads as - * a plugin; a provider-id clash with another plugin or a built-in is the registry's to settle when - * the daemon next composes its plugins. + * Installs, updates or removes one plugin selection. Install checks the staged package's identity + * and version and resolves its entry to a readable file; the factory first runs when the daemon next + * composes its plugins. A provider-id clash with another plugin or a built-in is the registry's to + * settle then, by first claim. */ export async function changePlugin( action: PluginAction, diff --git a/scripts/release-workspace.mjs b/scripts/release-workspace.mjs index 448108a94f..23659ead61 100644 --- a/scripts/release-workspace.mjs +++ b/scripts/release-workspace.mjs @@ -70,7 +70,8 @@ function checkPublishedDependencies(packed) { packages.filter((pkg) => pkg.manifest.private === true).map((pkg) => pkg.manifest.name), ); // A provider plugin exports its factory as `./agent-device` and imports only types from - // agent-device, so it must never carry the core as a runtime dependency. + // agent-device, so it must never carry the core as a runtime dependency. The root and `main` + // loading fallbacks stay a loader convenience; a published plugin package names `./agent-device`. if (packed.exports && Object.hasOwn(packed.exports, './agent-device')) unpublishableNames.add(rootPackage.manifest.name); for (const field of ['dependencies', 'optionalDependencies', 'peerDependencies']) { diff --git a/website/docs/docs/plugins.md b/website/docs/docs/plugins.md index df8523a6e5..72fa20b2e9 100644 --- a/website/docs/docs/plugins.md +++ b/website/docs/docs/plugins.md @@ -132,7 +132,7 @@ connection: { ### Package for installation -Bundle the plugin implementation and ship ready-to-run ESM: installation disables lifecycle scripts. Bundle shared helpers with the plugin; `AppError` carries a shared brand so the host preserves its code and details across package copies. Import types with `import type` to keep them out of the runtime dependency graph. +Bundle the plugin implementation and ship ready-to-run ESM: installation disables lifecycle scripts. Bundle shared helpers with the plugin; `AppError` carries a shared brand so the host preserves its code and details across package copies. Import types with `import type` to keep them out of the runtime dependency graph. A published plugin package names `./agent-device` in its `exports`: that is the subpath the host's loader and the publish checks read, so don't ship a plugin only through the root export or `main`. ## Migrating from a version 1 manifest @@ -141,7 +141,7 @@ Earlier plugin packages declared `agentDevicePlugin` with `apiVersion: 1` in `pa To move a package: 1. Export the factory from `./agent-device` instead of naming an entry file in the manifest, and drop `agentDevicePlugin` from `package.json`. -2. Return the manifest's values from the factory: `provider` stays `provider`, `credentialVariables` becomes `credentials: { variables: [...] }`, and the `connection` object goes on the plugin next to `setup`. +2. Return the manifest's values from the factory: `provider` stays `provider`, `credentialVariables` becomes `credentials: { variables: [...] }`, and the manifest's `connection` becomes `connection.capabilities`, with the `resolve` and `verify` the v1 entry returned for `connection` moved into that same `connection` object next to `setup`. 3. Return `apiVersion: 2` and keep the default export a function; the host calls it with the selection's options and `setup` receives the `ProviderPluginHost` the v1 entry used to receive first. ```diff @@ -159,4 +159,4 @@ To move a package: +}); ``` -A package that still ships the old manifest loads when it also exports `./agent-device`, and the manifest is then ignored. A package whose default export isn't a v2 plugin is listed as `failed` with `incompatible_plugin` and the daemon starts without it. +A package that still ships the old manifest loads when it also exports `./agent-device`, and the manifest is then ignored. A plugin object with an `apiVersion` other than 2 is listed as `failed` with `incompatible_plugin`, and a default export that is not a plugin factory with `invalid_plugin`; the daemon starts without either.