diff --git a/.changeset/explicit-sdk-hosts.md b/.changeset/explicit-sdk-hosts.md new file mode 100644 index 0000000000..fe5fde90e4 --- /dev/null +++ b/.changeset/explicit-sdk-hosts.md @@ -0,0 +1,11 @@ +--- +'agent-device': minor +--- + +Require explicit SDK host dependencies in 0.22. Part of #3759 section 3. + +Pass `{ env, cwd }` to `runAndroidShell(device, words, host, options?)`, `runAndroidExecOut(device, words, host, options?)`, `resolveAndroidArchivePackageName(archivePath, host, signal?)`, `prepareMetroRuntime(options, host)`, and `new LimrunRuntime(options, host)`. For example, capture `const host = { env: { ...process.env }, cwd: process.cwd() }` in your entry point, then call `await prepareMetroRuntime(options, host)`. + +`resolveRemoteConfigProfile({ configPath, cwd, env })` requires `env`, and `createLocalArtifactAdapter({ cwd })` requires `cwd`. Archive inspection resolves relative paths from the supplied host and no longer shares a cached SDK tool across hosts. The internal contracts, host-kit, remote, and platform-android packages are bundled into `agent-device`; this changeset covers their affected public APIs. + +Executable captures and `startAgentDevice`'s optional-host capture remain available. See [Build an integration](/docs/build-an-integration#migrate-sdk-hosts-to-022) for migration examples. diff --git a/.changeset/remove-provider-plugin-v1.md b/.changeset/remove-provider-plugin-v1.md new file mode 100644 index 0000000000..a18f09fb30 --- /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 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/.fallowrc.json b/.fallowrc.json index c1d92c5396..8a18a8bda2 100644 --- a/.fallowrc.json +++ b/.fallowrc.json @@ -6,11 +6,15 @@ "scripts/check-provider-plugin.mjs", "scripts/check-affected/command.ts", "packages/provider-testmu/test/package-smoke.mjs", + "packages/maestro/test/package-artifact.test.mjs", + "packages/maestro/test/packed-clickability.mjs", + "packages/maestro/test/packed-screen-origin.mjs", + "packages/maestro/test/package-test-support.mjs", + "packages/maestro/tsdown.config.ts", + "packages/maestro/src/plugin.ts", "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", @@ -152,13 +156,8 @@ "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`. - "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", + // A published plugin's default export is its contract; the plugin loader imports the installed package's resolved entry at runtime and reads `default`. + "file": "packages/{provider-*/src/index,maestro/src/plugin}.ts", "exports": ["default"] }, { @@ -288,7 +287,7 @@ }, { // Tool config default exports, loaded by the tool rather than imported. - "file": "{oxlint.config.ts,tsdown.config.ts,packages/provider-*/tsdown.config.ts,packages/proxy/tsdown.config.ts,vitest.mutation.config.ts}", + "file": "{oxlint.config.ts,tsdown.config.ts,packages/provider-*/tsdown.config.ts,packages/maestro/tsdown.config.ts,packages/proxy/tsdown.config.ts,vitest.mutation.config.ts}", "exports": ["default"] }, { diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 809d22b3ed..398963046a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -14,12 +14,13 @@ on: push: branches: - main + - '0.22' permissions: contents: read -# Release and nightly publishing require green CI on the exact main commit, so a -# main push never cancels or replaces another commit's run. +# Release and nightly publishing require green CI on the exact source commit, so a +# push never cancels or replaces another commit's run. concurrency: group: >- ci-${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.ref || github.sha }} @@ -101,6 +102,10 @@ jobs: uses: ./.github/actions/run-gate with: { gate: build } + - name: Verify the core and standalone Maestro packages + uses: ./.github/actions/run-gate + with: { gate: package } + - name: Verify emitted chunk ownership uses: ./.github/actions/run-gate with: { gate: bundle-owner-files } @@ -117,7 +122,7 @@ jobs: # # Runs the script directly rather than through `pnpm check:package`: the repo's pinned pnpm # requires Node >= 22.13 and refuses to start on the 22.12 floor this job exists to cover. The - # gate itself only needs `node` and `npm`, so it is the package.json script minus the launcher. + # root-package probe only needs `node` and `npm`. The full package gate runs above. - name: Verify the published package on Node.js 22.12 run: node --experimental-strip-types scripts/check-package.ts diff --git a/docs/adr/0034-provider-plugin-registry.md b/docs/adr/0034-provider-plugin-registry.md index 6c3d1bc277..5b97037db5 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 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 @@ -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/docs/agents/code-ownership.md b/docs/agents/code-ownership.md index e9b65ea372..30674c687c 100644 --- a/docs/agents/code-ownership.md +++ b/docs/agents/code-ownership.md @@ -15,11 +15,10 @@ Before you edit a module with many callers, run `pnpm depgraph affected `. | Output formatters | `packages/command-output/src/` | | Help and progress | `src/commands/` | | Input fields and audiences | `packages/command-surface/src/common-input-fields.ts`, `packages/command-surface/src/input-audience.ts` | -| Released SDK default hosts | `src/sdk/host.ts` | +| Released SDK command-host scopes | `src/sdk/host.ts` | | Apple runner host port and binding | `packages/apple-runner/src/host.ts`, `packages/platform-apple/src/core/runner-client.ts` | -For SDK entries `android-adb`, `artifacts`, `limrun`, `metro`, and `remote-config`, use `captureSdkHost` for defaults. -For command-host readers, use `withSdkHost`. +For SDK command-host readers, pass the supplied host to `withSdkHost`. Keep provider callbacks on their supplied host. Request cancellation and progress belong in `@agent-device/host-kit/request`. Per-call abort guards belong beside transports in `packages/daemon-client/src/daemon-client-transport.ts`. diff --git a/package.json b/package.json index ff36b8809e..5385e36e07 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "agent-device", - "version": "0.21.38-dev", + "version": "0.22.0-dev", "description": "Open source device layer for AI coding agents: a CLI, MCP server, and typed Node.js API to control mobile, web, TV, and desktop apps on devices and simulators, locally or in the cloud.", "mcpName": "io.github.callstack/agent-device", "license": "MIT", @@ -165,7 +165,7 @@ "depgraph:test": "node --experimental-strip-types scripts/node-test-tmpdir.ts --experimental-strip-types --test scripts/depgraph/model.test.ts scripts/depgraph/entries.test.ts scripts/depgraph/import-graph.test.ts scripts/depgraph/affected.test.ts scripts/depgraph/structure-summary.test.ts tools/depgraph-view/*.test.mjs", "check:production-exports": "fallow dead-code --config fallow-production-exports.json --production --unused-exports --fail-on-issues", "check:bundle-owner-files": "node --experimental-strip-types scripts/check-bundle-owner-files.ts", - "check:package": "node --experimental-strip-types scripts/check-package.ts", + "check:package": "node --experimental-strip-types scripts/check-package.ts && node --experimental-strip-types scripts/node-test-tmpdir.ts --test packages/maestro/test/package-artifact.test.mjs", "check:command-docs": "vitest run --project unit-core test/repo-guards/command-doc-coverage.test.ts", "check:adr-citations": "vitest run --project unit-core test/repo-guards/adr-citations.test.ts", "check:capabilities-matrix": "vitest run --project unit-core test/repo-guards/capability-matrix.test.ts", diff --git a/packages/command-registry/src/batch.ts b/packages/command-registry/src/batch.ts index ca1973fa89..3c6ff43547 100644 --- a/packages/command-registry/src/batch.ts +++ b/packages/command-registry/src/batch.ts @@ -6,7 +6,6 @@ import { type DaemonResponse, type ResponseLevel, isNonDefaultResponseLevel, - namesSessionExplicitly, } from '@agent-device/kernel/contracts'; import { AppError, @@ -14,7 +13,7 @@ import { BOUNDED_COMPOSITE_RESOURCE_UNSUPPORTED_REASON, type DaemonError, } from '@agent-device/kernel/errors'; -import { isRecord } from '@agent-device/kernel/record'; +import { isRecord, namesSessionExplicitly } from '@agent-device/kernel/record'; import { DEFAULT_BATCH_MAX_STEPS, assertBatchStepCount, diff --git a/packages/command-registry/src/daemon-command-descriptor.ts b/packages/command-registry/src/daemon-command-descriptor.ts index 316a3804a0..fe6098b126 100644 --- a/packages/command-registry/src/daemon-command-descriptor.ts +++ b/packages/command-registry/src/daemon-command-descriptor.ts @@ -38,6 +38,12 @@ export type DaemonCommandDescriptor = { sessionKind?: SessionCommandKind; refFrameEffect?: DaemonRefFrameEffect; leaseAdmissionExempt?: boolean; + /** + * This command uses neither the lease nor the device of the session it resolves, so only a lease + * it carries itself can make an unnamed request need a session. A command without it acts through + * that session and stays refused. + */ + ignoresSessionLease?: boolean; /** * packages/daemon/docs/remote-device-lease-contracts.md: this command may run under a `macos-app` lease, or on a daemon whose policy requires * one. A command without it is refused there, `leaseAdmissionExempt` or not, so a command diff --git a/packages/command-registry/src/descriptors/session-operations.ts b/packages/command-registry/src/descriptors/session-operations.ts index 37da302c34..9a153287e5 100644 --- a/packages/command-registry/src/descriptors/session-operations.ts +++ b/packages/command-registry/src/descriptors/session-operations.ts @@ -336,6 +336,7 @@ export const SESSION_OPERATION_COMMAND_DESCRIPTORS = [ daemon: { route: 'session', refFrameEffect: 'preserve', + ignoresSessionLease: true, ...REQUEST_EXECUTION_EXEMPT, }, timeoutPolicy: DEFAULT_TIMEOUT_POLICY, diff --git a/packages/command-registry/src/registry.ts b/packages/command-registry/src/registry.ts index 11a7a0edb4..b001fab87d 100644 --- a/packages/command-registry/src/registry.ts +++ b/packages/command-registry/src/registry.ts @@ -174,6 +174,7 @@ export const RAW_COMMAND_DESCRIPTORS = [ daemon: { route: 'lease', refFrameEffect: 'preserve', + ignoresSessionLease: true, ...ADMISSION_AND_LOCK_EXEMPT, }, timeoutPolicy: LEASE_ALLOCATE_TIMEOUT_POLICY, @@ -191,6 +192,7 @@ export const RAW_COMMAND_DESCRIPTORS = [ daemon: { route: 'lease', refFrameEffect: 'preserve', + ignoresSessionLease: true, ...ADMISSION_AND_LOCK_EXEMPT, appLease: 'allowed', }, @@ -209,6 +211,7 @@ export const RAW_COMMAND_DESCRIPTORS = [ daemon: { route: 'lease', refFrameEffect: 'preserve', + ignoresSessionLease: true, ...ADMISSION_AND_LOCK_EXEMPT, appLease: 'allowed', }, @@ -251,6 +254,7 @@ export const RAW_COMMAND_DESCRIPTORS = [ daemon: { route: 'session', refFrameEffect: 'preserve', + ignoresSessionLease: true, sessionKind: 'inventory', ...REQUEST_EXECUTION_EXEMPT, }, @@ -291,6 +295,7 @@ export const RAW_COMMAND_DESCRIPTORS = [ daemon: { route: 'session', refFrameEffect: 'preserve', + ignoresSessionLease: true, sessionKind: 'inventory', lockPolicySelectorOverride: true, ...REQUEST_EXECUTION_EXEMPT, diff --git a/packages/command-runtime/src/commands/capture/runtime/diff-screenshot.test.ts b/packages/command-runtime/src/commands/capture/runtime/diff-screenshot.test.ts index 346df406c9..42ef3accb2 100644 --- a/packages/command-runtime/src/commands/capture/runtime/diff-screenshot.test.ts +++ b/packages/command-runtime/src/commands/capture/runtime/diff-screenshot.test.ts @@ -36,7 +36,7 @@ test('runtime diff screenshot captures live current image and cleans temporary c fs.writeFileSync(outPath, solidPngBuffer(10, 10, { r: 255, g: 255, b: 255 })); return { path: outPath }; }), - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions, policy: localCommandPolicy(), }); @@ -74,7 +74,7 @@ test('runtime diff screenshot compares supplied current image without backend ca backend: createScreenshotBackend(() => { throw new Error('capture should not be called'); }), - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions, policy: localCommandPolicy(), }); @@ -97,7 +97,7 @@ test('runtime diff screenshot rejects overlay refs with supplied current image', backend: createScreenshotBackend(() => { throw new Error('capture should not be called'); }), - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions, policy: localCommandPolicy(), }); @@ -125,7 +125,7 @@ test('runtime diff screenshot enforces the normalized comparison pixel budget', backend: createScreenshotBackend(() => { throw new Error('capture should not be called'); }), - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions, policy: localCommandPolicy({ maxImagePixels: 50 }), }); @@ -172,7 +172,7 @@ test('runtime diff screenshot keeps the screen mask on current and overlay captu : {}), }; }), - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions, policy: localCommandPolicy(), }); @@ -238,7 +238,7 @@ test('runtime diff refuses a screen mask for saved images before reading or capt backend: createScreenshotBackend(() => { throw new Error('must not capture'); }), - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions, policy: localCommandPolicy(), }); diff --git a/packages/command-runtime/src/commands/capture/runtime/presented-surface-carriage.test.ts b/packages/command-runtime/src/commands/capture/runtime/presented-surface-carriage.test.ts index 5f71a5b919..ec1a99eae3 100644 --- a/packages/command-runtime/src/commands/capture/runtime/presented-surface-carriage.test.ts +++ b/packages/command-runtime/src/commands/capture/runtime/presented-surface-carriage.test.ts @@ -61,7 +61,7 @@ async function captureWith(result: BackendSnapshotResult) { }; const device = createAgentDevice({ backend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions, policy: localCommandPolicy(), }); diff --git a/packages/command-runtime/src/commands/capture/runtime/screenshot.test.ts b/packages/command-runtime/src/commands/capture/runtime/screenshot.test.ts index 1ef799ad7d..4933ef4076 100644 --- a/packages/command-runtime/src/commands/capture/runtime/screenshot.test.ts +++ b/packages/command-runtime/src/commands/capture/runtime/screenshot.test.ts @@ -19,7 +19,7 @@ test('runtime screenshot applies scale and forwards the capture rotation', async return { displayRotation: 'landscape-left' }; }, } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: { get: () => undefined, set: () => {} }, policy: localCommandPolicy(), }); @@ -47,7 +47,7 @@ test('runtime screenshot scales the already-cropped backend capture', async () = ); }, } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: { get: () => undefined, set: () => {} }, policy: localCommandPolicy(), }); @@ -94,7 +94,7 @@ for (const staged of [false, true]) { fs.writeFileSync(destination, sentinel); const controller = new AbortController(); const cancellation = new Error('caller cancelled after capture'); - const adapter = createLocalArtifactAdapter(); + const adapter = createLocalArtifactAdapter({ cwd: process.cwd() }); let publications = 0; let cleanups = 0; if (staged) { diff --git a/packages/command-runtime/src/commands/capture/runtime/snapshot-app-identity.test.ts b/packages/command-runtime/src/commands/capture/runtime/snapshot-app-identity.test.ts index 7cba3cd10d..61229d0f1d 100644 --- a/packages/command-runtime/src/commands/capture/runtime/snapshot-app-identity.test.ts +++ b/packages/command-runtime/src/commands/capture/runtime/snapshot-app-identity.test.ts @@ -28,7 +28,7 @@ async function snapshotWithForeground( ...sessionApp, }), }, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: { get: () => undefined, set: (record) => { @@ -94,7 +94,7 @@ test('a repeated unchanged snapshot of a foreign foreground app is acknowledged appBundleId: 'com.android.settings', }), }, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: { get: () => stored, set: (record) => { diff --git a/packages/command-runtime/src/commands/capture/runtime/snapshot-freshness.test.ts b/packages/command-runtime/src/commands/capture/runtime/snapshot-freshness.test.ts index 193b2ba2b6..5bbf12608f 100644 --- a/packages/command-runtime/src/commands/capture/runtime/snapshot-freshness.test.ts +++ b/packages/command-runtime/src/commands/capture/runtime/snapshot-freshness.test.ts @@ -17,7 +17,7 @@ function snapshotDevice( }; return createAgentDevice({ backend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: { get: () => session, set: () => {} }, policy: localCommandPolicy(), clock: { now: () => 1_500, sleep: async () => {} }, diff --git a/packages/command-runtime/src/commands/capture/runtime/snapshot.test.ts b/packages/command-runtime/src/commands/capture/runtime/snapshot.test.ts index a2320dc896..e844d008f6 100644 --- a/packages/command-runtime/src/commands/capture/runtime/snapshot.test.ts +++ b/packages/command-runtime/src/commands/capture/runtime/snapshot.test.ts @@ -29,7 +29,7 @@ test('runtime snapshot captures nodes and updates the session baseline', async ( appName: 'Demo', appBundleId: 'com.example.demo', })), - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: { get: () => undefined, set: (record) => { @@ -108,7 +108,7 @@ test('runtime snapshot recognizes equivalent bounds and still updates its baseli comparisonSafe: true, }), })), - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: { get: () => stored, set: (record) => { @@ -165,7 +165,7 @@ test('runtime snapshot forwards interactive capture options', async () => { }; }, }, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: { get: () => undefined, set: () => {}, @@ -198,7 +198,7 @@ test('runtime diff snapshot initializes and then compares against session baseli backend: createSnapshotBackend(() => ({ snapshot: makeSnapshotState([{ index: 0, depth: 0, type: 'Window', label: 'After' }]), })), - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: { get: () => session, set: (record) => { @@ -222,7 +222,7 @@ test('runtime diff snapshot initializes baseline when no previous snapshot exist backend: createSnapshotBackend(() => ({ snapshot: makeSnapshotState([{ index: 0, depth: 0, type: 'Window', label: 'Initial' }]), })), - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: { get: () => undefined, set: (record) => { @@ -632,7 +632,7 @@ test('runtime snapshot stale-drop warning uses the runtime clock', async () => { createdAt: 3_500, }), })), - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: { get: () => session, set: (record) => { @@ -678,7 +678,7 @@ test('runtime snapshot stale-drop warning uses backend snapshot timestamps when backend: createSnapshotBackend(() => ({ snapshot: currentSnapshot, })), - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: { get: () => session, set: (record) => { @@ -724,7 +724,7 @@ test('runtime snapshot stale-drop warning falls back to runtime clock on backend backend: createSnapshotBackend(() => ({ snapshot: currentSnapshot, })), - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: { get: () => session, set: (record) => { @@ -759,7 +759,7 @@ function createSnapshotBackend( function createSnapshotOnlyDevice(result: BackendSnapshotResult) { return createAgentDevice({ backend: createSnapshotBackend(() => result), - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: { get: () => undefined, set: () => {}, @@ -928,7 +928,7 @@ test('runtime snapshot carries backend clickability evidence through presentatio let stored: Parameters[0] | undefined; const device = createAgentDevice({ backend: createSnapshotBackend(() => ({ snapshot: state })), - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: { get: () => undefined, set: (record) => { diff --git a/packages/command-runtime/src/commands/interaction/runtime/__tests__/settle-device-fixtures.ts b/packages/command-runtime/src/commands/interaction/runtime/__tests__/settle-device-fixtures.ts index ea6c7f0962..a3176af3db 100644 --- a/packages/command-runtime/src/commands/interaction/runtime/__tests__/settle-device-fixtures.ts +++ b/packages/command-runtime/src/commands/interaction/runtime/__tests__/settle-device-fixtures.ts @@ -73,7 +73,7 @@ export function createSettleDevice(params: { fill: async () => ({ ok: true }), longPress: async () => ({ ok: true }), } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([ { name: 'default', diff --git a/packages/command-runtime/src/commands/interaction/runtime/__tests__/test-utils/index.ts b/packages/command-runtime/src/commands/interaction/runtime/__tests__/test-utils/index.ts index b646a045bc..cabbd788ee 100644 --- a/packages/command-runtime/src/commands/interaction/runtime/__tests__/test-utils/index.ts +++ b/packages/command-runtime/src/commands/interaction/runtime/__tests__/test-utils/index.ts @@ -390,7 +390,7 @@ export function createInteractionDevice( ? async (...args) => (await overrides.confirmOffscreenTargetVisible?.(...args)) ?? null : undefined, } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([ { name: 'default', snapshot, metadata: overrides.sessionMetadata }, ]), @@ -636,7 +636,7 @@ export function createSelectorDevice( options.captureSnapshot ? await options.captureSnapshot() : { snapshot }, readText: async () => ({ text: options.readText ?? '' }), } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions, policy: localCommandPolicy(), clock: options.clock ?? { diff --git a/packages/command-runtime/src/commands/interaction/runtime/interactions-find-carried-target.test.ts b/packages/command-runtime/src/commands/interaction/runtime/interactions-find-carried-target.test.ts index 06f1cdbc19..b98d0a76a5 100644 --- a/packages/command-runtime/src/commands/interaction/runtime/interactions-find-carried-target.test.ts +++ b/packages/command-runtime/src/commands/interaction/runtime/interactions-find-carried-target.test.ts @@ -65,7 +65,7 @@ function createDevice(stored: SnapshotState) { return {}; }, } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([{ name: 'default', snapshot: stored }]), policy: localCommandPolicy(), }); diff --git a/packages/command-runtime/src/commands/interaction/runtime/interactions-preresolved-target.test.ts b/packages/command-runtime/src/commands/interaction/runtime/interactions-preresolved-target.test.ts index b7aaf49ea8..f322f101fa 100644 --- a/packages/command-runtime/src/commands/interaction/runtime/interactions-preresolved-target.test.ts +++ b/packages/command-runtime/src/commands/interaction/runtime/interactions-preresolved-target.test.ts @@ -64,7 +64,7 @@ function deviceWithSessionTree(snapshot: ReturnType | taps.push(point); }, }, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([{ name: 'default', snapshot }]), policy: localCommandPolicy(), }); diff --git a/packages/command-runtime/src/commands/interaction/runtime/interactions.test.ts b/packages/command-runtime/src/commands/interaction/runtime/interactions.test.ts index 1621abe83f..79400dd6dd 100644 --- a/packages/command-runtime/src/commands/interaction/runtime/interactions.test.ts +++ b/packages/command-runtime/src/commands/interaction/runtime/interactions.test.ts @@ -309,7 +309,7 @@ test('native ref fast path proceeds untouched when the session has no snapshot', return { ref: target.ref.replace(/^@/, '') }; }, } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([{ name: 'default' }]), policy: localCommandPolicy(), }); @@ -333,7 +333,7 @@ test('runtime interactions pass runtime signal to backend primitives', async () signal = context.signal; }, } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), policy: localCommandPolicy(), signal: controller.signal, }); @@ -784,7 +784,7 @@ test('coordinate tap with no session snapshot has no warning', async () => { platform: 'ios', tap: async () => ({ ok: true }), } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([{ name: 'default' }]), policy: localCommandPolicy(), }); diff --git a/packages/command-runtime/src/commands/interaction/runtime/moving-target-gate.test.ts b/packages/command-runtime/src/commands/interaction/runtime/moving-target-gate.test.ts index 2532dbe22f..e0068063a8 100644 --- a/packages/command-runtime/src/commands/interaction/runtime/moving-target-gate.test.ts +++ b/packages/command-runtime/src/commands/interaction/runtime/moving-target-gate.test.ts @@ -113,7 +113,7 @@ function createGuardedDevice(params: { return { ok: true }; }, } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([ { name: 'default', @@ -667,7 +667,7 @@ test('a ref from a full-tree frame is re-observed in that presentation, not renu return { ok: true }; }, } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([ { name: 'default', diff --git a/packages/command-runtime/src/commands/interaction/runtime/pre-dispatch-admission.test.ts b/packages/command-runtime/src/commands/interaction/runtime/pre-dispatch-admission.test.ts index 43ab918789..94e4e6f322 100644 --- a/packages/command-runtime/src/commands/interaction/runtime/pre-dispatch-admission.test.ts +++ b/packages/command-runtime/src/commands/interaction/runtime/pre-dispatch-admission.test.ts @@ -84,7 +84,7 @@ function createAdmissionDevice(params: { const stored = params.trees[0]!; const device = createAgentDevice({ backend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([ { name: 'default', diff --git a/packages/command-runtime/src/commands/interaction/runtime/selector-is.test.ts b/packages/command-runtime/src/commands/interaction/runtime/selector-is.test.ts index 0e8594daa7..04d95fdfd6 100644 --- a/packages/command-runtime/src/commands/interaction/runtime/selector-is.test.ts +++ b/packages/command-runtime/src/commands/interaction/runtime/selector-is.test.ts @@ -20,7 +20,7 @@ test('runtime selectors forward public snapshot options to backend capture', asy return { snapshot }; }, } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([{ name: 'default', snapshot }]), policy: localCommandPolicy(), }); @@ -54,7 +54,7 @@ test('runtime visibility predicates request snapshot rects', async () => { return { snapshot }; }, } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([{ name: 'default', snapshot }]), policy: localCommandPolicy(), }); @@ -87,7 +87,7 @@ test('runtime focused predicate requests a full snapshot', async () => { return { snapshot }; }, } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([{ name: 'default', snapshot }]), policy: localCommandPolicy(), }); @@ -126,7 +126,7 @@ test('runtime focused predicate reads focused Android TV nodes from the full tre return { snapshot: options?.interactiveOnly ? interactiveSnapshot : fullSnapshot }; }, } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([{ name: 'default', snapshot: interactiveSnapshot }]), policy: localCommandPolicy(), }); @@ -189,7 +189,7 @@ test('runtime is absent uses one readAny capture without requesting rects', asyn return { snapshot }; }, } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([{ name: 'default', snapshot }]), policy: localCommandPolicy(), }); @@ -316,7 +316,7 @@ test('runtime is absent fails closed for a sparse capture and preserves the last platform: 'ios', captureSnapshot: async () => ({ snapshot: sparse }), } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions, policy: localCommandPolicy(), }); diff --git a/packages/command-runtime/src/commands/interaction/runtime/selector-read.test.ts b/packages/command-runtime/src/commands/interaction/runtime/selector-read.test.ts index bbbaa7f275..5524147978 100644 --- a/packages/command-runtime/src/commands/interaction/runtime/selector-read.test.ts +++ b/packages/command-runtime/src/commands/interaction/runtime/selector-read.test.ts @@ -52,7 +52,7 @@ test('runtime get selector target captures fresh snapshot without a stored sessi }, readText: async () => ({ text: 'Fresh text' }), } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions, policy: localCommandPolicy(), }); @@ -159,7 +159,7 @@ test('runtime selectors pass runtime signal to backend snapshot capture', async return { snapshot }; }, } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([{ name: 'default', snapshot }]), policy: localCommandPolicy(), signal: controller.signal, @@ -216,7 +216,7 @@ test('runtime web find text does not pass locator text as browser selector scope return { snapshot }; }, } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([{ name: 'default', snapshot }]), policy: localCommandPolicy(), }); @@ -266,7 +266,7 @@ test('runtime find wait reports sparse snapshot verdicts on the selector-read ro quality: sparseSnapshot.snapshotQuality, }), } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions, policy: localCommandPolicy(), clock: { @@ -311,7 +311,7 @@ test('runtime find wait skips hidden-content hint derivation on every poll (#127 return { snapshot }; }, } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([{ name: 'default', snapshot }]), policy: localCommandPolicy(), clock: { @@ -368,7 +368,7 @@ test('runtime find wait cancels and joins a capture that consumes its full deadl }); }, } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions, policy: localCommandPolicy(), }); @@ -438,7 +438,7 @@ function waitDeviceWithCaptures(captures: Array<() => ReturnType Error): { throw produceError(); }, } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([{ name: 'default' }]), policy: localCommandPolicy(), clock: createFakeClock(), diff --git a/packages/command-runtime/src/commands/interaction/runtime/selector-wait-cancellation.test.ts b/packages/command-runtime/src/commands/interaction/runtime/selector-wait-cancellation.test.ts index a9322e31d2..3f51f9b77a 100644 --- a/packages/command-runtime/src/commands/interaction/runtime/selector-wait-cancellation.test.ts +++ b/packages/command-runtime/src/commands/interaction/runtime/selector-wait-cancellation.test.ts @@ -27,7 +27,7 @@ for (const authority of ['runtime', 'command'] as const) { const reason = new Error(`${authority} wait canceled`); const device = createAgentDevice({ backend: { platform: 'ios' } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore(), policy: localCommandPolicy(), clock: { diff --git a/packages/command-runtime/src/commands/interaction/runtime/settle-capture-deadline.test.ts b/packages/command-runtime/src/commands/interaction/runtime/settle-capture-deadline.test.ts index 6e3d3e45b8..4f28d5b6aa 100644 --- a/packages/command-runtime/src/commands/interaction/runtime/settle-capture-deadline.test.ts +++ b/packages/command-runtime/src/commands/interaction/runtime/settle-capture-deadline.test.ts @@ -37,7 +37,7 @@ test('a stalled settle capture receives its deadline signal and the press still }, tap: async () => ({ ok: true }), } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([{ name: 'default', snapshot: before }]), policy: localCommandPolicy(), clock: createFakeClock(), diff --git a/packages/command-runtime/src/commands/interaction/runtime/settle-transition-baseline.test.ts b/packages/command-runtime/src/commands/interaction/runtime/settle-transition-baseline.test.ts index e7f09eb27c..30d57af0d4 100644 --- a/packages/command-runtime/src/commands/interaction/runtime/settle-transition-baseline.test.ts +++ b/packages/command-runtime/src/commands/interaction/runtime/settle-transition-baseline.test.ts @@ -21,7 +21,7 @@ test('settle recovers the session baseline when resolved target evidence is abse snapshot: elapsedMs < 1_200 ? elementTransientRoomSnapshot : elementSettledRoomSnapshot, }), } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([ { name: 'default', @@ -72,7 +72,7 @@ test('settle uses the authorized ref frame instead of a polluted evidence captur snapshot: elapsedMs < 1_200 ? elementTransientRoomSnapshot : elementSettledRoomSnapshot, }), } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([ { name: 'default', @@ -132,7 +132,7 @@ async function settlePointTargetAgainstSession(session: { snapshot: elapsedMs < 1_200 ? elementTransientRoomSnapshot : elementSettledRoomSnapshot, }), } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([session]), policy: localCommandPolicy(), clock: { diff --git a/packages/command-runtime/src/commands/interaction/runtime/settle-view-baseline.test.ts b/packages/command-runtime/src/commands/interaction/runtime/settle-view-baseline.test.ts index 04f5506323..c35bc5002a 100644 --- a/packages/command-runtime/src/commands/interaction/runtime/settle-view-baseline.test.ts +++ b/packages/command-runtime/src/commands/interaction/runtime/settle-view-baseline.test.ts @@ -92,7 +92,7 @@ function createDevice(params: { return { ok: true }; }, } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([ { name: 'default', snapshot: params.frame, refFrameSnapshot: params.frame }, ]), diff --git a/packages/command-runtime/src/commands/interaction/runtime/settle.test.ts b/packages/command-runtime/src/commands/interaction/runtime/settle.test.ts index ae2b6ae302..973604b496 100644 --- a/packages/command-runtime/src/commands/interaction/runtime/settle.test.ts +++ b/packages/command-runtime/src/commands/interaction/runtime/settle.test.ts @@ -157,7 +157,7 @@ test('press --settle routes its first capture afresh after a private-ax session fill: async () => ({ ok: true }), longPress: async () => ({ ok: true }), } satisfies import('@agent-device/contracts/backend').AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([{ name: 'default', snapshot: established }]), policy: localCommandPolicy(), clock: createFakeClock(), diff --git a/packages/command-runtime/src/commands/interaction/runtime/stable-capture.test.ts b/packages/command-runtime/src/commands/interaction/runtime/stable-capture.test.ts index 81f975f086..21a618c6b8 100644 --- a/packages/command-runtime/src/commands/interaction/runtime/stable-capture.test.ts +++ b/packages/command-runtime/src/commands/interaction/runtime/stable-capture.test.ts @@ -192,7 +192,7 @@ test('regular captures settle from visible semantics while offscreen rows churn' platform: 'ios', captureSnapshot: async () => ({ snapshot: snapshots[captures++ % snapshots.length]! }), } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore(), policy: localCommandPolicy(), clock, @@ -601,7 +601,7 @@ function staticSnapshotRuntime(snapshot: SnapshotState) { platform: 'ios', captureSnapshot: async () => ({ snapshot }), } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([{ name: 'default', snapshot }]), policy: localCommandPolicy(), clock: { @@ -687,7 +687,7 @@ function transitionRuntime( }; }, } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([ { name: 'default', snapshot: options.sessionSnapshot ?? presented }, ]), diff --git a/packages/command-runtime/src/commands/interaction/runtime/wait-absent.test.ts b/packages/command-runtime/src/commands/interaction/runtime/wait-absent.test.ts index ad09425f6d..9417095da5 100644 --- a/packages/command-runtime/src/commands/interaction/runtime/wait-absent.test.ts +++ b/packages/command-runtime/src/commands/interaction/runtime/wait-absent.test.ts @@ -51,7 +51,7 @@ function absentDevice( return capture!; }, } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([{ name: 'default' }]), policy: localCommandPolicy(), clock: createFakeClock(), @@ -75,7 +75,7 @@ function cancelledAbsentDevice(params: { platform: 'ios', captureSnapshot, } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([{ name: 'default' }]), policy: localCommandPolicy(), clock, diff --git a/packages/command-runtime/src/commands/interaction/runtime/wait-capture-options.test.ts b/packages/command-runtime/src/commands/interaction/runtime/wait-capture-options.test.ts index 9f744b8a45..3ec0256860 100644 --- a/packages/command-runtime/src/commands/interaction/runtime/wait-capture-options.test.ts +++ b/packages/command-runtime/src/commands/interaction/runtime/wait-capture-options.test.ts @@ -30,7 +30,7 @@ function pollingDevice(captureOptions: Array }; return createAgentDevice({ backend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: { get: () => undefined, set: () => {} }, policy: localCommandPolicy(), clock: createFakeClock(), diff --git a/packages/command-runtime/src/commands/interaction/runtime/wait-selector.test.ts b/packages/command-runtime/src/commands/interaction/runtime/wait-selector.test.ts index a4dccb81ff..88e5454577 100644 --- a/packages/command-runtime/src/commands/interaction/runtime/wait-selector.test.ts +++ b/packages/command-runtime/src/commands/interaction/runtime/wait-selector.test.ts @@ -30,7 +30,7 @@ test('runtime focused selector waits against a full snapshot', async () => { return { snapshot }; }, } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([{ name: 'default', snapshot }]), policy: localCommandPolicy(), }); @@ -95,7 +95,7 @@ function landmarkWaitDevice(captures: Array>) return { snapshot }; }, } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([{ name: 'default', snapshot: initial }]), policy: localCommandPolicy(), clock: createFakeClock(), @@ -239,7 +239,7 @@ async function landmarkRefusalAfter( return { snapshot: await finalCapture() }; }, } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([{ name: 'default', snapshot: impostor }]), policy: localCommandPolicy(), clock: createFakeClock(100), diff --git a/packages/command-runtime/src/commands/interaction/runtime/wait-stable.test.ts b/packages/command-runtime/src/commands/interaction/runtime/wait-stable.test.ts index 6f7fdcd79c..74a9ce9941 100644 --- a/packages/command-runtime/src/commands/interaction/runtime/wait-stable.test.ts +++ b/packages/command-runtime/src/commands/interaction/runtime/wait-stable.test.ts @@ -23,7 +23,7 @@ test('runtime wait stable preserves the requested scope, depth and raw view', as return { snapshot }; }, } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([{ name: 'default', snapshot }]), policy: localCommandPolicy(), clock: createFakeClock(), @@ -59,7 +59,7 @@ test('runtime wait stable settles after two unchanged captures', async () => { return { snapshot }; }, } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([{ name: 'default', snapshot }]), policy: localCommandPolicy(), clock, @@ -103,7 +103,7 @@ test('runtime wait stable retains a recovered private-ax backend after its first return { snapshot }; }, } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([{ name: 'default', snapshot }]), policy: localCommandPolicy(), clock: createFakeClock(), @@ -156,7 +156,7 @@ function createStableCaptureDevice(clock: { return { snapshot }; }, } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([{ name: 'default', snapshot }]), policy: localCommandPolicy(), clock, @@ -276,7 +276,7 @@ test('runtime wait stable hints when it settles on a nearly-empty tree', async ( platform: 'ios', captureSnapshot: async () => ({ snapshot: tinySnapshot }), } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([{ name: 'default', snapshot: tinySnapshot }]), policy: localCommandPolicy(), clock: createFakeClock(), @@ -312,7 +312,7 @@ test('runtime wait stable omits the loading hint for a normal-sized tree', async platform: 'ios', captureSnapshot: async () => ({ snapshot: normalSnapshot }), } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([{ name: 'default', snapshot: normalSnapshot }]), policy: localCommandPolicy(), clock: createFakeClock(), @@ -354,7 +354,7 @@ test('runtime wait stable requires quiet captures after instability before settl return { snapshot: changedSnapshot }; }, } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([{ name: 'default', snapshot }]), policy: localCommandPolicy(), clock, @@ -391,7 +391,7 @@ test('runtime wait stable times out with capture stats when never settling', asy }; }, } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([{ name: 'default' }]), policy: localCommandPolicy(), clock, @@ -421,7 +421,7 @@ test('runtime wait stable surfaces a capture failure instead of reporting a time throw new Error('AX bridge crashed'); }, } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([{ name: 'default' }]), policy: localCommandPolicy(), clock: createFakeClock(), @@ -465,7 +465,7 @@ test('runtime wait stable times out when a backend capture stalls past the wait ); }), } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([{ name: 'default' }]), policy: localCommandPolicy(), clock, @@ -502,7 +502,7 @@ test('runtime wait stable uses provided defaults when quietMs/timeoutMs are omit return { snapshot }; }, } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([{ name: 'default', snapshot }]), policy: localCommandPolicy(), clock, diff --git a/packages/command-runtime/src/commands/interaction/runtime/wait-text.test.ts b/packages/command-runtime/src/commands/interaction/runtime/wait-text.test.ts index 228a62646c..a43625596d 100644 --- a/packages/command-runtime/src/commands/interaction/runtime/wait-text.test.ts +++ b/packages/command-runtime/src/commands/interaction/runtime/wait-text.test.ts @@ -32,7 +32,7 @@ function textWaitDevice(params: { ...(params.findText ? { findText: params.findText } : {}), readText: params.readText ?? (async () => ({ text: '' })), } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([{ name: 'default' }]), policy: localCommandPolicy(), clock: params.clock ?? createFakeClock(), @@ -217,7 +217,7 @@ test('runtime wait passes its polling deadline signal to snapshot capture', asyn platform: 'ios', captureSnapshot: capture, } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), sessions: createMemorySessionStore([{ name: 'default', snapshot }]), policy: localCommandPolicy(), }); diff --git a/packages/contracts/src/__tests__/lease-scope-rpc.test.ts b/packages/contracts/src/__tests__/lease-scope-rpc.test.ts new file mode 100644 index 0000000000..44a5aaca90 --- /dev/null +++ b/packages/contracts/src/__tests__/lease-scope-rpc.test.ts @@ -0,0 +1,33 @@ +import { expect, test } from 'vitest'; +import { buildDaemonRpcRequest } from '../lease-scope.ts'; + +function leaseRpcParams( + flags: { session?: string }, + meta: { sessionExplicit?: boolean }, +): Record { + return buildDaemonRpcRequest( + { + token: 'token', + session: 'default', + command: 'lease_allocate', + positionals: [], + flags, + meta: { tenantId: 'acme', runId: 'run-a', leaseBackend: 'android-instance', ...meta }, + }, + { id: 'id', includeTokenParam: false }, + ).params as Record; +} + +test.each([ + ['a client that named none', {}, { sessionExplicit: false }, false], + ['a client that named one in its meta', {}, { sessionExplicit: true }, true], + [ + 'a client that named one in its flags', + { session: 'default' }, + { sessionExplicit: false }, + true, + ], + ['a caller that predates the fact', {}, {}, undefined], +])('the lease method carries what %s said about its session', (_label, flags, meta, expected) => { + expect(leaseRpcParams(flags, meta).sessionExplicit).toBe(expected); +}); diff --git a/packages/contracts/src/artifact-adapter.ts b/packages/contracts/src/artifact-adapter.ts index c6672e6721..6e498280a2 100644 --- a/packages/contracts/src/artifact-adapter.ts +++ b/packages/contracts/src/artifact-adapter.ts @@ -91,7 +91,7 @@ export type ArtifactAdapter = { }; export type LocalArtifactAdapterOptions = { - cwd?: string; + cwd: string; tempDir?: string; /** Restricts explicit paths lexically; symlinks are not resolved. This is not a sandbox. */ rootDir?: string; diff --git a/packages/contracts/src/host-diagnostics.ts b/packages/contracts/src/host-diagnostics.ts index fc99bd47aa..1611d41e61 100644 --- a/packages/contracts/src/host-diagnostics.ts +++ b/packages/contracts/src/host-diagnostics.ts @@ -46,3 +46,14 @@ export type HostDiagnostics = Readonly<{ context: HostDiagnosticsContext, ): Promise; }>; + +/** The severity an event is recorded with. */ +export type DiagnosticLevel = 'info' | 'warn' | 'error' | 'debug'; + +/** A diagnostic handed to the host that owns the request log and redaction. */ +export type DiagnosticEventInput = { + level?: DiagnosticLevel; + phase: string; + durationMs?: number; + data?: Record; +}; diff --git a/packages/contracts/src/lease-scope.ts b/packages/contracts/src/lease-scope.ts index f2a3856166..04d81d74db 100644 --- a/packages/contracts/src/lease-scope.ts +++ b/packages/contracts/src/lease-scope.ts @@ -1,6 +1,6 @@ import type { DaemonResponse, LeaseBackend } from '@agent-device/kernel/contracts'; import { AppError } from '@agent-device/kernel/errors'; -import { stripUndefined } from '@agent-device/kernel/record'; +import { namesSessionExplicitly, stripUndefined } from '@agent-device/kernel/record'; import type { CloudProviderProfileFields } from './remote-config-fields.ts'; import type { CommandFlags } from './command-flags.ts'; import type { DaemonWireRequest } from './daemon-wire-request.ts'; @@ -94,6 +94,19 @@ type LeaseOptionsLike = { clientId?: string; }; +/** The refusal for a request on a provider lease that names no session. */ +export function remoteSessionRequiredError(leaseProvider: string | undefined): AppError { + return new AppError( + 'INVALID_ARGS', + 'A leased remote connection needs its session named: pass --session , set AGENT_DEVICE_SESSION, or send the session parameter.', + { + reason: 'REMOTE_SESSION_REQUIRED', + ...(leaseProvider === undefined ? {} : { leaseProvider }), + hint: "Without a name, a command could reach another agent's connection.", + }, + ); +} + export function leaseScopeFromRequest(req: LeaseRequestLike): LeaseScope { return stripUndefined({ tenantId: req.meta?.tenantId ?? readFlagString(req.flags, 'tenant'), @@ -644,9 +657,14 @@ function buildLeaseRpcParams( command: LeaseRpcCommand, options: { includeTokenParam: boolean }, ): Record { - return leaseScopeToLeaseRpcParams(leaseScopeFromRequest(req), command, { - includeTokenParam: options.includeTokenParam, - token: req.token, - session: req.session, - }); + return { + ...leaseScopeToLeaseRpcParams(leaseScopeFromRequest(req), command, { + includeTokenParam: options.includeTokenParam, + token: req.token, + session: req.session, + }), + ...(req.meta?.sessionExplicit === undefined + ? {} + : { sessionExplicit: namesSessionExplicitly(req) }), + }; } diff --git a/packages/contracts/src/replay-backend.ts b/packages/contracts/src/replay-backend.ts index a8597b2037..43c2bb0e54 100644 --- a/packages/contracts/src/replay-backend.ts +++ b/packages/contracts/src/replay-backend.ts @@ -1,3 +1,5 @@ +import type { DiagnosticEventInput } from './host-diagnostics.ts'; +import type { SnapshotClickabilityEvidence } from './snapshot-private-evidence.ts'; import type { DaemonError } from '@agent-device/kernel/errors'; import type { DaemonResponse, SessionRuntimeHints } from '@agent-device/kernel/contracts'; import type { DeviceInfo } from '@agent-device/kernel/device'; @@ -230,6 +232,11 @@ export type ReplayBackendDeviceBinding = Readonly<{ * session policy is a member; stateless workspace packages stay direct imports of the plugin. */ export type ReplayBackendHost = Readonly<{ + emitDiagnostic(event: DiagnosticEventInput): void; + /** Reads capture-local facts from the host's private evidence owner, without wire fields. */ + readSnapshotClickabilityEvidence(owner: object): SnapshotClickabilityEvidence | undefined; + /** Refuses capture-derived input when the host has no established screen origin. */ + assertSnapshotScreenOrigin(owner: object, label: string): Promise; /** Appends one record to the run's trace file, if any; failures are diagnostics, never thrown. */ appendTraceEvent(tracePath: string | undefined, event: Record): void; /** The `AD_*` variables every replay run is seeded with. */ @@ -269,5 +276,5 @@ export type ReplayBackendDeclaration = Readonly<{ }>; export type ReplayBackendPlugin = Readonly<{ - create(host: ReplayBackendHost): ReplayBackend; + create(host: ReplayBackendHost): ReplayBackend | Promise>; }>; diff --git a/packages/daemon/src/core/__tests__/daemon-command-registry.test.ts b/packages/daemon/src/core/__tests__/daemon-command-registry.test.ts index 355866dc23..9df89295eb 100644 --- a/packages/daemon/src/core/__tests__/daemon-command-registry.test.ts +++ b/packages/daemon/src/core/__tests__/daemon-command-registry.test.ts @@ -4,8 +4,10 @@ import { INTERNAL_COMMANDS, PUBLIC_COMMANDS } from '@agent-device/command-regist import { canOverrideLockPolicySelector, canRunReplayScopedAction, + DAEMON_COMMAND_DESCRIPTORS, getDaemonCommandRoute, getSessionCommandKind, + ignoresSessionLease, isHumanControlMutation, isLeaseAdmissionExempt, resolveSessionlessLeaseAdmissionExemption, @@ -19,6 +21,22 @@ import { } from '../daemon-command-registry.ts'; import type { DaemonRequest } from '../daemon-request.ts'; +test('only the commands that never touch their session ignore its lease', () => { + assert.deepEqual( + DAEMON_COMMAND_DESCRIPTORS.map(({ command }) => command) + .filter(ignoresSessionLease) + .sort(), + [ + PUBLIC_COMMANDS.devices, + INTERNAL_COMMANDS.leaseAllocate, + INTERNAL_COMMANDS.leaseHeartbeat, + INTERNAL_COMMANDS.leaseRelease, + INTERNAL_COMMANDS.releaseMaterializedPaths, + INTERNAL_COMMANDS.sessionList, + ].sort(), + ); +}); + test('daemon command registry owns specialized handler routes', () => { assert.equal(getDaemonCommandRoute(INTERNAL_COMMANDS.humanControl), 'humanControl'); for (const command of [ diff --git a/packages/daemon/src/core/__tests__/execution-plan.test.ts b/packages/daemon/src/core/__tests__/execution-plan.test.ts index 0a9481930d..191664daca 100644 --- a/packages/daemon/src/core/__tests__/execution-plan.test.ts +++ b/packages/daemon/src/core/__tests__/execution-plan.test.ts @@ -47,3 +47,25 @@ test('batch steps carry the steps still ahead of them through the internal chann { command: 'snapshot', remaining: [] }, ]); }); + +test.each([ + ['keep', { sessionOmitted: true } as const, true], + ['do not gain', undefined, undefined], +])('batch steps %s the marker for an unnamed session', async (_label, internal, sessionOmitted) => { + const seen: unknown[] = []; + const req: DaemonRequest = { + token: 'token', + session: 'default', + command: 'batch', + positionals: [], + flags: { batchSteps: [{ command: 'snapshot' }] }, + ...(internal ? { internal } : {}), + }; + + await runBatchCommands(req, 'default', async (stepRequest) => { + seen.push(stepRequest.internal?.sessionOmitted); + return { ok: true, data: {} }; + }); + + assert.deepEqual(seen, [sessionOmitted]); +}); diff --git a/packages/daemon/src/core/daemon-command-registry.ts b/packages/daemon/src/core/daemon-command-registry.ts index 279acd28a5..bbfc477a2d 100644 --- a/packages/daemon/src/core/daemon-command-registry.ts +++ b/packages/daemon/src/core/daemon-command-registry.ts @@ -66,6 +66,10 @@ export function isLeaseAdmissionExempt(command: string): boolean { return getDaemonCommandDescriptor(command)?.leaseAdmissionExempt === true; } +export function ignoresSessionLease(command: string): boolean { + return getDaemonCommandDescriptor(command)?.ignoresSessionLease === true; +} + export function isAppLeaseAllowed(command: string): boolean { return getDaemonCommandDescriptor(command)?.appLease === 'allowed'; } diff --git a/packages/daemon/src/core/daemon-request.ts b/packages/daemon/src/core/daemon-request.ts index c541c252fa..1ad6514658 100644 --- a/packages/daemon/src/core/daemon-request.ts +++ b/packages/daemon/src/core/daemon-request.ts @@ -46,6 +46,12 @@ type DaemonRequestInternal = ReplayDispatchOptions & { */ retainDeviceExecutionLock?: (deviceId: string) => Promise; admittedLease?: DeviceLease; + /** + * The caller named no session. Set by `resolveRequestSessionAtIntake`, because the defaulted name + * cannot be told apart from a chosen one afterwards, and copied onto batch steps by + * `session-batch`. + */ + sessionOmitted?: true; /** * ADR 0014 / #1654: the complete ref/node/tree target a mutating `find` * resolved against its fresh capture. Its presence both marks the ref as diff --git a/packages/daemon/src/core/explicit-session-resolution.ts b/packages/daemon/src/core/explicit-session-resolution.ts index b33ee79512..2c8fb58d2f 100644 --- a/packages/daemon/src/core/explicit-session-resolution.ts +++ b/packages/daemon/src/core/explicit-session-resolution.ts @@ -1,6 +1,6 @@ import type { DaemonWireRequest } from '@agent-device/contracts/command'; import { shellQuoteIfNeeded } from '@agent-device/kernel/device-shell'; -import { namesSessionExplicitly } from '@agent-device/kernel/contracts'; +import { namesSessionExplicitly } from '@agent-device/kernel/record'; import { AppError, namedSessionNotFoundDetails, @@ -41,7 +41,7 @@ export function namedSessionNotFoundError(sessionAddress: string): AppError { * Two shapes keep the path they chose: a request that never named a session, which is using the * daemon sessionlessly by design, and one that names a device selector as well, which states its * target outright and needs no session to supply one. The predicate deciding the first is - * `namesSessionExplicitly` (`@agent-device/kernel/contracts`), traced from what the request carries + * `namesSessionExplicitly` (`@agent-device/kernel/record`), traced from what the request carries * rather than from the session string. */ export function requireNamedSessionHoldsDevice( diff --git a/packages/daemon/src/core/request-session-intake.test.ts b/packages/daemon/src/core/request-session-intake.test.ts new file mode 100644 index 0000000000..c1a9e26dd9 --- /dev/null +++ b/packages/daemon/src/core/request-session-intake.test.ts @@ -0,0 +1,30 @@ +import { expect, test } from 'vitest'; +import { resolveRequestSessionAtIntake } from './request-session-intake.ts'; + +const OMITTED = { internal: { sessionOmitted: true } }; + +test.each([ + ['a missing session', {}, { session: 'default', ...OMITTED }], + ['a blank session', { session: ' ' }, { session: ' ', ...OMITTED }], + ['an empty session', { session: '' }, { session: '', ...OMITTED }], + ['a session that is not a string', { session: 7 }, { session: 'default', ...OMITTED }], + [ + 'the literal default from a client that named none', + { session: 'default', meta: { sessionExplicit: false } }, + { session: 'default', ...OMITTED }, + ], + [ + 'a client that names the default session in its meta', + { session: 'default', meta: { sessionExplicit: true } }, + { session: 'default' }, + ], + [ + 'a client that names its session in its flags', + { session: 'default', flags: { session: 'default' }, meta: { sessionExplicit: false } }, + { session: 'default' }, + ], + ['a caller that predates the fact', { session: 'default' }, { session: 'default' }], + ['a named session', { session: 'agent-a' }, { session: 'agent-a' }], +])('intake reads %s', (_label, request, expected) => { + expect(resolveRequestSessionAtIntake(request)).toEqual(expected); +}); diff --git a/packages/daemon/src/core/request-session-intake.ts b/packages/daemon/src/core/request-session-intake.ts new file mode 100644 index 0000000000..0da852adfe --- /dev/null +++ b/packages/daemon/src/core/request-session-intake.ts @@ -0,0 +1,25 @@ +import { namesSessionExplicitly } from '@agent-device/kernel/record'; +import type { DaemonRequest } from './daemon-request.ts'; + +/** + * What a transport takes from a request's session: the name it runs under, and whether the caller + * named one at all. A missing session runs under `default`. A blank one names no session but keeps + * its literal, so a command that validates the name, such as a web open, still refuses it. The Node + * client always sends `default` and reports the omission in `meta.sessionExplicit`, so the literal + * stays and cwd-scoped routing keeps reading it. A caller on neither carrier predates the fact and + * counts as named. + */ +export function resolveRequestSessionAtIntake(request: { + session?: unknown; + flags?: { session?: unknown } | Record; + meta?: { sessionExplicit?: boolean | undefined }; +}): Pick { + const literal = typeof request.session === 'string' ? request.session : undefined; + const named = literal !== undefined && literal.trim().length > 0; + const omitted = + !named || (request.meta?.sessionExplicit === false && !namesSessionExplicitly(request)); + return { + session: literal ?? 'default', + ...(omitted ? { internal: { sessionOmitted: true } } : {}), + }; +} diff --git a/packages/daemon/src/server/__tests__/http-server-rpc-validation.test.ts b/packages/daemon/src/server/__tests__/http-server-rpc-validation.test.ts index f8ef230be4..1d4dc7d6ee 100644 --- a/packages/daemon/src/server/__tests__/http-server-rpc-validation.test.ts +++ b/packages/daemon/src/server/__tests__/http-server-rpc-validation.test.ts @@ -126,6 +126,7 @@ test('the rpc boundary never accepts internal request fields from the wire', asy id: 'req-1', method: 'agent_device.command', params: { + session: 'agent-a', command: 'snapshot', positionals: [], internal: { @@ -339,6 +340,7 @@ test('local command RPC keeps host paths unrestricted', async (t) => { try { const port = await listenOnLoopback(server); const response = await postCommandRpc(port, { + session: 'agent-a', command: 'install_source', positionals: [], flags: { platform: 'android' }, @@ -355,6 +357,50 @@ test('local command RPC keeps host paths unrestricted', async (t) => { } }); +test.for([ + ['omitted', {}, 'default', true], + ['blank', { session: ' ' }, ' ', true], + ['named', { session: 'agent-a' }, 'agent-a', undefined], +] as const)( + 'install_from_source records a session that is %s', + async ([_label, session, resolvedSession, sessionOmitted], t) => { + if (await skipWhenLoopbackUnavailable(t)) return; + + const received: DaemonRequest[] = []; + const server = await createDaemonHttpServer({ + handleRequest: async (req) => { + received.push(req); + return { ok: true, data: {} }; + }, + env: process.env, + cwd: process.cwd(), + }); + + try { + const port = await listenOnLoopback(server); + await fetch(`http://127.0.0.1:${port}/rpc`, { + method: 'POST', + headers: { 'content-type': 'application/json' }, + body: JSON.stringify({ + jsonrpc: '2.0', + id: 'req-1', + method: 'agent_device.install_from_source', + params: { + ...session, + platform: 'android', + source: { kind: 'url', url: 'https://example.com/app.apk' }, + }, + }), + }); + assert.equal(received.length, 1); + assert.equal(received[0]?.session, resolvedSession); + assert.equal(received[0]?.internal?.sessionOmitted, sessionOmitted); + } finally { + await closeLoopbackServer(server); + } + }, +); + test('lease.allocate forwards retainOnClose to the handler as lease meta', async (t) => { if (await skipWhenLoopbackUnavailable(t)) return; const received: DaemonRequest[] = []; diff --git a/packages/daemon/src/server/__tests__/request-execution-scope-unnamed-session.test.ts b/packages/daemon/src/server/__tests__/request-execution-scope-unnamed-session.test.ts new file mode 100644 index 0000000000..e5d925e16a --- /dev/null +++ b/packages/daemon/src/server/__tests__/request-execution-scope-unnamed-session.test.ts @@ -0,0 +1,132 @@ +import { bindTestCommandHost, createTestHostEnvironment } from '@agent-device/test-kit'; +import { expect, test, vi } from 'vitest'; +import { + daemonClaimRecoveryGatewayFixture, + daemonPlatformServicesFixture, +} from '../../__tests__/support/platform-services-fixture.ts'; +import { makeIosSession } from '../../__tests__/support/session-factories.ts'; +import { makeSessionStore } from '../../__tests__/support/store-factory.ts'; +import { + platformRequestScopeFixture, + unavailableDeviceRuntimeGateway, +} from '../../__tests__/support/unavailable-device-runtime-gateway.ts'; +import type { DaemonRequest } from '../../core/daemon-request.ts'; +import { LeaseRegistry } from '../../resources/lease-registry.ts'; +import { createRequestExecutionScope } from '../request-execution-scope.ts'; + +bindTestCommandHost(); + +function createTestRequestScope( + params: Pick< + Parameters[0], + 'req' | 'sessionStore' | 'leaseRegistry' + >, +) { + return createRequestExecutionScope({ + host: createTestHostEnvironment(), + ...params, + platformServices: daemonPlatformServicesFixture(), + claimRecoveryGateway: daemonClaimRecoveryGatewayFixture(), + deviceRuntimeGateway: unavailableDeviceRuntimeGateway, + platformRequestScope: platformRequestScopeFixture(), + }); +} + +function makeRequest(overrides: Partial = {}): DaemonRequest { + return { + token: 'test-token', + session: 'default', + command: 'snapshot', + positionals: [], + ...overrides, + }; +} + +function publishProviderLeasedDefaultSession( + sessionStore: ReturnType, + leaseRegistry: LeaseRegistry, +): void { + const lease = leaseRegistry.allocateLease({ + tenantId: 'tenant-a', + runId: 'run-1', + leaseProvider: 'proxy', + clientId: 'client-a', + deviceKey: 'ios:sim-1', + }); + sessionStore.publish( + 'default', + makeIosSession('default', { + lease: { + leaseId: lease.leaseId, + tenantId: lease.tenantId, + runId: lease.runId, + leaseBackend: lease.backend, + leaseProvider: 'proxy', + clientId: 'client-a', + deviceKey: 'ios:sim-1', + expiresAt: lease.expiresAt, + }, + }), + ); +} + +test.each(['snapshot', 'artifacts', 'events', 'logs', 'doctor', 'capabilities'])( + 'an unnamed %s cannot reach the provider lease another caller left on the default session', + async (command) => { + const sessionStore = makeSessionStore('agent-device-request-scope-'); + const leaseRegistry = new LeaseRegistry(); + publishProviderLeasedDefaultSession(sessionStore, leaseRegistry); + const dispatch = vi.fn(async () => 'ran'); + + const run = async () => { + const scope = await createTestRequestScope({ + req: makeRequest({ command, internal: { sessionOmitted: true } }), + sessionStore, + leaseRegistry, + }); + return await scope.runLocked(dispatch); + }; + + await expect(run()).rejects.toMatchObject({ + code: 'INVALID_ARGS', + details: { reason: 'REMOTE_SESSION_REQUIRED', leaseProvider: 'proxy' }, + }); + expect(dispatch).not.toHaveBeenCalled(); + }, +); + +test('an unnamed command is refused when the session gains a provider lease after the first check', async () => { + const sessionStore = makeSessionStore('agent-device-request-scope-'); + const leaseRegistry = new LeaseRegistry(); + const dispatch = vi.fn(async () => 'ran'); + const scope = await createTestRequestScope({ + req: makeRequest({ internal: { sessionOmitted: true } }), + sessionStore, + leaseRegistry, + }); + + publishProviderLeasedDefaultSession(sessionStore, leaseRegistry); + + await expect(scope.runLocked(dispatch)).rejects.toMatchObject({ + code: 'INVALID_ARGS', + details: { reason: 'REMOTE_SESSION_REQUIRED', leaseProvider: 'proxy' }, + }); + expect(dispatch).not.toHaveBeenCalled(); +}); + +test.each(['session_list', 'devices', 'release_materialized_paths'])( + 'an unnamed %s still answers while the default session holds a provider lease', + async (command) => { + const sessionStore = makeSessionStore('agent-device-request-scope-'); + const leaseRegistry = new LeaseRegistry(); + publishProviderLeasedDefaultSession(sessionStore, leaseRegistry); + + const scope = await createTestRequestScope({ + req: makeRequest({ command, internal: { sessionOmitted: true } }), + sessionStore, + leaseRegistry, + }); + + await expect(scope.runLocked(async () => 'ran')).resolves.toBe('ran'); + }, +); diff --git a/packages/daemon/src/server/http/daemon-runtime-leased-session.test.ts b/packages/daemon/src/server/http/daemon-runtime-leased-session.test.ts new file mode 100644 index 0000000000..65efb8af45 --- /dev/null +++ b/packages/daemon/src/server/http/daemon-runtime-leased-session.test.ts @@ -0,0 +1,216 @@ +import fs from 'node:fs'; +import { afterEach, beforeEach, expect, test } from 'vitest'; +import { resolveDaemonPaths } from '@agent-device/daemon-contracts/daemon-resolution'; +import { createTestHostEnvironment, mkdtempForTestSync } from '@agent-device/test-kit'; +import { daemonRuntimeDepsFixture } from '../../__tests__/support/daemon-runtime-deps-fixture.ts'; +import { startDaemonRuntime } from './daemon-runtime.ts'; + +const TENANT = 'tenant-a'; +const RUN = 'run-1'; +const PROXY_SCOPE = { + tenantId: TENANT, + runId: RUN, + leaseProvider: 'proxy', + clientId: 'client-a', + deviceKey: 'android:mobile:emulator-5554', + backend: 'android-instance', +} as const; + +type RpcBody = { + result?: { ok?: boolean; data?: { lease?: { leaseId?: string } } }; + error?: { data?: { code?: string; details?: { reason?: string; leaseProvider?: string } } }; +}; + +let daemon: { close: () => Promise; httpPort: number; token: string }; + +beforeEach(async () => { + const stateDir = mkdtempForTestSync('agent-device-leased-session-'); + const runtime = await startDaemonRuntime({ + host: createTestHostEnvironment({ + env: { + ...process.env, + AGENT_DEVICE_STATE_DIR: stateDir, + AGENT_DEVICE_DAEMON_IDLE_TIMEOUT_MS: '0', + AGENT_DEVICE_DAEMON_SERVER_MODE: 'http', + }, + }), + stderr: { write: () => {} }, + stdout: { write: () => {} }, + composeDeps: daemonRuntimeDepsFixture({}), + }); + const { httpPort, token } = JSON.parse( + fs.readFileSync(resolveDaemonPaths(stateDir).infoPath, 'utf8'), + ) as { httpPort: number; token: string }; + daemon = { + close: async () => { + await runtime.close(); + }, + httpPort, + token, + }; +}); + +afterEach(async () => { + await daemon.close(); +}); + +async function rpc(method: string, params: Record): Promise { + const response = await fetch(`http://127.0.0.1:${daemon.httpPort}/rpc`, { + method: 'POST', + headers: { authorization: `Bearer ${daemon.token}`, 'content-type': 'application/json' }, + body: JSON.stringify({ jsonrpc: '2.0', id: method, method, params }), + }); + return (await response.json()) as RpcBody; +} + +function allocate(params: Record): Promise { + return rpc('agent_device.lease.allocate', params); +} + +async function allocateNamedLease(session: string): Promise { + const allocated = await allocate({ ...PROXY_SCOPE, session }); + const leaseId = allocated.result?.data?.lease?.leaseId; + expect(leaseId, JSON.stringify(allocated)).toBeTypeOf('string'); + return leaseId as string; +} + +function expectSessionRequired(body: RpcBody): void { + expect(body.error?.data).toMatchObject({ + code: 'INVALID_ARGS', + details: { reason: 'REMOTE_SESSION_REQUIRED', leaseProvider: 'proxy' }, + }); +} + +test.each([ + ['omitted', {}], + ['blank', { session: ' ' }], +])('a %s session is refused before a provider lease is allocated', async (_label, session) => { + expectSessionRequired(await allocate({ ...PROXY_SCOPE, ...session })); + + // Another client finds the device free, so the refused request left no lease behind. + const other = await allocate({ ...PROXY_SCOPE, clientId: 'client-b', session: 'agent-b' }); + expect(other.result?.ok, JSON.stringify(other)).toBe(true); +}); + +test.each([ + [ + 'the command method', + () => { + const { backend: leaseBackend, ...scope } = PROXY_SCOPE; + return rpc('agent_device.command', { + session: 'default', + command: 'lease_allocate', + positionals: [], + meta: { ...scope, leaseBackend, sessionExplicit: false }, + }); + }, + ], + [ + 'the lease method', + () => allocate({ ...PROXY_SCOPE, session: 'default', sessionExplicit: false }), + ], +])('a client that names no session through %s is refused', async (_label, send) => { + expectSessionRequired(await send()); + + const other = await allocate({ ...PROXY_SCOPE, clientId: 'client-b', session: 'agent-b' }); + expect(other.result?.ok, JSON.stringify(other)).toBe(true); +}); + +test.each([ + ['in its meta', { sessionExplicit: true }, {}], + ['in its flags', { sessionExplicit: false }, { session: 'default' }], +])('a client that names the default session %s is not refused', async (_label, meta, flags) => { + const { backend: leaseBackend, ...scope } = PROXY_SCOPE; + + const allocated = await rpc('agent_device.command', { + session: 'default', + command: 'lease_allocate', + positionals: [], + flags, + meta: { ...scope, leaseBackend, ...meta }, + }); + + expect(allocated.result?.ok, JSON.stringify(allocated)).toBe(true); +}); + +test('an unnamed heartbeat is refused and the named lease stays usable', async () => { + const leaseId = await allocateNamedLease('agent-a'); + + expectSessionRequired(await rpc('agent_device.lease.heartbeat', { ...PROXY_SCOPE, leaseId })); + + const named = await rpc('agent_device.lease.heartbeat', { + ...PROXY_SCOPE, + leaseId, + session: 'agent-a', + }); + expect(named.result?.ok).toBe(true); +}); + +test('an unnamed release is refused and the lease is still released when named', async () => { + const leaseId = await allocateNamedLease('agent-a'); + + expectSessionRequired(await rpc('agent_device.lease.release', { ...PROXY_SCOPE, leaseId })); + + const named = await rpc('agent_device.lease.release', { + ...PROXY_SCOPE, + leaseId, + session: 'agent-a', + }); + expect(named.result?.data).toMatchObject({ released: true }); +}); + +test.each([ + ['shared', {}], + ['tenant-isolated', { sessionIsolation: 'tenant' }], +])( + 'an unnamed leased command is refused for its session in a %s daemon', + async (_label, isolation) => { + const leaseId = await allocateNamedLease('agent-a'); + const { backend: leaseBackend, ...scope } = PROXY_SCOPE; + + const refused = await rpc('agent_device.command', { + command: 'snapshot', + positionals: [], + meta: { ...scope, leaseBackend, leaseId, ...isolation }, + }); + + expectSessionRequired(refused); + }, +); + +test('a named leased command is not refused for its session', async () => { + const leaseId = await allocateNamedLease('agent-a'); + const { backend: leaseBackend, ...scope } = PROXY_SCOPE; + + const named = await rpc('agent_device.command', { + session: 'agent-a', + command: 'snapshot', + positionals: [], + meta: { ...scope, leaseBackend, leaseId }, + }); + + expect(named.error?.data?.code, JSON.stringify(named)).toBe('DEVICE_NOT_FOUND'); + expect(named.error?.data?.details?.reason).not.toBe('REMOTE_SESSION_REQUIRED'); +}); + +test('an unnamed request that names a provider but holds no lease is not refused for its session', async () => { + const listed = await rpc('agent_device.command', { + command: 'apps', + positionals: [], + flags: { platform: 'android', leaseProvider: 'proxy' }, + }); + + expect(listed.error?.data?.details?.reason).not.toBe('REMOTE_SESSION_REQUIRED'); +}); + +test('requests with no lease provider keep their unnamed default session', async () => { + const allocated = await allocate({ + tenantId: TENANT, + runId: RUN, + backend: 'android-instance', + }); + expect(allocated.result?.ok, JSON.stringify(allocated)).toBe(true); + + const listed = await rpc('agent_device.command', { command: 'session_list' }); + expect(listed.result?.ok, JSON.stringify(listed)).toBe(true); +}); diff --git a/packages/daemon/src/server/http/http-rpc-methods.ts b/packages/daemon/src/server/http/http-rpc-methods.ts index 948de61a0f..2d85d8cdc5 100644 --- a/packages/daemon/src/server/http/http-rpc-methods.ts +++ b/packages/daemon/src/server/http/http-rpc-methods.ts @@ -12,6 +12,7 @@ import type { import { commandRpcParamsSchema } from '@agent-device/kernel/contracts'; import { readLeaseAllocateProviderFlags } from '@agent-device/contracts/lease-scope'; import type { DaemonRequest } from '../../core/daemon-request.ts'; +import { resolveRequestSessionAtIntake } from '../../core/request-session-intake.ts'; import { resolveToken } from './http-authorization.ts'; import { resolveMaterializedPathRetentionMs } from '../../sessions/materialized-path-registry.ts'; @@ -47,7 +48,7 @@ const SUPPORTED_RPC_METHODS = new Set([ function toDaemonRequest(params: CommandRpcParams, headers: IncomingHttpHeaders): DaemonRequest { return { token: resolveToken(params as Record, headers), - session: params.session ?? 'default', + ...resolveRequestSessionAtIntake(params), command: params.command ?? '', positionals: params.positionals ?? [], input: params.input, @@ -155,7 +156,10 @@ function toLeaseDaemonRequest( ): DaemonRequest { return { token: resolveToken(params, headers), - session: readStringParam(params, 'session') ?? 'default', + ...resolveRequestSessionAtIntake({ + session: readStringParam(params, 'session'), + meta: { sessionExplicit: readBooleanParam(params, 'sessionExplicit') }, + }), command, positionals: [], flags: command === 'lease_allocate' ? readLeaseAllocateProviderFlags(params) : undefined, @@ -234,7 +238,7 @@ function toInstallFromSourceDaemonRequest( } return { token: resolveToken(params, headers), - session: readStringParam(params, 'session') ?? 'default', + ...resolveRequestSessionAtIntake({ session: readStringParam(params, 'session') }), command: 'install_source', positionals: [], flags: { platform }, @@ -260,7 +264,7 @@ function toReleaseMaterializedPathsDaemonRequest( } return { token: resolveToken(params, headers), - session: readStringParam(params, 'session') ?? 'default', + ...resolveRequestSessionAtIntake({ session: readStringParam(params, 'session') }), command: 'release_materialized_paths', positionals: [], meta: { diff --git a/packages/daemon/src/server/http/transport.test.ts b/packages/daemon/src/server/http/transport.test.ts index a4261f1320..9d080a9b3c 100644 --- a/packages/daemon/src/server/http/transport.test.ts +++ b/packages/daemon/src/server/http/transport.test.ts @@ -247,6 +247,38 @@ test('socket transport refuses a non-string positional before dispatch', async ( } }); +test.for([ + ['omitted', undefined, 'default', true], + ['blank', ' ', ' ', true], + ['named', 'agent-a', 'agent-a', undefined], +] as const)( + 'the socket records a session that is %s', + async ([_label, session, resolvedSession, sessionOmitted], t) => { + if (await skipWhenLoopbackUnavailable(t)) return; + + const observedRequests: DaemonRequest[] = []; + const server = createSocketServer(async (req): Promise => { + observedRequests.push(req); + return { ok: true, data: {} }; + }); + + try { + const client = await connectSocket(await listenNetServer(server)); + await writeSocketRequests( + client, + [JSON.stringify({ token: 'token', session, command: 'session_list', positionals: [] })], + 1, + ); + client.destroy(); + assert.equal(observedRequests.length, 1); + assert.equal(observedRequests[0]?.session, resolvedSession); + assert.equal(observedRequests[0]?.internal?.sessionOmitted, sessionOmitted); + } finally { + await closeLoopbackServer(server); + } + }, +); + // A socket client that vanishes mid-request must cancel that connection's // in-flight request via its request-scoped signal — never through a global // Apple-runner abort, and never touching another connection's request. diff --git a/packages/daemon/src/server/http/transport.ts b/packages/daemon/src/server/http/transport.ts index 12c5f82a7f..329f5ecb98 100644 --- a/packages/daemon/src/server/http/transport.ts +++ b/packages/daemon/src/server/http/transport.ts @@ -11,6 +11,7 @@ import { AsyncResource } from 'node:async_hooks'; import net from 'node:net'; import type { Server as HttpServer } from 'node:http'; import type { DaemonInvokeFn, DaemonRequest } from '../../core/daemon-request.ts'; +import { resolveRequestSessionAtIntake } from '../../core/request-session-intake.ts'; import { resolveDaemonRequestResultDeadlineMs } from '../../core/daemon-command-registry.ts'; import { clearRequestAbortRegistration, @@ -215,7 +216,7 @@ function parseSocketDaemonRequest(line: string): DaemonRequest { if (isRecord(request.meta)) { request.meta = { ...request.meta, devicePin: readDevicePin(request.meta.devicePin) }; } - return request as DaemonRequest; + return { ...request, ...resolveRequestSessionAtIntake(request) } as DaemonRequest; } export function listenNetServer(server: net.Server): Promise { diff --git a/packages/daemon/src/server/request-execution-scope.ts b/packages/daemon/src/server/request-execution-scope.ts index a030e354dd..af9e91d189 100644 --- a/packages/daemon/src/server/request-execution-scope.ts +++ b/packages/daemon/src/server/request-execution-scope.ts @@ -32,6 +32,7 @@ import { } from '../sessions/session-routing.ts'; import { deriveWebSessionIdentity } from '../core/session-tenant-scope.ts'; import { + assertProviderLeaseRequestNamesSession, assertRequestLeaseAdmissionPreflight, scopeRequestSession, } from '../sessions/request-admission.ts'; @@ -307,6 +308,7 @@ export async function createRequestExecutionScope(params: { : undefined; if (devicePin && pinPolicy) pinPolicy.assertRequestHonorsDevicePin(devicePin, scopedReq); if (params.daemonPolicy) assertDaemonPolicyAdmitsRequest(params.daemonPolicy, scopedReq); + assertProviderLeaseRequestNamesSession(scopedReq, sessionStore.get(sessionName)); assertRequestLeaseAdmissionPreflight(scopedReq); // Parse the budget once, before resolving the target device or taking any lock. The lock plan // still supplies the device to wait for, but an out-of-range budget is refused before either. @@ -398,6 +400,7 @@ export async function createRequestExecutionScope(params: { try { const existingRef = sessionStore.lookup(sessionName); const session = existingRef?.session; + assertProviderLeaseRequestNamesSession(scopedReq, session); const boundedResources = boundedStep ? await import('../core/composite-resource-admission.ts') : undefined; diff --git a/packages/daemon/src/server/request-router.ts b/packages/daemon/src/server/request-router.ts index 28f9d8e7e6..3cac1975ff 100644 --- a/packages/daemon/src/server/request-router.ts +++ b/packages/daemon/src/server/request-router.ts @@ -22,11 +22,11 @@ import { timingSafeStringEqual } from '@agent-device/host-kit/transport'; import { type ResponseCost, errorResponse, - namesSessionExplicitly, noActiveSessionError, type DaemonResponse, type DaemonResponseData, } from '@agent-device/kernel/contracts'; +import { namesSessionExplicitly } from '@agent-device/kernel/record'; import type { CloudArtifactProvider } from '@agent-device/contracts/observability'; import type { TrackDownloadableArtifact } from '../resources/artifact-tracking.ts'; import type { diff --git a/packages/daemon/src/sessions/__tests__/request-admission.test.ts b/packages/daemon/src/sessions/__tests__/request-admission.test.ts index efec73795c..4f76905c9b 100644 --- a/packages/daemon/src/sessions/__tests__/request-admission.test.ts +++ b/packages/daemon/src/sessions/__tests__/request-admission.test.ts @@ -4,7 +4,11 @@ import { makeIosSession, makeMacOsSession } from '../../__tests__/support/sessio import { parseDaemonPolicy } from '@agent-device/daemon-contracts/daemon-policy-file'; import { AppError } from '@agent-device/kernel/errors'; import { LeaseRegistry } from '../../resources/lease-registry.ts'; -import { assertRequestLeaseAdmission, isConfinedToAppLease } from '../request-admission.ts'; +import { + assertProviderLeaseRequestNamesSession, + assertRequestLeaseAdmission, + isConfinedToAppLease, +} from '../request-admission.ts'; import type { DaemonRequest } from '../../core/daemon-request.ts'; import type { ProviderAppCatalog } from '@agent-device/contracts/device'; @@ -550,3 +554,43 @@ test('a daemon policy that requires a macos-app lease refuses unleased and other lease.leaseId, ); }); + +const SESSION_LEASE = { tenantId: 'tenant-a', runId: 'run-1', leaseId: 'a'.repeat(32) }; + +test('an unnamed request reaching a provider lease through its session is refused', () => { + const session = makeIosSession('default', { + lease: { ...SESSION_LEASE, leaseProvider: 'proxy' }, + }); + + assert.throws( + () => + assertProviderLeaseRequestNamesSession( + makeRequest({ command: 'snapshot', internal: { sessionOmitted: true } }), + session, + ), + (error: unknown) => { + assert.ok(error instanceof AppError); + assert.equal(error.code, 'INVALID_ARGS'); + assert.equal(error.details?.reason, 'REMOTE_SESSION_REQUIRED'); + assert.equal(error.details?.leaseProvider, 'proxy'); + return true; + }, + ); +}); + +test('a named request on the same provider-leased session is not refused', () => { + const session = makeIosSession('default', { + lease: { ...SESSION_LEASE, leaseProvider: 'proxy' }, + }); + + assertProviderLeaseRequestNamesSession(makeRequest({ command: 'snapshot' }), session); +}); + +test('an unnamed request on a session whose lease has no provider is not refused', () => { + const session = makeIosSession('default', { lease: SESSION_LEASE }); + + assertProviderLeaseRequestNamesSession( + makeRequest({ command: 'snapshot', internal: { sessionOmitted: true } }), + session, + ); +}); diff --git a/packages/daemon/src/sessions/handlers/record-runtime-request.ts b/packages/daemon/src/sessions/handlers/record-runtime-request.ts index a3fc5920d2..02ffa78915 100644 --- a/packages/daemon/src/sessions/handlers/record-runtime-request.ts +++ b/packages/daemon/src/sessions/handlers/record-runtime-request.ts @@ -7,7 +7,7 @@ import { import { retiredScreenshotMaxSizeFlagError } from '@agent-device/contracts/capture'; import { AppError } from '@agent-device/kernel/errors'; import type { DaemonRequest } from '../../core/daemon-request.ts'; -import { namesSessionExplicitly } from '@agent-device/kernel/contracts'; +import { namesSessionExplicitly } from '@agent-device/kernel/record'; const IOS_DEVICE_RECORD_MIN_FPS = 1; const IOS_DEVICE_RECORD_MAX_FPS = 120; diff --git a/packages/daemon/src/sessions/handlers/record-runtime.ts b/packages/daemon/src/sessions/handlers/record-runtime.ts index d28da91dab..081f880252 100644 --- a/packages/daemon/src/sessions/handlers/record-runtime.ts +++ b/packages/daemon/src/sessions/handlers/record-runtime.ts @@ -19,7 +19,7 @@ import { } from '@agent-device/contracts/screen-recording-runtime-plan'; import { isWholeScreenRecordingScope } from '@agent-device/contracts/recording'; import { AppError, normalizeError } from '@agent-device/kernel/errors'; -import { namesSessionExplicitly } from '@agent-device/kernel/contracts'; +import { namesSessionExplicitly } from '@agent-device/kernel/record'; import { deviceIdentityFlag, type DeviceIdentity, diff --git a/packages/daemon/src/sessions/handlers/session-appstate.ts b/packages/daemon/src/sessions/handlers/session-appstate.ts index 208d14dadd..360d35181f 100644 --- a/packages/daemon/src/sessions/handlers/session-appstate.ts +++ b/packages/daemon/src/sessions/handlers/session-appstate.ts @@ -1,5 +1,5 @@ import type { DaemonResponse } from '@agent-device/kernel/contracts'; -import { namesSessionExplicitly } from '@agent-device/kernel/contracts'; +import { namesSessionExplicitly } from '@agent-device/kernel/record'; import { isApplePlatform } from '@agent-device/kernel/device'; import { hasExplicitDeviceSelector } from '../../core/device/device-selector-intent.ts'; import { diff --git a/packages/daemon/src/sessions/handlers/session-batch.ts b/packages/daemon/src/sessions/handlers/session-batch.ts index d6407d6575..352d86dfb4 100644 --- a/packages/daemon/src/sessions/handlers/session-batch.ts +++ b/packages/daemon/src/sessions/handlers/session-batch.ts @@ -15,6 +15,7 @@ export async function runBatchCommands( ...step.internal, webSession: req.internal?.webSession, ...(req.internal?.publicNetworkOnly ? { publicNetworkOnly: true } : {}), + ...(req.internal?.sessionOmitted ? { sessionOmitted: true } : {}), executionPlan: { remainingSteps: context.remainingSteps }, }, }); diff --git a/packages/daemon/src/sessions/request-admission.ts b/packages/daemon/src/sessions/request-admission.ts index 115eae1490..bf32e513d7 100644 --- a/packages/daemon/src/sessions/request-admission.ts +++ b/packages/daemon/src/sessions/request-admission.ts @@ -5,6 +5,7 @@ import { resolveSessionIsolationMode } from '../core/config.ts'; import { tenantScopedSessionName } from '../core/session-tenant-scope.ts'; import { isAppLeaseAllowed, + ignoresSessionLease, isLeaseAdmissionExempt, isHumanControlMutation, resolveSessionlessLeaseAdmissionExemption, @@ -15,7 +16,10 @@ import { resolveLeaseScope, resolveRequestOrSessionLeaseScope, } from '../core/lease-context.ts'; -import { leaseScopeToHeartbeatRequest } from '@agent-device/contracts/lease-scope'; +import { + leaseScopeToHeartbeatRequest, + remoteSessionRequiredError, +} from '@agent-device/contracts/lease-scope'; import type { LeaseRegistry } from '../resources/lease-registry.ts'; import type { DaemonRequest } from '../core/daemon-request.ts'; import type { SessionState } from '../core/session-state.ts'; @@ -169,6 +173,25 @@ function hasSessionlessLeaseAdmissionExemption( ); } +/** + * An unnamed session resolves to whichever connection holds the default name, so a request that + * would allocate, use or release a provider lease has to name the session it means. Naming a + * provider alone is not that: a sessionless catalog read holds no lease. A request that names only + * a lease id passes here too, because the registry's owner scope refuses it for omitting the + * provider. + */ +export function assertProviderLeaseRequestNamesSession( + req: DaemonRequest, + session: SessionState | undefined, +): void { + if (!req.internal?.sessionOmitted) return; + const { leaseProvider, leaseId } = ignoresSessionLease(req.command) + ? resolveLeaseScope(req) + : resolveRequestOrSessionLeaseScope(req, session); + if (!leaseProvider) return; + if (leaseId || req.command === 'lease_allocate') throw remoteSessionRequiredError(leaseProvider); +} + export function assertRequestLeaseAdmissionPreflight(req: DaemonRequest): void { if (isLeaseAdmissionExempt(req.command)) return; assertProxyOpenLeaseMetadata(req, resolveLeaseScope(req)); diff --git a/packages/daemon/src/sessions/session-routing.ts b/packages/daemon/src/sessions/session-routing.ts index 4caed91518..a7c3adf4b6 100644 --- a/packages/daemon/src/sessions/session-routing.ts +++ b/packages/daemon/src/sessions/session-routing.ts @@ -12,7 +12,7 @@ import type { DaemonRequest } from '../core/daemon-request.ts'; import type { SessionRef, SessionState } from '../core/session-state.ts'; import type { SessionScope } from '@agent-device/contracts/session'; import { SessionStore } from '../core/session-store.ts'; -import { namesSessionExplicitly } from '@agent-device/kernel/contracts'; +import { namesSessionExplicitly } from '@agent-device/kernel/record'; import { listSessionSelectorConflicts, type SessionSelectorConflict, diff --git a/packages/host-kit/src/internal/host-process-liveness.test.ts b/packages/host-kit/src/internal/host-process-liveness.test.ts index a2e6b212f8..69a4a8ddf1 100644 --- a/packages/host-kit/src/internal/host-process-liveness.test.ts +++ b/packages/host-kit/src/internal/host-process-liveness.test.ts @@ -21,6 +21,8 @@ import { readProcessIdentityFacts, } from './host-process.ts'; +const readFile = fs.readFileSync; + function psReturns(stdout: string, exitCode = 0): void { mockRunCmdSync.mockReturnValue({ stdout, stderr: '', exitCode }); } @@ -44,6 +46,11 @@ function psInstalledAt(installed: readonly string[]): void { beforeEach(() => { mockRunCmdSync.mockReset(); mockRunCmd.mockReset(); + vi.spyOn(fs, 'readFileSync').mockImplementation((...args) => { + // The ps fixture must not borrow the real host's identity for a fabricated pid. + if (String(args[0]) === '/proc/sys/kernel/random/boot_id') throw new Error('ENOENT'); + return readFile(...args); + }); }); afterEach(() => { diff --git a/packages/host-kit/src/internal/host-process-stop-confirm.test.ts b/packages/host-kit/src/internal/host-process-stop-confirm.test.ts index 4d59d70012..f156670cbe 100644 --- a/packages/host-kit/src/internal/host-process-stop-confirm.test.ts +++ b/packages/host-kit/src/internal/host-process-stop-confirm.test.ts @@ -1,4 +1,5 @@ import assert from 'node:assert/strict'; +import fs from 'node:fs'; import { afterEach, test, vi } from 'vitest'; // Every claim the stopper makes is about what the host answers, so one double answers both syscalls it @@ -16,6 +17,7 @@ import { type ProcessStopTarget, } from './host-process.ts'; +const readFile = fs.readFileSync; const PID = 4242; const BUDGET = { termTimeoutMs: 1_000, killTimeoutMs: 500 }; type Signal = 'SIGTERM' | 'SIGINT' | 'SIGKILL'; @@ -256,6 +258,11 @@ const STOP_CASES: HostCase[] = [ ]; function driveHost(model: HostCase): { signals: Signal[] } { + vi.spyOn(fs, 'readFileSync').mockImplementation((...args) => { + // This host model supplies process identity through its ps answers. + if (String(args[0]) === '/proc/sys/kernel/random/boot_id') throw new Error('ENOENT'); + return readFile(...args); + }); const signals: Signal[] = []; let psRefused = false; let ended = false; diff --git a/packages/host-kit/src/local-artifact-adapter.test.ts b/packages/host-kit/src/local-artifact-adapter.test.ts index 76f23ca0d0..8630885334 100644 --- a/packages/host-kit/src/local-artifact-adapter.test.ts +++ b/packages/host-kit/src/local-artifact-adapter.test.ts @@ -6,7 +6,7 @@ import { mkdtempForTestSync } from './internal/tmp-dir.fixtures.ts'; import { createLocalArtifactAdapter } from './local-artifact-adapter.ts'; test('local artifact adapter marks command outputs and temp files by visibility', async () => { - const adapter = createLocalArtifactAdapter(); + const adapter = createLocalArtifactAdapter({ cwd: process.cwd() }); const output = await adapter.reserveOutput(undefined, { field: 'path', ext: '.png', diff --git a/packages/host-kit/src/local-artifact-adapter.ts b/packages/host-kit/src/local-artifact-adapter.ts index 014d92ef2b..acefbb1523 100644 --- a/packages/host-kit/src/local-artifact-adapter.ts +++ b/packages/host-kit/src/local-artifact-adapter.ts @@ -1,4 +1,3 @@ -import { captureHostEnvironment } from './process.ts'; import { promises as fs } from 'node:fs'; import os from 'node:os'; import path from 'node:path'; @@ -8,10 +7,8 @@ import type { LocalArtifactAdapterOptions, } from '@agent-device/contracts/artifact-adapter'; -export function createLocalArtifactAdapter( - options: LocalArtifactAdapterOptions = {}, -): ArtifactAdapter { - const cwd = options.cwd ?? captureHostEnvironment(process).cwd; +export function createLocalArtifactAdapter(options: LocalArtifactAdapterOptions): ArtifactAdapter { + const cwd = options.cwd; const tempDir = options.tempDir ?? os.tmpdir(); const rootDir = options.rootDir ? resolveLocalPath(options.rootDir, cwd) : undefined; diff --git a/packages/kernel/src/contracts.ts b/packages/kernel/src/contracts.ts index 40f94588ae..0448e07da7 100644 --- a/packages/kernel/src/contracts.ts +++ b/packages/kernel/src/contracts.ts @@ -257,24 +257,6 @@ export function errorResponse( export const NO_ACTIVE_SESSION_MESSAGE = 'No active session. Run agent-device open first, then retry the command.'; -/** - * Whether the caller named the session it wants, traced from what the request carries rather than - * from the session string. Every request has a session *name*, because an unnamed one inherits the - * workspace's own session address, so comparing names cannot answer this. Both carriers count: - * every client sets `meta.sessionExplicit`, and the commands whose own input schema declares - * `--session` also deliver the value in `flags.session`. The flag bag reaches this predicate in - * both shapes the wire carries it in: a command's declared flag type, or a generic record from a - * runner that merges flags (batch steps); the string check below is what decides either way. - */ -export function namesSessionExplicitly(request: { - flags?: { session?: unknown } | Record | undefined; - meta?: { sessionExplicit?: boolean } | undefined; -}): boolean { - if (request.meta?.sessionExplicit === true) return true; - const value = request.flags?.session; - return typeof value === 'string' && value.trim().length > 0; -} - /** * Shared no-active-session failure used by handlers that require * an open session before dispatching. diff --git a/packages/kernel/src/contracts.test.ts b/packages/kernel/src/record-session-naming.test.ts similarity index 92% rename from packages/kernel/src/contracts.test.ts rename to packages/kernel/src/record-session-naming.test.ts index 45976dd723..f182e9b904 100644 --- a/packages/kernel/src/contracts.test.ts +++ b/packages/kernel/src/record-session-naming.test.ts @@ -1,6 +1,6 @@ import assert from 'node:assert/strict'; import { test } from 'vitest'; -import { namesSessionExplicitly } from './contracts.ts'; +import { namesSessionExplicitly } from './record.ts'; test('a client that set the explicit-session meta names its session', () => { assert.equal(namesSessionExplicitly({ meta: { sessionExplicit: true } }), true); diff --git a/packages/kernel/src/record.ts b/packages/kernel/src/record.ts index 700eff1e8b..2b90330049 100644 --- a/packages/kernel/src/record.ts +++ b/packages/kernel/src/record.ts @@ -284,6 +284,24 @@ type WithoutUndefined> = { [K in keyof T as undefined extends T[K] ? K : never]?: Exclude; }; +/** + * Whether the caller named the session it wants, traced from what the request carries rather than + * from the session string. Every request has a session *name*, because an unnamed one inherits the + * workspace's own session address, so comparing names cannot answer this. Both carriers count: + * every client sets `meta.sessionExplicit`, and the commands whose own input schema declares + * `--session` also deliver the value in `flags.session`. The flag bag reaches this predicate in + * both shapes the wire carries it in: a command's declared flag type, or a generic record from a + * runner that merges flags (batch steps); the string check below is what decides either way. + */ +export function namesSessionExplicitly(request: { + flags?: { session?: unknown } | Record | undefined; + meta?: { sessionExplicit?: boolean } | undefined; +}): boolean { + if (request.meta?.sessionExplicit === true) return true; + const value = request.flags?.session; + return typeof value === 'string' && value.trim().length > 0; +} + export function stripUndefined>(value: T): WithoutUndefined { const output = {} as WithoutUndefined; for (const [key, current] of Object.entries(value)) { diff --git a/packages/maestro/package.json b/packages/maestro/package.json index c56e47f68e..95c8ae8984 100644 --- a/packages/maestro/package.json +++ b/packages/maestro/package.json @@ -4,16 +4,7 @@ "private": true, "sideEffects": false, "type": "module", - "description": "Private Maestro compatibility engine for agent-device.", - "dependencies": { - "@agent-device/ad-script": "workspace:*", - "@agent-device/capture-kit": "workspace:*", - "@agent-device/contracts": "workspace:*", - "@agent-device/host-kit": "workspace:*", - "@agent-device/kernel": "workspace:*", - "@agent-device/provision-kit": "workspace:*", - "@agent-device/selectors": "workspace:*" - }, + "description": "Optional Maestro compatibility engine plugin for agent-device.", "exports": { ".": { "types": "./src/index.ts", @@ -30,10 +21,38 @@ "./run-script-http": { "types": "./src/daemon-port/run-script-http.ts", "default": "./src/daemon-port/run-script-http.ts" + }, + "./agent-device": { + "types": "./src/plugin.ts", + "default": "./src/plugin.ts" } }, "devDependencies": { "undici": "7.30.1", - "yaml": "^2.9.0" + "yaml": "^2.9.0", + "@agent-device/ad-script": "workspace:*", + "@agent-device/capture-kit": "workspace:*", + "@agent-device/contracts": "workspace:*", + "@agent-device/host-kit": "workspace:*", + "@agent-device/kernel": "workspace:*", + "@agent-device/provision-kit": "workspace:*", + "@agent-device/selectors": "workspace:*", + "agent-device": "workspace:*" + }, + "scripts": { + "build": "tsdown --config tsdown.config.ts", + "prepack": "pnpm build" + }, + "files": [ + "dist" + ], + "publishConfig": { + "exports": { + "./agent-device": { + "types": "./dist/agent-device.d.mts", + "import": "./dist/agent-device.mjs" + } + }, + "access": "public" } } diff --git a/packages/maestro/src/daemon-port/__tests__/daemon-runtime-port-fixtures.ts b/packages/maestro/src/daemon-port/__tests__/daemon-runtime-port-fixtures.ts index c340894509..c3c444e32d 100644 --- a/packages/maestro/src/daemon-port/__tests__/daemon-runtime-port-fixtures.ts +++ b/packages/maestro/src/daemon-port/__tests__/daemon-runtime-port-fixtures.ts @@ -1,4 +1,8 @@ import type { CommandFlags } from '@agent-device/contracts/command'; +import { + assertSnapshotScreenOrigin, + readSnapshotClickabilityEvidence, +} from '@agent-device/contracts/capture'; import { formatRole } from '@agent-device/kernel/snapshot'; import type { SnapshotNode } from '@agent-device/kernel/snapshot'; import type { SnapshotState } from '@agent-device/contracts/snapshot-model'; @@ -21,8 +25,13 @@ export function makeSnapshot( /** The daemon-owned half of the port options: the runtime envelope flags and the network origin. */ export function makeRuntimeEnvelope( overrides: { flags?: CommandFlags; publicNetworkOnly?: boolean } = {}, -): Pick { +): Pick< + CreateDaemonMaestroRuntimeOperationsOptions, + 'flags' | 'publicNetworkOnly' | 'readSnapshotClickabilityEvidence' | 'assertSnapshotScreenOrigin' +> { return { + readSnapshotClickabilityEvidence, + assertSnapshotScreenOrigin, publicNetworkOnly: false, ...overrides, }; diff --git a/packages/maestro/src/daemon-port/daemon-runtime-port-snapshot-source.ts b/packages/maestro/src/daemon-port/daemon-runtime-port-snapshot-source.ts index 5aa7b90d03..2059272164 100644 --- a/packages/maestro/src/daemon-port/daemon-runtime-port-snapshot-source.ts +++ b/packages/maestro/src/daemon-port/daemon-runtime-port-snapshot-source.ts @@ -1,6 +1,6 @@ import { AppError } from '@agent-device/kernel/errors'; import type { SnapshotState } from '@agent-device/contracts/snapshot-model'; -import { copySnapshotClickabilityEvidence } from '@agent-device/contracts/capture'; +import { attachSnapshotClickabilityEvidence } from '@agent-device/contracts/capture'; import { MAESTRO_RUNTIME_ADAPTER_POLICY, type MaestroObservationIdentity, @@ -36,7 +36,9 @@ export function createDaemonMaestroSnapshotSource( if (!data || !Array.isArray(data.nodes)) { throw new AppError('COMMAND_FAILED', 'Maestro snapshot did not return node data.'); } - const snapshot = copySnapshotClickabilityEvidence(data, data as SnapshotState); + const snapshot = data as SnapshotState; + const clickability = options.readSnapshotClickabilityEvidence(data); + if (clickability) attachSnapshotClickabilityEvidence(snapshot, clickability); cached = { generation: context.generation, snapshot }; return snapshot; }; diff --git a/packages/maestro/src/daemon-port/daemon-runtime-port-support.ts b/packages/maestro/src/daemon-port/daemon-runtime-port-support.ts index a8b87f36d2..38c823f9d3 100644 --- a/packages/maestro/src/daemon-port/daemon-runtime-port-support.ts +++ b/packages/maestro/src/daemon-port/daemon-runtime-port-support.ts @@ -1,4 +1,5 @@ import type { CommandFlags } from '@agent-device/contracts/command'; +import type { ReplayBackendHost } from '@agent-device/contracts/replay-backend'; import path from 'node:path'; import type { MaestroObservation, @@ -22,7 +23,10 @@ export type MaestroDaemonOperationInvoke = ( request: MaestroDaemonOperationRequest, ) => Promise; -export type CreateDaemonMaestroRuntimeOperationsOptions = { +export type CreateDaemonMaestroRuntimeOperationsOptions = Pick< + ReplayBackendHost, + 'readSnapshotClickabilityEvidence' | 'assertSnapshotScreenOrigin' +> & { readonly invoke: MaestroDaemonOperationInvoke; /** The runtime envelope every operation carries: platform, target, device, and recording flags. */ readonly flags?: CommandFlags; diff --git a/packages/maestro/src/daemon-port/daemon-runtime-port.ts b/packages/maestro/src/daemon-port/daemon-runtime-port.ts index 44ae555403..9e7fb91342 100644 --- a/packages/maestro/src/daemon-port/daemon-runtime-port.ts +++ b/packages/maestro/src/daemon-port/daemon-runtime-port.ts @@ -10,7 +10,6 @@ import { } from '@agent-device/maestro'; import { registerDiagnosticSensitiveValue } from '@agent-device/host-kit/diagnostics'; import { AppError } from '@agent-device/kernel/errors'; -import { assertSnapshotScreenOrigin } from '@agent-device/contracts/capture'; import { stripUndefined } from '@agent-device/kernel/record'; import { executeRunScriptFile } from './run-script-execution.ts'; import { captureMaestroComparisonScreenshot } from './maestro-comparison-screenshot.ts'; @@ -301,7 +300,8 @@ function createDaemonMaestroRuntimeParts(options: CreateDaemonMaestroRuntimeOper input.durationMs, platform, ); - if (gesture) await assertSnapshotScreenOrigin(snapshot.nodes, 'Maestro scroll target'); + if (gesture) + await options.assertSnapshotScreenOrigin(snapshot.nodes, 'Maestro scroll target'); await invokeMutation( gesture ? { kind: 'swipe', ...gesture } diff --git a/packages/maestro/src/daemon-port/daemon-runtime-tap.ts b/packages/maestro/src/daemon-port/daemon-runtime-tap.ts index 1ebf721e7b..ed241456ea 100644 --- a/packages/maestro/src/daemon-port/daemon-runtime-tap.ts +++ b/packages/maestro/src/daemon-port/daemon-runtime-tap.ts @@ -1,5 +1,4 @@ import { AppError, asAppError } from '@agent-device/kernel/errors'; -import { assertSnapshotScreenOrigin } from '@agent-device/contracts/capture'; import { INTERACTION_ERROR_REASONS } from '@agent-device/selectors/interaction-error'; import type { Rect } from '@agent-device/kernel/snapshot'; import { @@ -52,7 +51,7 @@ export async function resolveDaemonMaestroTarget(params: { { context, snapshot: snapshots.capture, dependencies: options.dependencies }, deadline, ); - await assertSnapshotScreenOrigin(currentSnapshot.nodes, 'Maestro selector target'); + await options.assertSnapshotScreenOrigin(currentSnapshot.nodes, 'Maestro selector target'); const match = resolveTypedMaestroTarget({ query: input, context, diff --git a/packages/maestro/src/index.test.ts b/packages/maestro/src/index.test.ts index 4a7ec925e8..204c3602ef 100644 --- a/packages/maestro/src/index.test.ts +++ b/packages/maestro/src/index.test.ts @@ -22,18 +22,19 @@ describe('@agent-device/maestro facade', () => { test('keeps the plugin and helper off the engine entry and declares pure modules', () => { const manifest = JSON.parse( fs.readFileSync(path.join(import.meta.dirname, '../package.json'), 'utf8'), - ) as { exports: Record; sideEffects?: boolean }; - // The runScript HTTP helper is a subpath, not part of the engine entry, and the replay - // backend plugin (#3377) is the only other way in: its engine-free declaration lets help list - // the backend without evaluating the engine. This pins the surface; - // scripts/__tests__/eager-closure-budgets.test.ts is what keeps `.` from starting to evaluate - // host-kit, capture-kit, or provision-kit. + ) as { + exports: Record; + publishConfig: { exports: Record }; + sideEffects?: boolean; + }; expect(Object.keys(manifest.exports)).toEqual([ '.', './replay-backend', './replay-backend-declaration', './run-script-http', + './agent-device', ]); + expect(Object.keys(manifest.publishConfig.exports)).toEqual(['./agent-device']); expect(manifest.sideEffects).toBe(false); }); }); diff --git a/packages/maestro/src/internal/export-flow.test.ts b/packages/maestro/src/internal/export-flow.test.ts new file mode 100644 index 0000000000..edc12e281e --- /dev/null +++ b/packages/maestro/src/internal/export-flow.test.ts @@ -0,0 +1,308 @@ +import { parseAllDocuments } from 'yaml'; +import { describe, expect, test } from 'vitest'; +import { AppError } from '@agent-device/kernel/errors'; +import { + exportReplayActionsToMaestro, + inspectMaestroFlow, + MAESTRO_SELECTOR_PROJECTION, +} from '../index.ts'; +import { parseReplayScriptDetailed, readReplayScriptMetadata } from '@agent-device/ad-script'; +import { projectSelectorExpression } from '@agent-device/selectors'; + +describe('exportReplayScriptToMaestro', () => { + test('exports app launch, selectors, input, keyboard, assertions, and screenshots', () => { + const result = exportReplayScriptToMaestro(`env USER="Ada" +context platform=ios target=mobile +open com.example.app --relaunch +click id="email" +fill id="email" "ada@example.com" +keyboard dismiss +find text "Continue" exists +screenshot "./artifacts/checkout" +`); + + const docs = parseYamlDocs(result.yaml); + expect(() => inspectMaestroFlow(result.yaml, 'export.yaml')).not.toThrow(); + expect(docs).toEqual([ + { appId: 'com.example.app', env: { USER: 'Ada' } }, + [ + { launchApp: { appId: 'com.example.app', stopApp: true } }, + { tapOn: { id: 'email' } }, + { tapOn: { id: 'email' } }, + { inputText: 'ada@example.com' }, + 'hideKeyboard', + { assertVisible: 'Continue' }, + { takeScreenshot: './artifacts/checkout' }, + ], + ]); + expect(result.warnings).toEqual([ + { + line: 5, + action: 'fill id="email" ada@example.com', + message: + 'fill exports as tapOn + inputText; Maestro may append text instead of replacing existing field contents', + }, + ]); + }); + + test('exports each app target when a script switches apps and returns', () => { + const result = exportReplayScriptToMaestro(`open com.example.shop +open com.example.auth +open com.example.shop +`); + + expect(() => inspectMaestroFlow(result.yaml, 'apps.yaml')).not.toThrow(); + expect(parseYamlDocs(result.yaml)).toEqual([ + { appId: 'com.example.shop' }, + [ + { launchApp: { appId: 'com.example.shop' } }, + { launchApp: { appId: 'com.example.auth' } }, + { launchApp: { appId: 'com.example.shop' } }, + ], + ]); + expect(result.warnings).toEqual([]); + }); + + test('exports the empty-fill clear as eraseText, never a vacuous inputText', () => { + // `fill ""` is the clear-field primitive (#2063); Maestro's `inputText: ""` types + // nothing, so the recorded clear must become its clear verb. + const result = exportReplayScriptToMaestro(`context platform=ios target=mobile +open com.example.app +fill id="email" "" +`); + + const docs = parseYamlDocs(result.yaml); + expect(docs[1]).toEqual([ + { launchApp: { appId: 'com.example.app' } }, + { tapOn: { id: 'email' } }, + 'eraseText', + ]); + expect(result.warnings).toEqual([ + { + line: 3, + action: 'fill id="email"', + message: + 'fill "" exports as tapOn + eraseText; Maestro erases at most its 50-character default', + }, + ]); + }); + + test('exports coordinate gestures and sleep waits with warnings', () => { + const result = exportReplayScriptToMaestro(`open com.example.app +click 120 240 +swipe 200 700 200 200 --count 2 +wait 500 +`); + + expect(parseYamlDocs(result.yaml)).toEqual([ + { appId: 'com.example.app' }, + [ + { launchApp: { appId: 'com.example.app' } }, + { tapOn: { point: '120,240' } }, + { swipe: { start: '200,700', end: '200,200', duration: 100 } }, + { swipe: { start: '200,700', end: '200,200', duration: 100 } }, + { waitForAnimationToEnd: { timeout: 500 } }, + ], + ]); + expect(result.warnings).toEqual([ + { + line: 4, + action: 'wait 500', + message: + 'wait exports as waitForAnimationToEnd and may return before the full duration', + }, + ]); + }); + + test('exports wait stable as waitForAnimationToEnd and text or selector waits with their timeouts', () => { + const result = exportReplayScriptToMaestro(`open com.example.app +wait stable +wait stable 500 3000 +wait text "Ready" 2000 +wait 'id="done"' 4000 +wait id="save" enabled=true 25000 +wait text Sign in 2000 +`); + + expect(parseYamlDocs(result.yaml)).toEqual([ + { appId: 'com.example.app' }, + [ + { launchApp: { appId: 'com.example.app' } }, + 'waitForAnimationToEnd', + { waitForAnimationToEnd: { timeout: 3000 } }, + { extendedWaitUntil: { visible: 'Ready', timeout: 2000 } }, + { extendedWaitUntil: { visible: { id: 'done' }, timeout: 4000 } }, + { extendedWaitUntil: { visible: { id: 'save', enabled: true }, timeout: 25000 } }, + { extendedWaitUntil: { visible: 'Sign in', timeout: 2000 } }, + ], + ]); + const stableWarning = + 'wait stable exports as waitForAnimationToEnd, which uses its own screen-stability threshold instead of the quiet window'; + expect(result.warnings).toEqual([ + { line: 2, action: 'wait stable', message: stableWarning }, + { line: 3, action: 'wait stable 500 3000', message: stableWarning }, + ]); + }); + + test('rejects wait forms that have no on-screen text to wait for', () => { + const run = () => + exportReplayScriptToMaestro(`open com.example.app +wait @e3 +wait text +wait stable 500 junk +wait visible label="Save" 25000 +`); + expect(run).toThrowError(AppError); + expect(run).toThrowError('line 2 (wait @e3): wait @ref names a session-local ref'); + expect(run).toThrowError('line 3 (wait text): wait text requires the text to wait for'); + expect(run).toThrowError( + 'line 4 (wait stable 500 junk): wait stable takes at most a numeric quietMs and timeoutMs', + ); + // The whole selector reaches the projection, which refuses `visible`; it never exports as text. + expect(run).toThrowError( + 'line 5 (wait visible label="Save" 25000): wait selector is not Maestro-compatible', + ); + }); + + // #3197: `scroll --until` became part of a scroll action, so the export names + // the stop condition it cannot carry instead of exporting a bare page scroll. + test('warns when scroll --until exports as a bare Maestro scroll', () => { + const result = exportReplayScriptToMaestro(`open com.example.app +scroll down --until 'id="far-button"' +`); + + expect(parseYamlDocs(result.yaml)).toEqual([ + { appId: 'com.example.app' }, + [{ launchApp: { appId: 'com.example.app' } }, 'scroll'], + ]); + expect(result.warnings).toEqual([ + { + line: 2, + // The action label names positionals only, so the flag shows in the message. + action: 'scroll down', + message: 'scroll --until id="far-button" is not represented by Maestro scroll', + }, + ]); + }); + + test('warns when explicit long-press durations export to Maestro defaults', () => { + const result = exportReplayScriptToMaestro(`open com.example.app +longpress "label=\\"Last message\\"" 800 +click id="hold-button" --hold-ms 1200 +press text="Retry" --hold-ms 1500 +`); + + expect(parseYamlDocs(result.yaml)).toEqual([ + { appId: 'com.example.app' }, + [ + { launchApp: { appId: 'com.example.app' } }, + { longPressOn: { text: 'Last message' } }, + { longPressOn: { id: 'hold-button' } }, + { longPressOn: { text: 'Retry' } }, + ], + ]); + expect(result.warnings).toEqual([ + { + line: 2, + action: 'longpress label="Last message" 800', + message: + 'label= selectors export as Maestro text; Maestro text matching is broader than agent-device label-only matching', + }, + { + line: 2, + action: 'longpress label="Last message" 800', + message: + 'long-press duration exports as Maestro longPressOn; Maestro uses its default long-press duration instead of 800ms', + }, + { + line: 3, + action: 'click id="hold-button"', + message: + 'long-press duration exports as Maestro longPressOn; Maestro uses its default long-press duration instead of 1200ms', + }, + { + line: 4, + action: 'press text="Retry"', + message: + 'long-press duration exports as Maestro longPressOn; Maestro uses its default long-press duration instead of 1500ms', + }, + ]); + }); + + test('warns when double-tap and hold exports ignore repeated tap options', () => { + const result = exportReplayScriptToMaestro(`open com.example.app +click id="retry" --double-tap --count 2 --interval-ms 200 +press text="Hold" --hold-ms 1000 --count 3 --interval-ms 150 +`); + + expect(parseYamlDocs(result.yaml)).toEqual([ + { appId: 'com.example.app' }, + [ + { launchApp: { appId: 'com.example.app' } }, + { doubleTapOn: { id: 'retry' } }, + { longPressOn: { text: 'Hold' } }, + ], + ]); + expect(result.warnings).toEqual([ + { + line: 2, + action: 'click id="retry"', + message: 'tap --count 2 is not represented by Maestro doubleTapOn', + }, + { + line: 2, + action: 'click id="retry"', + message: 'tap --interval-ms 200 is not represented by Maestro doubleTapOn', + }, + { + line: 3, + action: 'press text="Hold"', + message: + 'long-press duration exports as Maestro longPressOn; Maestro uses its default long-press duration instead of 1000ms', + }, + { + line: 3, + action: 'press text="Hold"', + message: 'tap --count 3 is not represented by Maestro longPressOn', + }, + { + line: 3, + action: 'press text="Hold"', + message: 'tap --interval-ms 150 is not represented by Maestro longPressOn', + }, + ]); + }); + + test('rejects native-only replay actions', () => { + expect(() => + exportReplayScriptToMaestro(`open com.example.app +snapshot -i +get text id="status" +`), + ).toThrowError(AppError); + try { + exportReplayScriptToMaestro(`open com.example.app +snapshot -i +get text id="status" +`); + } catch (error) { + expect(error).toBeInstanceOf(AppError); + expect((error as AppError).message).toContain('line 2 (snapshot)'); + expect((error as AppError).message).toContain('line 3 (get text id="status")'); + } + }); +}); + +function exportReplayScriptToMaestro(script: string) { + const parsed = parseReplayScriptDetailed(script); + return exportReplayActionsToMaestro(parsed.actions, { + actionLines: parsed.actionLines, + metadata: readReplayScriptMetadata(script), + resolveSelector: (expression) => + projectSelectorExpression(expression, MAESTRO_SELECTOR_PROJECTION), + }); +} + +function parseYamlDocs(script: string): unknown[] { + return parseAllDocuments(script).map((doc) => doc.toJSON()); +} diff --git a/packages/maestro/src/plugin.test.ts b/packages/maestro/src/plugin.test.ts new file mode 100644 index 0000000000..72f462e562 --- /dev/null +++ b/packages/maestro/src/plugin.test.ts @@ -0,0 +1,105 @@ +import assert from 'node:assert/strict'; +import { beforeEach, expect, test, vi } from 'vitest'; +import type { ReplayBackendHost } from '@agent-device/contracts/replay-backend'; +import type { retainPngWorker } from '@agent-device/capture-kit/png-worker-client'; + +const state = vi.hoisted(() => ({ + engineLoads: 0, + retain: vi.fn(), +})); + +vi.mock('./replay-backend/replay-maestro-backend.ts', async (importOriginal) => { + state.engineLoads += 1; + return await importOriginal(); +}); + +vi.mock('@agent-device/capture-kit/png-worker-client', async (importOriginal) => ({ + ...(await importOriginal()), + retainPngWorker: state.retain, +})); + +const setupHost = { + env: {}, + options: {}, + clientVersion: '0.22.0-dev', + createError: () => { + throw new Error('setup must not use host services'); + }, +}; + +beforeEach(() => { + vi.resetModules(); + state.engineLoads = 0; + state.retain.mockReset(); +}); + +test('factory setup and unused disposal leave the engine and PNG worker unloaded', async () => { + const { default: maestroPlugin } = await import('./plugin.ts'); + const plugin = maestroPlugin(); + expect({ apiVersion: plugin.apiVersion, kind: plugin.kind, backend: plugin.backend }).toEqual({ + apiVersion: 2, + kind: 'replay-backend', + backend: 'maestro', + }); + + const setup = await plugin.setup(setupHost); + await setup.dispose?.(); + + expect(state.engineLoads).toBe(0); + expect(state.retain).not.toHaveBeenCalled(); +}); + +test('selected creation retains one worker, forwards its diagnostic to the host and releases it', async () => { + const sinks: Parameters[0][] = []; + const release = vi.fn(async () => {}); + state.retain.mockImplementation((sink) => { + sinks.push(sink); + return release; + }); + const host: ReplayBackendHost = { + emitDiagnostic: vi.fn(), + appendTraceEvent: () => { + throw new Error('trace unused'); + }, + buildBuiltinVars: () => { + throw new Error('variables unused'); + }, + readScriptSourceFile: () => { + throw new Error('source reader unused'); + }, + readSnapshotClickabilityEvidence: () => undefined, + assertSnapshotScreenOrigin: () => Promise.reject(new Error('screen origin unused')), + scriptSourceRequiredMessage: '', + resolveTargetDevice: () => Promise.reject(new Error('device selection unused')), + requestSignal: () => undefined, + buildActionFailureResponse: () => Promise.reject(new Error('failure response unused')), + }; + const { default: maestroPlugin } = await import('./plugin.ts'); + const setup = await maestroPlugin().setup(setupHost); + const backend = await setup.replayBackend.create(host); + const nextBackend = await setup.replayBackend.create(host); + + expect(state.engineLoads).toBe(1); + expect(backend.id).toBe('maestro'); + expect( + nextBackend.inspectSource( + 'appId: com.example.app\nname: Checkout\n---\n- launchApp', + '/flow.yaml', + ), + ).toEqual({ title: 'Checkout', appTarget: 'com.example.app' }); + expect(state.retain).toHaveBeenCalledTimes(1); + expect(release).not.toHaveBeenCalled(); + + const reason = { kind: 'worker-exited', detail: 'exit code 1' } as const; + const onUnavailable = sinks[0]; + assert.ok(onUnavailable); + onUnavailable(reason); + expect(host.emitDiagnostic).toHaveBeenCalledExactlyOnceWith({ + level: 'warn', + phase: 'png_worker_unavailable', + data: reason, + }); + + await setup.dispose?.(); + expect(release).toHaveBeenCalledTimes(1); +}); diff --git a/packages/maestro/src/plugin.ts b/packages/maestro/src/plugin.ts new file mode 100644 index 0000000000..f6af5b2c92 --- /dev/null +++ b/packages/maestro/src/plugin.ts @@ -0,0 +1,32 @@ +import type { ReplayEnginePlugin } from 'agent-device/plugins'; + +/** The managed entry is engine-free. Only a selected backend evaluates the implementation. */ +function maestroPlugin(): ReplayEnginePlugin { + return { + apiVersion: 2, + kind: 'replay-backend', + backend: 'maestro', + setup: () => { + let releasePngWorker: (() => Promise) | undefined; + return { + replayBackend: { + create: async (host) => { + const [{ maestroReplayBackendPlugin }, { retainPngWorker }] = await Promise.all([ + import('./replay-backend/replay-maestro-backend.ts'), + import('@agent-device/capture-kit/png-worker-client'), + ]); + releasePngWorker ??= retainPngWorker((reason) => + host.emitDiagnostic({ level: 'warn', phase: 'png_worker_unavailable', data: reason }), + ); + return await maestroReplayBackendPlugin.create(host); + }, + }, + dispose: async () => { + await releasePngWorker?.(); + }, + }; + }, + }; +} + +export { maestroPlugin as default }; diff --git a/packages/maestro/src/replay-backend/__tests__/replay-maestro-backend.test.ts b/packages/maestro/src/replay-backend/__tests__/replay-maestro-backend.test.ts index 68e4237f19..8c2d989b41 100644 --- a/packages/maestro/src/replay-backend/__tests__/replay-maestro-backend.test.ts +++ b/packages/maestro/src/replay-backend/__tests__/replay-maestro-backend.test.ts @@ -7,6 +7,9 @@ import { maestroReplayBackendPlugin } from '../replay-maestro-backend.ts'; // each test the behavior through the registry; what is pinned here is the adapter's own mapping. // None of these capabilities reach host services, so the host is never called. const unusedHost: ReplayBackendHost = { + emitDiagnostic: () => { + throw new Error('host unused'); + }, appendTraceEvent: () => { throw new Error('host unused'); }, @@ -16,6 +19,8 @@ const unusedHost: ReplayBackendHost = { readScriptSourceFile: () => { throw new Error('host unused'); }, + readSnapshotClickabilityEvidence: () => undefined, + assertSnapshotScreenOrigin: () => Promise.reject(new Error('host unused')), scriptSourceRequiredMessage: '', resolveTargetDevice: () => Promise.reject(new Error('host unused')), requestSignal: () => undefined, diff --git a/packages/maestro/src/replay-backend/__tests__/session-replay-maestro-failure.test.ts b/packages/maestro/src/replay-backend/__tests__/session-replay-maestro-failure.test.ts index 6617455911..4987caa3bc 100644 --- a/packages/maestro/src/replay-backend/__tests__/session-replay-maestro-failure.test.ts +++ b/packages/maestro/src/replay-backend/__tests__/session-replay-maestro-failure.test.ts @@ -78,9 +78,12 @@ test('the failure response hands the host the step, its warnings, and its sugges await buildTypedMaestroFailureResponse( { + emitDiagnostic: () => {}, appendTraceEvent: () => {}, buildBuiltinVars: () => ({}), readScriptSourceFile: () => '', + readSnapshotClickabilityEvidence: () => undefined, + assertSnapshotScreenOrigin: () => Promise.reject(new Error('unused')), scriptSourceRequiredMessage: '', resolveTargetDevice: () => Promise.reject(new Error('unused')), requestSignal: () => undefined, diff --git a/packages/maestro/src/replay-backend/replay-maestro-backend.ts b/packages/maestro/src/replay-backend/replay-maestro-backend.ts index f0bc099c1d..6064337116 100644 --- a/packages/maestro/src/replay-backend/replay-maestro-backend.ts +++ b/packages/maestro/src/replay-backend/replay-maestro-backend.ts @@ -44,6 +44,6 @@ function createMaestroReplayBackend(host: ReplayBackendHost): ReplayBackend<'mae }; } -export const maestroReplayBackendPlugin: ReplayBackendPlugin<'maestro'> = { +export const maestroReplayBackendPlugin = { create: createMaestroReplayBackend, -}; +} satisfies ReplayBackendPlugin<'maestro'>; diff --git a/packages/maestro/src/replay-backend/session-replay-maestro-runtime.ts b/packages/maestro/src/replay-backend/session-replay-maestro-runtime.ts index 451576385e..37b5e9fea0 100644 --- a/packages/maestro/src/replay-backend/session-replay-maestro-runtime.ts +++ b/packages/maestro/src/replay-backend/session-replay-maestro-runtime.ts @@ -116,6 +116,7 @@ async function executeTypedMaestroReplay( // for flows that did not arrive over the daemon's remote HTTP surface. const publicNetworkOnly = command.publicNetworkOnly === true; const port = createMaestroReplayPort({ + host, command, device: context.device, platform: context.platform, @@ -334,6 +335,7 @@ function buildTypedMaestroEnv(req: DaemonWireRequest, hostEnv: EnvMap): Record; @@ -349,6 +351,8 @@ function createMaestroReplayPort(params: { ...(command.dispatch ? { dispatch: command.dispatch } : {}), }; return createDaemonMaestroRuntimePort({ + readSnapshotClickabilityEvidence: params.host.readSnapshotClickabilityEvidence, + assertSnapshotScreenOrigin: params.host.assertSnapshotScreenOrigin, invoke: (operation) => invoke(maestroOperationDispatchRequest(replay, operation)), flags: maestroRuntimeDeviceFlags(device, platform, req.flags, publicNetworkOnly), publicNetworkOnly, diff --git a/packages/maestro/test/conformance/differential/flows/optional-scroll-and-wait.yaml b/packages/maestro/test/conformance/differential/flows/optional-scroll-and-wait.yaml index e1c36c7935..60562182cd 100644 --- a/packages/maestro/test/conformance/differential/flows/optional-scroll-and-wait.yaml +++ b/packages/maestro/test/conformance/differential/flows/optional-scroll-and-wait.yaml @@ -16,4 +16,4 @@ appId: com.callstack.agentdevicelab id: this-element-never-exists optional: true timeout: 1000 -- assertVisible: Agent Device Tester +- assertVisible: Home diff --git a/packages/maestro/test/package-artifact.test.mjs b/packages/maestro/test/package-artifact.test.mjs new file mode 100644 index 0000000000..75daa18f60 --- /dev/null +++ b/packages/maestro/test/package-artifact.test.mjs @@ -0,0 +1,57 @@ +import assert from 'node:assert/strict'; +import fs from 'node:fs'; +import os from 'node:os'; +import path from 'node:path'; +import { test } from 'node:test'; +import { run, assertPackagedRunScriptChildren } from './package-test-support.mjs'; + +const root = path.resolve(import.meta.dirname, '../../..'); + +test('packed managed plugin contains its factory and runs real script children without workspace dependencies', async () => { + const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-maestro-artifact-')); + try { + const pluginTarball = path.join(scratch, 'maestro.tgz'); + run('pnpm', ['pack', '--out', pluginTarball], path.join(root, 'packages/maestro')); + const store = path.join(scratch, 'store'); + fs.mkdirSync(store); + fs.writeFileSync(path.join(store, 'package.json'), '{"private":true,"type":"module"}'); + run('npm', ['install', '--ignore-scripts', '--no-audit', '--no-fund', pluginTarball], store); + const plugin = path.join(store, 'node_modules/@agent-device/maestro'); + const manifest = JSON.parse(fs.readFileSync(path.join(plugin, 'package.json'), 'utf8')); + assert.deepEqual(Object.keys(manifest.exports), ['./agent-device']); + assert.equal(manifest.dependencies, undefined); + assert.equal(manifest.peerDependencies, undefined); + assert.ok(!fs.existsSync(path.join(store, 'node_modules/agent-device'))); + for (const entry of [ + 'agent-device.mjs', + 'agent-device.d.mts', + 'png-worker.mjs', + 'run-script-child.mjs', + 'run-script-http-child.mjs', + ]) + assert.ok(fs.existsSync(path.join(plugin, 'dist', entry)), entry); + await assertPackagedRunScriptChildren(plugin, scratch); + run( + process.execPath, + [ + '--experimental-strip-types', + path.join(import.meta.dirname, 'packed-clickability.mjs'), + plugin, + scratch, + ], + root, + ); + run( + process.execPath, + [ + '--experimental-strip-types', + path.join(import.meta.dirname, 'packed-screen-origin.mjs'), + plugin, + scratch, + ], + root, + ); + } finally { + fs.rmSync(scratch, { recursive: true, force: true }); + } +}); diff --git a/packages/maestro/test/package-test-support.mjs b/packages/maestro/test/package-test-support.mjs new file mode 100644 index 0000000000..e88c41f817 --- /dev/null +++ b/packages/maestro/test/package-test-support.mjs @@ -0,0 +1,49 @@ +import { runCmdSync } from '@agent-device/host-kit/command'; +import http from 'node:http'; +import { promisify } from 'node:util'; +import assert from 'node:assert/strict'; +import { execFile } from 'node:child_process'; +import fs from 'node:fs'; +import path from 'node:path'; + +function run(command, args, cwd, env = process.env) { + return runCmdSync(command, args, { + cwd, + env, + timeoutMs: 120_000, + maxBuffer: 16 * 1024 * 1024, + }).stdout; +} +async function assertPackagedRunScriptChildren(plugin, scratch) { + const alias = path.join(scratch, 'plugin-alias'); + fs.symlinkSync(plugin, alias, process.platform === 'win32' ? 'junction' : 'dir'); + const server = http.createServer((_request, response) => + response.end('x'.repeat(2 * 1024 * 1024)), + ); + await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve)); + try { + const scriptPath = path.join(scratch, 'http.js'); + fs.writeFileSync(scriptPath, 'output.size = http.post(SERVER_URL).body.length'); + for (const directory of [plugin, alias]) { + const result = promisify(execFile)( + process.execPath, + [path.join(directory, 'dist/run-script-child.mjs')], + { timeout: 120_000, maxBuffer: 16 * 1024 * 1024 }, + ); + result.child.stdin.end( + JSON.stringify({ + scriptPath, + env: { SERVER_URL: `http://127.0.0.1:${server.address().port}/` }, + publicNetworkOnly: false, + }), + ); + assert.deepEqual(JSON.parse((await result).stdout), { + outputEnv: { 'output.size': String(2 * 1024 * 1024) }, + }); + } + } finally { + await new Promise((resolve) => server.close(resolve)); + } +} + +export { run, assertPackagedRunScriptChildren }; diff --git a/packages/maestro/test/packed-clickability.mjs b/packages/maestro/test/packed-clickability.mjs new file mode 100644 index 0000000000..df66440b27 --- /dev/null +++ b/packages/maestro/test/packed-clickability.mjs @@ -0,0 +1,102 @@ +import assert from 'node:assert/strict'; +import path from 'node:path'; +import { pathToFileURL } from 'node:url'; +import { + parseUiHierarchyTree, + buildUiHierarchySnapshot, +} from '../../platform-android/src/ui-hierarchy.ts'; +import { buildAndroidSnapshotClickabilityEvidence } from '../../platform-android/src/snapshot-clickability.ts'; +import { + createAndroidSnapshotCapture, + androidSnapshotPublicationInput, +} from '../../platform-android/src/snapshot-capture.ts'; +import { readSnapshotClickabilityEvidence } from '../../contracts/src/snapshot-private-evidence.ts'; +import { createReplayBackendHost } from '../../replay-port/src/daemon-port/replay-backend-host.ts'; + +const [plugin, scratch] = process.argv.slice(2); +const { default: maestroPlugin } = await import( + pathToFileURL(path.join(plugin, 'dist/agent-device.mjs')) +); +const target = 'maestro-clickable-first-target'; +const setup = maestroPlugin().setup(); +const host = { + ...createReplayBackendHost(), + resolveTargetDevice: () => { + throw new Error('explicit platform must not discover devices'); + }, + buildActionFailureResponse: (failure) => { + throw new Error(JSON.stringify(failure.error)); + }, +}; +const backend = await setup.replayBackend.create(host); + +try { + for (const indexed of [false, true]) { + let selection = 'none'; + const points = []; + const expectedPoint = indexed ? [20, 20] : [20, 80]; + const expectedSelection = indexed ? 'inert' : 'clickable'; + const entry = path.join(scratch, `clickability-${indexed}.yaml`); + const source = `appId: com.example.app\n---\n- tapOn:\n id: ${target}\n${indexed ? ' index: 0\n' : ''}- assertVisible:\n text: "Maestro selection: ${expectedSelection}"\n`; + const capture = () => { + const xml = ``; + const built = buildUiHierarchySnapshot(parseUiHierarchyTree(xml), undefined, {}); + const { sourceNodes: _sourceNodes, occlusionContext, ...snapshot } = built; + const data = androidSnapshotPublicationInput( + createAndroidSnapshotCapture( + { ...snapshot, createdAt: Date.now(), androidSnapshot: {} }, + { clickability: buildAndroidSnapshotClickabilityEvidence(built), occlusionContext }, + ), + ); + assert.equal(readSnapshotClickabilityEvidence(data)?.kind, 'exact'); + assert.ok(data.nodes.every((node) => !Object.hasOwn(node, 'clickable'))); + return data; + }; + const result = await backend.runReplay({ + request: { + command: 'replay', + positionals: [entry], + flags: { + platform: 'android', + replayBackend: 'maestro', + replayScriptSource: { entry, files: { [entry]: source } }, + }, + }, + host: { env: {}, cwd: scratch }, + session: { + name: 'packed-clickability', + logPath: path.join(scratch, 'clickability.log'), + store: { + get: () => undefined, + lookup: () => undefined, + resolveOpenRuntimeHints: () => undefined, + }, + }, + invoke: async (request) => { + if (request.command === 'snapshot') return { ok: true, data: capture() }; + if (request.command === 'runtime') + return { ok: true, data: { viewport: { x: 0, y: 0, width: 200, height: 200 } } }; + if (request.command === 'click') { + const point = request.positionals.map(Number); + points.push(point); + assert.deepEqual( + point, + expectedPoint, + indexed + ? 'explicit index must retain source order' + : 'no-index Maestro must select the clickable duplicate', + ); + selection = point[1] < 40 ? 'inert' : 'clickable'; + return { ok: true, data: {} }; + } + throw new Error(`unexpected native boundary command: ${request.command}`); + }, + }); + assert.equal(result.ok, true, JSON.stringify(result)); + assert.equal(result.data.replayed, 2); + assert.deepEqual(points, [expectedPoint]); + } + console.log('packed clickability: no-index and explicit-index contracts passed'); +} finally { + await setup.dispose(); +} diff --git a/packages/maestro/test/packed-screen-origin.mjs b/packages/maestro/test/packed-screen-origin.mjs new file mode 100644 index 0000000000..e3b82d68a2 --- /dev/null +++ b/packages/maestro/test/packed-screen-origin.mjs @@ -0,0 +1,108 @@ +import assert from 'node:assert/strict'; +import path from 'node:path'; +import { pathToFileURL } from 'node:url'; +import { createIosSnapshotAcquisition } from '../../capture-kit/src/ios-snapshot-acquisition.ts'; +import { presentIosSnapshotAcquisition } from '../../capture-kit/src/snapshot/ios-snapshot-runtime.ts'; +import { buildSnapshotState } from '../../capture-kit/src/snapshot-state.ts'; +import { createReplayBackendHost } from '../../replay-port/src/daemon-port/replay-backend-host.ts'; + +const [plugin, scratch] = process.argv.slice(2); +const { default: maestroPlugin } = await import( + pathToFileURL(path.join(plugin, 'dist/agent-device.mjs')) +); +const setup = maestroPlugin().setup(); +const backend = await setup.replayBackend.create({ + ...createReplayBackendHost(), + resolveTargetDevice: () => { + throw new Error('explicit platform must not discover devices'); + }, + buildActionFailureResponse: async ({ error }) => ({ ok: false, error }), +}); +const rect = { x: 0, y: 0, width: 390, height: 844 }; + +try { + for (const kind of ['derived', 'missing', 'reported']) { + for (const action of ['tap', 'scroll']) { + let dispatched = false; + const requests = []; + const nodes = [ + { index: 0, type: 'Application', rect }, + { index: 1, parentIndex: 0, type: 'ScrollView', identifier: 'container', rect }, + { + index: 2, + parentIndex: 1, + type: 'Button', + identifier: 'action', + label: 'Action', + rect: { x: 100, y: 100, width: 80, height: 40 }, + }, + ]; + const entry = path.join(scratch, `screen-origin-${kind}-${action}.yaml`); + const source = `appId: com.example.app\n---\n${action === 'tap' ? '- tapOn:\n id: action\n index: 0\n' : '- scrollUntilVisible:\n element: Found\n direction: DOWN\n timeout: 1000\n'}`; + const result = await backend.runReplay({ + request: { + command: 'replay', + positionals: [entry], + flags: { + platform: 'ios', + replayBackend: 'maestro', + replayScriptSource: { entry, files: { [entry]: source } }, + }, + }, + host: { env: {}, cwd: scratch }, + session: { + name: 'packed-screen-origin', + logPath: path.join(scratch, 'screen-origin.log'), + store: { + get: () => undefined, + lookup: () => undefined, + resolveOpenRuntimeHints: () => undefined, + }, + }, + invoke: async (request) => { + requests.push(request); + if (request.command === 'snapshot') { + const acquisition = createIosSnapshotAcquisition({ + producer: 'appium-source', + nodes: dispatched + ? [...nodes, { index: 3, parentIndex: 1, type: 'StaticText', label: 'Found', rect }] + : nodes, + viewport: kind === 'missing' ? { kind, reason: 'not-provided' } : { kind, rect }, + lineage: { targetId: 'ios-origin:com.example.app' }, + }); + return { + ok: true, + data: buildSnapshotState(presentIosSnapshotAcquisition(acquisition, { raw: true }), { + snapshotRaw: true, + }), + }; + } + if (request.command === 'runtime') return { ok: true, data: { viewport: rect } }; + if (request.command === 'click' || request.command === 'gesture') { + dispatched = true; + return { ok: true, data: {} }; + } + throw new Error(`unexpected native boundary command: ${request.command}`); + }, + }); + if (kind === 'reported') { + assert.equal(result.ok, true, JSON.stringify(result)); + assert.equal(result.data.replayed, 1); + assert.equal(dispatched, true, `${action} must dispatch with reported origin`); + const input = requests.find( + ({ command }) => command === (action === 'tap' ? 'click' : 'gesture'), + ); + assert.ok(input); + if (action === 'tap') assert.deepEqual(input.positionals, ['140', '120']); + } else { + assert.equal(dispatched, false, `${kind} ${action} must refuse before input`); + assert.equal(result.ok, false); + assert.equal(result.error.details.reason, 'window-origin-unknown'); + assert.equal(result.error.details.dispatched, 'no'); + } + } + } + console.log('packed screen origin: derived/missing refusal and reported tap/scroll passed'); +} finally { + await setup.dispose(); +} diff --git a/packages/maestro/tsconfig.json b/packages/maestro/tsconfig.json index 6614d7d44e..8c7b3a73e0 100644 --- a/packages/maestro/tsconfig.json +++ b/packages/maestro/tsconfig.json @@ -6,17 +6,34 @@ "emitDeclarationOnly": true, "declaration": true, "declarationDir": "./dist-types", - "rootDir": "./src", - "tsBuildInfoFile": "./dist-types/index.tsbuildinfo" + "rootDir": ".", + "tsBuildInfoFile": "./dist-types/index.tsbuildinfo", + "paths": { + "agent-device/plugins": ["./node_modules/agent-device/src/sdk/plugins.ts"] + } }, "include": ["src"], "references": [ - { "path": "../ad-script" }, - { "path": "../capture-kit" }, - { "path": "../contracts" }, - { "path": "../host-kit" }, - { "path": "../kernel" }, - { "path": "../provision-kit" }, - { "path": "../selectors" } + { + "path": "../ad-script" + }, + { + "path": "../capture-kit" + }, + { + "path": "../contracts" + }, + { + "path": "../host-kit" + }, + { + "path": "../kernel" + }, + { + "path": "../provision-kit" + }, + { + "path": "../selectors" + } ] } diff --git a/packages/maestro/tsdown.config.ts b/packages/maestro/tsdown.config.ts new file mode 100644 index 0000000000..d1d1807d28 --- /dev/null +++ b/packages/maestro/tsdown.config.ts @@ -0,0 +1,29 @@ +import { defineConfig } from 'tsdown'; + +export default defineConfig({ + entry: { + 'agent-device': 'src/plugin.ts', + 'png-worker': '../capture-kit/src/png-worker.ts', + 'run-script-child': 'src/daemon-port/run-script-child.ts', + 'run-script-http-child': 'src/daemon-port/run-script-http-child.ts', + }, + outDir: 'dist', + tsconfig: '../../tsconfig.lib.json', + format: 'esm', + platform: 'node', + target: 'es2022', + minify: true, + dts: true, + hash: false, + deps: { + neverBundle: ['agent-device/plugins'], + alwaysBundle: [/^@agent-device\//], + onlyBundle: ['yaml', 'undici', 'ipaddr.js', 'pngjs', 'jpeg-js'], + }, + inputOptions: { + onLog(level, log, handler) { + if (log.code === 'UNRESOLVED_IMPORT') throw new Error(log.message); + handler(level, log); + }, + }, +}); diff --git a/packages/platform-android/src/manifest.ts b/packages/platform-android/src/manifest.ts index a07e21468b..ffeb25a94c 100644 --- a/packages/platform-android/src/manifest.ts +++ b/packages/platform-android/src/manifest.ts @@ -24,28 +24,30 @@ const TYPE_STRING = 0x03; const NO_INDEX = 0xffffffff; const utf16Decoder = new TextDecoder('utf-16le'); -let aaptPathCache: string | null | undefined; export async function resolveAndroidArchivePackageName( archivePath: string, signal?: AbortSignal, + cwd?: string, ): Promise { for (const entry of ['AndroidManifest.xml', 'base/manifest/AndroidManifest.xml']) { - const manifest = await readZipEntry(archivePath, entry, signal); + const manifest = await readZipEntry(archivePath, entry, signal, cwd); if (!manifest) continue; const packageName = parseAndroidManifestPackageName(manifest); if (packageName) return packageName; } - return await resolveAndroidArchivePackageNameWithAapt(archivePath, signal); + return await resolveAndroidArchivePackageNameWithAapt(archivePath, signal, cwd); } async function readZipEntry( archivePath: string, entry: string, signal?: AbortSignal, + cwd?: string, ): Promise { try { const result = await runCmd('unzip', ['-p', archivePath, entry], { + cwd, allowFailure: true, binaryStdout: true, timeoutMs: ARCHIVE_INSPECTION_TIMEOUT_MS, @@ -324,11 +326,13 @@ function readUtf16Length(chunk: Buffer, offset: number): PoolLength | undefined async function resolveAndroidArchivePackageNameWithAapt( archivePath: string, signal?: AbortSignal, + cwd?: string, ): Promise { signal?.throwIfAborted(); const aaptPath = await resolveAaptPath(); if (!aaptPath) return undefined; const result = await runCmd(aaptPath, ['dump', 'badging', archivePath], { + cwd, allowFailure: true, timeoutMs: ARCHIVE_INSPECTION_TIMEOUT_MS, signal, @@ -339,10 +343,6 @@ async function resolveAndroidArchivePackageNameWithAapt( } async function resolveAaptPath(): Promise { - if (aaptPathCache !== undefined) { - return aaptPathCache ?? undefined; - } - try { const files = requireAndroidAdbHost().files; const { hostPlatform } = await import('@agent-device/host-kit/process'); @@ -357,7 +357,6 @@ async function resolveAaptPath(): Promise { const candidate = path.join(buildToolsDir, version, 'aapt'); // SDK roots can come from env vars; reject relative roots before returning an executable. if (path.isAbsolute(candidate) && (await files.isExecutable(candidate))) { - aaptPathCache = candidate; return candidate; } } @@ -369,6 +368,5 @@ async function resolveAaptPath(): Promise { // Ignore SDK lookup failures and fall back to undefined. } - aaptPathCache = null; return undefined; } diff --git a/packages/plugins/package.json b/packages/plugins/package.json index 319a6e2fb0..5bbe4534db 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" @@ -45,6 +41,10 @@ "./credential-fingerprint": { "types": "./src/credential-fingerprint.ts", "default": "./src/credential-fingerprint.ts" + }, + "./replay-backend": { + "types": "./src/replay-backend.ts", + "default": "./src/replay-backend.ts" } }, "devDependencies": { 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..31ea661dd9 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..b44c4ef0c3 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. + */ +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..00acf6328f 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` 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; - /** 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/replay-backend.ts b/packages/plugins/src/replay-backend.ts new file mode 100644 index 0000000000..55944fe4fc --- /dev/null +++ b/packages/plugins/src/replay-backend.ts @@ -0,0 +1,15 @@ +import type { ReplayBackendPlugin } from '@agent-device/contracts/replay-backend'; +import type { ProviderPluginHost } from './host.ts'; + +/** A managed v2 replay engine. The host retains sessions, dispatch, cancellation and cleanup. */ +export type ReplayEnginePlugin = Readonly<{ + apiVersion: 2; + kind: 'replay-backend'; + backend: string; + setup(host: ProviderPluginHost): Promise | ReplayEngineSetup; +}>; + +export type ReplayEngineSetup = Readonly<{ + replayBackend: ReplayBackendPlugin; + dispose?(): Promise | void; +}>; 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..6e30bbcf85 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 dormant built-in claims the id first, so a store package cannot take it either. + const { home: otherHome, env: otherEnv } = pluginHome(); + selectV2Plugin(otherHome, 'limrun-plugin', v2RegistrationSource('limrun')); + const limrun = await listPlugins(otherEnv, ['limrun']); + assert.deepEqual( + limrun.map(({ name, compatible, error }) => [name, compatible, error?.reason]), + [['limrun-plugin', false, 'duplicate_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..8faf7ec77b 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); +} + +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,16 @@ async function stagePlugin( } } +/** + * 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, input: string, env: NodeJS.ProcessEnv, - reservedProviders: readonly string[], ): Promise { const { name, version } = parsePluginRequest(action, input); const configPath = resolveUserConfigPath(env); @@ -234,13 +273,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 +291,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..a17e04067a 100644 --- a/packages/provider-revyl/package.json +++ b/packages/provider-revyl/package.json @@ -1,6 +1,6 @@ { "name": "@agent-device/revyl", - "version": "0.21.38-dev", + "version": "0.22.0-dev", "type": "module", "description": "Revyl cloud iOS simulator and Android emulator plugin for agent-device.", "files": [ @@ -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..5a9a740597 100644 --- a/packages/provider-testmu/package.json +++ b/packages/provider-testmu/package.json @@ -1,6 +1,6 @@ { "name": "@agent-device/testmu", - "version": "0.21.38-dev", + "version": "0.22.0-dev", "type": "module", "description": "TestMu AI real and virtual mobile device plugin for agent-device.", "files": [ @@ -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-tizen/package.json b/packages/provider-tizen/package.json index 11ac6c0ecd..83691ebebd 100644 --- a/packages/provider-tizen/package.json +++ b/packages/provider-tizen/package.json @@ -1,6 +1,6 @@ { "name": "@agent-device/tizen", - "version": "0.21.38-dev", + "version": "0.22.0-dev", "type": "module", "description": "Samsung Tizen TV web app plugin for agent-device.", "files": [ 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/provider-webos/package.json b/packages/provider-webos/package.json index c64cb7da72..b00eea3445 100644 --- a/packages/provider-webos/package.json +++ b/packages/provider-webos/package.json @@ -1,6 +1,6 @@ { "name": "@agent-device/webos", - "version": "0.21.38-dev", + "version": "0.22.0-dev", "type": "module", "description": "LG webOS TV web app plugin for agent-device.", "files": [ diff --git a/packages/proxy/package.json b/packages/proxy/package.json index b0cfee808e..2652debc04 100644 --- a/packages/proxy/package.json +++ b/packages/proxy/package.json @@ -1,6 +1,6 @@ { "name": "@agent-device/proxy", - "version": "0.21.38-dev", + "version": "0.22.0-dev", "type": "module", "description": "Transport-neutral authenticating proxy in front of an agent-device daemon.", "license": "MIT", diff --git a/packages/remote/src/remote-config-core.ts b/packages/remote/src/remote-config-core.ts index f5913ebb6c..38a1bc518d 100644 --- a/packages/remote/src/remote-config-core.ts +++ b/packages/remote/src/remote-config-core.ts @@ -5,19 +5,13 @@ import { getRemoteConfigEnvNames, getRemoteConfigFieldSpec, type RemoteConfigProfile, + type RemoteConfigProfileOptions, type ResolvedRemoteConfigProfile, } from './remote-config-schema.ts'; import { AppError } from '@agent-device/kernel/errors'; import { resolveUserPath } from '@agent-device/host-kit/file'; import { parseSourceValue, type EnvMap } from '@agent-device/kernel/source-value'; -/** The remote-config location and the host environment it resolves against. */ -export type HostRemoteConfigProfileOptions = { - configPath: string; - cwd: string; - env: EnvMap; -}; - // Deliberately narrower than `resolveRemoteConfigProfile`: this reads only // what the config *file itself* declares, with no ambient environment // defaults merged in. Callers that need to know a credential provably @@ -25,7 +19,7 @@ export type HostRemoteConfigProfileOptions = { // somewhere") must use this, not the env-merged resolver, or provenance is // lost — an env var is global and cannot say which endpoint it belongs to. export function readRemoteConfigFile( - options: HostRemoteConfigProfileOptions, + options: RemoteConfigProfileOptions, ): ResolvedRemoteConfigProfile { const { env } = options; const resolvedPath = resolveRemoteConfigPath(options); @@ -117,13 +111,13 @@ function mergeRemoteConfigProfile( return merged; } -export function resolveRemoteConfigPath(options: HostRemoteConfigProfileOptions): string { +export function resolveRemoteConfigPath(options: RemoteConfigProfileOptions): string { const { env } = options; return resolveUserPath(options.configPath, { cwd: options.cwd, env }); } export function resolveRemoteConfigProfile( - options: HostRemoteConfigProfileOptions, + options: RemoteConfigProfileOptions, ): ResolvedRemoteConfigProfile { const loaded = readRemoteConfigFile(options); return { diff --git a/packages/remote/src/remote-config-schema.ts b/packages/remote/src/remote-config-schema.ts index 517a0931d2..b11fecc44b 100644 --- a/packages/remote/src/remote-config-schema.ts +++ b/packages/remote/src/remote-config-schema.ts @@ -13,7 +13,7 @@ import { PLATFORM_SELECTORS } from '@agent-device/kernel/device'; export type RemoteConfigProfileOptions = { configPath: string; cwd: string; - env?: Record; + env: Record; }; export type ResolvedRemoteConfigProfile = { diff --git a/packages/remote/src/remote-connection-state.ts b/packages/remote/src/remote-connection-state.ts index 93ffa02f48..be0875dbf8 100644 --- a/packages/remote/src/remote-connection-state.ts +++ b/packages/remote/src/remote-connection-state.ts @@ -30,6 +30,7 @@ import { leaseScopeToCommandFlags, leaseScopeToConnectionMetadata, parseLeaseDeviceKey, + remoteSessionRequiredError, } from '@agent-device/contracts/lease-scope'; export type RemoteConnectionState = { @@ -453,19 +454,6 @@ export function requireLeasedConnectionSession( throw remoteSessionRequiredError(connection.leaseProvider); } -/** The refusal for a command on a leased connection that names no session. */ -export function remoteSessionRequiredError(leaseProvider: string | undefined): AppError { - return new AppError( - 'INVALID_ARGS', - 'A leased remote connection needs its session named: pass --session or set AGENT_DEVICE_SESSION.', - { - reason: 'REMOTE_SESSION_REQUIRED', - ...(leaseProvider === undefined ? {} : { leaseProvider }), - hint: "Without a name, a command could reach another agent's connection on this machine.", - }, - ); -} - function isLeasedConnection(connection: Pick): boolean { return connection.leaseProvider !== undefined; } diff --git a/packages/replay-port/src/daemon-port/replay-backend-host.ts b/packages/replay-port/src/daemon-port/replay-backend-host.ts index 2d9e6aa1e0..67c0ae8ce7 100644 --- a/packages/replay-port/src/daemon-port/replay-backend-host.ts +++ b/packages/replay-port/src/daemon-port/replay-backend-host.ts @@ -1,4 +1,9 @@ +import { emitDiagnostic } from '@agent-device/host-kit/diagnostics'; import type { ReplayBackendHost } from '@agent-device/contracts/replay-backend'; +import { + assertSnapshotScreenOrigin, + readSnapshotClickabilityEvidence, +} from '@agent-device/contracts/capture'; import { resolveTargetDevice } from '@agent-device/device-selection/dispatch-resolve'; import { getRequestSignal } from '@agent-device/host-kit/request'; import { buildReplayBuiltinVars } from '../session-replay-vars.ts'; @@ -16,6 +21,9 @@ import { appendReplayTraceEvent } from './session-replay-trace.ts'; */ export function createReplayBackendHost(): ReplayBackendHost { return { + emitDiagnostic, + readSnapshotClickabilityEvidence, + assertSnapshotScreenOrigin, appendTraceEvent: appendReplayTraceEvent, buildBuiltinVars: (params) => buildReplayBuiltinVars({ ...params, metadata: {} }), readScriptSourceFile: readReplayScriptSourceFile, 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/pnpm-lock.yaml b/pnpm-lock.yaml index a899704bfe..e50157475c 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -682,7 +682,7 @@ importers: packages/kernel: {} packages/maestro: - dependencies: + devDependencies: '@agent-device/ad-script': specifier: workspace:* version: link:../ad-script @@ -704,7 +704,9 @@ importers: '@agent-device/selectors': specifier: workspace:* version: link:../selectors - devDependencies: + agent-device: + specifier: workspace:* + version: link:../.. undici: specifier: 7.30.1 version: 7.30.1 diff --git a/scripts/check-affected/device-lanes.test.ts b/scripts/check-affected/device-lanes.test.ts index 72452fa6ba..6ae88a0299 100644 --- a/scripts/check-affected/device-lanes.test.ts +++ b/scripts/check-affected/device-lanes.test.ts @@ -143,10 +143,15 @@ test('unit tests under src/ and packages/*/src own no lane', () => { const imeFixture = 'packages/platform-android/src/fixtures/android-ime-capture.raw.json'; assert.ok(fs.existsSync(imeFixture), imeFixture); assert.ok(!isUnitTest(imeFixture)); - // Package tests outside src/ have no owner and keep failing open. assert.ok(!isUnitTest('packages/maestro/test/conformance/verify.test.ts')); + const conformance = selectChecks({ + changedFiles: ['packages/maestro/test/conformance/verify.test.ts'], + }); + assert.equal(conformance.failOpen, false); + assert.ok(conformance.checks.includes('maestro-conformance')); + assert.ok(conformance.checks.includes('maestro-differential')); assert.equal( - selectChecks({ changedFiles: ['packages/maestro/test/conformance/verify.test.ts'] }).failOpen, + selectChecks({ changedFiles: ['packages/unknown/test/unowned.test.ts'] }).failOpen, true, ); }); diff --git a/scripts/check-affected/model.test.ts b/scripts/check-affected/model.test.ts index 46aee98647..99a08602c5 100644 --- a/scripts/check-affected/model.test.ts +++ b/scripts/check-affected/model.test.ts @@ -552,3 +552,18 @@ test('every configured scan root selects native duplication regardless of extens assert.ok(ids([file]).includes('native-dupes-model'), file); } }); + +test('managed engine and loading changes retain every Maestro oracle lane', () => { + for (const file of [ + 'packages/maestro/src/plugin.ts', + 'packages/plugins/src/registry.ts', + 'packages/plugins/src/replay-backend.ts', + 'packages/plugins/src/store.ts', + 'packages/plugins/src/validate.ts', + 'packages/replay-port/src/daemon-port/replay-backend-registry.ts', + ]) { + const result = plan([file]); + assert.ok(result.checks.includes('maestro-conformance'), file); + assert.ok(result.checks.includes('maestro-differential'), file); + } +}); diff --git a/scripts/check-affected/model.ts b/scripts/check-affected/model.ts index 3a2aa8494c..e8dc9a4196 100644 --- a/scripts/check-affected/model.ts +++ b/scripts/check-affected/model.ts @@ -262,6 +262,26 @@ const vitestRelatedOwnership: OwnershipRule = ({ file, isTs, underSrc, underTest // claimed its resolver could not follow workspace specifiers, which stopped // being true (it resolves @agent-device/* through each exports map), so an // extraction into packages/ no longer takes its own dead code out of scope. +const replayBackendOwnership: OwnershipRule = ({ file }) => + file.startsWith('packages/maestro/') || + file.startsWith('packages/replay-port/') || + /^packages\/plugins\/src\/(?:registry|replay-backend|store|discovery|validate)\./.test(file) + ? [ + reason( + 'maestro-conformance', + file, + 'own:replay-backend-conformance', + 'managed replay backends retain the generated conformance oracle', + ), + reason( + 'maestro-differential', + file, + 'own:replay-backend-differential', + 'installed replay backends retain live outcome and timing invariants', + ), + ] + : []; + const workspacePackageOwnership: OwnershipRule = ({ file, isTs }) => { if (!isTs || !/^packages\/[^/]+\/src\//.test(file)) return []; const selections = [ @@ -689,6 +709,7 @@ const OWNERSHIP_RULES: readonly OwnershipRule[] = [ macosCoverageOwnership, testAppOwnership, replayCompatOwnership, + replayBackendOwnership, daemonWireCompatOwnership, buildOwnership, nativeDupesOwnership, diff --git a/scripts/gate/workflows.test.ts b/scripts/gate/workflows.test.ts index fad6ac94d0..e85cca71c1 100644 --- a/scripts/gate/workflows.test.ts +++ b/scripts/gate/workflows.test.ts @@ -68,9 +68,13 @@ function planted(files: Record): ReturnType { } test('a command repeating a script body verbatim credits that script', () => { - const body = model.scripts['check:package'] as string; - assert.deepEqual(verbatimScripts(body, model.scripts), ['check:package']); - assert.deepEqual(verbatimScripts('node scripts/something-else.ts', model.scripts), []); + const scripts = { + verify: 'node scripts/verify.ts', + combined: 'node scripts/verify.ts && node scripts/other.ts', + }; + assert.deepEqual(verbatimScripts(scripts.verify, scripts), ['verify']); + assert.deepEqual(verbatimScripts(scripts.combined, scripts), ['verify']); + assert.deepEqual(verbatimScripts('node scripts/something-else.ts', scripts), []); }); test('path filters use GitHub glob semantics', () => { diff --git a/scripts/layering/package-boundaries-dev-dependencies.test.ts b/scripts/layering/package-boundaries-dev-dependencies.test.ts index 7d0ff537ef..e79d816846 100644 --- a/scripts/layering/package-boundaries-dev-dependencies.test.ts +++ b/scripts/layering/package-boundaries-dev-dependencies.test.ts @@ -101,3 +101,16 @@ test('a published package keeps its siblings in devDependencies for every file', assert.deepEqual(violations(published, file), [], file); } }); + +test('a private publication placeholder keeps bundled dependencies in the publication field', () => { + const staged = { + ...DEV_ONLY, + publishConfig: { exports: { './agent-device': { import: './dist/plugin.mjs' } } }, + }; + assert.deepEqual(violations(staged, 'packages/owner/src/thing.ts'), []); + assert.equal( + violations({ ...staged, devDependencies: {} }, 'packages/owner/src/thing.ts').length, + 1, + ); + assert.equal(violations(DEV_ONLY, 'packages/owner/src/thing.ts').length, 1); +}); diff --git a/scripts/layering/package-boundaries.test.ts b/scripts/layering/package-boundaries.test.ts index cee6d6dc56..063267faaf 100644 --- a/scripts/layering/package-boundaries.test.ts +++ b/scripts/layering/package-boundaries.test.ts @@ -675,11 +675,10 @@ test('the real tree parses, declares, and passes R11', () => { ]); const maestroPackage = packages.find((pkg) => pkg.name === '@agent-device/maestro'); assert.ok(maestroPackage, 'maestro package must exist'); - // Locks the export surface: `.` (the engine), the replay backend plugin (#3377) with its - // engine-free declaration, and the runScript HTTP helper. The eager-closure budget gate - // (scripts/__tests__/eager-closure-budgets.test.ts) is what keeps the plugin off `.`. + // Source test facades stay private to the workspace; package smoke pins the published host entry. assert.deepEqual([...maestroPackage.exportTargets.keys()].sort(), [ '@agent-device/maestro', + '@agent-device/maestro/agent-device', '@agent-device/maestro/replay-backend', '@agent-device/maestro/replay-backend-declaration', '@agent-device/maestro/run-script-http', @@ -692,6 +691,7 @@ test('the real tree parses, declares, and passes R11', () => { '@agent-device/kernel', '@agent-device/provision-kit', '@agent-device/selectors', + 'agent-device', ]); const adScriptPackage = packages.find((pkg) => pkg.name === '@agent-device/ad-script'); assert.ok(adScriptPackage, 'ad-script package must exist'); diff --git a/scripts/layering/package-boundaries.ts b/scripts/layering/package-boundaries.ts index 0b4a70f31d..b19d1dbc57 100644 --- a/scripts/layering/package-boundaries.ts +++ b/scripts/layering/package-boundaries.ts @@ -147,6 +147,7 @@ export function workspacePackagesFromManifests( const manifest = JSON.parse(manifests.get(manifestFile)!) as { name?: string; private?: boolean; + publishConfig?: { exports?: unknown }; exports?: | string | Record; @@ -179,14 +180,16 @@ export function workspacePackagesFromManifests( ), ), ); - const workspaceDependencyField = manifest.private === true ? 'dependencies' : 'devDependencies'; + const bundledForPublication = + manifest.private !== true || manifest.publishConfig?.exports !== undefined; + const workspaceDependencyField = bundledForPublication ? 'devDependencies' : 'dependencies'; const workspaceDependencies = new Set( Object.entries(manifest[workspaceDependencyField] ?? {}) .filter(([, range]) => range.startsWith('workspace:')) .map(([name]) => name), ); const workspaceDevDependencies = new Set( - manifest.private === true + !bundledForPublication ? Object.entries(manifest.devDependencies ?? {}) .filter(([, range]) => range.startsWith('workspace:')) .map(([name]) => name) diff --git a/scripts/layering/process-globals-policy.test.ts b/scripts/layering/process-globals-policy.test.ts index 2b416afc6e..374caf2415 100644 --- a/scripts/layering/process-globals-policy.test.ts +++ b/scripts/layering/process-globals-policy.test.ts @@ -61,8 +61,6 @@ test('entry declarations permit process reads but do not permit ambient command- 'packages/capture-kit/src/png-worker.ts', 'packages/maestro/src/daemon-port/run-script-http-child.ts', 'packages/react-native/src/companion/client-companion-tunnel-worker.ts', - 'src/sdk/host.ts', - 'packages/host-kit/src/local-artifact-adapter.ts', ]) { assert.deepEqual(check('process.env; process.on("SIGINT", stop);', file), [], file); assert.equal(check('commandHostEnvironment();', file).length, 1, file); @@ -124,11 +122,16 @@ test('bare process values are captures in calls, aliases, spreads, returns and c "import * as p from 'node:process'; captureHostEnvironment(p.default);", ]) { assert.equal(check(source).length, 1, source); - assert.deepEqual(check(source, 'src/sdk/host.ts'), [], source); + assert.equal(check(source, 'src/sdk/host.ts').length, 1, source); + assert.equal( + check(source, 'packages/host-kit/src/local-artifact-adapter.ts').length, + 1, + source, + ); } }); -test('SDK adapters capture their default host only through the shared entry', () => { +test('SDK adapters cannot capture a process host', () => { for (const file of [ 'src/sdk/android-adb.ts', 'src/sdk/artifacts.ts', diff --git a/scripts/layering/process-globals-policy.ts b/scripts/layering/process-globals-policy.ts index e42b332759..8c8663b6b6 100644 --- a/scripts/layering/process-globals-policy.ts +++ b/scripts/layering/process-globals-policy.ts @@ -17,9 +17,6 @@ const PROCESS_ENTRIES = new Set([ 'packages/react-native/src/companion/client-companion-tunnel-worker.ts', 'packages/maestro/src/daemon-port/run-script-child.ts', 'packages/maestro/src/daemon-port/run-script-http-child.ts', - // Released SDK defaults; #3759 removes these captures in 0.22. - 'packages/host-kit/src/local-artifact-adapter.ts', - 'src/sdk/host.ts', 'src/mcp/command-tools.ts', 'packages/daemon-client/src/index.ts', 'packages/daemon-client/src/daemon-client-ensure.ts', diff --git a/scripts/release-workspace.mjs b/scripts/release-workspace.mjs index d526775a92..23659ead61 100644 --- a/scripts/release-workspace.mjs +++ b/scripts/release-workspace.mjs @@ -69,7 +69,11 @@ 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. 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']) { checkDependencyField(field, packed[field] ?? {}, unpublishableNames); } diff --git a/server.json b/server.json index dabbfd3e6f..abc83af3db 100644 --- a/server.json +++ b/server.json @@ -7,12 +7,12 @@ "url": "https://github.com/callstack/agent-device", "source": "github" }, - "version": "0.21.38-dev", + "version": "0.22.0-dev", "packages": [ { "registryType": "npm", "identifier": "agent-device", - "version": "0.21.38-dev", + "version": "0.22.0-dev", "transport": { "type": "stdio" }, diff --git a/src/__tests__/cli-leased-session.test.ts b/src/__tests__/cli-leased-session.test.ts index f0b8f22c43..526a8ab1aa 100644 --- a/src/__tests__/cli-leased-session.test.ts +++ b/src/__tests__/cli-leased-session.test.ts @@ -146,6 +146,7 @@ async function leaseIdsOnRealDaemon(allocations: CapturedDaemonRequest[]): Promi daemonBaseUrl: daemon.baseUrl, daemonAuthToken: daemon.runtime.token, daemonTransport: 'http', + session: 'lease-reader', }); const leaseIds = []; for (const allocate of allocations) { @@ -164,6 +165,40 @@ async function leaseIdsOnRealDaemon(allocations: CapturedDaemonRequest[]): Promi } } +test('the Node client is refused a provider lease until it names a session', async () => { + const daemon = await startPublicDaemonRuntime({ serverMode: 'http' }); + const connection = { + daemonBaseUrl: daemon.baseUrl, + daemonAuthToken: daemon.runtime.token, + daemonTransport: 'http', + } as const; + const lease = { + tenant: 'acme', + runId: 'run-a', + leaseBackend: 'android-instance', + leaseProvider: 'proxy', + clientId: 'client-a', + } as const; + try { + await assert.rejects( + createAgentDeviceClient(connection).leases.allocate(lease), + (error: { details?: { reason?: string } }) => + error.details?.reason === 'REMOTE_SESSION_REQUIRED', + ); + + const named = createAgentDeviceClient({ ...connection, session: 'agent-a' }); + const leaseId = (await named.leases.allocate(lease)).leaseId; + assert.ok(leaseId); + const namedPerCall = await createAgentDeviceClient(connection).leases.allocate({ + ...lease, + session: 'agent-a', + }); + assert.equal(namedPerCall.leaseId, leaseId); + } finally { + await daemon.close(); + } +}); + function allocationOf(result: Awaited>): CapturedDaemonRequest { const allocate = result.calls.find((call) => call.command === 'lease_allocate'); assert.ok(allocate, result.stdout); @@ -302,6 +337,7 @@ test('a session named by flag, env or config never falls back onto the pointer', result.calls.map((call) => call.command), ['snapshot'], ); + assert.equal(result.calls[0]?.meta?.sessionExplicit, true); assert.equal(scopeOf(result.calls[0]!, 'tenantId'), undefined); assert.equal(leaseIdOf(result.calls[0]), undefined); } diff --git a/src/__tests__/cli-maestro-suite.test.ts b/src/__tests__/cli-maestro-suite.test.ts new file mode 100644 index 0000000000..542a33fa6e --- /dev/null +++ b/src/__tests__/cli-maestro-suite.test.ts @@ -0,0 +1,46 @@ +import { test } from 'vitest'; +import assert from 'node:assert/strict'; +import { promises as fs } from 'node:fs'; +import path from 'node:path'; +import { runCliCapture } from './cli-capture.ts'; +import { mkdtempForTest } from '@agent-device/test-kit'; + +test('test --maestro forwards Maestro backend and platform for directory suites', async () => { + const tmpDir = await mkdtempForTest('agent-device-cli-maestro-suite-'); + await fs.writeFile( + path.join(tmpDir, 'auth-flow.yml'), + ['appId: demo.app', '---', '- launchApp', ''].join('\n'), + ); + + try { + const result = await runCliCapture( + ['test', '--maestro', '--platform', 'android', tmpDir], + async () => ({ + ok: true, + data: { + total: 1, + executed: 1, + passed: 1, + failed: 0, + skipped: 0, + notRun: 0, + durationMs: 5, + failures: [], + tests: [], + }, + }), + { cwd: tmpDir }, + ); + + assert.equal(result.code, null); + assert.equal(result.calls.length, 1); + assert.equal(result.calls[0]?.command, 'test'); + assert.deepEqual(result.calls[0]?.positionals, [tmpDir]); + assert.equal(result.calls[0]?.flags?.replayBackend, 'maestro'); + assert.equal(result.calls[0]?.flags?.platform, 'android'); + assert.equal(result.calls[0]?.meta?.requestProgress, 'replay-test'); + assert.doesNotMatch(result.stderr, /Running replay suite\.\.\./); + } finally { + await fs.rm(tmpDir, { recursive: true, force: true }); + } +}); diff --git a/src/__tests__/cli-network.test.ts b/src/__tests__/cli-network.test.ts index af178c0772..8b93f0344d 100644 --- a/src/__tests__/cli-network.test.ts +++ b/src/__tests__/cli-network.test.ts @@ -703,45 +703,6 @@ test('test command --debug prints failed attempt step window when timing trace e } }); -test('test --maestro forwards Maestro backend and platform for directory suites', async () => { - const tmpDir = await mkdtempForTest('agent-device-cli-maestro-suite-'); - await fs.writeFile( - path.join(tmpDir, 'auth-flow.yml'), - ['appId: demo.app', '---', '- launchApp', ''].join('\n'), - ); - - try { - const result = await runTestSuiteCli( - ['test', '--maestro', '--platform', 'android', tmpDir], - async () => ({ - ok: true, - data: { - total: 1, - executed: 1, - passed: 1, - failed: 0, - skipped: 0, - notRun: 0, - durationMs: 5, - failures: [], - tests: [], - }, - }), - ); - - assert.equal(result.code, null); - assert.equal(result.calls.length, 1); - assert.equal(result.calls[0]?.command, 'test'); - assert.deepEqual(result.calls[0]?.positionals, [tmpDir]); - assert.equal(result.calls[0]?.flags?.replayBackend, 'maestro'); - assert.equal(result.calls[0]?.flags?.platform, 'android'); - assert.equal(result.calls[0]?.meta?.requestProgress, 'replay-test'); - assert.doesNotMatch(result.stderr, /Running replay suite\.\.\./); - } finally { - await fs.rm(tmpDir, { recursive: true, force: true }); - } -}); - test('test forwards shard flags and comma device lists', async () => { const result = await runTestSuiteCli( ['test', '--maestro', '--device', 'udid1,emulator-5554', '--shard-all', '2', './suite'], 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__/daemon-composition/snapshot-presentation-transitions.test.ts b/src/__tests__/daemon-composition/snapshot-presentation-transitions.test.ts index abe7231e1b..728291c636 100644 --- a/src/__tests__/daemon-composition/snapshot-presentation-transitions.test.ts +++ b/src/__tests__/daemon-composition/snapshot-presentation-transitions.test.ts @@ -68,7 +68,7 @@ test('promoted navigation title dispatches as its presented button semantics, no tappedPoint = point; }, }, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), policy: localCommandPolicy(), }); await device.sessions.set({ name: 'default', snapshot }); diff --git a/src/__tests__/lease-provider-profile-fields.test.ts b/src/__tests__/lease-provider-profile-fields.test.ts index 7733211aef..dd07a710d8 100644 --- a/src/__tests__/lease-provider-profile-fields.test.ts +++ b/src/__tests__/lease-provider-profile-fields.test.ts @@ -38,6 +38,7 @@ test('leases.allocate refuses an OS version Limrun cannot honour instead of igno daemonBaseUrl: daemon.baseUrl, daemonAuthToken: daemon.runtime.token, daemonTransport: 'http', + session: 'agent-a', }); await assert.rejects( client.leases.allocate({ diff --git a/src/__tests__/limrun-runtime.test.ts b/src/__tests__/limrun-runtime.test.ts index 8e8d4c9a5c..57312584cc 100644 --- a/src/__tests__/limrun-runtime.test.ts +++ b/src/__tests__/limrun-runtime.test.ts @@ -5,14 +5,18 @@ import { afterEach, expect, test, vi } from 'vitest'; import type { ClientOptions } from '@limrun/api'; import { createInstanceClient as createAndroidInstanceClient } from '@limrun/api/instance-client'; import { createInstanceClient as createIosInstanceClient } from '@limrun/api/ios-client'; -import { LimrunRuntime } from '../sdk/limrun.ts'; +import { LimrunRuntime, type LimrunRuntimeOptions } from '../sdk/limrun.ts'; import type { DeviceLease } from '@agent-device/contracts/device'; import type { DeviceInfo } from '@agent-device/kernel/device'; import { AppError } from '@agent-device/kernel/errors'; -import { runCmd } from '@agent-device/host-kit/command'; +import { commandHostEnvironment, withCommandHost, runCmd } from '@agent-device/host-kit/command'; import { readVersion } from '@agent-device/host-kit/version'; import { mkdtempForTestSync } from '@agent-device/test-kit'; +function createTestRuntime(options: LimrunRuntimeOptions): LimrunRuntime { + return new LimrunRuntime(options, { env: process.env, cwd: process.cwd() }); +} + type LimrunInstancePage = { getPaginatedItems: () => Array<{ metadata: { id: string } }>; }; @@ -147,7 +151,7 @@ afterEach(() => { }); test('Limrun runtime identifies direct CLI usage when creating an instance', async () => { - const runtime = new LimrunRuntime({ + const runtime = createTestRuntime({ apiKey: 'lim_test_key', }); @@ -193,7 +197,7 @@ test('Limrun runtime identifies direct CLI usage when creating an instance', asy }); test('Limrun refuses a refused field on a repeat allocation of its live lease', async () => { - const runtime = new LimrunRuntime({ apiKey: 'lim_test_key' }); + const runtime = createTestRuntime({ apiKey: 'lim_test_key' }); const lease: DeviceLease = { leaseId: 'lease-repeat', tenantId: 'team-a', @@ -222,7 +226,7 @@ test('Limrun refuses a refused field on a repeat allocation of its live lease', }); test('Limrun iOS uses shared deep-link classification', async () => { - const runtime = new LimrunRuntime({ apiKey: 'lim_test_key' }); + const runtime = createTestRuntime({ apiKey: 'lim_test_key' }); const metadata = new Map([ ['com.apple.Preferences', ''], [ @@ -281,7 +285,7 @@ test('Limrun iOS uses shared deep-link classification', async () => { }); test('Limrun reclaims a labeled iOS instance without an in-memory session', async () => { - const runtime = new LimrunRuntime({ apiKey: 'lim_test_key' }); + const runtime = createTestRuntime({ apiKey: 'lim_test_key' }); const lease: DeviceLease = { leaseId: 'lease-recovered-ios', tenantId: 'team-a', @@ -313,7 +317,7 @@ test('Limrun reclaims a labeled iOS instance without an in-memory session', asyn }); test('Limrun Android reverses localhost URL ports through the persistent ADB tunnel', async () => { - const runtime = new LimrunRuntime({ + const runtime = createTestRuntime({ apiKey: 'lim_test_key', }); @@ -340,7 +344,7 @@ test('Limrun Android reverses localhost URL ports through the persistent ADB tun test('Limrun keepAlive pings the session client every 30 s until release', async () => { vi.useFakeTimers(); try { - const runtime = new LimrunRuntime({ apiKey: 'lim_test_key', keepAlive: true }); + const runtime = createTestRuntime({ apiKey: 'lim_test_key', keepAlive: true }); const lease = androidLease(); await allocateLimrunDevice(runtime, lease); await vi.advanceTimersByTimeAsync(60_000); @@ -357,7 +361,7 @@ test('Limrun keepAlive pings the session client every 30 s until release', async test('Limrun keepAlive is off by default', async () => { vi.useFakeTimers(); try { - const runtime = new LimrunRuntime({ apiKey: 'lim_test_key' }); + const runtime = createTestRuntime({ apiKey: 'lim_test_key' }); await allocateLimrunDevice(runtime, androidLease()); await vi.advanceTimersByTimeAsync(60_000); assert.equal(limrunMockState.androidKeepAlive.mock.calls.length, 0); @@ -373,7 +377,7 @@ test('Limrun keepAlive keeps pinging after the client throws', async () => { limrunMockState.androidKeepAlive.mockImplementationOnce(() => { throw new Error('socket closed'); }); - const runtime = new LimrunRuntime({ apiKey: 'lim_test_key', keepAlive: true }); + const runtime = createTestRuntime({ apiKey: 'lim_test_key', keepAlive: true }); await allocateLimrunDevice(runtime, androidLease()); await vi.advanceTimersByTimeAsync(60_000); assert.equal(limrunMockState.androidKeepAlive.mock.calls.length, 2); @@ -452,7 +456,7 @@ function assertAndroidTunnelLifecycle(openUrl: string): void { test('Limrun Android syncs direct local artifacts', async () => { const apkPath = path.join(mkdtempForTestSync('limrun-install-'), 'app-debug.apk'); fs.writeFileSync(apkPath, 'apk fixture'); - const runtime = new LimrunRuntime({ + const runtime = createTestRuntime({ apiKey: 'lim_test_key', }); const lease: DeviceLease = { @@ -498,7 +502,7 @@ test('Limrun Android syncs direct local artifacts', async () => { }); test('Limrun Android shares an in-flight ADB tunnel across concurrent port reverse requests', async () => { - const runtime = new LimrunRuntime({ apiKey: 'lim_test_key' }); + const runtime = createTestRuntime({ apiKey: 'lim_test_key' }); try { await allocateLimrunDevice(runtime, androidLease()); @@ -527,7 +531,7 @@ test('Limrun iOS syncs direct local artifacts', async () => { const tempRoot = mkdtempForTestSync('agent-device-limrun-install-'); const ipaPath = path.join(tempRoot, 'Demo.ipa'); fs.writeFileSync(ipaPath, 'demo'); - const runtime = new LimrunRuntime({ + const runtime = createTestRuntime({ apiKey: 'lim_test_key', }); const lease: DeviceLease = { @@ -588,7 +592,7 @@ test('Limrun iOS reads the bundle display name before syncing an app bundle', as '', ].join(''), ); - const runtime = new LimrunRuntime({ apiKey: 'lim_test_key' }); + const runtime = createTestRuntime({ apiKey: 'lim_test_key' }); try { const device = await allocateLimrunDevice(runtime, { @@ -610,7 +614,7 @@ test('Limrun iOS reads the bundle display name before syncing an app bundle', as }); test('Limrun Android configures an explicit port reverse', async () => { - const runtime = new LimrunRuntime({ + const runtime = createTestRuntime({ apiKey: 'lim_test_key', }); const lease: DeviceLease = { @@ -656,7 +660,7 @@ test('Limrun Android configures an explicit port reverse', async () => { }); test('Limrun Android preserves canonical ADB failure classification', async () => { - const runtime = new LimrunRuntime({ apiKey: 'lim_test_key' }); + const runtime = createTestRuntime({ apiKey: 'lim_test_key' }); try { await allocateLimrunDevice(runtime, androidLease()); @@ -691,7 +695,7 @@ test('Limrun deletes iOS instance when post-create validation fails', async () = metadata: { id: 'ios-instance-missing-api' }, status: { token: 'instance-token' }, } as never); - const runtime = new LimrunRuntime({ + const runtime = createTestRuntime({ apiKey: 'lim_test_key', }); const lease: DeviceLease = { @@ -723,7 +727,7 @@ test('Limrun deletes Android instance when post-create validation fails', async apiUrl: 'https://android.example', }, } as never); - const runtime = new LimrunRuntime({ + const runtime = createTestRuntime({ apiKey: 'lim_test_key', }); const lease: DeviceLease = { @@ -748,7 +752,7 @@ test('Limrun deletes Android instance when post-create validation fails', async }); test('Limrun keeps session tracked when release fails so release can be retried', async () => { - const runtime = new LimrunRuntime({ + const runtime = createTestRuntime({ apiKey: 'lim_test_key', }); const lease: DeviceLease = { @@ -805,7 +809,7 @@ function iosLease(leaseId: string): DeviceLease { } test('Limrun drives existing instances without an API key and never deletes them', async () => { - const runtime = new LimrunRuntime({ + const runtime = createTestRuntime({ instances: { ios: ATTACHED_IOS, android: ATTACHED_ANDROID }, }); const releaseLease = runtime.leaseLifecycle.release; @@ -845,7 +849,7 @@ test('Limrun drives existing instances without an API key and never deletes them }); test('Limrun removes only its own port reverse mappings from an attached Android instance', async () => { - const runtime = new LimrunRuntime({ instances: { android: ATTACHED_ANDROID } }); + const runtime = createTestRuntime({ instances: { android: ATTACHED_ANDROID } }); const lease = { ...androidLease(), leaseId: 'lease-attached-android' }; vi.mocked(runCmd).mockImplementation(async (_command, args) => ({ stdout: args.includes('--list') @@ -875,7 +879,7 @@ test('Limrun removes only its own port reverse mappings from an attached Android }); test('Limrun refuses to replace an owner port reverse on an attached Android instance', async () => { - const runtime = new LimrunRuntime({ instances: { android: ATTACHED_ANDROID } }); + const runtime = createTestRuntime({ instances: { android: ATTACHED_ANDROID } }); const lease = { ...androidLease(), leaseId: 'lease-attached-android' }; vi.mocked(runCmd).mockImplementation(async (_command, args) => args.includes('--no-rebind') @@ -917,7 +921,7 @@ test('Limrun refuses to replace an owner port reverse on an attached Android ins }); test('Limrun instance access wins over the API key for its platform only', async () => { - const runtime = new LimrunRuntime({ apiKey: 'lim_test_key', instances: { ios: ATTACHED_IOS } }); + const runtime = createTestRuntime({ apiKey: 'lim_test_key', instances: { ios: ATTACHED_IOS } }); await allocateLimrunDevice(runtime, iosLease('lease-attached-ios')); await allocateLimrunDevice(runtime, androidLease()); @@ -933,7 +937,7 @@ test('Limrun instance access wins over the API key for its platform only', async }); test('Limrun without an API key refuses operations that need one', async () => { - const runtime = new LimrunRuntime({ instances: { ios: ATTACHED_IOS } }); + const runtime = createTestRuntime({ instances: { ios: ATTACHED_IOS } }); try { await assert.rejects(allocateLimrunDevice(runtime, androidLease()), { @@ -943,11 +947,11 @@ test('Limrun without an API key refuses operations that need one', async () => { } finally { await runtime.shutdown(); } - assert.throws(() => new LimrunRuntime({}), /requires an apiKey or instance access/); + assert.throws(() => createTestRuntime({}), /requires an apiKey or instance access/); }); test('Limrun attaches an existing instance under a consumed field and refuses a refused one', async () => { - const runtime = new LimrunRuntime({ instances: { ios: ATTACHED_IOS } }); + const runtime = createTestRuntime({ instances: { ios: ATTACHED_IOS } }); const allocateLease = runtime.leaseLifecycle.allocate; if (!allocateLease) throw new Error('Limrun runtime must provide lease allocation'); try { @@ -964,3 +968,32 @@ test('Limrun attaches an existing instance under a consumed field and refuses a await runtime.shutdown(); } }); + +test('public Limrun runtimes keep their hosts in concurrent deferred Android callbacks', async () => { + const host = (owner: string) => ({ env: { SDK_OWNER: owner }, cwd: process.cwd() }); + const runtimes = ['first', 'second'].map( + (owner) => new LimrunRuntime({ apiKey: 'lim_test_key' }, host(owner)), + ); + vi.mocked(runCmd).mockImplementation(async () => ({ + stdout: `mCurrentFocus=Window{1 u0 com.${commandHostEnvironment().env.SDK_OWNER}/.MainActivity}`, + stderr: '', + exitCode: 0, + })); + try { + const sessions = await Promise.all( + runtimes.map(async (runtime) => { + const device = await allocateLimrunDevice(runtime, androidLease()); + const session = runtime.getDeviceSession(device); + assert.ok(session?.platform === 'android'); + return session; + }), + ); + const results = await withCommandHost( + { host: host('foreign'), requestEnv: { SDK_OWNER: 'request' } }, + () => Promise.all(sessions.map((session) => session.getForegroundApp())), + ); + expect(results.map((app) => app?.appId)).toEqual(['com.first', 'com.second']); + } finally { + await Promise.all(runtimes.map((runtime) => runtime.shutdown())); + } +}); 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.ts b/src/cli.ts index d5e11c386b..37a5b0b85a 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -51,8 +51,8 @@ import { } from '@agent-device/host-kit/diagnostics'; import { resolveCliOptions } from './cli/resolve-cli-options.ts'; import { maybeRunUpgradeNotifier } from './cli/update-check.ts'; +import { remoteSessionRequiredError } from '@agent-device/contracts/lease-scope'; import { - remoteSessionRequiredError, resolveRemoteConnectionDefaults, type RemoteConnectionRequestMetadata, } from '@agent-device/remote/remote-connection-state'; diff --git a/src/cli/__tests__/update-check.test.ts b/src/cli/__tests__/update-check.test.ts index 03e517e44c..155fc27e30 100644 --- a/src/cli/__tests__/update-check.test.ts +++ b/src/cli/__tests__/update-check.test.ts @@ -252,3 +252,37 @@ test('a failed check after a channel switch records the new channel and drops th assert.equal(cache.latestVersion, undefined); assert.equal(cache.checkedAt, '2026-03-31T10:00:00.000Z'); }); + +test('a 0.22 nightly follows its own dist-tag and ignores cached main-nightly updates', async () => { + const stateDir = makeTempStateDir(); + cleanupPaths.push(stateDir); + const currentVersion = '0.22.0-nightly-0-22.20261113.7'; + writeCache(stateDir, { latestVersion: '0.23.0-nightly.20261114.8', distTag: 'nightly' }); + assert.equal( + withCapturedStderr( + () => maybeRunUpgradeNotifier({ command: 'devices', currentVersion, stateDir, flags: {} }), + { interactive: true }, + ), + '', + ); + const fetchMock = vi.fn().mockResolvedValue({ + ok: true, + json: async () => ({ version: '0.22.0-nightly-0-22.20261114.8' }), + }); + vi.stubGlobal('fetch', fetchMock); + await runUpdateCheckWorker({ + cachePath: path.join(stateDir, 'update-check.json'), + currentVersion, + }); + assert.equal( + fetchMock.mock.calls[0]?.[0], + 'https://registry.npmjs.org/agent-device/nightly-0.22', + ); + assert.match( + withCapturedStderr( + () => maybeRunUpgradeNotifier({ command: 'devices', currentVersion, stateDir, flags: {} }), + { interactive: true }, + ), + /npm install -g agent-device@nightly-0\.22/, + ); +}); 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/__tests__/replay-maestro-export.test.ts b/src/cli/commands/__tests__/replay-maestro-export.test.ts index fcb775472b..363b867dab 100644 --- a/src/cli/commands/__tests__/replay-maestro-export.test.ts +++ b/src/cli/commands/__tests__/replay-maestro-export.test.ts @@ -2,14 +2,7 @@ import fs from 'node:fs'; import path from 'node:path'; import { parseAllDocuments } from 'yaml'; import { describe, expect, test } from 'vitest'; -import { AppError } from '@agent-device/kernel/errors'; -import { - exportReplayActionsToMaestro, - inspectMaestroFlow, - MAESTRO_SELECTOR_PROJECTION, -} from '@agent-device/maestro'; -import { parseReplayScriptDetailed, readReplayScriptMetadata } from '@agent-device/ad-script'; -import { projectSelectorExpression } from '@agent-device/selectors'; +import { inspectMaestroFlow } from '@agent-device/maestro'; import { runCliCapture } from '../../../__tests__/cli-capture.ts'; import { mkdtempForTestSync } from '@agent-device/test-kit'; @@ -51,300 +44,8 @@ describe('exportReplayScriptToMaestro', () => { expect(written).toMatchObject({ code: null, calls: [], stderr: '', stdout: `${outPath}\n` }); expect(fs.readFileSync(outPath, 'utf8')).toBe(output.data.yaml); }); - - test('exports app launch, selectors, input, keyboard, assertions, and screenshots', () => { - const result = exportReplayScriptToMaestro(`env USER="Ada" -context platform=ios target=mobile -open com.example.app --relaunch -click id="email" -fill id="email" "ada@example.com" -keyboard dismiss -find text "Continue" exists -screenshot "./artifacts/checkout" -`); - - const docs = parseYamlDocs(result.yaml); - expect(() => inspectMaestroFlow(result.yaml, 'export.yaml')).not.toThrow(); - expect(docs).toEqual([ - { appId: 'com.example.app', env: { USER: 'Ada' } }, - [ - { launchApp: { appId: 'com.example.app', stopApp: true } }, - { tapOn: { id: 'email' } }, - { tapOn: { id: 'email' } }, - { inputText: 'ada@example.com' }, - 'hideKeyboard', - { assertVisible: 'Continue' }, - { takeScreenshot: './artifacts/checkout' }, - ], - ]); - expect(result.warnings).toEqual([ - { - line: 5, - action: 'fill id="email" ada@example.com', - message: - 'fill exports as tapOn + inputText; Maestro may append text instead of replacing existing field contents', - }, - ]); - }); - - test('exports each app target when a script switches apps and returns', () => { - const result = exportReplayScriptToMaestro(`open com.example.shop -open com.example.auth -open com.example.shop -`); - - expect(() => inspectMaestroFlow(result.yaml, 'apps.yaml')).not.toThrow(); - expect(parseYamlDocs(result.yaml)).toEqual([ - { appId: 'com.example.shop' }, - [ - { launchApp: { appId: 'com.example.shop' } }, - { launchApp: { appId: 'com.example.auth' } }, - { launchApp: { appId: 'com.example.shop' } }, - ], - ]); - expect(result.warnings).toEqual([]); - }); - - test('exports the empty-fill clear as eraseText, never a vacuous inputText', () => { - // `fill ""` is the clear-field primitive (#2063); Maestro's `inputText: ""` types - // nothing, so the recorded clear must become its clear verb. - const result = exportReplayScriptToMaestro(`context platform=ios target=mobile -open com.example.app -fill id="email" "" -`); - - const docs = parseYamlDocs(result.yaml); - expect(docs[1]).toEqual([ - { launchApp: { appId: 'com.example.app' } }, - { tapOn: { id: 'email' } }, - 'eraseText', - ]); - expect(result.warnings).toEqual([ - { - line: 3, - action: 'fill id="email"', - message: - 'fill "" exports as tapOn + eraseText; Maestro erases at most its 50-character default', - }, - ]); - }); - - test('exports coordinate gestures and sleep waits with warnings', () => { - const result = exportReplayScriptToMaestro(`open com.example.app -click 120 240 -swipe 200 700 200 200 --count 2 -wait 500 -`); - - expect(parseYamlDocs(result.yaml)).toEqual([ - { appId: 'com.example.app' }, - [ - { launchApp: { appId: 'com.example.app' } }, - { tapOn: { point: '120,240' } }, - { swipe: { start: '200,700', end: '200,200', duration: 100 } }, - { swipe: { start: '200,700', end: '200,200', duration: 100 } }, - { waitForAnimationToEnd: { timeout: 500 } }, - ], - ]); - expect(result.warnings).toEqual([ - { - line: 4, - action: 'wait 500', - message: - 'wait exports as waitForAnimationToEnd and may return before the full duration', - }, - ]); - }); - - test('exports wait stable as waitForAnimationToEnd and text or selector waits with their timeouts', () => { - const result = exportReplayScriptToMaestro(`open com.example.app -wait stable -wait stable 500 3000 -wait text "Ready" 2000 -wait 'id="done"' 4000 -wait id="save" enabled=true 25000 -wait text Sign in 2000 -`); - - expect(parseYamlDocs(result.yaml)).toEqual([ - { appId: 'com.example.app' }, - [ - { launchApp: { appId: 'com.example.app' } }, - 'waitForAnimationToEnd', - { waitForAnimationToEnd: { timeout: 3000 } }, - { extendedWaitUntil: { visible: 'Ready', timeout: 2000 } }, - { extendedWaitUntil: { visible: { id: 'done' }, timeout: 4000 } }, - { extendedWaitUntil: { visible: { id: 'save', enabled: true }, timeout: 25000 } }, - { extendedWaitUntil: { visible: 'Sign in', timeout: 2000 } }, - ], - ]); - const stableWarning = - 'wait stable exports as waitForAnimationToEnd, which uses its own screen-stability threshold instead of the quiet window'; - expect(result.warnings).toEqual([ - { line: 2, action: 'wait stable', message: stableWarning }, - { line: 3, action: 'wait stable 500 3000', message: stableWarning }, - ]); - }); - - test('rejects wait forms that have no on-screen text to wait for', () => { - const run = () => - exportReplayScriptToMaestro(`open com.example.app -wait @e3 -wait text -wait stable 500 junk -wait visible label="Save" 25000 -`); - expect(run).toThrowError(AppError); - expect(run).toThrowError('line 2 (wait @e3): wait @ref names a session-local ref'); - expect(run).toThrowError('line 3 (wait text): wait text requires the text to wait for'); - expect(run).toThrowError( - 'line 4 (wait stable 500 junk): wait stable takes at most a numeric quietMs and timeoutMs', - ); - // The whole selector reaches the projection, which refuses `visible`; it never exports as text. - expect(run).toThrowError( - 'line 5 (wait visible label="Save" 25000): wait selector is not Maestro-compatible', - ); - }); - - // #3197: `scroll --until` became part of a scroll action, so the export names - // the stop condition it cannot carry instead of exporting a bare page scroll. - test('warns when scroll --until exports as a bare Maestro scroll', () => { - const result = exportReplayScriptToMaestro(`open com.example.app -scroll down --until 'id="far-button"' -`); - - expect(parseYamlDocs(result.yaml)).toEqual([ - { appId: 'com.example.app' }, - [{ launchApp: { appId: 'com.example.app' } }, 'scroll'], - ]); - expect(result.warnings).toEqual([ - { - line: 2, - // The action label names positionals only, so the flag shows in the message. - action: 'scroll down', - message: 'scroll --until id="far-button" is not represented by Maestro scroll', - }, - ]); - }); - - test('warns when explicit long-press durations export to Maestro defaults', () => { - const result = exportReplayScriptToMaestro(`open com.example.app -longpress "label=\\"Last message\\"" 800 -click id="hold-button" --hold-ms 1200 -press text="Retry" --hold-ms 1500 -`); - - expect(parseYamlDocs(result.yaml)).toEqual([ - { appId: 'com.example.app' }, - [ - { launchApp: { appId: 'com.example.app' } }, - { longPressOn: { text: 'Last message' } }, - { longPressOn: { id: 'hold-button' } }, - { longPressOn: { text: 'Retry' } }, - ], - ]); - expect(result.warnings).toEqual([ - { - line: 2, - action: 'longpress label="Last message" 800', - message: - 'label= selectors export as Maestro text; Maestro text matching is broader than agent-device label-only matching', - }, - { - line: 2, - action: 'longpress label="Last message" 800', - message: - 'long-press duration exports as Maestro longPressOn; Maestro uses its default long-press duration instead of 800ms', - }, - { - line: 3, - action: 'click id="hold-button"', - message: - 'long-press duration exports as Maestro longPressOn; Maestro uses its default long-press duration instead of 1200ms', - }, - { - line: 4, - action: 'press text="Retry"', - message: - 'long-press duration exports as Maestro longPressOn; Maestro uses its default long-press duration instead of 1500ms', - }, - ]); - }); - - test('warns when double-tap and hold exports ignore repeated tap options', () => { - const result = exportReplayScriptToMaestro(`open com.example.app -click id="retry" --double-tap --count 2 --interval-ms 200 -press text="Hold" --hold-ms 1000 --count 3 --interval-ms 150 -`); - - expect(parseYamlDocs(result.yaml)).toEqual([ - { appId: 'com.example.app' }, - [ - { launchApp: { appId: 'com.example.app' } }, - { doubleTapOn: { id: 'retry' } }, - { longPressOn: { text: 'Hold' } }, - ], - ]); - expect(result.warnings).toEqual([ - { - line: 2, - action: 'click id="retry"', - message: 'tap --count 2 is not represented by Maestro doubleTapOn', - }, - { - line: 2, - action: 'click id="retry"', - message: 'tap --interval-ms 200 is not represented by Maestro doubleTapOn', - }, - { - line: 3, - action: 'press text="Hold"', - message: - 'long-press duration exports as Maestro longPressOn; Maestro uses its default long-press duration instead of 1000ms', - }, - { - line: 3, - action: 'press text="Hold"', - message: 'tap --count 3 is not represented by Maestro longPressOn', - }, - { - line: 3, - action: 'press text="Hold"', - message: 'tap --interval-ms 150 is not represented by Maestro longPressOn', - }, - ]); - }); - - test('rejects native-only replay actions', () => { - expect(() => - exportReplayScriptToMaestro(`open com.example.app -snapshot -i -get text id="status" -`), - ).toThrowError(AppError); - try { - exportReplayScriptToMaestro(`open com.example.app -snapshot -i -get text id="status" -`); - } catch (error) { - expect(error).toBeInstanceOf(AppError); - expect((error as AppError).message).toContain('line 2 (snapshot)'); - expect((error as AppError).message).toContain('line 3 (get text id="status")'); - } - }); }); -function exportReplayScriptToMaestro(script: string) { - const parsed = parseReplayScriptDetailed(script); - return exportReplayActionsToMaestro(parsed.actions, { - actionLines: parsed.actionLines, - metadata: readReplayScriptMetadata(script), - resolveSelector: (expression) => - projectSelectorExpression(expression, MAESTRO_SELECTOR_PROJECTION), - }); -} - function parseYamlDocs(script: string): unknown[] { return parseAllDocuments(script).map((doc) => doc.toJSON()); } 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/cli/update-check.ts b/src/cli/update-check.ts index 916d2f84f4..5a82fc535e 100644 --- a/src/cli/update-check.ts +++ b/src/cli/update-check.ts @@ -169,8 +169,9 @@ function cachedDistTag(cache: UpdateCheckCache): string { return cache.distTag ?? 'latest'; } -/** A nightly build follows the `nightly` dist-tag; every other build follows `latest`. */ -function distTagFor(version: string): 'latest' | 'nightly' { +/** Each nightly follows its source channel; other builds follow `latest`. */ +function distTagFor(version: string): 'latest' | 'nightly' | 'nightly-0.22' { + if (version.includes('-nightly-0-22.')) return 'nightly-0.22'; return version.includes('-nightly.') ? 'nightly' : 'latest'; } diff --git a/src/commands/schema/cli-help.ts b/src/commands/schema/cli-help.ts index 869e8455b6..35b397f26d 100644 --- a/src/commands/schema/cli-help.ts +++ b/src/commands/schema/cli-help.ts @@ -598,6 +598,7 @@ Rules: Prefer connect --remote-config over --daemon-base-url, --tenant, --run-id, and --lease-id when using a local profile. Use agent-device proxy for direct tunnel access to a Mac you control. Expose the proxy through cloudflared/ngrok, configure --public-origin with the public tunnel origin, then run agent-device connect proxy with the tunnel URL and printed token before normal commands. Use Limrun, BrowserStack, AWS Device Farm, TestMu AI, and Revyl through local provider profiles; they do not accept a remote agent-device daemon URL. + Node SDK integrations in 0.22 pass an explicit { env, cwd } host to Android host ADB helpers, archive inspection, Metro preparation, and LimrunRuntime. resolveRemoteConfigProfile requires env; createLocalArtifactAdapter requires cwd. CLI and MCP entry points capture their process host. Device cloud credentials must be available before the command starts. Limrun uses LIMRUN_API_KEY, or the LIM_*_INSTANCE_* variables for an existing instance. BrowserStack uses BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY. TestMu AI uses LT_USERNAME and LT_ACCESS_KEY. Revyl uses REVYL_API_KEY, with REVYL_API_URL to point at another Revyl backend. AWS Device Farm uses the AWS CLI credential chain, including CI-provided AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY/AWS_SESSION_TOKEN, AWS profiles, or web identity role variables. A local daemon keeps the Limrun, BrowserStack, TestMu AI, and Revyl credentials it started with. When the shell holds different ones, the first command that allocates a lease refuses with reason provider-credentials-changed; run agent-device daemon stop with the same --state-dir, then rerun the command. A shell that sets none of them uses the daemon's. A daemon with an HTTP auth hook serves remote callers and does not compare. A lease for a provider the daemon has no runtime for refuses with UNSUPPORTED_OPERATION, reason provider-not-registered, and lists the registered providers, plus the plugins that failed to register as failedPlugins; no lease is recorded. Restart the daemon with the provider configured. Provider-less leases, proxy, and cloud need no provider runtime. diff --git a/src/daemon-composition-credentials.test.ts b/src/daemon-composition-credentials.test.ts index 5609f0f392..535c94f4b6 100644 --- a/src/daemon-composition-credentials.test.ts +++ b/src/daemon-composition-credentials.test.ts @@ -84,6 +84,7 @@ test('daemon startup compares lease credentials with its own startup environment method: 'agent_device.lease.allocate', params: { token, + session: 'agent-a', tenantId: 'tenant', runId: 'run', leaseProvider: 'browserstack', diff --git a/src/daemon-runtime-limrun-public-http.test.ts b/src/daemon-runtime-limrun-public-http.test.ts index d18886091f..b0f75306f7 100644 --- a/src/daemon-runtime-limrun-public-http.test.ts +++ b/src/daemon-runtime-limrun-public-http.test.ts @@ -142,6 +142,7 @@ test('public HTTP rejects Limrun uploaded-app listing and allocation before prov id: 'limrun-public-allocation', method: 'agent_device.lease.allocate', params: { + session: 'agent-a', tenantId: 'tenant-a', runId: 'run-a', backend: 'android-instance', diff --git a/src/platform-runtime-android-adb-host.ts b/src/platform-runtime-android-adb-host.ts index 55e32ba9f7..d1fd13562c 100644 --- a/src/platform-runtime-android-adb-host.ts +++ b/src/platform-runtime-android-adb-host.ts @@ -97,6 +97,7 @@ bindAndroidAdbHost({ const lowered = lowerAndroidAdbInvocation(invocation, options, commandHostEnvironment().env); return await runCmd('adb', lowered.args, { ...lowered.options, + cwd: commandHostEnvironment().cwd, // adb's fork-server is a grandchild: without its own process group a deadline can only // signal `adb` itself, and the server keeps the stdio pipes open behind it. detached: process.platform !== 'win32', @@ -107,6 +108,7 @@ bindAndroidAdbHost({ const lowered = lowerAndroidAdbInvocation(invocation, options, commandHostEnvironment().env); const background = runCmdBackground('adb', lowered.args, { ...lowered.options, + cwd: commandHostEnvironment().cwd, allowFailure: true, captureOutput: false, }); 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-device-runtimes.test.ts b/src/provider-device-runtimes.test.ts index a023aba458..5ff9a3f553 100644 --- a/src/provider-device-runtimes.test.ts +++ b/src/provider-device-runtimes.test.ts @@ -42,7 +42,11 @@ test('Limrun retries an expired provider lease persisted by a daemon before rest try { firstDaemon = await startPublicDaemonRuntime({ stateDir, env }); - const client = createAgentDeviceClient({ stateDir, daemonTransport: 'http' }); + const client = createAgentDeviceClient({ + stateDir, + daemonTransport: 'http', + session: 'agent-a', + }); const lease = await client.leases.allocate({ tenant: 'team-a', runId: 'run-a', diff --git a/src/provider-limrun-runtime.ts b/src/provider-limrun-runtime.ts index 793e28d213..97b610890f 100644 --- a/src/provider-limrun-runtime.ts +++ b/src/provider-limrun-runtime.ts @@ -1,4 +1,4 @@ -import { captureSdkHost } from './sdk/host.ts'; +import type { HostEnvironment } from '@agent-device/kernel/source-value'; import type { DeviceInventoryProvider, LeaseLifecycleProvider, @@ -24,11 +24,8 @@ export class LimrunRuntime implements ProviderDeviceRuntime { // Called through ProviderDeviceRuntime composition and the public Limrun SDK. readonly provider = LIMRUN_PROVIDER; - constructor(options: LimrunRuntimeOptions) { - this.implementation = createLimrunRuntime( - options, - createLimrunRuntimeDependencies(captureSdkHost()), - ); + constructor(options: LimrunRuntimeOptions, host: HostEnvironment) { + this.implementation = createLimrunRuntime(options, createLimrunRuntimeDependencies(host)); } get leaseLifecycle(): LeaseLifecycleProvider { 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/src/sdk/android-adb.test.ts b/src/sdk/android-adb.test.ts index 7472c2fcee..72d0422b42 100644 --- a/src/sdk/android-adb.test.ts +++ b/src/sdk/android-adb.test.ts @@ -39,29 +39,47 @@ test('getAndroidAppStateWithAdb falls back to activity focus and settles empty', }); test.skipIf(process.platform === 'win32')( - 'standalone public Android shell helpers establish their process host before dispatch', + 'public Android helpers retain explicit hosts and only their own request overlays', async () => { const { runAndroidShell, runAndroidExecOut } = await import('./android-adb.ts'); const { ANDROID_EMULATOR, mkdtempForTestSync } = await import('@agent-device/test-kit'); - const { writeFileSync, chmodSync } = await import('node:fs'); + const { withCommandHost } = await import('@agent-device/host-kit/command'); + const { writeFileSync, chmodSync, realpathSync } = await import('node:fs'); const { join } = await import('node:path'); const bin = mkdtempForTestSync('agent-device-sdk-adb-'); - const adbPath = join(bin, 'adb'); writeFileSync( - adbPath, - `#!${process.execPath}\nprocess.stdout.write(JSON.stringify(process.argv.slice(2)));`, + join(bin, 'adb'), + `#!${process.execPath}\nprocess.stdout.write(JSON.stringify({args:process.argv.slice(2),owner:process.env.SDK_OWNER,cwd:process.cwd()}));`, ); - chmodSync(adbPath, 0o755); - const previousPath = process.env.PATH; - process.env.PATH = bin; - try { - const shell = await runAndroidShell(ANDROID_EMULATOR, ['id']); - const execOut = await runAndroidExecOut(ANDROID_EMULATOR, ['id']); - assert.deepEqual(JSON.parse(shell.stdout), ['-s', ANDROID_EMULATOR.id, 'shell', 'id']); - assert.deepEqual(JSON.parse(execOut.stdout), ['-s', ANDROID_EMULATOR.id, 'exec-out', 'id']); - } finally { - if (previousPath === undefined) delete process.env.PATH; - else process.env.PATH = previousPath; + chmodSync(join(bin, 'adb'), 0o755); + const host = (owner: string) => ({ env: { PATH: bin, SDK_OWNER: owner }, cwd: bin }); + const results = await withCommandHost( + { host: host('foreign'), requestEnv: { SDK_OWNER: 'request' } }, + () => + Promise.all([ + runAndroidShell(ANDROID_EMULATOR, ['id'], host('shell')), + runAndroidExecOut(ANDROID_EMULATOR, ['id'], host('exec')), + ]), + ); + for (const [index, command, owner] of [ + [0, 'shell', 'shell'], + [1, 'exec-out', 'exec'], + ] as const) { + assert.deepEqual(JSON.parse(results[index].stdout), { + args: ['-s', ANDROID_EMULATOR.id, command, 'id'], + owner, + cwd: realpathSync(bin), + }); } + const sharedHost = host('base'); + const scoped = await withCommandHost( + { host: sharedHost, requestEnv: { SDK_OWNER: 'overlay' } }, + () => runAndroidShell(ANDROID_EMULATOR, ['id'], sharedHost), + ); + assert.deepEqual(JSON.parse(scoped.stdout), { + args: ['-s', ANDROID_EMULATOR.id, 'shell', 'id'], + owner: 'overlay', + cwd: realpathSync(bin), + }); }, ); diff --git a/src/sdk/android-adb.ts b/src/sdk/android-adb.ts index 46c187b437..57de3c4319 100644 --- a/src/sdk/android-adb.ts +++ b/src/sdk/android-adb.ts @@ -1,3 +1,4 @@ +import type { HostEnvironment } from '@agent-device/kernel/source-value'; import '../platform-runtime-android-adb-host.ts'; export { createAndroidPortReverseManager, @@ -14,12 +15,22 @@ import { } from '@agent-device/platform-android/mechanics'; import { withSdkHost } from './host.ts'; -export async function runAndroidShell(...args: Parameters) { - return await withSdkHost(() => runAndroidShellOnHost(...args)); +export async function runAndroidShell( + device: Parameters[0], + words: Parameters[1], + host: HostEnvironment, + options?: Parameters[2], +) { + return await withSdkHost(host, () => runAndroidShellOnHost(device, words, options)); } -export async function runAndroidExecOut(...args: Parameters) { - return await withSdkHost(() => runAndroidExecOutOnHost(...args)); +export async function runAndroidExecOut( + device: Parameters[0], + words: Parameters[1], + host: HostEnvironment, + options?: Parameters[2], +) { + return await withSdkHost(host, () => runAndroidExecOutOnHost(device, words, options)); } export type { ShellWord } from '@agent-device/kernel/device-shell'; diff --git a/src/sdk/artifacts.test.ts b/src/sdk/artifacts.test.ts index 493eaa06c0..061a122273 100644 --- a/src/sdk/artifacts.test.ts +++ b/src/sdk/artifacts.test.ts @@ -1,6 +1,6 @@ import assert from 'node:assert/strict'; import { execFileSync } from 'node:child_process'; -import { chmodSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'; +import { chmodSync, mkdirSync, realpathSync, writeFileSync } from 'node:fs'; import path from 'node:path'; import { test } from 'vitest'; import { mkdtempForTestSync } from '@agent-device/test-kit'; @@ -8,53 +8,77 @@ import { withCommandHost } from '@agent-device/host-kit/command'; import { resolveAndroidArchivePackageName } from './artifacts.ts'; test.skipIf(process.platform === 'win32')( - 'standalone artifact resolution uses aapt after an unparseable manifest without poisoning later scoped calls', + 'public artifact resolution keeps each concurrent caller SDK and environment', async () => { const root = mkdtempForTestSync('agent-device-sdk-artifacts-'); + writeFileSync(path.join(root, 'AndroidManifest.xml'), ''); + const archive = path.join(root, 'fallback.apk'); + execFileSync('zip', ['-q', archive, 'AndroidManifest.xml'], { cwd: root }); + const host = (owner: string) => { + const sdk = path.join(root, owner); + const tools = path.join(sdk, 'build-tools', '99.0.0'); + mkdirSync(tools, { recursive: true }); + const aapt = path.join(tools, 'aapt'); + writeFileSync( + aapt, + `#!${process.execPath}\nprocess.stdout.write("package: name='com.example.${owner}' versionCode='1'\\n");`, + ); + chmodSync(aapt, 0o755); + return { + env: { ANDROID_HOME: sdk, ANDROID_SDK_ROOT: sdk, PATH: process.env.PATH }, + cwd: root, + }; + }; + const first = host('first'); + const second = host('second'); + assert.equal( + await resolveAndroidArchivePackageName(path.basename(archive), first), + 'com.example.first', + ); + const result = await withCommandHost({ host: host('foreign'), requestEnv: undefined }, () => + Promise.all([ + resolveAndroidArchivePackageName(path.basename(archive), first), + resolveAndroidArchivePackageName(path.basename(archive), second), + ]), + ); + assert.deepEqual(result, ['com.example.first', 'com.example.second']); + }, +); + +test.skipIf(process.platform === 'win32').each(['manifest', 'aapt'] as const)( + 'public archive inspection runs %s tools in the supplied cwd with a relative PATH', + async (source) => { + const root = realpathSync(mkdtempForTestSync('agent-device-sdk-archive-cwd-')); + const bin = path.join(root, 'bin'); const sdk = path.join(root, 'sdk'); const tools = path.join(sdk, 'build-tools', '99.0.0'); + mkdirSync(bin); mkdirSync(tools, { recursive: true }); - const manifest = path.join(root, 'AndroidManifest.xml'); - writeFileSync(manifest, ''); - const archive = path.join(root, 'fallback.apk'); - execFileSync('zip', ['-q', archive, 'AndroidManifest.xml'], { cwd: root }); - const calls = path.join(root, 'aapt-calls.jsonl'); + const unzip = path.join(bin, 'unzip'); const aapt = path.join(tools, 'aapt'); + const cwdGuard = `if(process.cwd()!==${JSON.stringify(root)})process.exit(2);`; + writeFileSync( + unzip, + `#!${process.execPath}\n${cwdGuard}${ + source === 'manifest' + ? `process.stdout.write('');` + : 'process.exit(1);' + }`, + ); writeFileSync( aapt, - `#!${process.execPath}\n` + - `require('node:fs').appendFileSync(${JSON.stringify(calls)}, JSON.stringify(process.argv.slice(2))+'\\n');\n` + - `process.stdout.write("package: name='com.example.fallback' versionCode='1'\\n");\n`, + `#!${process.execPath}\n${cwdGuard}process.stdout.write("package: name='com.example.aapt' versionCode='1'\\n");`, ); + chmodSync(unzip, 0o755); chmodSync(aapt, 0o755); - const previous = { - ANDROID_HOME: process.env.ANDROID_HOME, - ANDROID_SDK_ROOT: process.env.ANDROID_SDK_ROOT, - }; - process.env.ANDROID_HOME = sdk; - process.env.ANDROID_SDK_ROOT = sdk; - try { - const standalone = await resolveAndroidArchivePackageName(archive); - const scoped = await withCommandHost( - { host: { env: { ...process.env }, cwd: root }, requestEnv: undefined }, - () => resolveAndroidArchivePackageName(archive), - ); - assert.deepEqual([standalone, scoped], ['com.example.fallback', 'com.example.fallback']); - assert.deepEqual( - readFileSync(calls, 'utf8') - .trim() - .split('\n') - .map((line) => JSON.parse(line)), - [ - ['dump', 'badging', archive], - ['dump', 'badging', archive], - ], - ); - } finally { - for (const [key, value] of Object.entries(previous)) { - if (value === undefined) delete process.env[key]; - else process.env[key] = value; - } - } + const archive = path.join(root, 'app.apk'); + writeFileSync(archive, 'archive fixture'); + assert.equal( + await resolveAndroidArchivePackageName(archive, { + cwd: root, + env: { PATH: './bin', ANDROID_SDK_ROOT: sdk }, + }), + `com.example.${source}`, + ); }, ); diff --git a/src/sdk/artifacts.ts b/src/sdk/artifacts.ts index 379bfd87bc..61090690bd 100644 --- a/src/sdk/artifacts.ts +++ b/src/sdk/artifacts.ts @@ -1,3 +1,5 @@ +import path from 'node:path'; +import type { HostEnvironment } from '@agent-device/kernel/source-value'; import { loadAndroidMechanics } from '../platform-runtime-android-mechanics.ts'; import { withSdkHost } from './host.ts'; @@ -5,10 +7,12 @@ type ResolveAndroidArchivePackageName = typeof import('@agent-device/platform-android/mechanics').resolveAndroidArchivePackageName; export async function resolveAndroidArchivePackageName( - ...args: Parameters + archivePath: string, + host: HostEnvironment, + signal?: AbortSignal, ): Promise>> { - return await withSdkHost(async () => { + return await withSdkHost(host, async () => { const { resolveAndroidArchivePackageName: resolve } = await loadAndroidMechanics(); - return await resolve(...args); + return await resolve(path.resolve(host.cwd, archivePath), signal, host.cwd); }); } diff --git a/src/sdk/host.ts b/src/sdk/host.ts index a91f70e955..f7b2a20496 100644 --- a/src/sdk/host.ts +++ b/src/sdk/host.ts @@ -1,12 +1,6 @@ import type { HostEnvironment } from '@agent-device/kernel/source-value'; -import { captureHostEnvironment } from '@agent-device/host-kit/process'; import { withCommandHost } from '@agent-device/host-kit/command'; -/** Released SDK defaults removed in 0.22 (#3759). */ -export function captureSdkHost(): HostEnvironment { - return captureHostEnvironment(process); -} - -export async function withSdkHost(task: () => Promise): Promise { - return await withCommandHost({ host: captureSdkHost(), requestEnv: undefined }, task); +export async function withSdkHost(host: HostEnvironment, task: () => Promise): Promise { + return await withCommandHost({ host, requestEnv: undefined }, task); } diff --git a/src/sdk/limrun-runtime-dependencies.test.ts b/src/sdk/limrun-runtime-dependencies.test.ts index 07e05ce4cb..c3113eac7f 100644 --- a/src/sdk/limrun-runtime-dependencies.test.ts +++ b/src/sdk/limrun-runtime-dependencies.test.ts @@ -36,7 +36,10 @@ vi.mock('@agent-device/platform-apple/install-artifact', async (importOriginal) test('Limrun construction defers operation and opposite-platform helper modules', async () => { const { LimrunRuntime } = await import('../provider-limrun-runtime.ts'); - const runtime = new LimrunRuntime({ apiKey: 'lim_test_key' }); + const runtime = new LimrunRuntime( + { apiKey: 'lim_test_key' }, + { env: process.env, cwd: process.cwd() }, + ); assert.deepEqual(moduleLoads, { androidAppHelpers: 0, diff --git a/src/sdk/metro-public.test.ts b/src/sdk/metro-public.test.ts index 27a90f8764..052ce0034c 100644 --- a/src/sdk/metro-public.test.ts +++ b/src/sdk/metro-public.test.ts @@ -1,3 +1,4 @@ +import { once } from 'node:events'; import { test } from 'vitest'; import assert from 'node:assert/strict'; import { @@ -73,7 +74,45 @@ test('public prepareMetroRuntime runs without a daemon or CLI host around it', a const { prepareMetroRuntime } = await import('./metro.ts'); await assert.rejects( - prepareMetroRuntime({}), + prepareMetroRuntime({}, { env: {}, cwd: process.cwd() }), (error: unknown) => (error as { code?: string }).code === 'INVALID_ARGS', ); }); + +test('public Metro preparation resolves concurrent runtime files against each explicit cwd', async () => { + const { prepareMetroRuntime } = await import('./metro.ts'); + const { createServer } = await import('node:http'); + const { readFileSync } = await import('node:fs'); + const { join } = await import('node:path'); + const { mkdtempForTestSync, closeLoopbackServer } = await import('@agent-device/test-kit'); + const server = createServer((_req, res) => res.end('packager-status:running')); + server.listen(0, '127.0.0.1'); + await once(server, 'listening'); + const address = server.address(); + assert.ok(address && typeof address !== 'string'); + const roots = [mkdtempForTestSync('sdk-metro-first-'), mkdtempForTestSync('sdk-metro-second-')]; + try { + const results = await Promise.all( + roots.map((cwd) => + prepareMetroRuntime( + { + kind: 'react-native', + publicBaseUrl: `http://127.0.0.1:${address.port}`, + metroPort: address.port, + installDependenciesIfNeeded: false, + runtimeFilePath: 'runtime.json', + }, + { env: {}, cwd }, + ), + ), + ); + for (const [index, result] of results.entries()) { + const runtimePath = join(roots[index]!, 'runtime.json'); + assert.equal(result.projectRoot, roots[index]); + assert.equal(result.runtimeFilePath, runtimePath); + assert.equal(JSON.parse(readFileSync(runtimePath, 'utf8')).reused, true); + } + } finally { + await closeLoopbackServer(server); + } +}); diff --git a/src/sdk/metro.ts b/src/sdk/metro.ts index ac0689b1a8..00658b0297 100644 --- a/src/sdk/metro.ts +++ b/src/sdk/metro.ts @@ -1,7 +1,5 @@ -import * as devServer from '@agent-device/react-native'; -import { captureSdkHost } from './host.ts'; - export { + prepareMetroRuntime, normalizeBaseUrl, buildBundleUrl, resolveRuntimeTransport, @@ -11,10 +9,3 @@ export { type MetroTunnelRequestMessage, type MetroTunnelResponseMessage, } from '@agent-device/react-native'; - -/** A JS host calls this with no daemon or CLI around it, so it reads the process's current environment. */ -export async function prepareMetroRuntime( - input: Parameters[0] = {}, -): ReturnType { - return await devServer.prepareMetroRuntime(input, captureSdkHost()); -} diff --git a/src/sdk/plugins.ts b/src/sdk/plugins.ts index 15dca39bd1..851631fa16 100644 --- a/src/sdk/plugins.ts +++ b/src/sdk/plugins.ts @@ -25,3 +25,6 @@ export type AgentDevicePluginFactory> = Contra Options, CloudWebDriverProviderOptions >; + +export type { ReplayEnginePlugin, ReplayEngineSetup } from '@agent-device/plugins/replay-backend'; +export type { ReplayBackend, ReplayBackendHost } from '@agent-device/contracts/replay-backend'; diff --git a/src/sdk/remote-config.test.ts b/src/sdk/remote-config.test.ts index 0d10d35e3c..4a57c041f7 100644 --- a/src/sdk/remote-config.test.ts +++ b/src/sdk/remote-config.test.ts @@ -5,20 +5,15 @@ import path from 'node:path'; import { mkdtempForTestSync } from '@agent-device/test-kit'; import { resolveRemoteConfigProfile } from './remote-config.ts'; -test('the released remote-config entry reads the process environment when none is given', () => { +test('the public remote-config resolver uses each supplied environment and cwd', () => { const root = mkdtempForTestSync('agent-device-sdk-remote-config-'); - const previous = process.env.AGENT_DEVICE_METRO_PREPARE_PORT; - try { - const configPath = path.join(root, 'demo.remote.json'); - fs.writeFileSync(configPath, JSON.stringify({ platform: 'ios' }), 'utf8'); - process.env.AGENT_DEVICE_METRO_PREPARE_PORT = '9191'; - - const resolved = resolveRemoteConfigProfile({ configPath, cwd: root }); - - assert.equal(resolved.profile.metroPreparePort, 9191); - } finally { - if (previous === undefined) delete process.env.AGENT_DEVICE_METRO_PREPARE_PORT; - else process.env.AGENT_DEVICE_METRO_PREPARE_PORT = previous; - fs.rmSync(root, { recursive: true, force: true }); - } + fs.writeFileSync(path.join(root, 'demo.remote.json'), JSON.stringify({ platform: 'ios' })); + const resolve = (port: string) => + resolveRemoteConfigProfile({ + configPath: 'demo.remote.json', + cwd: root, + env: { AGENT_DEVICE_METRO_PREPARE_PORT: port }, + }); + assert.equal(resolve('9191').profile.metroPreparePort, 9191); + assert.equal(resolve('9292').profile.metroPreparePort, 9292); }); diff --git a/src/sdk/remote-config.ts b/src/sdk/remote-config.ts index 75aa99ac9e..34dd52e409 100644 --- a/src/sdk/remote-config.ts +++ b/src/sdk/remote-config.ts @@ -1,18 +1,2 @@ -import { captureSdkHost } from './host.ts'; -import { resolveRemoteConfigProfile as resolveRemoteConfigProfileOnHost } from '@agent-device/remote/remote-config'; -import type { - RemoteConfigProfileOptions, - ResolvedRemoteConfigProfile, -} from '@agent-device/remote/remote-config-schema'; - +export { resolveRemoteConfigProfile } from '@agent-device/remote/remote-config'; export type { RemoteConfigProfile } from '@agent-device/remote/remote-config-schema'; - -/** The released entry: without `env`, the profile resolves against the process's environment. */ -export function resolveRemoteConfigProfile( - options: RemoteConfigProfileOptions, -): ResolvedRemoteConfigProfile { - return resolveRemoteConfigProfileOnHost({ - ...options, - env: options.env ?? captureSdkHost().env, - }); -} diff --git a/test/ci/release-workflow.test.ts b/test/ci/release-workflow.test.ts index 7f4fb51541..987eae7083 100644 --- a/test/ci/release-workflow.test.ts +++ b/test/ci/release-workflow.test.ts @@ -52,3 +52,8 @@ test('the published bytes are built without a restored dependency cache', () => ); expect(setup?.with?.['cache-store']).toBe('false'); }); + +test('both fixed nightly source branches receive push CI', () => { + const ci = parse(fs.readFileSync(path.join(repoRoot, '.github/workflows/ci.yml'), 'utf8')); + expect(ci.on.push.branches).toEqual(['main', '0.22']); +}); diff --git a/test/integration/installed-package-metro.test.ts b/test/integration/installed-package-metro.test.ts index af30a389c7..f69ac28a1a 100644 --- a/test/integration/installed-package-metro.test.ts +++ b/test/integration/installed-package-metro.test.ts @@ -627,6 +627,7 @@ assert.equal(fs.existsSync(path.join(cwd, 'host-a', 'daemon.json')), false); './artifacts': async (mod) => { const name = await mod.resolveAndroidArchivePackageName( nodePath.join(process.cwd(), 'package.json'), + { env: { ...process.env }, cwd: process.cwd() }, ); return String(name); }, @@ -645,7 +646,7 @@ assert.equal(fs.existsSync(path.join(cwd, 'host-a', 'daemon.json')), false); './install-source': (mod) => typeof mod.isTrustedInstallSourceUrl('https://example.test/app.apk'), './io': (mod) => typeof mod.createLocalArtifactAdapter({ cwd: process.cwd() }).reserveOutput, './limrun': async (mod) => { - const runtime = new mod.LimrunRuntime({ apiKey: 'lim_test_key' }); + const runtime = new mod.LimrunRuntime({ apiKey: 'lim_test_key' }, { env: process.env, cwd: process.cwd() }); await runtime.shutdown(); return runtime.provider; }, diff --git a/test/integration/interaction-contract/runtime-harness.ts b/test/integration/interaction-contract/runtime-harness.ts index 4edfc4bd33..927b8ecac8 100644 --- a/test/integration/interaction-contract/runtime-harness.ts +++ b/test/integration/interaction-contract/runtime-harness.ts @@ -53,7 +53,7 @@ export function createContractDevice( performGesture: overrides.performGesture, resolveGestureViewport: overrides.resolveGestureViewport, } satisfies AgentDeviceBackend, - artifacts: createLocalArtifactAdapter(), + artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }), policy: localCommandPolicy(), ...(overrides.clock ? { clock: overrides.clock } : {}), }); diff --git a/test/integration/limrun-public-types.test.ts b/test/integration/limrun-public-types.test.ts index 6accf62a49..a7146a93fa 100644 --- a/test/integration/limrun-public-types.test.ts +++ b/test/integration/limrun-public-types.test.ts @@ -19,7 +19,7 @@ function ensureBuiltPackage(): void { }); } -test('compiled Limrun subpath preserves its downstream type surface', () => { +test('compiled SDK subpaths require explicit hosts and preserve Limrun types', () => { ensureBuiltPackage(); // Keep the fixture under the package root so TypeScript resolves the @@ -49,9 +49,14 @@ test('compiled Limrun subpath preserves its downstream type surface', () => { LimrunDeviceSession, LimrunIosCommandExecution, LimrunIosDeviceSession, - LimrunRuntime, LimrunRuntimeOptions, } from 'agent-device/limrun'; +import { LimrunRuntime } from 'agent-device/limrun'; +import { runAndroidShell, runAndroidExecOut } from 'agent-device/android-adb'; +import { resolveAndroidArchivePackageName } from 'agent-device/artifacts'; +import { prepareMetroRuntime } from 'agent-device/metro'; +import { resolveRemoteConfigProfile } from 'agent-device/remote-config'; +import { createLocalArtifactAdapter, type LocalArtifactAdapterOptions } from 'agent-device/io'; declare const runtime: LimrunRuntime; declare const options: LimrunRuntimeOptions; @@ -59,6 +64,32 @@ declare const session: LimrunDeviceSession; declare const iosSession: LimrunIosDeviceSession; declare const execution: LimrunIosCommandExecution; void [runtime, options, session, iosSession, execution]; +const host = { env: {}, cwd: '/workspace' }; +declare const device: Parameters[0]; +runAndroidShell(device, ['id'], host); +runAndroidExecOut(device, ['id'], host); +resolveAndroidArchivePackageName('app.apk', host); +prepareMetroRuntime({}, host); +resolveRemoteConfigProfile({ configPath: 'remote.json', ...host }); +createLocalArtifactAdapter({ cwd: host.cwd }); +new LimrunRuntime(options, host); +// @ts-expect-error Android shell requires a host. +runAndroidShell(device, ['id']); +// @ts-expect-error Android exec-out requires a host. +runAndroidExecOut(device, ['id']); +// @ts-expect-error Archive inspection requires a host. +resolveAndroidArchivePackageName('app.apk'); +// @ts-expect-error Metro requires a host. +prepareMetroRuntime({}); +// @ts-expect-error Remote config requires env, including when it is empty. +resolveRemoteConfigProfile({ configPath: 'remote.json', cwd: host.cwd }); +// @ts-expect-error Local artifact I/O requires cwd. +createLocalArtifactAdapter(); +// @ts-expect-error Local artifact options require cwd. +const missingCwd: LocalArtifactAdapterOptions = {}; +void missingCwd; +// @ts-expect-error Limrun requires a host. +new LimrunRuntime(options); `, ); diff --git a/test/integration/provider-scenarios/cloud-webdriver-runtime.test.ts b/test/integration/provider-scenarios/cloud-webdriver-runtime.test.ts index 942133fef5..4a7ec82b11 100644 --- a/test/integration/provider-scenarios/cloud-webdriver-runtime.test.ts +++ b/test/integration/provider-scenarios/cloud-webdriver-runtime.test.ts @@ -223,6 +223,7 @@ test('packaged Cloud WebDriver cancels an abandoned source capture and keeps its try { const capture = daemon.client().capture.snapshot({ + session: 'default', signal: controller.signal, ...leaseClientOptions(lease.leaseId), }); diff --git a/test/integration/provider-scenarios/remote-proxy-artifact-tenant.test.ts b/test/integration/provider-scenarios/remote-proxy-artifact-tenant.test.ts index d128c4ec91..0ddd644259 100644 --- a/test/integration/provider-scenarios/remote-proxy-artifact-tenant.test.ts +++ b/test/integration/provider-scenarios/remote-proxy-artifact-tenant.test.ts @@ -51,6 +51,7 @@ test('Provider-backed integration proxy materializes tenant-owned test artifacts id: 'tenant-artifact-lease', method: 'agent_device.lease.allocate', params: { + session: 'default', tenantId: TENANT, runId: 'artifact-run', backend: 'android-instance', diff --git a/test/repo-guards/npm-package-scripts.test.ts b/test/repo-guards/npm-package-scripts.test.ts index 7ad65885a9..a4379e8984 100644 --- a/test/repo-guards/npm-package-scripts.test.ts +++ b/test/repo-guards/npm-package-scripts.test.ts @@ -98,7 +98,11 @@ test('publishing cannot skip the package gate', () => { assert.equal(getCheckSpec('package').localRunnable, true); // The minimum-Node job runs the script directly — the repo's pinned pnpm needs a newer Node than // the floor that job covers — so it must still name the same entry point the script does. - assert.match(script('check:package'), /scripts\/check-package\.ts$/); + assert.deepEqual(script('check:package').split(' && '), [ + 'node --experimental-strip-types scripts/check-package.ts', + 'node --experimental-strip-types scripts/node-test-tmpdir.ts --test packages/maestro/test/package-artifact.test.mjs', + ]); + assert.match(packagedCliWorkflow, /with: \{ gate: package \}/); assert.match( packagedCliWorkflow, /run: node --experimental-strip-types scripts\/check-package\.ts/, diff --git a/test/wire-compat/ledger.json b/test/wire-compat/ledger.json index e464f3f929..3f522b6239 100644 --- a/test/wire-compat/ledger.json +++ b/test/wire-compat/ledger.json @@ -118,10 +118,10 @@ "packages/daemon/src/server/http/http-authorization.ts#readHeaderValue": "sha256:0ec16993e5d9b460ba02deb4a43bbc4c248f9697eaed9aa64003eec7d5dce6bf", "packages/daemon/src/server/http/http-authorization.ts#resolveToken": "sha256:3abcb019e1325317618045b7138e41845990af10953dd937571997cd6ec35981", "packages/daemon/src/server/http/http-rpc-envelope.ts#sendJson": "sha256:a1de00da3f1db8c98e69a85dfe2e11b626a4d2ce472840e3b8f519aa8a207a8f", - "packages/daemon/src/server/http/http-rpc-methods.ts#toDaemonRequest": "sha256:d6afa5f8f1219e519e72bbd6fddd7de7763818f1ed7ae2a1e2a12001bd66bd52", - "packages/daemon/src/server/http/http-rpc-methods.ts#toInstallFromSourceDaemonRequest": "sha256:071c53e7bd8e553cb9df820961294ed4d1e2e385053485364d895cb1777e9429", - "packages/daemon/src/server/http/http-rpc-methods.ts#toLeaseDaemonRequest": "sha256:e017795c86534feb8a7e6e53ffbd614db893aad20c5406b2bc53c771ee646948", - "packages/daemon/src/server/http/http-rpc-methods.ts#toReleaseMaterializedPathsDaemonRequest": "sha256:708736ca03d6a3fc449bb408382dbd509e490de1f84ecc8771fd77d4adda0154", + "packages/daemon/src/server/http/http-rpc-methods.ts#toDaemonRequest": "sha256:14743424656a7a4097eb184d2be2c6272d0b1ff645591e4f4f9430d030789013", + "packages/daemon/src/server/http/http-rpc-methods.ts#toInstallFromSourceDaemonRequest": "sha256:ed1ddf10113ac9c076b3fc0d08a77c12f22ac1ca98347f8f3f8271a5a0daf74e", + "packages/daemon/src/server/http/http-rpc-methods.ts#toLeaseDaemonRequest": "sha256:3e4211293791d67371ece10bf88a6f197598b399ece1041fc22e253691f3cdc2", + "packages/daemon/src/server/http/http-rpc-methods.ts#toReleaseMaterializedPathsDaemonRequest": "sha256:a600285c173c95a75093c9eae65ee96df63d9524f7cc96c0479cf9884069f17c", "packages/daemon/src/server/http/http-rpc-envelope.ts#writeProgressEnvelope": "sha256:7be778b3902c72d7aa6282c16dc7106fdd64e99c0b5daf9f413ff5dd3fb044f1", "packages/daemon/src/server/http/http-rpc-envelope.ts#writeRpcResponseEnvelope": "sha256:7a8155e9fcbb53485489728250a85109b5dab0d96cdd4aa8b7e7eb87a4898ddb", "packages/daemon/src/core/session-tenant-scope.ts#TenantSessionNamespace": "sha256:a6613d22933caa053e479f05b7f016664f6be8d0afdbbf81e578ff497fc1b13d", @@ -194,7 +194,7 @@ "packages/daemon-client/src/daemon-client-transport.ts#isRemoteInstanceMismatchResponse": "sha256:7670f48fe0fc7344f8a000cd303e49788ec7ea9d1c729bcdc2af73ff02dae04d", "packages/daemon-client/src/daemon-client-transport.ts#isRemoteInstanceMismatch": "sha256:6d4cfdd36bd44686d2a48990491faf63ba9117fb760f982fd72922c99be8daee", "packages/contracts/src/lease-scope.ts#buildDaemonRpcRequest": "sha256:b3d03bb08f8f332b04dea6d2ea30abca2faf83a10f11cb874df2344b3f54c2b6", - "packages/contracts/src/lease-scope.ts#buildLeaseRpcParams": "sha256:365490a0fe1833d7ce8b0d3f5425462608a85119b12c1a2c4f16bb83b5d28e06", + "packages/contracts/src/lease-scope.ts#buildLeaseRpcParams": "sha256:25b138457410480048ee3899ce758cdd80bd7a4d11dc6e025f1365e7e8729116", "packages/contracts/src/lease-scope.ts#isLeaseRpcCommand": "sha256:955dc1b73462d40593e5728dbcbaeec1307944b08262a22627e84cc5dc507e8f", "packages/contracts/src/lease-scope.ts#leaseRpcMethodForCommand": "sha256:3613555c6002c23ab5bec4b98bc1b4d6947014b52fa100176177f955cf762881", "packages/contracts/src/daemon-wire-request.ts#DaemonWireRequestMeta": "sha256:369be6aca9cfe20d221b40f5f6ab287ff11e148cc3f7e04fbbfa78be5df31e52", @@ -205,7 +205,8 @@ "packages/contracts/src/device-inventory.ts#readDevicePin": "sha256:bb15ca2a086a881c6cf945c25d432c092be165e58165d229c25df69c4c9fafbd", "packages/proxy/src/daemon-proxy.ts#rewriteUploadDirectUrl": "sha256:b121db3ffb5a520b4b31810a2e28ff01c1a15d959514c9fbe2a61cd960d2af93", "packages/proxy/src/daemon-proxy.ts#rewriteUploadPreflightResponse": "sha256:332820b6f10e079632330c2c4996c4faa6f339e921f12f287bd83c9296df5ccd", - "packages/proxy/src/daemon-proxy.ts#rewrittenUploadPreflightResponse": "sha256:21d633d947cd72f5008bcc886a8f3ecd4f778b594d0654b8d0741db8594003db" + "packages/proxy/src/daemon-proxy.ts#rewrittenUploadPreflightResponse": "sha256:21d633d947cd72f5008bcc886a8f3ecd4f778b594d0654b8d0741db8594003db", + "packages/daemon/src/core/request-session-intake.ts#resolveRequestSessionAtIntake": "sha256:d620b6ee56a8c2f74d2c161016fa19974cbc833e3b87fa522411e35b381d9bc9" }, "compatibleChanges": [ { @@ -221,7 +222,7 @@ { "declaration": "packages/remote/src/daemon-artifacts.ts#DownloadRemoteArtifactParams", "digest": "sha256:ba6d2f6ac51e05ccc5e0c940b355d62374e018b1ae6f6f744becf6e1760cbb63", - "rationale": "#2246 adds the optional isDirectory field. It is pure client-local state — never serialized, never sent to the daemon — that tells the CLIENT'S OWN download logic to extract a tar body instead of writing it verbatim; the GET /artifacts/:id request and response framing are unchanged. Every existing call site (screenshot, recording) omits it and keeps writing a single file exactly as before. The signature also names the client request as DaemonWireRequest and the response as the kernel DaemonResponse instead of the daemon package aliases; only compile-time type names moved." + "rationale": "#2246 adds the optional isDirectory field. It is pure client-local state \u2014 never serialized, never sent to the daemon \u2014 that tells the CLIENT'S OWN download logic to extract a tar body instead of writing it verbatim; the GET /artifacts/:id request and response framing are unchanged. Every existing call site (screenshot, recording) omits it and keeps writing a single file exactly as before. The signature also names the client request as DaemonWireRequest and the response as the kernel DaemonResponse instead of the daemon package aliases; only compile-time type names moved." }, { "declaration": "packages/remote/src/daemon-artifacts.ts#downloadRemoteArtifact", @@ -240,8 +241,8 @@ }, { "declaration": "packages/daemon/src/server/http/http-rpc-methods.ts#toLeaseDaemonRequest", - "digest": "sha256:e017795c86534feb8a7e6e53ffbd614db893aad20c5406b2bc53c771ee646948", - "rationale": "#2110 read the optional providerApp lease-allocation parameter into the existing flags bag; #2494 reads the full provider-allocation flag set into that same bag through the shared readLeaseAllocateProviderFlags projection, so the reconstructed req.flags handed to prepareSession match what the line transport forwards for free. Released protocol-2 clients omit these and follow the unchanged allocation path; no existing field is required or reinterpreted. The optional retainOnClose boolean parameter is read into meta.leaseRetainOnClose; a released daemon ignores it and keeps releasing on session close. Reads the optional providerCredentialFingerprint lease-allocation parameter into request meta, so a local caller over HTTP gets the same credential check as over the socket. A daemon with an auth hook treats every HTTP caller as remote and strips it, as it does developerDir. Released protocol-2 clients omit it and follow the unchanged allocation path; no existing field is required or reinterpreted. Reads or forwards the optional devicePin allocation parameter. Released clients omit it; older daemons ignore it. Existing fields keep their meanings under ADR 0006. Validates the optional devicePin metadata through the shared parser before dispatch. Existing valid pins and requests that omit a pin keep their request projection. Malformed pin objects now fail clearly with the existing INVALID_ARGS envelope and invalid_device_pin reason instead of a later TypeError. This repairs validation of an unreleased optional field; routes, authentication, framing, and existing fields are unchanged under ADR 0006." + "digest": "sha256:3e4211293791d67371ece10bf88a6f197598b399ece1041fc22e253691f3cdc2", + "rationale": "#2110 read the optional providerApp lease-allocation parameter into the existing flags bag; #2494 reads the full provider-allocation flag set into that same bag through the shared readLeaseAllocateProviderFlags projection, so the reconstructed req.flags handed to prepareSession match what the line transport forwards for free. Released protocol-2 clients omit these and follow the unchanged allocation path; no existing field is required or reinterpreted. The optional retainOnClose boolean parameter is read into meta.leaseRetainOnClose; a released daemon ignores it and keeps releasing on session close. Reads the optional providerCredentialFingerprint lease-allocation parameter into request meta, so a local caller over HTTP gets the same credential check as over the socket. A daemon with an auth hook treats every HTTP caller as remote and strips it, as it does developerDir. Released protocol-2 clients omit it and follow the unchanged allocation path; no existing field is required or reinterpreted. Reads or forwards the optional devicePin allocation parameter. Released clients omit it; older daemons ignore it. Existing fields keep their meanings under ADR 0006. Validates the optional devicePin metadata through the shared parser before dispatch. Existing valid pins and requests that omit a pin keep their request projection. Malformed pin objects now fail clearly with the existing INVALID_ARGS envelope and invalid_device_pin reason instead of a later TypeError. This repairs validation of an unreleased optional field; routes, authentication, framing, and existing fields are unchanged under ADR 0006. #4171 records a request that names no session in daemon-only request state: a missing or blank session, or meta.sessionExplicit false with no named flag. A missing name becomes default, a blank one keeps its literal as released daemons did, and the literal default from a client stays. Lease params gain an optional sessionExplicit, which a released daemon ignores. A released client that names no session on a provider lease through the command method now gets a normal INVALID_ARGS error with reason REMOTE_SESSION_REQUIRED, and no peer misreads a payload." }, { "declaration": "packages/kernel/src/errors.ts#DaemonError", @@ -296,7 +297,7 @@ { "declaration": "packages/daemon/src/server/http/http-authorization.ts#authorizeAuxiliaryHttpRequest", "digest": "sha256:1c323f97c3cefec8f95633b6abd127342bf75494bfb109d1cc6eadf3ceacaeae", - "rationale": "#2198 context: adds one optional field to the value this DAEMON-INTERNAL gate hands its own route handlers — sessionNamespace, the caller's tenant plus whether the daemon partitioned that caller's session names. Nothing about it is serialized: no request header is read that was not read before, no response field is added, and a refusal keeps the same 401 {ok:false,error,code} REST body sendRestJsonError already sent. What it enables is a refusal DROPPED, never one added — an unattested (client-declared) tenant no longer has the : prefix rule applied to it, because scopeRequestSession never applied that prefix to its sessions either. A released peer that now gets 200 where it got 401 is getting the ndjson record it asked for and already parses." + "rationale": "#2198 context: adds one optional field to the value this DAEMON-INTERNAL gate hands its own route handlers \u2014 sessionNamespace, the caller's tenant plus whether the daemon partitioned that caller's session names. Nothing about it is serialized: no request header is read that was not read before, no response field is added, and a refusal keeps the same 401 {ok:false,error,code} REST body sendRestJsonError already sent. What it enables is a refusal DROPPED, never one added \u2014 an unattested (client-declared) tenant no longer has the : prefix rule applied to it, because scopeRequestSession never applied that prefix to its sessions either. A released peer that now gets 200 where it got 401 is getting the ndjson record it asked for and already parses." }, { "declaration": "packages/daemon/src/server/request-diagnostics-http.ts#RequestDiagnosticsHttpAuthorizer", @@ -460,8 +461,8 @@ }, { "declaration": "packages/contracts/src/lease-scope.ts#buildLeaseRpcParams", - "digest": "sha256:365490a0fe1833d7ce8b0d3f5425462608a85119b12c1a2c4f16bb83b5d28e06", - "rationale": "The client names its request as DaemonWireRequest (packages/contracts/src/daemon-wire-request.ts, a narrowing of the listed kernel DaemonRequest) and its response as the kernel DaemonResponse, instead of the daemon package's DaemonRequest/DaemonResponse aliases, so the daemon package is no longer a client import. The declaration's serialized fields, method names and framing are unchanged; only the compile-time type names in its signature moved, so a peer on protocol 2 parses exactly what it did." + "digest": "sha256:25b138457410480048ee3899ce758cdd80bd7a4d11dc6e025f1365e7e8729116", + "rationale": "The client names its request as DaemonWireRequest (packages/contracts/src/daemon-wire-request.ts, a narrowing of the listed kernel DaemonRequest) and its response as the kernel DaemonResponse, instead of the daemon package's DaemonRequest/DaemonResponse aliases, so the daemon package is no longer a client import. The declaration's serialized fields, method names and framing are unchanged; only the compile-time type names in its signature moved, so a peer on protocol 2 parses exactly what it did. #4171 records a request that names no session in daemon-only request state: a missing or blank session, or meta.sessionExplicit false with no named flag. A missing name becomes default, a blank one keeps its literal as released daemons did, and the literal default from a client stays. Lease params gain an optional sessionExplicit, which a released daemon ignores. A released client that names no session on a provider lease through the command method now gets a normal INVALID_ARGS error with reason REMOTE_SESSION_REQUIRED, and no peer misreads a payload." }, { "declaration": "packages/daemon/src/server/http-errors.ts#statusCodeForNormalizedError", @@ -520,8 +521,8 @@ }, { "declaration": "packages/daemon/src/server/http/http-rpc-methods.ts#toInstallFromSourceDaemonRequest", - "digest": "sha256:071c53e7bd8e553cb9df820961294ed4d1e2e385053485364d895cb1777e9429", - "rationale": "Implementation-only validation repair: a supplied retentionMs is validated before request projection instead of silently dropping fractions or malformed values. Existing integer values in the supported 1..2147483647 range and omitted values keep their request projection, defaults, payload fields and response framing. Unsupported durations now fail clearly with the existing INVALID_ARGS envelope; released clients can parse that normal command error. No route, authentication, method or wire field changes; no protocol bump under ADR 0006." + "digest": "sha256:ed1ddf10113ac9c076b3fc0d08a77c12f22ac1ca98347f8f3f8271a5a0daf74e", + "rationale": "Implementation-only validation repair: a supplied retentionMs is validated before request projection instead of silently dropping fractions or malformed values. Existing integer values in the supported 1..2147483647 range and omitted values keep their request projection, defaults, payload fields and response framing. Unsupported durations now fail clearly with the existing INVALID_ARGS envelope; released clients can parse that normal command error. No route, authentication, method or wire field changes; no protocol bump under ADR 0006. #4171 records a request that names no session in daemon-only request state: a missing or blank session, or meta.sessionExplicit false with no named flag. A missing name becomes default, a blank one keeps its literal as released daemons did, and the literal default from a client stays. Lease params gain an optional sessionExplicit, which a released daemon ignores. A released client that names no session on a provider lease through the command method now gets a normal INVALID_ARGS error with reason REMOTE_SESSION_REQUIRED, and no peer misreads a payload." }, { "declaration": "packages/contracts/src/lease-scope.ts#buildDaemonRpcRequest", @@ -530,8 +531,8 @@ }, { "declaration": "packages/daemon/src/server/http/http-rpc-methods.ts#toDaemonRequest", - "digest": "sha256:d6afa5f8f1219e519e72bbd6fddd7de7763818f1ed7ae2a1e2a12001bd66bd52", - "rationale": "Validates the optional devicePin metadata through the shared parser before dispatch. Existing valid pins and requests that omit a pin keep their request projection. Malformed pin objects now fail clearly with the existing INVALID_ARGS envelope and invalid_device_pin reason instead of a later TypeError. This repairs validation of an unreleased optional field; routes, authentication, framing, and existing fields are unchanged under ADR 0006." + "digest": "sha256:14743424656a7a4097eb184d2be2c6272d0b1ff645591e4f4f9430d030789013", + "rationale": "Validates the optional devicePin metadata through the shared parser before dispatch. Existing valid pins and requests that omit a pin keep their request projection. Malformed pin objects now fail clearly with the existing INVALID_ARGS envelope and invalid_device_pin reason instead of a later TypeError. This repairs validation of an unreleased optional field; routes, authentication, framing, and existing fields are unchanged under ADR 0006. #4171 records a request that names no session in daemon-only request state: a missing or blank session, or meta.sessionExplicit false with no named flag. A missing name becomes default, a blank one keeps its literal as released daemons did, and the literal default from a client stays. Lease params gain an optional sessionExplicit, which a released daemon ignores. A released client that names no session on a provider lease through the command method now gets a normal INVALID_ARGS error with reason REMOTE_SESSION_REQUIRED, and no peer misreads a payload." }, { "declaration": "packages/contracts/src/device-inventory.ts#parseDevicePinSelector", @@ -557,6 +558,16 @@ "declaration": "packages/daemon/src/server/upload-http.ts#handleUploadPreflight", "digest": "sha256:8f9915c23fbf86903bee4db02e1b45aa835bc4d234c8e9a0fe4da5e67da8163e", "rationale": "#4434 passes the origin validated by the HTTP ingress owner, or the explicitly configured publicOrigin, into the existing ticket producer. Protocol-2 clients receive the same uploadId and upload URL/header object, use the returned absolute URL, and keep the existing byte, range, authentication and finalize contracts. Forwarding headers no longer select authority under the documented operator migration; no wire field becomes required or changes interpretation." + }, + { + "declaration": "packages/daemon/src/server/http/http-rpc-methods.ts#toReleaseMaterializedPathsDaemonRequest", + "digest": "sha256:a600285c173c95a75093c9eae65ee96df63d9524f7cc96c0479cf9884069f17c", + "rationale": "#4171 records a request that names no session in daemon-only request state: a missing or blank session, or meta.sessionExplicit false with no named flag. A missing name becomes default, a blank one keeps its literal as released daemons did, and the literal default from a client stays. Lease params gain an optional sessionExplicit, which a released daemon ignores. A released client that names no session on a provider lease through the command method now gets a normal INVALID_ARGS error with reason REMOTE_SESSION_REQUIRED, and no peer misreads a payload." + }, + { + "declaration": "packages/daemon/src/core/request-session-intake.ts#resolveRequestSessionAtIntake", + "digest": "sha256:d620b6ee56a8c2f74d2c161016fa19974cbc833e3b87fa522411e35b381d9bc9", + "rationale": "#4171 records a request that names no session in daemon-only request state: a missing or blank session, or meta.sessionExplicit false with no named flag. A missing name becomes default, a blank one keeps its literal as released daemons did, and the literal default from a client stays. Lease params gain an optional sessionExplicit, which a released daemon ignores. A released client that names no session on a provider lease through the command method now gets a normal INVALID_ARGS error with reason REMOTE_SESSION_REQUIRED, and no peer misreads a payload." } ] } diff --git a/test/wire-compat/surface.ts b/test/wire-compat/surface.ts index a434384d33..83096be183 100644 --- a/test/wire-compat/surface.ts +++ b/test/wire-compat/surface.ts @@ -263,6 +263,10 @@ export const WIRE_SURFACE: readonly WireSurfaceGroup[] = [ 'toInstallFromSourceDaemonRequest', 'toReleaseMaterializedPathsDaemonRequest', ), + ...from( + 'packages/daemon/src/core/request-session-intake.ts', + 'resolveRequestSessionAtIntake', + ), // Consumer side: the payload the client actually puts on the wire. A // client-only change here breaks an older daemon just as surely. ...from(CLIENT_RPC, 'buildHttpRpcPayload'), diff --git a/test/wire-compat/wire-mutations.test.ts b/test/wire-compat/wire-mutations.test.ts index 92340a37c4..9dbaeb948f 100644 --- a/test/wire-compat/wire-mutations.test.ts +++ b/test/wire-compat/wire-mutations.test.ts @@ -140,6 +140,13 @@ const MUTATIONS: readonly WireMutation[] = [ from: "'agent-device.lease.allocate': 'lease_allocate',", to: '', }, + { + breakClass: 'session intake: an unnamed request stops being marked as unnamed', + file: 'packages/daemon/src/core/request-session-intake.ts', + name: 'resolveRequestSessionAtIntake', + from: 'internal: { sessionOmitted: true }', + to: 'internal: {}', + }, { breakClass: 'response serialization: the RPC envelope stops being newline-framed', file: 'packages/daemon-contracts/src/request-progress-protocol.ts', diff --git a/tsdown.config.ts b/tsdown.config.ts index 5412d1a204..7357c19e9f 100644 --- a/tsdown.config.ts +++ b/tsdown.config.ts @@ -151,10 +151,16 @@ export default defineConfig({ hash: false, outputOptions: { codeSplitting: { - groups: publicSdkChunkGroups.flatMap(([name, dtsTest, jsTest]) => [ - { test: dtsTest, name: `${name}.d` }, - { test: jsTest, name }, - ]), + groups: [ + ...publicSdkChunkGroups.flatMap(([name, dtsTest, jsTest]) => [ + { test: dtsTest, name: `${name}.d` }, + { test: jsTest, name }, + ]), + { + test: /packages[\\/]contracts[\\/]src[\\/]replay-backend\.d\.[cm]?ts$/, + name: 'sdk-replay-backend.d', + }, + ], }, }, outExtensions: () => ({ js: '.js', dts: '.d.ts' }), diff --git a/website/docs/docs/aws-device-farm.md b/website/docs/docs/aws-device-farm.md index 5770ec8d24..0206b7b814 100644 --- a/website/docs/docs/aws-device-farm.md +++ b/website/docs/docs/aws-device-farm.md @@ -86,6 +86,7 @@ Configure the client directly when your Node.js process manages the AWS credenti import { createAgentDeviceClient } from 'agent-device'; const client = createAgentDeviceClient({ + session: 'checkout-android', leaseProvider: 'aws-device-farm', awsProjectArn: process.env.AWS_DEVICE_FARM_PROJECT_ARN, awsDeviceArn: process.env.AWS_DEVICE_FARM_DEVICE_ARN, diff --git a/website/docs/docs/browserstack.md b/website/docs/docs/browserstack.md index fd78e337b3..827916213e 100644 --- a/website/docs/docs/browserstack.md +++ b/website/docs/docs/browserstack.md @@ -93,6 +93,7 @@ Configure the client directly when your Node.js process manages the BrowserStack import { createAgentDeviceClient } from 'agent-device'; const client = createAgentDeviceClient({ + session: 'checkout-android', leaseProvider: 'browserstack', providerOsVersion: '14.0', providerApp: 'bs://app-id', diff --git a/website/docs/docs/build-an-integration.md b/website/docs/docs/build-an-integration.md index 6118f6b90a..c62354685e 100644 --- a/website/docs/docs/build-an-integration.md +++ b/website/docs/docs/build-an-integration.md @@ -35,7 +35,7 @@ Entry points for integrations: - `listAndroidAppsWithAdb(executor)` - `getAndroidAppStateWithAdb(executor)` - `runAdbShell(executor, words, options?)` / `runAdbExecOut(executor, words, options?)` - - `runAndroidShell(device, words, options?)` / `runAndroidExecOut(device, words, options?)` + - `runAndroidShell(device, words, host, options?)` / `runAndroidExecOut(device, words, host, options?)` - types: `AndroidAdbExecutor`, `AndroidAdbExecutorOptions`, `AndroidAdbProvider`, `AndroidKeyboardState`, `AndroidKeyboardDismissResult`, `AndroidPortReverseEndpoint` - `agent-device/batch` @@ -47,7 +47,7 @@ Entry points for integrations: - `buildBundleUrl(baseUrl, platform)` - `normalizeBaseUrl(baseUrl)` - `resolveRuntimeTransport(runtime)` - - `prepareMetroRuntime(options?)`, `reloadMetro(options?)`, `stopMetroTunnel(options)` + - `prepareMetroRuntime(options, host)`, `reloadMetro(options?)`, `stopMetroTunnel(options)` - types: `MetroBridgeDescriptor`, `MetroTunnelRequestMessage`, `MetroTunnelResponseMessage` - `agent-device/contracts` - `centerOfRect(rect)` @@ -74,9 +74,9 @@ Entry points for integrations: - `validateDownloadSourceUrl(url)` - types: `MaterializeInstallSource` - `agent-device/artifacts` - - `resolveAndroidArchivePackageName(archivePath)` + - `resolveAndroidArchivePackageName(archivePath, host, signal?)` - `agent-device/limrun` - - `new LimrunRuntime(options)` + - `new LimrunRuntime(options, host)` - `runtime.getDeviceSession(device)` - types: `LimrunRuntimeOptions`, `LimrunDeviceSession`, `LimrunAndroidDeviceSession`, `LimrunIosDeviceSession`, `LimrunIosCommandExecution` @@ -85,6 +85,21 @@ Entry points for integrations: - `agent-device/plugins` - experimental plugin contract: `AgentDevicePluginFactory` and `ProviderPluginHost`; see [provider plugins](./plugins.md). +## Migrate SDK hosts to 0.22 + +In 0.22, Android host ADB helpers, archive inspection, Metro preparation, and `LimrunRuntime` require an explicit `{ env, cwd }` host. `resolveRemoteConfigProfile` requires `env`, and `createLocalArtifactAdapter` requires `cwd`. Capture these values in your application's entry point and pass the same host to its operations: + +```ts +import { resolveAndroidArchivePackageName } from 'agent-device/artifacts'; +import { createLocalArtifactAdapter } from 'agent-device/io'; + +const host = { env: { ...process.env }, cwd: process.cwd() }; +const artifacts = createLocalArtifactAdapter({ cwd: host.cwd }); +const packageName = await resolveAndroidArchivePackageName('./app.apk', host); +``` + +Use separate hosts for integrations with different environments or working directories. Pass `env: {}` when profile resolution should use only the file's settings. `startAgentDevice({ stateDir })` still captures a host when you omit `host`. CLI and MCP entry points continue to capture their process host. + ## Android ADB providers Use `agent-device/android-adb` when your bridge owns Android device access and you want @@ -112,7 +127,7 @@ begins with `shell` or `exec-out` and did not come from those builders is refuse `details.reason: 'unguarded-device-shell-argv'` instead of being dispatched. A bridge that composes its own device commands calls `runAdbShell(executor, words, options?)` or `runAdbExecOut(executor, words, options?)` from `agent-device/android-adb`, passing each value as its -own word; `runAndroidShell(device, words, options?)` and `runAndroidExecOut(device, words, options?)` +own word; `runAndroidShell(device, words, host, options?)` and `runAndroidExecOut(device, words, host, options?)` resolve the executor from a device instead. ```ts @@ -143,9 +158,10 @@ Full example from [`examples/sdk/batch-orchestration.ts`](https://github.com/cal import { prepareMetroRuntime, reloadMetro, stopMetroTunnel } from 'agent-device/metro'; import { resolveRemoteConfigProfile } from 'agent-device/remote-config'; +const host = { env: { ...process.env }, cwd: process.cwd() }; const remoteConfig = resolveRemoteConfigProfile({ configPath: './agent-device.remote.json', - cwd: process.cwd(), + ...host, }); const prepared = await prepareMetroRuntime({ @@ -159,7 +175,7 @@ const prepared = await prepareMetroRuntime({ leaseId: remoteConfig.profile.leaseId!, }, companionProfileKey: remoteConfig.resolvedPath, -}); +}, host); console.log(prepared.iosRuntime, prepared.androidRuntime); diff --git a/website/docs/docs/client-api.md b/website/docs/docs/client-api.md index 3a5153203b..d5870559c4 100644 --- a/website/docs/docs/client-api.md +++ b/website/docs/docs/client-api.md @@ -32,7 +32,7 @@ Entry points for driving devices from Node.js: - `startAgentDevice(options)` - types: `AgentDeviceHost`, `StartAgentDeviceOptions` - `ensureDaemon(options?)` - - `createLocalArtifactAdapter(options?)` + - `createLocalArtifactAdapter({ cwd, rootDir?, tempDir? })` - `AppError`, `isAgentDeviceError(error)`, `normalizeAgentDeviceError(error)` - `isUnreadableCaptureContentError(error)`: true when an Android helper capture found no readable app content yet (`empty-helper-output`, `system-window-only`, `content-poor-app-window`), for @@ -47,7 +47,7 @@ Entry points for driving devices from Node.js: - types: `SnapshotNode`, `RawSnapshotNode`, `SnapshotState`, `Rect`, `Point` - types: `NormalizedError`, `AppErrorCode`, `KnownAppErrorCode`, `AppErrorDetails`, `ErrorCause` - `agent-device/io` - - `createLocalArtifactAdapter(options?)` + - `createLocalArtifactAdapter({ cwd, rootDir?, tempDir? })` - types: `ArtifactAdapter`, `ArtifactDescriptor`, `CreateTempFileOptions`, `FileInputRef`, `FileOutputRef`, `LocalArtifactAdapterOptions`, `OutputVisibility`, `ReserveOutputOptions`, `ReservedOutputFile`, `ResolveInputOptions`, `ResolvedInputFile`, `TemporaryFile` @@ -168,6 +168,7 @@ You drive Limrun, BrowserStack, AWS Device Farm, and TestMu AI devices with the import { createAgentDeviceClient } from 'agent-device'; const client = createAgentDeviceClient({ + session: 'checkout-android', leaseProvider: 'browserstack', providerOsVersion: '14.0', providerApp: 'bs://app-id', @@ -351,7 +352,7 @@ Domain client methods: - `client.sessions.list()`, `stateDir()`, `close()`, `saveScript()`, `artifacts()` - `client.apps.install()`, `reinstall()`, `uninstall()`, `installFromSource()`, `list()`, `open()`, `close()`, `push()`, `triggerEvent()` - `client.materializations.release()` -- `client.leases.allocate()`, `heartbeat()`, `release()`. Pass `retainOnClose: true` to `allocate()` when you release the lease yourself; session `close` then leaves it active until `release()`, expiry, or graceful daemon shutdown. The returned lease has `retainOnClose: true` only when the daemon honored it. Keep heartbeating a retained lease between sessions: it expires after its `ttlMs` like any other lease. On iOS simulators, a healthy idle XCTest runner can stay available between those sessions. Releasing or expiring the lease stops its runner unless a session outside the lease has taken over the device. Pass `leaseId` (16 to 128 hex characters) to `allocate()` to name a new lease with an id the daemon has never issued, or to get back your live lease with that id when you retry with the same tenant, run, client, lease backend, and provider (and no device, or the leased one), then use the returned `leaseId`: a run that already holds a lease gets that one back, and an older daemon mints its own. `allocate()` also tells you which of those you got, on the returned lease's `created`: `true` when your request created that lease, `false` when it was already there, and omitted on `heartbeat()` or when an older daemon does not support ownership evidence. The CLI releases an allocate response it discards before recording (a spec refusal, identity refusal, or keyless replacement), unless `created` is `false`. After binding, rollback on a later preparation failure requires `created:true`. Against an older daemon that omits `created`, refused or replaced leases are released, but a bound, unrecorded lease remains until expiry if preparation fails. `allocate()` with a `leaseProvider` the daemon has no runtime for fails with `UNSUPPORTED_OPERATION`, reason `provider-not-registered`, and `details.registeredProviders`; no lease is recorded. Leases with no provider, `proxy`, or `cloud` need no runtime. +- `client.leases.allocate()`, `heartbeat()`, `release()`. A client on a lease from a lease provider must name its session, or the daemon refuses it with reason `REMOTE_SESSION_REQUIRED`. Pass `retainOnClose: true` to `allocate()` when you release the lease yourself; session `close` then leaves it active until `release()`, expiry, or graceful daemon shutdown. The returned lease has `retainOnClose: true` only when the daemon honored it. Keep heartbeating a retained lease between sessions: it expires after its `ttlMs` like any other lease. On iOS simulators, a healthy idle XCTest runner can stay available between those sessions. Releasing or expiring the lease stops its runner unless a session outside the lease has taken over the device. Pass `leaseId` (16 to 128 hex characters) to `allocate()` to name a new lease with an id the daemon has never issued, or to get back your live lease with that id when you retry with the same tenant, run, client, lease backend, and provider (and no device, or the leased one), then use the returned `leaseId`: a run that already holds a lease gets that one back, and an older daemon mints its own. `allocate()` also tells you which of those you got, on the returned lease's `created`: `true` when your request created that lease, `false` when it was already there, and omitted on `heartbeat()` or when an older daemon does not support ownership evidence. The CLI releases an allocate response it discards before recording (a spec refusal, identity refusal, or keyless replacement), unless `created` is `false`. After binding, rollback on a later preparation failure requires `created:true`. Against an older daemon that omits `created`, refused or replaced leases are released, but a bound, unrecorded lease remains until expiry if preparation fails. `allocate()` with a `leaseProvider` the daemon has no runtime for fails with `UNSUPPORTED_OPERATION`, reason `provider-not-registered`, and `details.registeredProviders`; no lease is recorded. Leases with no provider, `proxy`, or `cloud` need no runtime. - `client.metro.prepare()`, `reload()` - `client.capture.snapshot()`, `screenshot()`, `diff()` - `client.interactions.gesture()`, `click()`, `press()`, `longPress()`, `swipe()`, `pan()`, `drag()`, `fling()`, `swipeGesture()`, `focus()`, `type()`, `fill()`, `scroll()`, `pinch()`, `rotateGesture()`, `transformGesture()`, `tapGesture()`, `get()`, `is()`, `find()` diff --git a/website/docs/docs/installation.md b/website/docs/docs/installation.md index bd9afb69dc..7840eaabd7 100644 --- a/website/docs/docs/installation.md +++ b/website/docs/docs/installation.md @@ -61,7 +61,11 @@ Nightly builds publish `main` after its CI passes, at most once per UTC day: npm install -g agent-device@nightly ``` -A nightly install's update notice recommends a newer nightly when an update check finds one. To +The `0.22` preview channel requires a separate activation and first successful publish. Once +available, install it with `npm install -g agent-device@nightly-0.22`. If npm reports that the tag +is missing, that channel has not published yet; use `@nightly` for `main` or `@latest` for stable. + +A nightly install's update notice follows the channel you installed, including `nightly-0.22`. To return to stable releases, install `agent-device@latest`. ## Without installing diff --git a/website/docs/docs/limrun.md b/website/docs/docs/limrun.md index 3c93401ab5..52599813a9 100644 --- a/website/docs/docs/limrun.md +++ b/website/docs/docs/limrun.md @@ -214,10 +214,11 @@ import { LimrunRuntime } from 'agent-device/limrun'; const apiKey = process.env.LIMRUN_API_KEY; if (!apiKey) throw new Error('LIMRUN_API_KEY is required'); -const runtime = new LimrunRuntime({ - apiKey, - region: process.env.LIMRUN_REGION, -}); +const host = { env: { ...process.env }, cwd: process.cwd() }; +const runtime = new LimrunRuntime( + { apiKey, region: process.env.LIMRUN_REGION }, + host, +); ``` To drive existing instances, pass `instances: { ios: { apiUrl, token } }` (Android also takes `adbUrl`), with or without `apiKey`. The runtime never creates or deletes instances for a platform listed there. @@ -247,7 +248,7 @@ const provider = { }; }, release: async (lease: { id: string }) => { - await createAgentDeviceClient({}).leases.release({ ...scope, leaseId: lease.id }); + await createAgentDeviceClient({ session: `lease-${lease.id}` }).leases.release({ ...scope, leaseId: lease.id }); }, }; ``` diff --git a/website/docs/docs/plugins.md b/website/docs/docs/plugins.md index d98f2cd4d1..72fa20b2e9 100644 --- a/website/docs/docs/plugins.md +++ b/website/docs/docs/plugins.md @@ -132,14 +132,31 @@ 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`. -## 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 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 +-{"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 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/website/docs/docs/remote-proxy.md b/website/docs/docs/remote-proxy.md index 86d93fcf0f..b8b920091c 100644 --- a/website/docs/docs/remote-proxy.md +++ b/website/docs/docs/remote-proxy.md @@ -46,6 +46,8 @@ agent-device disconnect Every command on a proxy connection must name its session, with `AGENT_DEVICE_SESSION`, `--session `, or a `session` in your config. The same applies to every device-cloud connection. A command that names none fails with `INVALID_ARGS` and `details.reason: "REMOTE_SESSION_REQUIRED"`, and sends nothing to the proxy. It never falls back to the connection that another agent on the same machine saved last. This includes `connect proxy` and `open --remote-config ` with a proxy profile. The client and run that the proxy leases under come from the session name, so two agents with different names never share a lease. +The daemon enforces the same rule for direct RPC callers. An `agent_device.command`, `agent_device.install_from_source`, or `agent_device.lease.*` request that would allocate, use, or release a lease from a lease provider fails with the same reason before anything is allocated or dispatched if it names no session. A request names no session when its `session` param is missing or blank. An `agent_device.command` request also names none when `meta.sessionExplicit` is `false` and no `flags.session` is set, and an `agent_device.lease.*` request when its `sessionExplicit` param is `false`. `agent_device.install_from_source` reads only `session`. `createAgentDeviceClient` sends that fact when you do not pass `session`. Requests with no lease provider keep their default session. + `--daemon-auth-token ` works instead of the environment variable, but it authenticates only the command you pass it to. Later commands need the token again through the environment variable, a `daemonAuthToken` entry in your remote config profile, or the flag on each command. `connect proxy` stores the proxy profile and client identity. `open` leases the device for you, and the lease expires after five minutes without commands. A lease allocated directly over the RPC without `ttlMs` gets the daemon's one-minute inactivity default instead. Either window starts when allocation completes, not when it was requested. `close` releases the active session and its device lease, unless the lease was allocated with `retainOnClose`; only `leases.release`, expiry, or daemon shutdown ends that one. The reply to any request that closed a session lists the leases it ended in `endedLeases`, as `{ leaseId, outcome: 'released' }`. This covers `close`, a `batch` with a close step, and a `replay` or `test` script that closes, as well as the session cleanup `test` runs after each script. A successful reply has the field in `data`, and a failed one has it in `error.details`. A gateway in front of the daemon reads the lease end from that reply. When the reply names the stored lease, the CLI forgets it, so the next `open` leases a device again. `disconnect` clears local connection state. diff --git a/website/docs/docs/revyl.md b/website/docs/docs/revyl.md index 46d0c84f88..49258f2f39 100644 --- a/website/docs/docs/revyl.md +++ b/website/docs/docs/revyl.md @@ -134,6 +134,7 @@ const host = await startAgentDevice({ }); const scope = { + session: 'checkout-ios', tenant: 'revyl', runId: process.env.GITHUB_RUN_ID ?? 'local-run', leaseBackend: 'ios-instance', diff --git a/website/docs/docs/testmu.md b/website/docs/docs/testmu.md index 1aa95a632b..4433c2c06a 100644 --- a/website/docs/docs/testmu.md +++ b/website/docs/docs/testmu.md @@ -158,6 +158,7 @@ The daemon reads `LT_USERNAME` and `LT_ACCESS_KEY` from its environment, unless import { createAgentDeviceClient } from 'agent-device'; const scope = { + session: 'checkout-ios', tenant: 'testmu', runId: process.env.GITHUB_RUN_ID ?? 'local-run', leaseBackend: 'ios-instance',