Skip to content

Commit c9aa2f2

Browse files
committed
Merge remote-tracking branch 'origin/main' into refactor/host-environment
* origin/main: feat(provider-testmu): publish @agent-device/testmu on plugin contract v2 (#3770) docs(plugins): document plugin contract v2, the inventory and ADR 0034 (#3769) feat(daemon): daemon status lists the registered provider plugins (#3768) feat(plugins): plugin contract v2 and one provider registry (#3767) # Conflicts: # packages/daemon/src/sessions/handlers/lease.ts # src/__tests__/cloud-connect-testmu.test.ts # src/cli/commands/connection.ts # src/cli/commands/daemon.ts # src/daemon-client/daemon-client-metadata.ts # src/daemon-client/daemon-client.ts
2 parents f744554 + e6340d2 commit c9aa2f2

98 files changed

Lines changed: 4511 additions & 1272 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.fallowrc.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,11 @@
9999
"file": "packages/provider-*/src/index.ts",
100100
"exports": ["default"]
101101
},
102+
{
103+
// The version 1 entry a provider package's `agentDevicePlugin.entry` names; hosts without the version 2 contract import the built file and read `default`.
104+
"file": "packages/provider-*/src/plugin.ts",
105+
"exports": ["default"]
106+
},
102107
{
103108
// packages/platform-apple/src/lifecycle.ts loads this module on demand and reads the member off the memoized import() promise, which Fallow cannot follow.
104109
"file": "packages/platform-apple/src/expo-dev-client-launch.ts",

‎CHANGELOG.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,15 @@
33
## Unreleased
44

55
- Fix `ensureDaemon()`, the CLI and MCP killing a daemon they had just asked to leave. After the daemon answers the quiesce request with `draining`, the client now waits up to 60 s for it to exit by itself and clean up its registration, so plugin disposal and lease finalization finish (on Windows a signal ends the process outright, and on POSIX a drain longer than 3 s was killed). A daemon still running at the deadline that fails its liveness probes is force-retired; one that still answers is left running and the call fails with `details.reason: 'daemon-drain-timeout'`, with a hint naming `agent-device daemon stop --state-dir <path>`.
6+
- `@agent-device/testmu` is now a version 2 provider plugin. `import testmu from '@agent-device/testmu'` gives a factory, `testmu({ credentials: { username, accessKey } })`, that reads those credentials instead of `LT_USERNAME` and `LT_ACCESS_KEY`; without options it reads the variables as before. The package still declares the version 1 plugin entry, so `agent-device plugins add @agent-device/testmu` keeps working on hosts that predate the version 2 contract.
7+
- Provider plugins have a new contract. A package exports a factory at `./agent-device` that returns `{ apiVersion: 2, provider, credentials, connection?, setup(host) }`, typed by `AgentDevicePluginFactory` from `agent-device/plugins`. The store calls the factory with the package's `config.json` options, and a JavaScript host can call it directly. Version 1 plugins (`agentDevicePlugin.apiVersion: 1`) keep loading.
8+
- Bundled providers and installed plugins now register through one registry, in that order, with a third slot for embedder plugins (#3757). The first plugin to name a provider id claims it; a later duplicate is recorded as failed, and `cloud` and `proxy` stay reserved.
9+
- A plugin that fails to load, validate, or set up no longer stops the daemon. It is listed as `failed` with a typed `error.reason`, and the other providers still register. The new `agent-device daemon status [--json]` shows the inventory, which the daemon also publishes in `daemon.json`; `plugins list --json` works without a daemon and reports a running daemon's inventory under `daemon`.
10+
- The client reads provider credential variable names from that inventory, narrowed per lease backend, and falls back to version 1 manifests. A Limrun credential fingerprint now hashes the exact variable values, so padding whitespace around a value counts as a change, as it does for BrowserStack.
11+
- A partial Limrun instance set now appears in `daemon status` as a failed provider and as `provider_plugin_failed` in `daemon.log`, replacing `provider_runtime_skipped`.
612
- Behavior change: the CLI and MCP now call `ensureDaemon()` explicitly once their config is resolved, then attach to the daemon it leaves. A command that finds a daemon from another version or build replaces it only if the daemon reports no request, session, repair session or live lease. A resumable upload still streaming and a host human-control hold that names no lease are not counted, so a replacement can end them. A daemon that answers nothing on any transport is retired after repeated failed liveness probes, which cannot show it idle. A busy one fails the command with `details.reason: 'daemon-busy'` instead of being replaced with its sessions, and a daemon from a release that predates quiescing fails it with `'daemon-incompatible'`; stop either with `agent-device daemon stop --state-dir <path>`. The takeover notice moves from `Replacing daemon … : <reason>` to `Replaced idle daemon …` (an incompatible daemon) or `Replaced unreachable daemon …` (one that answered nothing). A request that times out no longer retires an unresponsive daemon from the CLI or MCP; the error names `agent-device daemon stop --state-dir <path>`. A one-shot `replay` or `test` with an explicit `--state-dir` leaves the daemon it started running until its idle reap instead of stopping it. Remote `--daemon-base-url` connections and replay on its private ephemeral daemon are unchanged. Node.js clients keep `daemonLifecycle: 'managed'` until 0.22.
713
- Add `ensureDaemon({ stateDir })` and the client config `daemonLifecycle: 'attach' | 'managed'`. An `attach` client connects to the daemon registered in the state directory and never starts, replaces or kills one, including after a request times out. It fails with `details.reason: 'daemon-not-running'` (the hint points at `ensureDaemon()`) or `'daemon-incompatible'` (both identities in `details`, the hint names `agent-device daemon stop`). `ensureDaemon()` starts a missing daemon and replaces an incompatible one that answers only through an authenticated quiesce request the daemon answers itself (a resumable upload still streaming and a human-control hold that names no lease are not counted, so a replacement can end them): it refuses with `daemon-busy` while any request is in flight or any session, repair session or live lease exists, and a daemon from a release before this one is never replaced. A registered daemon that answers nothing is retired, as is one that times out on the quiesce request and then fails repeated liveness probes; neither can be asked. A remote `daemonBaseUrl` connection never starts or retires a local daemon in either mode. `managed` stays the default and behaves as before until 0.22.
8-
- `lease_allocate` (and `client.leases.allocate()`) with a `leaseProvider` that no registered runtime claims now refuses before recording a lease, with `UNSUPPORTED_OPERATION`, `error.details.reason: provider-not-registered`, `details.provider` and `details.registeredProviders`. Previously a plugin provider that the daemon never loaded passed admission and recorded a lease with no device behind it. Leases with no provider (a `leaseBackend` alone included), `proxy` and `cloud` need no runtime and still allocate. Restart the daemon with the provider configured, then retry.
14+
- `lease_allocate` (and `client.leases.allocate()`) with a `leaseProvider` that no registered runtime claims now refuses before recording a lease, with `UNSUPPORTED_OPERATION`, `error.details.reason: provider-not-registered`, `details.provider`, `details.registeredProviders`, and `details.failedPlugins` naming a plugin that failed to register. Previously a plugin provider that the daemon never loaded passed admission and recorded a lease with no device behind it. Leases with no provider (a `leaseBackend` alone included), `proxy` and `cloud` need no runtime and still allocate. Restart the daemon with the provider configured, then retry.
915
- Add `uninstall <app>` and `client.apps.uninstall({ app })` to remove an installed app on adb-backed Android targets, iOS simulators, and CoreDevice iOS devices. Both report `wasInstalled`. A package name or bundle id that is not installed succeeds with `wasInstalled: false`. Other targets, Appium and Limrun sessions included, refuse it before anything runs.
1016
- Add `settings mobile-data on|off` for adb-backed Android targets. It switches mobile data through `svc data` and reports the `mobileData` state stored in the global `mobile_data` row; multi-SIM read-back is not covered yet. Every other target refuses it before anything runs, and `--app` is refused because the switch is device-wide.
1117
- On iOS, a `fill` that runs under a degraded XCTest snapshot channel now aims at a point, including ref, selector and replay fills. When the runner identifies no text input under that point, it refuses with `NO_TEXT_INPUT_AT_POINT` (`error.details.reason: no_text_input_at_point`, `dispatched: no`) before dispatching its focus tap, and no field changes; when the input lookup itself cannot answer, it refuses with `TEXT_INPUT_PROBE_UNAVAILABLE` (`error.details.reason: text_input_probe_unavailable`). Previously such a fill cleared and typed through the app-level first responder, so it could rewrite a field the caller never named, or report a clear failure after emptying it. A ref or selector fill whose rect centre misses the real field (an outer container, a non-input node) now needs a point inside the input's own rect.
Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# 0034. Provider plugin registry
2+
3+
Status: accepted. Umbrella #3747; contract and registry #3755.
4+
5+
## Rules at a glance
6+
7+
- One contract. A provider plugin is a factory that returns `{ apiVersion: 2, provider, credentials,
8+
connection?, setup(host) }`. `setup` returns `{ runtime, platformModule, dispose? }` or
9+
`{ webDriver, dispose? }`. A `{ webDriver }` result stays a data descriptor the host interprets.
10+
- One registry. Sources compose in the order built-in, store, embedder; the embedder slot arrives with #3757. Built-in providers use the
11+
same shape as an installed plugin, and one function validates what every factory returns.
12+
- Plugins import only types from agent-device. The type-only contract is `agent-device/plugins`;
13+
there is no runtime helper, and the contract does not depend on a plugin's module URL.
14+
- The first registration of a provider id claims it, even when that registration fails. Later ones
15+
are recorded as failed. `cloud` and `proxy` are routing identities no plugin can claim.
16+
- A plugin that fails to enumerate, load, validate or set up is recorded and skipped. The daemon
17+
starts with the rest. The inventory lists every plugin as `active` or `failed`, with a typed
18+
`error.reason`, and is published in `daemon.json` and by `agent-device daemon status`.
19+
- `registry.close()` is the single, idempotent cleanup owner. It shuts down each runtime, then calls
20+
its `dispose`, and returns an outcome per plugin and step. Runtimes are never wrapped.
21+
Composition is transactional: when a later step fails, it closes the registry before it throws.
22+
- The registry receives candidates. Composition chooses the sources.
23+
- `daemon.json` has one reader. Its states are `absent`, `unreadable`, and `invalid`. A missing or
24+
stale record reads as a stopped daemon; an unreadable or invalid one never does.
25+
- 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.
30+
31+
## Context
32+
33+
Three things loaded providers: a hand-kept `RESERVED_PLUGIN_PROVIDERS` list, a second list of
34+
providers the daemon must have a runtime for, and a store that treated one bad plugin as a daemon
35+
startup failure. Each provider kind also needed its own path for credential fingerprints and for
36+
`connect` capabilities, which read manifests the bundled providers do not have. An embedding host
37+
had to fake the store to load a plugin from its own dependencies (#3747).
38+
39+
## Decisions
40+
41+
- **A factory takes options.** The store calls it with `config.json` `plugins[name].options`; a JS
42+
host calls it directly with its own, such as credentials. A plugin that takes credentials as
43+
options declares no environment variables for them, so they stay out of the environment
44+
fingerprint.
45+
- **A package exports its entry as `./agent-device`.** The host resolves it with import
46+
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.
48+
- **The registry owns identity, not the retired lists.** Duplicate ids and bundled ids are one
49+
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.
52+
- **Failure is data.** A failed plugin is an inventory entry, not an exception. Behavior keys on
53+
`error.reason`, never on the message.
54+
- **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.
58+
59+
## Daemon ownership
60+
61+
The target is that starting or replacing a daemon is an explicit act, not a side effect of a client
62+
call. Today a client call can still start a daemon; #3754 makes that explicit for the client
63+
lifecycle, and #3757 adds `agent-device/host`, where an embedder owns its daemon and passes its
64+
plugins as the third source.
65+
66+
## Alternatives refused
67+
68+
- **Keep the manifest as the contract.** It cannot describe options-dependent credentials, and a
69+
bundled provider has no package to hold one.
70+
- **A runtime helper such as `definePlugin`.** It would make plugins depend on a runtime export of
71+
agent-device and its version, which is what a type-only contract avoids.
72+
- **Fail the daemon on a bad plugin.** One broken optional package then takes every provider down.

‎docs/adr/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@
3535
| [0031 macOS Native App Backend](0031-macos-native-app-backend.md) | `AGENT_DEVICE_MACOS_APP_BACKEND`, driving macOS app sessions without XCTest Automation Mode, why pointer actions are accessibility actions only, and the ghost cursor |
3636
| [0032 Layering Graph Engine](0032-layering-graph-engine.md) | evaluating replacement of `scripts/layering/` graph rules with dependency-cruiser or fallow `boundaries`, why graph-based layering checks share one replaceable import model, the measured edge-set and parity gaps, and the revisit triggers |
3737
| [0033 Collocation decision table](0033-collocation-decision-table.md) | moving or adding a file listed in umbrella #3276 §5, re-proposing a move that table refused, reading a zone's collocation decisions |
38+
| [0034 Provider plugin registry](0034-provider-plugin-registry.md) | provider plugins, the `agent-device/plugins` contract, plugin sources and order, duplicate provider ids, plugin failure isolation, the daemon plugin inventory and `daemon status` |
3839

3940
ADRs record *why*; the registries and gates they describe are the living source of truth — when
4041
prose and a registry disagree, the registry wins and the ADR needs a follow-up.

‎packages/contracts/package.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -300,6 +300,10 @@
300300
"types": "./src/lease-scope.ts",
301301
"default": "./src/lease-scope.ts"
302302
},
303+
"./plugin-inventory": {
304+
"types": "./src/plugin-inventory.ts",
305+
"default": "./src/plugin-inventory.ts"
306+
},
303307
"./local-interactor-operation-set": {
304308
"types": "./src/local-interactor-operation-set.ts",
305309
"default": "./src/local-interactor-operation-set.ts"
Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
import { expect, test } from 'vitest';
2+
import { pluginCredentialVariables, readPluginInventory } from './plugin-inventory.ts';
3+
4+
const credentials = { variables: ['A'], byBackend: { ios: ['A', 'B'] } };
5+
6+
test('the reader keeps well-formed entries and drops entries that lose plugin state', () => {
7+
const active = { provider: 'p', source: 'store', state: 'active', credentials };
8+
const failed = {
9+
source: 'builtin',
10+
state: 'failed',
11+
error: { code: 'INVALID_ARGS', message: 'bad', reason: 'invalid_plugin' },
12+
credentials,
13+
};
14+
expect(
15+
readPluginInventory([
16+
active,
17+
failed,
18+
{ ...active, credentials: undefined },
19+
{ ...active, credentials: { variables: 'A' } },
20+
{ ...failed, error: undefined },
21+
{ ...active, state: 'unknown' },
22+
'not an entry',
23+
]),
24+
).toEqual([active, failed]);
25+
});
26+
27+
test('credential variables narrow to the lease backend of an active plugin only', () => {
28+
const inventory = readPluginInventory([
29+
{ provider: 'p', source: 'store', state: 'active', credentials },
30+
{
31+
provider: 'q',
32+
source: 'store',
33+
state: 'failed',
34+
error: { code: 'X', message: 'm' },
35+
credentials,
36+
},
37+
]);
38+
expect(pluginCredentialVariables(inventory, 'p', 'ios')).toEqual(['A', 'B']);
39+
expect(pluginCredentialVariables(inventory, 'p', 'android')).toEqual(['A']);
40+
expect(pluginCredentialVariables(inventory, 'q')).toBeUndefined();
41+
});

0 commit comments

Comments
 (0)