Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .changeset/remove-provider-plugin-v1.md
Original file line number Diff line number Diff line change
@@ -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 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.
9 changes: 1 addition & 8 deletions .fallowrc.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down Expand Up @@ -152,15 +150,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",
Expand Down
17 changes: 7 additions & 10 deletions docs/adr/0034-provider-plugin-registry.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 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

Expand All @@ -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

Expand Down
4 changes: 0 additions & 4 deletions packages/plugins/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
19 changes: 6 additions & 13 deletions packages/plugins/src/connection.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<{
Expand All @@ -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<PluginInventoryEntry, { state: 'failed' }>;

type PrimedStore = Readonly<{
Expand Down Expand Up @@ -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()] : [];
}
3 changes: 3 additions & 0 deletions packages/plugins/src/contract.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
14 changes: 5 additions & 9 deletions packages/plugins/src/credential-fingerprint.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,23 +4,22 @@ 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<Record<string, string | undefined>>;

/**
* 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,
env: EnvMap,
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(
Expand All @@ -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 {
Expand Down
67 changes: 62 additions & 5 deletions packages/plugins/src/discovery.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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',
);
});
48 changes: 30 additions & 18 deletions packages/plugins/src/discovery.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,37 +2,26 @@ 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-]*$/;

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 =
Expand All @@ -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.
*/
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<string, unknown> {
Expand Down
Loading
Loading