Skip to content

Commit 4d75aa4

Browse files
authored
refactor(plugins): remove the version 1 provider plugin contract (#3759) (#4504)
* 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. * 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. * 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.
1 parent 2b2eb83 commit 4d75aa4

40 files changed

Lines changed: 679 additions & 1072 deletions
Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
'agent-device': minor
3+
'@agent-device/testmu': minor
4+
'@agent-device/revyl': minor
5+
---
6+
7+
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.
8+
9+
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.

‎.fallowrc.json‎

Lines changed: 1 addition & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,8 @@
77
"scripts/check-affected/command.ts",
88
"packages/provider-testmu/test/package-smoke.mjs",
99
"packages/provider-testmu/tsdown.config.ts",
10-
"packages/provider-testmu/src/plugin.ts",
1110
"packages/provider-revyl/test/package-smoke.mjs",
1211
"packages/provider-revyl/tsdown.config.ts",
13-
"packages/provider-revyl/src/plugin.ts",
1412
"packages/provider-webos/test/package-smoke.mjs",
1513
"packages/provider-webos/tsdown.config.ts",
1614
"packages/provider-tizen/test/package-smoke.mjs",
@@ -152,15 +150,10 @@
152150
"exports": ["*"]
153151
},
154152
{
155-
// 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`.
153+
// 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`.
156154
"file": "packages/provider-*/src/index.ts",
157155
"exports": ["default"]
158156
},
159-
{
160-
// The version 1 entry a provider package's `agentDevicePlugin.entry` names; hosts without the version 2 contract import the built file and read `default`.
161-
"file": "packages/provider-*/src/plugin.ts",
162-
"exports": ["default"]
163-
},
164157
{
165158
// packages/platform-apple/src/lifecycle.ts loads this module on demand and reads the member off the memoized import() promise, which Fallow cannot follow.
166159
"file": "packages/platform-apple/src/expo-dev-client-launch.ts",

‎docs/adr/0034-provider-plugin-registry.md‎

Lines changed: 7 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -23,10 +23,9 @@ Status: accepted. Umbrella #3747; contract and registry #3755.
2323
- `daemon.json` has one reader. Its states are `absent`, `unreadable`, and `invalid`. A missing or
2424
stale record reads as a stopped daemon; an unreadable or invalid one never does.
2525
- The plugin set is fixed for a daemon's lifetime. A plugin change takes effect on the next daemon.
26-
- v1 plugins (`agentDevicePlugin.apiVersion: 1`) without a `./agent-device` export are dispatched by
27-
their manifest before any code runs and load through an adapter until 0.22 removes them (#3759).
28-
A package that keeps the manifest and also exports `./agent-device` loads as v2; hosts without
29-
v2 still read the manifest.
26+
- A store package is discovered through its package targets: the `./agent-device` export, else the
27+
root export, which is `main` for a package that declares no `exports`. Nothing is read from
28+
`package.json` to declare a provider, connection capabilities, or credential variables (#3759).
3029

3130
## Context
3231

@@ -44,17 +43,15 @@ had to fake the store to load a plugin from its own dependencies (#3747).
4443
fingerprint.
4544
- **A package exports its entry as `./agent-device`.** The host resolves it with import
4645
conditions and falls back to the package root only when the subpath is absent. A subpath whose
47-
import or setup throws never falls back. A v2 package needs no manifest.
46+
import or setup throws never falls back. A plugin package needs no manifest.
4847
- **The registry owns identity, not the retired lists.** Duplicate ids and bundled ids are one
4948
question answered by claim order. Credential variables, per-backend narrowing and connect
50-
capabilities are read from the registry's plugins, not from manifests. A v1 manifest still
51-
supplies them for a v1 plugin.
49+
capabilities are read from the registry's plugins, not from manifests.
5250
- **Failure is data.** A failed plugin is an inventory entry, not an exception. Behavior keys on
5351
`error.reason`, never on the message.
5452
- **A client reads a daemon's inventory from `daemon.json`.** The client credential fingerprint
55-
takes variable names from it and falls back to v1 manifests. A v2 plugin declares its connect
56-
capabilities in code, so a client loads the store, without setting up a runtime, before it reads
57-
them.
53+
takes variable names from it. A v2 plugin declares its connect capabilities in code, so a client
54+
loads the store, without setting up a runtime, before it reads them.
5855

5956
## Daemon ownership
6057

‎packages/plugins/package.json‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -30,10 +30,6 @@
3030
"types": "./src/load.ts",
3131
"default": "./src/load.ts"
3232
},
33-
"./manifest": {
34-
"types": "./src/manifest.ts",
35-
"default": "./src/manifest.ts"
36-
},
3733
"./registry": {
3834
"types": "./src/registry.ts",
3935
"default": "./src/registry.ts"

‎packages/plugins/src/connection.ts‎

Lines changed: 6 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ import type { ConnectionProviderCapabilities } from '@agent-device/contracts/rem
22
import { resolveUserConfigPath } from '@agent-device/host-kit/file';
33
import type { PluginInventoryEntry } from '@agent-device/contracts/plugin-inventory';
44
import type { PluginConnection, PluginConnectionContext } from './contract.ts';
5-
import { legacyStoreManifests, storePluginCandidates } from './store.ts';
5+
import { storePluginCandidates } from './store.ts';
66

77
/** A plugin's connection as the client calls it: the registry adds the `host` to each context. */
88
export type PluginConnectionCallbacks = Readonly<{
@@ -15,10 +15,9 @@ export type PluginConnectionCallbacks = Readonly<{
1515
export type RegisteredConnection = PluginConnectionCallbacks &
1616
Readonly<{ capabilities: PluginConnection['capabilities'] }>;
1717

18-
// Capabilities live in the plugin, so a v2 store plugin answers only once its package has loaded.
19-
// A client loads the store once per process through primePluginConnections; every synchronous
20-
// reader below then answers from that registry alone. Before the store is primed, a v1 plugin
21-
// answers from its manifest.
18+
// A plugin declares its connection capabilities in code, so a store plugin answers only once its
19+
// package has loaded. A client loads the store once per process through primePluginConnections;
20+
// every synchronous reader below then answers from that registry alone.
2221
export type FailedPlugin = Extract<PluginInventoryEntry, { state: 'failed' }>;
2322

2423
type PrimedStore = Readonly<{
@@ -69,16 +68,10 @@ export function pluginConnectionCapabilities(
6968
env: NodeJS.ProcessEnv,
7069
): ConnectionProviderCapabilities | undefined {
7170
if (provider === undefined) return undefined;
72-
const store = primed.get(resolveUserConfigPath(env));
73-
if (store) return store.connections.get(provider)?.capabilities;
74-
return legacyStoreManifests(env).find((plugin) => plugin.agentDevicePlugin.provider === provider)
75-
?.agentDevicePlugin.connection;
71+
return primed.get(resolveUserConfigPath(env))?.connections.get(provider)?.capabilities;
7672
}
7773

7874
export function pluginConnectionNames(env: NodeJS.ProcessEnv): string[] {
7975
const store = primed.get(resolveUserConfigPath(env));
80-
if (store) return [...store.connections.keys()];
81-
return legacyStoreManifests(env)
82-
.filter((plugin) => plugin.agentDevicePlugin.connection)
83-
.map((plugin) => plugin.agentDevicePlugin.provider);
76+
return store ? [...store.connections.keys()] : [];
8477
}

‎packages/plugins/src/contract.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,9 @@ import type { ProviderPluginHost } from './host.ts';
99
/** The provider plugin contract version this module defines. */
1010
export const PROVIDER_PLUGIN_API_VERSION = 2;
1111

12+
/** Provider ids that name daemon routing; no plugin can claim either of them. */
13+
export const ROUTING_PROVIDER_IDENTITIES: readonly string[] = ['cloud', 'proxy'];
14+
1215
/**
1316
* The environment variables a plugin reads credentials from. The host fingerprints their values to
1417
* refuse a lease when the shell holds different credentials than the daemon started with. List

‎packages/plugins/src/credential-fingerprint.ts‎

Lines changed: 5 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -4,23 +4,22 @@ import {
44
type PluginInventoryEntry,
55
} from '@agent-device/contracts/plugin-inventory';
66
import type { EnvMap } from '@agent-device/kernel/source-value';
7-
import { legacyStoreManifests } from './store-legacy.ts';
87

98
type CredentialValues = Readonly<Record<string, string | undefined>>;
109

1110
/**
1211
* A versioned, non-reversible digest of the credentials a lease on `leaseBackend` reads from `env`,
1312
* or undefined when `env` holds none of them or the provider's credentials do not come from the
1413
* environment. Provider names are trimmed before lookup. Variable names come from the daemon's
15-
* plugin inventory, then from v1 manifests.
14+
* plugin inventory.
1615
*/
1716
export function providerCredentialFingerprint(
1817
provider: string,
1918
env: EnvMap,
2019
leaseBackend?: string,
2120
inventory?: readonly PluginInventoryEntry[],
2221
): string | undefined {
23-
const variables = declaredCredentialVariables(provider.trim(), env, leaseBackend, inventory);
22+
const variables = declaredCredentialVariables(provider.trim(), leaseBackend, inventory);
2423
// Whitespace-only counts as unset and other values are kept as is, as the provider's requireEnv does.
2524
return variables
2625
? digest(
@@ -31,17 +30,14 @@ export function providerCredentialFingerprint(
3130
: undefined;
3231
}
3332

34-
// Read from the inventory or manifest, so neither the client nor the daemon evaluates provider code.
33+
// Read from the inventory the daemon published, so neither the client nor the daemon evaluates
34+
// provider code.
3535
function declaredCredentialVariables(
3636
provider: string,
37-
env: EnvMap,
3837
leaseBackend: string | undefined,
3938
inventory: readonly PluginInventoryEntry[] | undefined,
4039
): readonly string[] | undefined {
41-
const published = inventory && pluginCredentialVariables(inventory, provider, leaseBackend);
42-
if (published) return published;
43-
return legacyStoreManifests(env).find((plugin) => plugin.agentDevicePlugin.provider === provider)
44-
?.agentDevicePlugin.credentialVariables;
40+
return inventory && pluginCredentialVariables(inventory, provider, leaseBackend);
4541
}
4642

4743
function digest(values: CredentialValues): string | undefined {

‎packages/plugins/src/discovery.test.ts‎

Lines changed: 62 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -120,11 +120,68 @@ test('package export resolution agrees with Node for each shape a plugin package
120120
entry.name,
121121
);
122122
} else {
123-
assert.deepEqual(
124-
discoverPluginEntry(directory),
125-
{ kind: 'v2', file: path.join(directory, entry.loads) },
126-
entry.name,
127-
);
123+
assert.equal(discoverPluginEntry(directory), path.join(directory, entry.loads), entry.name);
128124
}
129125
}
130126
});
127+
128+
test('a manifest entry never selects the loaded file', () => {
129+
const root = fs.realpathSync(mkdtempForTestSync('agent-device-manifest-entry-'));
130+
const directory = path.join(root, 'node_modules', 'declared');
131+
fs.mkdirSync(directory, { recursive: true });
132+
fs.writeFileSync(
133+
path.join(directory, 'package.json'),
134+
JSON.stringify({
135+
name: 'declared',
136+
version: '1.0.0',
137+
type: 'module',
138+
main: './main.js',
139+
agentDevicePlugin: { apiVersion: 1, provider: 'declared', entry: './legacy.js' },
140+
}),
141+
);
142+
for (const file of ['main.js', 'legacy.js'])
143+
fs.writeFileSync(path.join(directory, file), 'export {};');
144+
145+
assert.equal(discoverPluginEntry(directory), path.join(directory, 'main.js'));
146+
});
147+
148+
test('an entry outside the installed package is refused', () => {
149+
const root = mkdtempForTestSync('agent-device-entry-containment-');
150+
const outside = path.join(root, 'outside.js');
151+
fs.writeFileSync(outside, 'export {};');
152+
153+
const escaped = path.join(root, 'node_modules', 'traversal');
154+
fs.mkdirSync(escaped, { recursive: true });
155+
fs.writeFileSync(
156+
path.join(escaped, 'package.json'),
157+
JSON.stringify({
158+
name: 'traversal',
159+
version: '1.0.0',
160+
type: 'module',
161+
exports: { './agent-device': './../../outside.js' },
162+
}),
163+
);
164+
assert.throws(
165+
() => discoverPluginEntry(escaped),
166+
(error: unknown) =>
167+
(error as { details?: { reason?: string } }).details?.reason === 'plugin_load_failed',
168+
);
169+
170+
const linked = path.join(root, 'node_modules', 'symlinked');
171+
fs.mkdirSync(linked, { recursive: true });
172+
fs.writeFileSync(
173+
path.join(linked, 'package.json'),
174+
JSON.stringify({
175+
name: 'symlinked',
176+
version: '1.0.0',
177+
type: 'module',
178+
exports: { './agent-device': './plugin.js' },
179+
}),
180+
);
181+
fs.symlinkSync(outside, path.join(linked, 'plugin.js'));
182+
assert.throws(
183+
() => discoverPluginEntry(linked),
184+
(error: unknown) =>
185+
(error as { details?: { reason?: string } }).details?.reason === 'plugin_load_failed',
186+
);
187+
});

‎packages/plugins/src/discovery.ts‎

Lines changed: 30 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -2,37 +2,26 @@ import fs from 'node:fs';
22
import path from 'node:path';
33
import { AppError } from '@agent-device/kernel/errors';
44
import { isRecord } from '@agent-device/kernel/record';
5-
import { readPluginManifest, resolvePluginEntry, type PluginManifest } from './manifest.ts';
65

76
const PROVIDER_ID = /^[a-z][a-z0-9-]*$/;
87

98
export function isProviderId(value: unknown): value is string {
109
return typeof value === 'string' && PROVIDER_ID.test(value);
1110
}
1211

13-
/** The subpath a v2 plugin package exports; its default export is the plugin factory. */
12+
/** The subpath a plugin package exports; its default export is the plugin factory. */
1413
const PLUGIN_ENTRY_SUBPATH = './agent-device';
1514

16-
export type PluginPackageEntry =
17-
| Readonly<{ kind: 'v2'; file: string }>
18-
| Readonly<{ kind: 'v1'; manifest: PluginManifest }>;
19-
2015
/**
21-
* Chooses how an installed package loads, without evaluating it. The `./agent-device` export wins;
22-
* a package that lacks that subpath and declares `agentDevicePlugin` is a v1 plugin dispatched by
23-
* its manifest; any other package falls back to its root export. A subpath that exists but does
24-
* not resolve is an error, never a reason to fall back.
16+
* Chooses the file an installed package loads, without evaluating it. The `./agent-device` export
17+
* wins; a package that lacks that subpath falls back to its root export. A subpath that exists but
18+
* does not resolve is an error, never a reason to fall back.
2519
*/
26-
export function discoverPluginEntry(directory: string): PluginPackageEntry {
20+
export function discoverPluginEntry(directory: string): string {
2721
const manifest = readPackageJson(directory);
2822
const subpath = resolveExport(manifest.exports, PLUGIN_ENTRY_SUBPATH);
29-
if (subpath.status === 'resolved') {
30-
return { kind: 'v2', file: resolvePluginEntry(directory, subpath.target) };
31-
}
23+
if (subpath.status === 'resolved') return resolvePluginEntry(directory, subpath.target);
3224
if (subpath.status === 'blocked') throw unresolvableEntry(directory, PLUGIN_ENTRY_SUBPATH);
33-
if (manifest.agentDevicePlugin !== undefined) {
34-
return { kind: 'v1', manifest: readPluginManifest(directory) };
35-
}
3625
const root = resolveExport(manifest.exports, '.');
3726
if (root.status === 'blocked') throw unresolvableEntry(directory, '.');
3827
const target =
@@ -43,7 +32,30 @@ export function discoverPluginEntry(directory: string): PluginPackageEntry {
4332
? `./${path.posix.normalize(manifest.main)}`
4433
: undefined;
4534
if (target === undefined) throw missingEntry(directory, PLUGIN_ENTRY_SUBPATH);
46-
return { kind: 'v2', file: resolvePluginEntry(directory, target) };
35+
return resolvePluginEntry(directory, target);
36+
}
37+
38+
/**
39+
* The entry a plugin package names: a readable file inside the package directory it is installed
40+
* in. Traversal and a symlink out of that directory are refused.
41+
*/
42+
function resolvePluginEntry(directory: string, target: string): string {
43+
try {
44+
const root = fs.realpathSync(directory);
45+
const resolved = fs.realpathSync(path.resolve(directory, target));
46+
if (
47+
target.startsWith('./') &&
48+
resolved.startsWith(`${root}${path.sep}`) &&
49+
fs.statSync(resolved).isFile()
50+
) {
51+
return resolved;
52+
}
53+
} catch {}
54+
throw new AppError('INVALID_ARGS', 'Plugin entry must be a readable file inside its package', {
55+
reason: 'plugin_load_failed',
56+
directory,
57+
entry: target,
58+
});
4759
}
4860

4961
export function readPackageJson(directory: string): Record<string, unknown> {

0 commit comments

Comments
 (0)