From 69bb6ba7a9b53887538cd527d6d72d85617e0c6a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Fri, 20 Nov 2026 17:52:39 +0100 Subject: [PATCH 01/26] refactor(limrun): ship Limrun as the @agent-device/limrun plugin Limrun leaves the core package. The runtime, the connection, the iOS runner orchestration, the file download and the Limrun SDK dependency now live in packages/provider-limrun, published as @agent-device/limrun and installed through `agent-device plugins add`. - Core adds device capabilities to every provider `setup` host: the Android lease interactor and ADB mechanics, the shared Apple XCTest runner with its tool-provider scope, and the host's retry and archive mechanics. Each facet loads on first use. - The Android interactor is the core-owned one, bound to the lease's provider-owned executor. A host that supplies no capabilities gets a typed `provider_host_capability_missing` failure. - `connect limrun` without the plugin answers `plugin-not-installed` with the install command. The built-in candidate, its reserved id and the `@limrun/api` bundling are removed. Part of #3311 --- LICENSES/xdelta3-wasm.txt | 23 -- THIRD_PARTY_NOTICES.md | 6 - examples/sdk/tsconfig.json | 1 + package.json | 2 +- packages/plugins/src/host.ts | 3 + packages/plugins/src/registry.ts | 16 +- packages/provider-limrun/README.md | 11 + packages/provider-limrun/package.json | 70 ++++-- .../provider-limrun/src/connection.test.ts | 3 +- packages/provider-limrun/src/connection.ts | 2 +- .../provider-limrun/src/download-file.test.ts | 2 +- .../provider-limrun/src/download-file.ts | 2 +- .../provider-limrun/src/host-dependencies.ts | 86 +++++++ packages/provider-limrun/src/host-entry.ts | 10 + packages/provider-limrun/src/index.ts | 13 +- packages/provider-limrun/src/internal.ts | 8 - .../provider-limrun/src/ios-app-logs.ts | 8 +- .../src/ios-application-tools.ts | 3 +- .../provider-limrun/src/ios-files.ts | 18 +- packages/provider-limrun/src/ios-host.ts | 19 ++ .../src/ios-runner-errors.test.ts | 2 +- .../provider-limrun/src/ios-runner-errors.ts | 0 .../src/ios-runner-products.test.ts | 30 ++- .../src/ios-runner-products.ts | 38 ++-- .../provider-limrun/src/ios-runner.ts | 81 +++---- .../provider-limrun/src/ios-tools.ts | 11 +- packages/provider-limrun/src/plugin.test.ts | 29 ++- packages/provider-limrun/src/plugin.ts | 45 ++-- packages/provider-limrun/src/runtime.ts | 2 + .../provider-limrun/test/package-smoke.mjs | 115 ++++++++++ packages/provider-limrun/tsconfig.json | 40 ++-- packages/provider-limrun/tsdown.config.ts | 12 + pnpm-lock.yaml | 29 ++- .../__tests__/bundled-license-notices.test.ts | 35 --- .../fixtures/bundled-license-build.mts | 1 - scripts/capability-matrix/collect.ts | 23 +- scripts/lib/bundled-license-notices.ts | 16 +- src/__tests__/cli-config-limrun.test.ts | 8 +- src/__tests__/cli-leased-session.test.ts | 6 + src/__tests__/cli-run-transport.test.ts | 6 + .../cloud-connect-profile-fields.test.ts | 33 ++- src/__tests__/cloud-connect-profile.test.ts | 6 + src/__tests__/cloud-connect-testmu.test.ts | 54 ----- ...daemon-client-provider-credentials.test.ts | 4 +- .../lease-provider-profile-fields.test.ts | 6 + src/__tests__/limrun-runtime.test.ts | 65 +++--- .../provider-device-runtimes.test.ts | 111 ++++----- src/__tests__/remote-connection.test.ts | 6 + .../test-utils/builtin-plugin-inventory.ts | 14 -- .../test-utils/limrun-plugin-inventory.ts | 9 + .../test-utils/limrun-plugin-store.ts | 30 +++ src/builtin-provider-ids.ts | 25 --- src/builtin-provider-plugins.test.ts | 212 ------------------ src/builtin-provider-plugins.ts | 71 ------ .../connection-runtime-shutdown.test.ts | 8 +- src/cli/commands/plugins.ts | 3 +- .../connection/connect-provider-adapters.ts | 20 +- src/cli/connection/ended-lease.test.ts | 13 +- .../provider-policy-limrun-absent.test.ts | 23 ++ src/cli/connection/provider-policy.test.ts | 17 +- src/cli/connection/provider-policy.ts | 25 +-- src/commands/provider-plugin-catalog.ts | 8 + src/commands/schema/cli-help-topics.test.ts | 3 +- src/commands/schema/cli-help.ts | 4 +- src/daemon-composition-credentials.test.ts | 8 +- src/daemon-runtime-limrun-public-http.test.ts | 2 +- src/host.test.ts | 8 +- src/platform-runtime-gateway.fixtures.ts | 6 +- src/platform-runtime-gateway.test.ts | 2 +- src/provider-credential-fingerprint.test.ts | 24 +- src/provider-device-runtimes.test.ts | 6 + src/provider-device-runtimes.ts | 11 +- ...-capabilities-android-performance.test.ts} | 6 +- ...ugin-host-capabilities-host-scope.test.ts} | 12 +- ...-capabilities-limrun-ios-app-logs.test.ts} | 9 +- ...capabilities-limrun-ios-files.fixtures.ts} | 0 ...ost-capabilities-limrun-ios-files.test.ts} | 30 +-- ...bilities-limrun-ios-runner-parity.test.ts} | 6 +- ...st-capabilities-limrun-ios-runner.test.ts} | 2 +- ...ost-capabilities-limrun-ios-tools.test.ts} | 24 +- ...-host-capabilities-limrun-ios.fixtures.ts} | 17 +- ...vider-plugin-host-capabilities.fixtures.ts | 43 ++++ ...provider-plugin-host-capabilities.test.ts} | 20 +- src/provider-plugin-host-capabilities.ts | 160 +++++++++++++ src/provider-plugin-policy.ts | 5 +- src/sdk/limrun-runtime-dependencies.ts | 150 ------------- src/sdk/plugin-device-host.ts | 148 ++++++++++++ .../installed-package-metro.test.ts | 6 +- .../limrun-android-performance.test.ts | 6 +- ...limrun-deployment-cancellation.fixtures.ts | 2 +- .../limrun-ios-appstate.test.ts | 10 +- .../limrun-ios-settings.test.ts | 8 +- .../limrun-ios-snapshot-owner.test.ts | 10 +- .../stale-provider-runtime-admission.test.ts | 2 +- tsconfig.json | 3 +- tsdown.config.ts | 40 +--- website/docs/docs/device-clouds.md | 4 +- website/docs/docs/limrun.md | 27 ++- website/docs/docs/plugins.md | 8 +- 99 files changed, 1322 insertions(+), 1108 deletions(-) delete mode 100644 LICENSES/xdelta3-wasm.txt create mode 100644 packages/provider-limrun/README.md rename src/core/limrun-download-file.test.ts => packages/provider-limrun/src/download-file.test.ts (99%) rename src/core/limrun-download-file.ts => packages/provider-limrun/src/download-file.ts (98%) create mode 100644 packages/provider-limrun/src/host-dependencies.ts create mode 100644 packages/provider-limrun/src/host-entry.ts delete mode 100644 packages/provider-limrun/src/internal.ts rename src/core/interactors/limrun-ios-app-logs.ts => packages/provider-limrun/src/ios-app-logs.ts (93%) rename src/core/interactors/limrun-ios-application-tools.ts => packages/provider-limrun/src/ios-application-tools.ts (97%) rename src/core/interactors/limrun-ios-files.ts => packages/provider-limrun/src/ios-files.ts (93%) create mode 100644 packages/provider-limrun/src/ios-host.ts rename src/core/interactors/limrun-ios-runner-errors.test.ts => packages/provider-limrun/src/ios-runner-errors.test.ts (95%) rename src/core/interactors/limrun-ios-runner-errors.ts => packages/provider-limrun/src/ios-runner-errors.ts (100%) rename src/core/interactors/limrun-ios-runner-products.test.ts => packages/provider-limrun/src/ios-runner-products.test.ts (89%) rename src/core/interactors/limrun-ios-runner-products.ts => packages/provider-limrun/src/ios-runner-products.ts (92%) rename src/core/interactors/limrun-ios-runner.ts => packages/provider-limrun/src/ios-runner.ts (81%) rename src/core/interactors/limrun-ios-tools.ts => packages/provider-limrun/src/ios-tools.ts (92%) create mode 100644 packages/provider-limrun/test/package-smoke.mjs create mode 100644 packages/provider-limrun/tsdown.config.ts delete mode 100644 src/__tests__/test-utils/builtin-plugin-inventory.ts create mode 100644 src/__tests__/test-utils/limrun-plugin-inventory.ts create mode 100644 src/__tests__/test-utils/limrun-plugin-store.ts delete mode 100644 src/builtin-provider-ids.ts delete mode 100644 src/builtin-provider-plugins.test.ts delete mode 100644 src/builtin-provider-plugins.ts create mode 100644 src/cli/connection/provider-policy-limrun-absent.test.ts rename src/{sdk/limrun-runtime-dependencies-android-performance.test.ts => provider-plugin-host-capabilities-android-performance.test.ts} (93%) rename src/{sdk/limrun-runtime-dependencies-host-scope.test.ts => provider-plugin-host-capabilities-host-scope.test.ts} (90%) rename src/{core/interactors/limrun-ios-app-logs.test.ts => provider-plugin-host-capabilities-limrun-ios-app-logs.test.ts} (93%) rename src/{core/interactors/limrun-ios-files.fixtures.ts => provider-plugin-host-capabilities-limrun-ios-files.fixtures.ts} (100%) rename src/{core/interactors/limrun-ios-files.test.ts => provider-plugin-host-capabilities-limrun-ios-files.test.ts} (91%) rename src/{core/interactors/limrun-ios-runner-parity.test.ts => provider-plugin-host-capabilities-limrun-ios-runner-parity.test.ts} (96%) rename src/{core/interactors/limrun-ios-runner.test.ts => provider-plugin-host-capabilities-limrun-ios-runner.test.ts} (99%) rename src/{core/interactors/limrun-ios-tools.test.ts => provider-plugin-host-capabilities-limrun-ios-tools.test.ts} (94%) rename src/{core/interactors/limrun-ios-runner.fixtures.ts => provider-plugin-host-capabilities-limrun-ios.fixtures.ts} (95%) create mode 100644 src/provider-plugin-host-capabilities.fixtures.ts rename src/{sdk/limrun-runtime-dependencies.test.ts => provider-plugin-host-capabilities.test.ts} (88%) create mode 100644 src/provider-plugin-host-capabilities.ts delete mode 100644 src/sdk/limrun-runtime-dependencies.ts create mode 100644 src/sdk/plugin-device-host.ts diff --git a/LICENSES/xdelta3-wasm.txt b/LICENSES/xdelta3-wasm.txt deleted file mode 100644 index 07c2ac68d3..0000000000 --- a/LICENSES/xdelta3-wasm.txt +++ /dev/null @@ -1,23 +0,0 @@ -@limrun/xdelta3-wasm 0.2.0 source-file notices - -The published package declares Apache-2.0 but omits the license text. -Package source: https://github.com/limrun-inc/typescript-sdk/tree/main/packages/xdelta3-wasm -Native source: https://github.com/jmacd/xdelta/tree/7508fd2a823443b1f0173ca361620f21d62a7d37/xdelta3 - -xdelta3 - delta compression tools and library - Copyright 2016 Joshua MacDonald - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - - -Full Apache-2.0 license follows in THIRD_PARTY_NOTICES.txt. diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md index be02cf24e8..7d8868279c 100644 --- a/THIRD_PARTY_NOTICES.md +++ b/THIRD_PARTY_NOTICES.md @@ -15,12 +15,6 @@ the package-level BSD license. These are retained in [`LICENSES/jpeg-js.txt`](LICENSES/jpeg-js.txt) and included with the Apache License 2.0 in the generated notice file whenever `jpeg-js` is bundled. -`@limrun/xdelta3-wasm` 0.2.0 omits license files from its npm archive. Its Apache-2.0 -license text and xdelta3 source attribution are retained through -[`LICENSES/xdelta3-wasm.txt`](LICENSES/xdelta3-wasm.txt) and -[`LICENSES/Apache-2.0.txt`](LICENSES/Apache-2.0.txt). The build verifies the package -version before including these notices. - ## Maestro conformance fixtures The 42 upstream flows in `scripts/maestro-conformance/corpus/upstream/` are copied diff --git a/examples/sdk/tsconfig.json b/examples/sdk/tsconfig.json index 0752b6f6b1..0b1044af7f 100644 --- a/examples/sdk/tsconfig.json +++ b/examples/sdk/tsconfig.json @@ -15,6 +15,7 @@ "agent-device/android-adb": ["../../src/sdk/android-adb.ts"], "agent-device/plugins": ["../../src/sdk/plugins.ts"], "agent-device/plugins/webdriver": ["../../src/sdk/plugin-webdriver.ts"], + "agent-device/plugins/device-host": ["../../src/sdk/plugin-device-host.ts"], "agent-device/contracts": ["../../src/sdk/contracts.ts"], "agent-device/finders": ["../../src/sdk/finders.ts"], "agent-device/selectors": ["../../src/sdk/selectors.ts"], diff --git a/package.json b/package.json index efedadf00c..1205afddc1 100644 --- a/package.json +++ b/package.json @@ -321,10 +321,10 @@ "@agent-device/host-kit": "workspace:*", "@agent-device/host-swift": "workspace:*", "@agent-device/kernel": "workspace:*", + "@agent-device/limrun": "workspace:*", "@agent-device/platform-android": "workspace:*", "@agent-device/platform-apple": "workspace:*", "@agent-device/plugins": "workspace:*", - "@agent-device/provider-limrun": "workspace:*", "@agent-device/provider-webdriver": "workspace:*", "@agent-device/provision-kit": "workspace:*", "@agent-device/proxy": "workspace:*", diff --git a/packages/plugins/src/host.ts b/packages/plugins/src/host.ts index 0fc8ff3312..ce8a20d5aa 100644 --- a/packages/plugins/src/host.ts +++ b/packages/plugins/src/host.ts @@ -32,8 +32,11 @@ export type ReplaySetupHost = Readonly<{ export function createPluginHost( host: HostEnvironment, options: Record | undefined, + capabilities?: object, ): ProviderPluginHost { return Object.freeze({ + // The composing root's own additions, such as platform facets; this package names none. + ...capabilities, env: Object.freeze({ ...host.env }), options: Object.freeze({ ...options }), clientVersion: readVersion(), diff --git a/packages/plugins/src/registry.ts b/packages/plugins/src/registry.ts index 9ec2927180..1565c73cbb 100644 --- a/packages/plugins/src/registry.ts +++ b/packages/plugins/src/registry.ts @@ -91,6 +91,8 @@ export function claimProviderIds(providers: readonly string[]): PluginCandidate[ export type PluginRegistryPolicy = Readonly<{ platformHost?: PlatformHost; assertSelectionCurrent?(packageName: string): void; + /** What the root adds to every provider `setup` host, such as its platform facets. */ + hostCapabilities?(host: HostEnvironment): object | Promise; adaptWebDriver( descriptor: WebDriverDescriptor, context: Readonly<{ clientVersion: string }>, @@ -609,12 +611,8 @@ async function cleanUpClaim(claim: Claim): Promise { }; } -/** - * A plugin's connection with the host it declares added to each context. Exported for the composing - * root: a built-in provider wires its plugin's callbacks to a CLI call through the same helper the - * registry uses, so both answer `connect` identically. - */ -export function withConnectionHost( +/** A plugin's connection with the host it declares added to each context. */ +function withConnectionHost( connection: PluginConnection, hostOptions: Record | undefined, ): RegisteredConnection { @@ -639,7 +637,11 @@ async function setUpProviderClaim( host: HostEnvironment, policy: PluginRegistryPolicy, ): Promise { - const pluginHost = createPluginHost(host, claim.slot.candidate.hostOptions); + const pluginHost = createPluginHost( + host, + claim.slot.candidate.hostOptions, + await policy.hostCapabilities?.(host), + ); const result = await contribution.setup(pluginHost); try { const { runtime, platformModule } = await buildRegistration( diff --git a/packages/provider-limrun/README.md b/packages/provider-limrun/README.md new file mode 100644 index 0000000000..f7d591a18b --- /dev/null +++ b/packages/provider-limrun/README.md @@ -0,0 +1,11 @@ +# Limrun for agent-device + +Install the plugin on the daemon host. + +```sh +agent-device plugins add @agent-device/limrun@nightly-0.22 +``` + +Run `agent-device help remote` to see the install command for your CLI. + +Set `LIMRUN_API_KEY`, or the `LIM_*_INSTANCE_*` variables of an existing instance, then connect with `agent-device connect limrun --platform android` or `--platform ios`. See the [Limrun guide](https://agent-device.dev/docs/limrun). diff --git a/packages/provider-limrun/package.json b/packages/provider-limrun/package.json index 9fa20ff969..2e08d700c2 100644 --- a/packages/provider-limrun/package.json +++ b/packages/provider-limrun/package.json @@ -1,6 +1,6 @@ { - "name": "@agent-device/provider-limrun", - "version": "0.0.0", + "name": "@agent-device/limrun", + "version": "0.22.0-dev", "engines": { "node": ">=22.12" }, @@ -10,27 +10,67 @@ }, "private": true, "type": "module", - "description": "Limrun provider runtime for agent-device. Internal workspace package bundled into the published artifact.", - "dependencies": { - "@agent-device/capture-kit": "workspace:*", - "@agent-device/contracts": "workspace:*", - "@agent-device/kernel": "workspace:*", - "@agent-device/platform-android": "workspace:*", - "@agent-device/plugins": "workspace:*" + "description": "Limrun Android instance and iOS simulator plugin for agent-device.", + "files": [ + "dist" + ], + "scripts": { + "build": "tsdown --config tsdown.config.ts", + "prepack": "pnpm build" }, "exports": { ".": { "types": "./src/index.ts", "default": "./src/index.ts" }, - "./internal": { - "types": "./src/internal.ts", - "default": "./src/internal.ts" - } + "./agent-device": { + "types": "./src/index.ts", + "default": "./src/index.ts" + }, + "./runtime": { + "types": "./src/runtime.ts", + "default": "./src/runtime.ts" + }, + "./host": { + "types": "./src/host-entry.ts", + "default": "./src/host-entry.ts" + }, + "./package.json": "./package.json" + }, + "dependencies": { + "@limrun/api": "^0.69.1" }, "devDependencies": { + "@agent-device/build-config": "workspace:*", + "@agent-device/capture-kit": "workspace:*", + "@agent-device/contracts": "workspace:*", + "@agent-device/host-kit": "workspace:*", + "@agent-device/kernel": "workspace:*", + "@agent-device/platform-android": "workspace:*", "@agent-device/platform-apple": "workspace:*", "@agent-device/test-kit": "workspace:*", - "@limrun/api": "^0.69.1" - } + "@agent-device/xml": "workspace:*", + "agent-device": "workspace:*" + }, + "publishConfig": { + "exports": { + ".": { + "types": "./dist/agent-device.d.mts", + "import": "./dist/agent-device.mjs" + }, + "./agent-device": { + "types": "./dist/agent-device.d.mts", + "import": "./dist/agent-device.mjs" + }, + "./package.json": "./package.json" + }, + "access": "public" + }, + "license": "MIT", + "repository": { + "type": "git", + "url": "git+https://github.com/callstack/agent-device.git", + "directory": "packages/provider-limrun" + }, + "homepage": "https://agent-device.dev/docs/limrun" } diff --git a/packages/provider-limrun/src/connection.test.ts b/packages/provider-limrun/src/connection.test.ts index d64ced10cf..82835f7140 100644 --- a/packages/provider-limrun/src/connection.test.ts +++ b/packages/provider-limrun/src/connection.test.ts @@ -1,7 +1,6 @@ import assert from 'node:assert/strict'; import { afterEach, test, vi } from 'vitest'; -import type { PluginConnectionContext } from '@agent-device/plugins/contract'; -import type { ProviderPluginHost } from '@agent-device/plugins/host'; +import type { PluginConnectionContext, ProviderPluginHost } from 'agent-device/plugins'; import { AppError } from '@agent-device/kernel/errors'; import { createLimrunConnection } from './connection.ts'; import { LIMRUN_CONNECTION_CAPABILITIES } from './device.ts'; diff --git a/packages/provider-limrun/src/connection.ts b/packages/provider-limrun/src/connection.ts index 681397d9a8..9049888e0e 100644 --- a/packages/provider-limrun/src/connection.ts +++ b/packages/provider-limrun/src/connection.ts @@ -1,6 +1,6 @@ import crypto from 'node:crypto'; import type { RemoteConfigProfile } from '@agent-device/contracts/remote'; -import type { PluginConnection, PluginConnectionContext } from '@agent-device/plugins/contract'; +import type { PluginConnection, PluginConnectionContext } from 'agent-device/plugins'; import { rejectRefusedProviderProfileFields, requireResolvedProfilePlatform, diff --git a/src/core/limrun-download-file.test.ts b/packages/provider-limrun/src/download-file.test.ts similarity index 99% rename from src/core/limrun-download-file.test.ts rename to packages/provider-limrun/src/download-file.test.ts index 324128028c..5cadd5bcca 100644 --- a/src/core/limrun-download-file.test.ts +++ b/packages/provider-limrun/src/download-file.test.ts @@ -5,7 +5,7 @@ import type { AddressInfo } from 'node:net'; import { afterEach, expect, test, vi } from 'vitest'; import { AppError, createRequestCanceledError } from '@agent-device/kernel/errors'; import { mkdtempForTest } from '@agent-device/test-kit'; -import { downloadLimrunFile } from './limrun-download-file.ts'; +import { downloadLimrunFile } from './download-file.ts'; const servers: http.Server[] = []; diff --git a/src/core/limrun-download-file.ts b/packages/provider-limrun/src/download-file.ts similarity index 98% rename from src/core/limrun-download-file.ts rename to packages/provider-limrun/src/download-file.ts index 52f5e5b59f..d9cf6ee7d1 100644 --- a/src/core/limrun-download-file.ts +++ b/packages/provider-limrun/src/download-file.ts @@ -4,7 +4,7 @@ import { Readable } from 'node:stream'; import { pipeline } from 'node:stream/promises'; import type { ReadableStream as WebReadableStream } from 'node:stream/web'; import { AppError, createRequestCanceledError } from '@agent-device/kernel/errors'; -import type { LimrunFileDownload } from '@agent-device/provider-limrun'; +import type { LimrunFileDownload } from './runtime-dependencies.ts'; const RESPONSE_BODY_PREVIEW_BYTES = 500; diff --git a/packages/provider-limrun/src/host-dependencies.ts b/packages/provider-limrun/src/host-dependencies.ts new file mode 100644 index 0000000000..5965667620 --- /dev/null +++ b/packages/provider-limrun/src/host-dependencies.ts @@ -0,0 +1,86 @@ +import type { + DeviceProviderPluginHost, + ProviderHostCapabilities, +} from 'agent-device/plugins/device-host'; +import { createLimrunIosAppLogReader } from './ios-app-logs.ts'; +import type { LimrunIosHost } from './ios-host.ts'; +import type { LimrunRuntimeDependencies } from './runtime-dependencies.ts'; + +/** The `error.details.reason` values a Limrun host refusal publishes. */ +const LIMRUN_HOST_REASONS = { + capabilityMissing: 'provider_host_capability_missing', +} as const satisfies Record; + +/** + * Answers what the runtime asks for from the host it is set up on. The Android interactor, the ADB + * mechanics and the shared XCTest runner are the host's own, bound here to the executor or the + * simulator this provider reaches its lease through. The Android facet loads with the runtime + * because `getInteractor` answers synchronously; the Apple facet loads with the first iOS lease. + */ +export async function createLimrunRuntimeDependencies( + host: DeviceProviderPluginHost, +): Promise { + const { emitDiagnostic, loadAndroid, loadApple, loadHostKit } = requireHostCapabilities(host); + const android = await loadAndroid(); + const loadIosHost = async (): Promise => { + const [apple, kit] = await Promise.all([loadApple(), loadHostKit()]); + return { + apple, + kit, + env: host.env, + clientVersion: host.clientVersion, + emitDiagnostic, + }; + }; + return { + clientVersion: host.clientVersion, + android: { + bindPerformance: android.bindPerformance, + bindDeployment: android.bindDeployment, + createInteractor: android.createLeaseInteractor, + createPortReverse: async (adb, options) => android.createPortReverse(adb, options), + inferAppName: async (packageName) => android.inferAppName(packageName), + listApps: android.listApps, + getForegroundApp: async (_device, adb, signal) => await android.getForegroundApp(adb, signal), + getKeyboardState: android.getKeyboardState, + dismissKeyboard: android.dismissKeyboard, + readLogs: android.readLogs, + forceStopApp: android.forceStopApp, + deviceAdbInvocation: android.deviceAdbInvocation, + hostAdbInvocation: android.hostAdbInvocation, + adbError: async (message, result, invocation) => + android.adbError(message, result, invocation), + }, + host: { + runAdb: android.runAdb, + downloadFile: async (options) => { + const { downloadLimrunFile } = await import('./download-file.ts'); + await downloadLimrunFile(options); + }, + }, + ios: { + createAppLogReader: (input) => + createLimrunIosAppLogReader(input, async () => (await loadApple()).tools.parsePlist), + createRunner: async (session) => { + const { createLimrunIosRunner } = await import('./ios-runner.ts'); + return await createLimrunIosRunner(session, await loadIosHost()); + }, + readBundleAppName: async (appPath) => await (await loadApple()).readBundleAppName(appPath), + }, + }; +} + +/** The capabilities the daemon and `startAgentDevice` add to a `setup` host; refuses a host without them. */ +function requireHostCapabilities(host: DeviceProviderPluginHost): ProviderHostCapabilities { + const { stateDir, emitDiagnostic, loadAndroid, loadApple, loadHostKit } = host; + if (stateDir !== undefined && emitDiagnostic && loadAndroid && loadApple && loadHostKit) + return { stateDir, emitDiagnostic, loadAndroid, loadApple, loadHostKit }; + throw host.createError( + 'UNSUPPORTED_OPERATION', + 'This agent-device host does not provide the device capabilities Limrun needs.', + { + reason: LIMRUN_HOST_REASONS.capabilityMissing, + hint: 'Run Limrun through the agent-device daemon or startAgentDevice of a matching release.', + }, + ); +} diff --git a/packages/provider-limrun/src/host-entry.ts b/packages/provider-limrun/src/host-entry.ts new file mode 100644 index 0000000000..6ad6b6c5eb --- /dev/null +++ b/packages/provider-limrun/src/host-entry.ts @@ -0,0 +1,10 @@ +/** + * The host-facing half of the plugin, for this repository's own suites: they drive the adapters the + * plugin builds from a `setup` host, and the iOS runner, over the root's real host capabilities + * without installing the plugin. The published package exports only the plugin factory. + */ +export { createLimrunRuntimeDependencies } from './host-dependencies.ts'; +export { createLimrunIosRunner } from './ios-runner.ts'; +export { createLimrunAppleToolProvider } from './ios-tools.ts'; +export { createLimrunAppleApplicationTools } from './ios-application-tools.ts'; +export type { LimrunIosHost } from './ios-host.ts'; diff --git a/packages/provider-limrun/src/index.ts b/packages/provider-limrun/src/index.ts index 5d05533253..d5b2ee50cb 100644 --- a/packages/provider-limrun/src/index.ts +++ b/packages/provider-limrun/src/index.ts @@ -1,3 +1,12 @@ -export { createLimrunRuntime, type LimrunRuntimeOptions } from './runtime.ts'; +import type { ProviderAgentDevicePlugin } from 'agent-device/plugins'; +import { limrunPlugin } from './plugin.ts'; -export type { LimrunFileDownload, LimrunRuntimeDependencies } from './runtime-dependencies.ts'; +/** + * Limrun as a plugin: Android instances and iOS simulators rented from the Limrun API. Credentials + * come from `LIMRUN_API_KEY`, or from the `LIM_*_INSTANCE_*` variables of an existing instance. + */ +function limrun(): ProviderAgentDevicePlugin { + return limrunPlugin(); +} + +export { limrun as default }; diff --git a/packages/provider-limrun/src/internal.ts b/packages/provider-limrun/src/internal.ts deleted file mode 100644 index b71d335c7e..0000000000 --- a/packages/provider-limrun/src/internal.ts +++ /dev/null @@ -1,8 +0,0 @@ -/** - * The seam core composes Limrun through while the provider is still built in. Nothing here loads the - * Limrun SDK: the runtime, the platform adapters, and the connection's verification each load when - * their own path asks for them. The root entry keeps the SDK-side surface. - */ -export { limrunPlugin, LIMRUN_CONNECTION, type LimrunPluginOptions } from './plugin.ts'; -export { LIMRUN_CONNECTION_CAPABILITIES } from './device.ts'; -export { readLimrunCredentials } from './credentials.ts'; diff --git a/src/core/interactors/limrun-ios-app-logs.ts b/packages/provider-limrun/src/ios-app-logs.ts similarity index 93% rename from src/core/interactors/limrun-ios-app-logs.ts rename to packages/provider-limrun/src/ios-app-logs.ts index b12c98ff29..9dc257ef62 100644 --- a/src/core/interactors/limrun-ios-app-logs.ts +++ b/packages/provider-limrun/src/ios-app-logs.ts @@ -1,13 +1,15 @@ import { awaitWithSignal } from '@agent-device/kernel/await-with-signal'; -import type { LimrunRuntimeDependencies } from '@agent-device/provider-limrun'; +import type { LimrunRuntimeDependencies } from './runtime-dependencies.ts'; import type { ProviderAppLogReader } from '@agent-device/capture-kit/provider-app-log'; import type { LogStream } from '@limrun/api/ios-client'; +import type { LimrunIosHost } from './ios-host.ts'; const MAX_LOG_BYTES = 1024 * 1024; /** Keeps app console and filtered unified logs in one bounded tail for the shared log collector. */ export function createLimrunIosAppLogReader( input: Parameters[0], + loadPlistParser: () => Promise, ): ProviderAppLogReader { const lifetime = new AbortController(); let active: { app: string; controller: AbortController; streams: LogStream[] } | undefined; @@ -65,8 +67,8 @@ export function createLimrunIosAppLogReader( // Metadata can outlive a short poll, but never the app's streams or the reader. const pending = (async () => { try { - const { readLimrunAppInfo } = await import('./limrun-ios-files.ts'); - const info = await readLimrunAppInfo(input, app, signal); + const { readLimrunAppInfo } = await import('./ios-files.ts'); + const info = await readLimrunAppInfo(input, await loadPlistParser(), app, signal); if (active !== owned) return; executable = typeof info?.CFBundleExecutable === 'string' ? info.CFBundleExecutable : undefined; diff --git a/src/core/interactors/limrun-ios-application-tools.ts b/packages/provider-limrun/src/ios-application-tools.ts similarity index 97% rename from src/core/interactors/limrun-ios-application-tools.ts rename to packages/provider-limrun/src/ios-application-tools.ts index 1646047ebd..3e548ca04b 100644 --- a/src/core/interactors/limrun-ios-application-tools.ts +++ b/packages/provider-limrun/src/ios-application-tools.ts @@ -1,7 +1,7 @@ import type { AppleApplicationTools } from '@agent-device/contracts/application-lifecycle-runtime'; import type { DeviceInfo } from '@agent-device/kernel/device'; import { AppError } from '@agent-device/kernel/errors'; -import { emitDiagnostic } from '@agent-device/host-kit/diagnostics'; +import type { LimrunIosHost } from './ios-host.ts'; type RunnerLifecycle = { prepareCache(signal?: AbortSignal): Promise; @@ -27,6 +27,7 @@ export function createLimrunAppleApplicationTools( AppleApplicationTools, 'resolveOpenTarget' | 'applyRuntimeHints' | 'clearRuntimeHints' >, + emitDiagnostic: LimrunIosHost['emitDiagnostic'], ): AppleApplicationTools { const requireDevice = (target: DeviceInfo | string) => { if ((typeof target === 'string' ? target : target.id) !== device.id) diff --git a/src/core/interactors/limrun-ios-files.ts b/packages/provider-limrun/src/ios-files.ts similarity index 93% rename from src/core/interactors/limrun-ios-files.ts rename to packages/provider-limrun/src/ios-files.ts index 9ad197b71d..307cf34c45 100644 --- a/src/core/interactors/limrun-ios-files.ts +++ b/packages/provider-limrun/src/ios-files.ts @@ -2,20 +2,23 @@ import { promises as fs } from 'node:fs'; import os from 'node:os'; import path from 'node:path'; import { randomUUID } from 'node:crypto'; -import { - type AppleToolProvider, - type AppleToolExecOptions, +import type { + AppleToolProvider, + AppleToolExecOptions, } from '@agent-device/platform-apple/tool-provider'; -import type { LimrunRuntimeDependencies } from '@agent-device/provider-limrun'; +import type { LimrunRuntimeDependencies } from './runtime-dependencies.ts'; import { AppError, createRequestCanceledError } from '@agent-device/kernel/errors'; -import { downloadLimrunFile } from '../limrun-download-file.ts'; +import { downloadLimrunFile } from './download-file.ts'; +import type { LimrunIosHost } from './ios-host.ts'; type Session = Parameters[0]; type Files = AppleToolProvider['simulatorFiles']; +type ParsePlist = LimrunIosHost['apple']['tools']['parsePlist']; type Container = Parameters[0]; export function createLimrunSimulatorFiles( session: Session, + parsePlist: ParsePlist, lifetime: AbortSignal, requestSignal?: AbortSignal, ): { simulatorFiles: Files; readInfoPlist: AppleToolProvider['simulatorApps']['readInfoPlist'] } { @@ -161,6 +164,7 @@ export function createLimrunSimulatorFiles( if (metadata.has(key)) return metadata.get(key)!; const info = await readLimrunAppInfo( session, + parsePlist, input.bundleId, signalFor(input.signal), input.timeoutMs, @@ -173,6 +177,7 @@ export function createLimrunSimulatorFiles( export async function readLimrunAppInfo( access: { apiUrl: string; token: string }, + parsePlist: ParsePlist, bundleId: string, signal: AbortSignal, timeoutMs = 15_000, @@ -193,8 +198,7 @@ export async function readLimrunAppInfo( timeoutMs, signal, }); - const { parseApplePlist } = await import('@agent-device/platform-apple/tool-provider'); - return await parseApplePlist(await fs.readFile(destinationPath, { signal })); + return await parsePlist(await fs.readFile(destinationPath, { signal })); } catch (error) { if (error instanceof AppError && error.details?.statusCode === 404) return null; throw error; diff --git a/packages/provider-limrun/src/ios-host.ts b/packages/provider-limrun/src/ios-host.ts new file mode 100644 index 0000000000..639886a4ce --- /dev/null +++ b/packages/provider-limrun/src/ios-host.ts @@ -0,0 +1,19 @@ +import type { ProviderPluginHost } from 'agent-device/plugins'; +import type { + ProviderAppleHost, + ProviderHostCapabilities, + ProviderHostKit, +} from 'agent-device/plugins/device-host'; + +/** + * What the lease's XCTest runner asks of the host it is set up on. The shared Apple runner, its + * tool-provider scope and the host's own retry and archive mechanics stay with the host; this + * provider supplies the simulator they reach. + */ +export type LimrunIosHost = Readonly<{ + apple: ProviderAppleHost; + kit: ProviderHostKit; + env: ProviderPluginHost['env']; + clientVersion: string; + emitDiagnostic: ProviderHostCapabilities['emitDiagnostic']; +}>; diff --git a/src/core/interactors/limrun-ios-runner-errors.test.ts b/packages/provider-limrun/src/ios-runner-errors.test.ts similarity index 95% rename from src/core/interactors/limrun-ios-runner-errors.test.ts rename to packages/provider-limrun/src/ios-runner-errors.test.ts index 2abb40857f..aa518bd128 100644 --- a/src/core/interactors/limrun-ios-runner-errors.test.ts +++ b/packages/provider-limrun/src/ios-runner-errors.test.ts @@ -1,6 +1,6 @@ import { expect, test } from 'vitest'; import { AppError } from '@agent-device/kernel/errors'; -import { limrunRunnerError, withLimrunRunnerErrors } from './limrun-ios-runner-errors.ts'; +import { limrunRunnerError, withLimrunRunnerErrors } from './ios-runner-errors.ts'; test.each(['capture-failed', 'budget'] as const)( 'reports %s snapshot failure with a remote recovery hint', diff --git a/src/core/interactors/limrun-ios-runner-errors.ts b/packages/provider-limrun/src/ios-runner-errors.ts similarity index 100% rename from src/core/interactors/limrun-ios-runner-errors.ts rename to packages/provider-limrun/src/ios-runner-errors.ts diff --git a/src/core/interactors/limrun-ios-runner-products.test.ts b/packages/provider-limrun/src/ios-runner-products.test.ts similarity index 89% rename from src/core/interactors/limrun-ios-runner-products.test.ts rename to packages/provider-limrun/src/ios-runner-products.test.ts index 2ea6fa925c..7218f2d430 100644 --- a/src/core/interactors/limrun-ios-runner-products.test.ts +++ b/packages/provider-limrun/src/ios-runner-products.test.ts @@ -2,10 +2,24 @@ import { promises as fs } from 'node:fs'; import path from 'node:path'; import { afterEach, expect, test, vi } from 'vitest'; import { mkdtempForTest } from '@agent-device/test-kit'; +import { extractArchiveSafely } from '@agent-device/host-kit/archive'; import { - prepareLimrunRunnerProducts, - uploadLimrunRunnerProducts, -} from './limrun-ios-runner-products.ts'; + runnerListenerEnv, + RUNNER_XCTESTRUN_CAPTURE_OPTIONS, +} from '@agent-device/platform-apple/runner/operations'; +import type { LimrunIosHost } from './ios-host.ts'; +import { prepareLimrunRunnerProducts, uploadLimrunRunnerProducts } from './ios-runner-products.ts'; + +// The products are staged over the host's own archive and runner-listener owners. +const host = { + kit: { extractArchiveSafely }, + apple: { + runner: { + listenerEnv: runnerListenerEnv, + xctestrunCaptureOptions: RUNNER_XCTESTRUN_CAPTURE_OPTIONS, + }, + }, +} as unknown as Pick; afterEach(() => vi.unstubAllGlobals()); const endpoint = { port: 8100, token: 'a'.repeat(32) }; @@ -17,7 +31,7 @@ test('a normal app without a test bundle reports the invalid runner path', async const fetch = vi.fn(); vi.stubGlobal('fetch', fetch); await expect( - prepareLimrunRunnerProducts({ + prepareLimrunRunnerProducts(host, { directory, appPath, version: '0.1.0', @@ -43,7 +57,7 @@ test('a runner that embeds its own XCTest is refused before it reaches Limrun', const fetch = vi.fn(); vi.stubGlobal('fetch', fetch); await expect( - prepareLimrunRunnerProducts({ + prepareLimrunRunnerProducts(host, { directory, appPath, version: '0.1.0', @@ -76,7 +90,7 @@ test('an HTML upload failure preserves the HTTP status', async () => { for (const bindAddress of ['0.0.0.0', 'localhost', '', '::1']) { test(`refuses ${JSON.stringify(bindAddress)} as a pod binding`, async () => { await expect( - prepareLimrunRunnerProducts({ + prepareLimrunRunnerProducts(host, { directory: await mkdtempForTest('runner-products-'), version: '0.1.0', bindAddress, @@ -103,7 +117,7 @@ test('refuses release bytes with a mismatched checksum before extracting or depl }); const directory = await mkdtempForTest('runner-products-'); await expect( - prepareLimrunRunnerProducts({ + prepareLimrunRunnerProducts(host, { directory, version: '0.1.0', bindAddress: '10.244.1.2', @@ -124,7 +138,7 @@ test('nightly builds require a packaged runner instead of requesting unpublished const fetch = vi.fn(); vi.stubGlobal('fetch', fetch); await expect( - prepareLimrunRunnerProducts({ + prepareLimrunRunnerProducts(host, { directory: await mkdtempForTest('runner-products-'), version: '0.1.0-nightly.20261030.123', bindAddress: '10.244.1.2', diff --git a/src/core/interactors/limrun-ios-runner-products.ts b/packages/provider-limrun/src/ios-runner-products.ts similarity index 92% rename from src/core/interactors/limrun-ios-runner-products.ts rename to packages/provider-limrun/src/ios-runner-products.ts index e7394a8f21..660921daf1 100644 --- a/src/core/interactors/limrun-ios-runner-products.ts +++ b/packages/provider-limrun/src/ios-runner-products.ts @@ -1,8 +1,5 @@ -import { limrunRunnerError } from './limrun-ios-runner-errors.ts'; -import { - runnerListenerEnv, - RUNNER_XCTESTRUN_CAPTURE_OPTIONS, -} from '@agent-device/platform-apple/runner/operations'; +import { limrunRunnerError } from './ios-runner-errors.ts'; +import type { LimrunIosHost } from './ios-host.ts'; import { createHash, randomUUID } from 'node:crypto'; import { createReadStream, promises as fs } from 'node:fs'; import { isIP } from 'node:net'; @@ -10,19 +7,21 @@ import path from 'node:path'; import { Readable } from 'node:stream'; import { pipeline } from 'node:stream/promises'; import { createGzip } from 'node:zlib'; -import { extractArchiveSafely } from '@agent-device/host-kit/archive'; import { escapeXmlTextAndAttribute } from '@agent-device/xml'; -import { downloadLimrunFile } from '../limrun-download-file.ts'; +import { downloadLimrunFile } from './download-file.ts'; /** Stages the version-matched release runner, or an explicitly supplied development build. */ -export async function prepareLimrunRunnerProducts(input: { - directory: string; - version: string; - appPath?: string; - bindAddress: string; - endpoint: { port: number; token: string }; - signal: AbortSignal; -}): Promise { +export async function prepareLimrunRunnerProducts( + host: Pick, + input: { + directory: string; + version: string; + appPath?: string; + bindAddress: string; + endpoint: { port: number; token: string }; + signal: AbortSignal; + }, +): Promise { if (isIP(input.bindAddress) !== 4 || input.bindAddress === '0.0.0.0') { throw limrunRunnerError( 'limrun_runner_products_invalid', @@ -80,7 +79,7 @@ export async function prepareLimrunRunnerProducts(input: { if (digest !== manifest.sha256) throw limrunRunnerError('limrun_runner_products_invalid', 'iOS runner checksum mismatch'); const extracted = path.join(input.directory, 'extracted'); - await extractArchiveSafely({ + await host.kit.extractArchiveSafely({ archivePath, outputRoot: extracted, type: 'tgz', @@ -136,17 +135,18 @@ export async function prepareLimrunRunnerProducts(input: { ); } await fs.cp(appPath, path.join(products, 'Runner.app'), { recursive: true }); - await writeLimrunRunnerConfiguration(products, input.bindAddress, input.endpoint); + await writeLimrunRunnerConfiguration(host, products, input.bindAddress, input.endpoint); return products; } export async function writeLimrunRunnerConfiguration( + host: Pick, directory: string, bindAddress: string, endpoint: { port: number; token: string }, ): Promise { const string = (value: string) => `${escapeXmlTextAndAttribute(value)}`; - const environment = runnerListenerEnv(endpoint, bindAddress); + const environment = host.apple.runner.listenerEnv(endpoint, bindAddress); const xml = ` AgentDeviceRunnerUITests @@ -156,7 +156,7 @@ export async function writeLimrunRunnerConfiguration( TestBundlePath__TESTHOST__/PlugIns/AgentDeviceRunnerUITests.xctest IsUITestBundle UITargetAppPath__TESTROOT__/Runner.app -${Object.entries(RUNNER_XCTESTRUN_CAPTURE_OPTIONS) +${Object.entries(host.apple.runner.xctestrunCaptureOptions) .map(([key, value]) => `${key}${string(value)}`) .join('')} OnlyTestIdentifiersRunnerTests/testCommand diff --git a/src/core/interactors/limrun-ios-runner.ts b/packages/provider-limrun/src/ios-runner.ts similarity index 81% rename from src/core/interactors/limrun-ios-runner.ts rename to packages/provider-limrun/src/ios-runner.ts index e1778f3add..5c60da61f6 100644 --- a/src/core/interactors/limrun-ios-runner.ts +++ b/packages/provider-limrun/src/ios-runner.ts @@ -1,24 +1,21 @@ -import { limrunRunnerError, withLimrunRunnerErrors } from './limrun-ios-runner-errors.ts'; +import { limrunRunnerError, withLimrunRunnerErrors } from './ios-runner-errors.ts'; import { awaitWithSignal } from '@agent-device/kernel/await-with-signal'; -import { Deadline, type DeadlineClock, retryWithPolicy } from '@agent-device/host-kit/retry'; -import { createLimrunAppleToolProvider } from './limrun-ios-tools.ts'; -import type { AppleApplicationTools } from '@agent-device/contracts/application-lifecycle-runtime'; +import type { DeadlineClock } from '@agent-device/host-kit/retry'; +import { createLimrunAppleToolProvider } from './ios-tools.ts'; import { withMethodScope } from '@agent-device/kernel/scoped-provider'; -import { createLimrunAppleApplicationTools } from './limrun-ios-application-tools.ts'; +import { createLimrunAppleApplicationTools } from './ios-application-tools.ts'; import { randomInt } from 'node:crypto'; import { promises as fs } from 'node:fs'; import os from 'node:os'; import path from 'node:path'; -import type { LimrunRuntimeDependencies } from '@agent-device/provider-limrun'; -import type { HostEnvironment } from '@agent-device/kernel/source-value'; +import type { LimrunRuntimeDependencies } from './runtime-dependencies.ts'; +import type { LimrunIosHost } from './ios-host.ts'; import { AppError } from '@agent-device/kernel/errors'; -import { readVersion } from '@agent-device/host-kit/version'; -import { emitDiagnostic } from '@agent-device/host-kit/diagnostics'; import { prepareLimrunRunnerProducts, uploadLimrunRunnerProducts, writeLimrunRunnerConfiguration, -} from './limrun-ios-runner-products.ts'; +} from './ios-runner-products.ts'; type LimrunIosRunner = Awaited>; type Session = Parameters[0]; @@ -26,28 +23,18 @@ type Session = Parameters[0]; /** Owns the lease’s XCTest runs; closing an attached lease never terminates its simulator. */ export async function createLimrunIosRunner( session: Session, - host: HostEnvironment, - appleApplications: Pick< - AppleApplicationTools, - 'resolveOpenTarget' | 'applyRuntimeHints' | 'clearRuntimeHints' - >, + host: LimrunIosHost, ): Promise { - const { - createAppleRunnerRuntime, - createLaunchedAppleRunnerProvider, - RUNNER_STARTUP_TIMEOUT_MS, - mintRunnerToken, - } = await import('@agent-device/platform-apple/runner/operations'); - const { withAppleToolProvider, hasScopedAppleToolProvider, runXcrun } = - await import('@agent-device/platform-apple/tool-provider'); - const { buildSimctlArgsForDevice } = await import('@agent-device/platform-apple/simctl'); + const { apple, kit, emitDiagnostic } = host; + const { Deadline, retryWithPolicy } = kit; const lifetime = new AbortController(); const withTools = (task: () => Promise, signal?: AbortSignal) => - withAppleToolProvider(createLimrunAppleToolProvider(session, lifetime.signal, signal), () => - withLimrunRunnerErrors(task), + apple.tools.withProvider( + createLimrunAppleToolProvider(session, host, lifetime.signal, signal), + () => withLimrunRunnerErrors(task), ); - const hostTools = withMethodScope({ ...appleApplications }, (task) => - hasScopedAppleToolProvider() ? task() : withTools(task), + const hostTools = withMethodScope({ ...apple.applicationTools }, (task) => + apple.tools.hasScopedProvider() ? task() : withTools(task), ); const port = randomInt(20000, 50000); const apiUrl = session.apiUrl.replace(/\/$/, ''); @@ -59,15 +46,11 @@ export async function createLimrunIosRunner( let preparationWaiters = 0; let prepared = false; let canceledRunMayHoldSlot = false; - const endpoint = { port, token: mintRunnerToken(), http: { url: commandUrl, headers } }; - const provider = await createLaunchedAppleRunnerProvider( - session.device, - { endpoint, launch }, - host.env, - ); + const endpoint = { port, token: apple.runner.mintToken(), http: { url: commandUrl, headers } }; + const provider = await apple.runner.createLaunchedProvider(session.device, { endpoint, launch }); const { stop, release, prepare, isStarted, releaseSpeculative } = provider; const isReady = provider.hasLiveSession; - const transport = await createAppleRunnerRuntime({ device: session.device, host, provider }); + const transport = await apple.runner.createRuntime({ device: session.device, provider }); const prepareProducts = async (callerSignal?: AbortSignal) => { const preparation = AbortSignal.any([lifetime.signal, ...(callerSignal ? [callerSignal] : [])]); @@ -79,9 +62,9 @@ export async function createLimrunIosRunner( }); if (bind.code !== 0) throw limrunRunnerError('limrun_runner_bind_address_missing', 'Limrun did not expose USE_IP'); - const directory = await prepareLimrunRunnerProducts({ + const directory = await prepareLimrunRunnerProducts(host, { directory: staging, - version: readVersion(), + version: host.clientVersion, appPath: host.env.AGENT_DEVICE_LIMRUN_IOS_RUNNER_APP, bindAddress: bind.stdout.trim(), endpoint, @@ -152,7 +135,7 @@ export async function createLimrunIosRunner( try { startupSignal.throwIfAborted(); const { directory, bindAddress } = await cachedProducts(signal); - await writeLimrunRunnerConfiguration(directory, bindAddress, ownedEndpoint); + await writeLimrunRunnerConfiguration(host, directory, bindAddress, ownedEndpoint); await uploadLimrunRunnerProducts(directory, apiUrl, session.token, signal, [ 'Runner.xctestrun', ]); @@ -283,7 +266,7 @@ export async function createLimrunIosRunner( await provider.ensure(input); return; } - await prepare(session.device, { ...input, healthTimeoutMs: RUNNER_STARTUP_TIMEOUT_MS }); + await prepare(session.device, { ...input, healthTimeoutMs: apple.runner.startupTimeoutMs }); }, prepare: (_device, input, signal) => transport.prepare(input, signal), resetTarget, @@ -294,6 +277,7 @@ export async function createLimrunIosRunner( releaseSpeculative, }, hostTools, + emitDiagnostic, ); return { applicationTools, @@ -312,14 +296,17 @@ export async function createLimrunIosRunner( ...request, appleApplications: applicationTools, ensureReady: async (device, signal, options) => { - await runXcrun(buildSimctlArgsForDevice(device, ['bootstatus', device.id, '-b']), { - signal, - ...(options?.deadlineAtMs === undefined - ? {} - : { - timeoutMs: Math.max(1, options.deadlineAtMs - Date.now()), - }), - }); + await apple.tools.runXcrun( + apple.tools.simctlArgsForDevice(device, ['bootstatus', device.id, '-b']), + { + signal, + ...(options?.deadlineAtMs === undefined + ? {} + : { + timeoutMs: Math.max(1, options.deadlineAtMs - Date.now()), + }), + }, + ); return { ...device, booted: true }; }, }); diff --git a/src/core/interactors/limrun-ios-tools.ts b/packages/provider-limrun/src/ios-tools.ts similarity index 92% rename from src/core/interactors/limrun-ios-tools.ts rename to packages/provider-limrun/src/ios-tools.ts index b1831e36b3..d1a44be67d 100644 --- a/src/core/interactors/limrun-ios-tools.ts +++ b/packages/provider-limrun/src/ios-tools.ts @@ -1,18 +1,20 @@ import { awaitWithSignal } from '@agent-device/kernel/await-with-signal'; -import { createLimrunSimulatorFiles } from './limrun-ios-files.ts'; +import { createLimrunSimulatorFiles } from './ios-files.ts'; import type { AppleToolProvider, AppleToolExecOptions, } from '@agent-device/platform-apple/tool-provider'; -import { execFailureDetails, type ExecResult } from '@agent-device/host-kit/command'; +import type { ExecResult } from '@agent-device/host-kit/command'; +import type { LimrunIosHost } from './ios-host.ts'; import { AppError, createRequestCanceledError } from '@agent-device/kernel/errors'; -import type { LimrunRuntimeDependencies } from '@agent-device/provider-limrun'; +import type { LimrunRuntimeDependencies } from './runtime-dependencies.ts'; type Session = Parameters[0]; /** Runs the shared Apple host commands against the lease's simulator. */ export function createLimrunAppleToolProvider( session: Session, + host: Pick, lifetime: AbortSignal, requestSignal?: AbortSignal, ): AppleToolProvider { @@ -98,7 +100,7 @@ export function createLimrunAppleToolProvider( throw new AppError('COMMAND_FAILED', `xcrun exited with code ${result.code}`, { cmd: 'simctl', args, - ...execFailureDetails({ exitCode: result.code, stdout, stderr: result.stderr }), + ...host.kit.execFailureDetails({ exitCode: result.code, stdout, stderr: result.stderr }), }); } return { exitCode: result.code, stdout, stderr: result.stderr }; @@ -109,6 +111,7 @@ export function createLimrunAppleToolProvider( }; const { simulatorFiles, readInfoPlist } = createLimrunSimulatorFiles( session, + host.apple.tools.parsePlist, lifetime, requestSignal, ); diff --git a/packages/provider-limrun/src/plugin.test.ts b/packages/provider-limrun/src/plugin.test.ts index e7c5931318..7c80f4be8f 100644 --- a/packages/provider-limrun/src/plugin.test.ts +++ b/packages/provider-limrun/src/plugin.test.ts @@ -1,13 +1,15 @@ import assert from 'node:assert/strict'; import path from 'node:path'; import { afterEach, test, vi } from 'vitest'; -import type { ProviderPluginHost } from '@agent-device/plugins/host'; +import type { + ProviderAgentDevicePlugin as AgentDevicePlugin, + ProviderPluginHost, +} from 'agent-device/plugins'; import { AppError } from '@agent-device/kernel/errors'; import { mkdtempForTestSync } from '@agent-device/test-kit'; import type { LimrunRuntimeDependencies } from './runtime-dependencies.ts'; import { stubLimrunRuntimeDependencies } from './runtime-dependencies.fixtures.ts'; import { limrunPlugin } from './plugin.ts'; -import type { AgentDevicePlugin } from '@agent-device/plugins/contract'; function providerOf

(plugin: P) { const [contribution] = plugin.contributes; @@ -161,12 +163,15 @@ test('verify runs its own SDK check over scoped credentials, version and platfor }); test('setup builds the runtime over the credentials, host and HAR directory it was given', async () => { - const host = pluginHost({ LIMRUN_API_KEY: 'lim_test_key', LIMRUN_KEEP_ALIVE: '1' }); + const stateDir = mkdtempForTestSync('limrun-plugin-state-'); + const host = { + ...pluginHost({ LIMRUN_API_KEY: 'lim_test_key', LIMRUN_KEEP_ALIVE: '1' }), + stateDir, + }; const dependencies = stubDependencies(); const createDependencies = vi.fn(() => dependencies); - const stateDir = mkdtempForTestSync('limrun-plugin-state-'); - const setup = await providerOf(limrunPlugin({ createDependencies, stateDir })).setup(host); + const setup = await providerOf(limrunPlugin({ createDependencies })).setup(host); if (!('runtime' in setup)) throw new Error('Limrun sets up its own runtime'); assert.equal(setup.runtime.provider, 'limrun'); @@ -185,6 +190,20 @@ test('setup builds the runtime over the credentials, host and HAR directory it w ]); }); +test('setup refuses a host that supplies no device capabilities', async () => { + await assert.rejects( + async () => { + await providerOf(limrunPlugin()).setup(pluginHost({ LIMRUN_API_KEY: 'lim_test_key' })); + }, + (error: unknown) => { + assert.ok(error instanceof AppError); + assert.equal(error.code, 'UNSUPPORTED_OPERATION'); + assert.equal(error.details?.reason, 'provider_host_capability_missing'); + return true; + }, + ); +}); + test('setup with only an attached instance builds a runtime without an API key or HAR directory', async () => { await providerOf(limrunPlugin({ createDependencies: () => stubDependencies() })).setup( pluginHost({ LIM_IOS_INSTANCE_URL: 'https://x/api', LIM_IOS_INSTANCE_TOKEN: 'token' }), diff --git a/packages/provider-limrun/src/plugin.ts b/packages/provider-limrun/src/plugin.ts index 6a82385261..9b81d85f8f 100644 --- a/packages/provider-limrun/src/plugin.ts +++ b/packages/provider-limrun/src/plugin.ts @@ -1,32 +1,24 @@ import path from 'node:path'; -import type { PluginConnection, ProviderOnlyPlugin } from '@agent-device/plugins/contract'; -import type { ProviderPluginHost } from '@agent-device/plugins/host'; +import type { PluginConnection, ProviderAgentDevicePlugin } from 'agent-device/plugins'; +import type { DeviceProviderPluginHost } from 'agent-device/plugins/device-host'; import { limrunCredentialDeclaration, requireLimrunCredentials } from './credentials.ts'; import { LIMRUN_CONNECTION_CAPABILITIES, LIMRUN_PROVIDER } from './device.ts'; import type { LimrunRuntimeDependencies } from './runtime-dependencies.ts'; export type LimrunPluginOptions = Readonly<{ /** - * Builds the runtime's host and platform adapters for one setup host. The provider names what a - * runtime needs; whoever composes the host supplies how those needs are served, so the runtime - * graph stays free of platform implementation. + * Builds the runtime's host and platform adapters for one setup host. Defaults to the adapters + * the host's own capabilities answer. */ - createDependencies( - host: ProviderPluginHost, + createDependencies?( + host: DeviceProviderPluginHost, ): LimrunRuntimeDependencies | Promise; - /** - * The daemon's own state directory. Each lease's `--provider-network-logs` HAR file is written - * beside the session files under it; without it the capture is unavailable. - */ - stateDir?: string; }>; -/** - * Limrun's own `connect` callbacks, exported so the built-in composition can wire them to a CLI call - * without reading the plugin declaration back. Each callback loads the SDK only when it runs. - */ -export const LIMRUN_CONNECTION: PluginConnection = { +const LIMRUN_CONNECTION: PluginConnection = { capabilities: LIMRUN_CONNECTION_CAPABILITIES, + // The connect callbacks load when the first `connect` runs them, so a process that only lists or + // fingerprints this provider evaluates none of them. resolve: async (context) => await (await import('./connection.ts')).createLimrunConnection().resolve(context), verify: async (context) => @@ -42,8 +34,7 @@ export const LIMRUN_CONNECTION: PluginConnection = { * list, fingerprint, or route a `connect` to the provider: the connection's flags and credential * reading, the runtime, and its host adapters all load in the path that asks for them. */ -export function limrunPlugin(options: LimrunPluginOptions): ProviderOnlyPlugin { - const { createDependencies, stateDir } = options; +export function limrunPlugin(options: LimrunPluginOptions = {}): ProviderAgentDevicePlugin { return { apiVersion: 3, contributes: [ @@ -51,23 +42,25 @@ export function limrunPlugin(options: LimrunPluginOptions): ProviderOnlyPlugin { kind: 'provider', provider: LIMRUN_PROVIDER, credentials: limrunCredentialDeclaration(), - // The connect callbacks are the provider's own and load when the first `connect` runs them, - // so a process that only lists or fingerprints this provider evaluates none of them. connection: LIMRUN_CONNECTION, - setup: async (host) => { + setup: async (host: DeviceProviderPluginHost) => { const credentials = requireLimrunCredentials(host.env); const [register, dependencies] = await Promise.all([ import('./runtime.ts'), - Promise.resolve(createDependencies(host)), + options.createDependencies + ? options.createDependencies(host) + : import('./host-dependencies.ts').then((module) => + module.createLimrunRuntimeDependencies(host), + ), ]); return register.createLimrunRuntime( { ...credentials, - ...(stateDir === undefined + ...(host.stateDir === undefined ? {} : { - // HAR captures land beside the session files, under the daemon's own state dir. - networkHarDir: path.join(stateDir, 'network-har'), + // HAR captures land beside the session files, under the daemon's state dir. + networkHarDir: path.join(host.stateDir, 'network-har'), }), }, dependencies, diff --git a/packages/provider-limrun/src/runtime.ts b/packages/provider-limrun/src/runtime.ts index 63d2fe8db2..7cfcb11aa3 100644 --- a/packages/provider-limrun/src/runtime.ts +++ b/packages/provider-limrun/src/runtime.ts @@ -974,3 +974,5 @@ async function readLimrunTerminationReason( return undefined; } } + +export type { LimrunRuntimeDependencies } from './runtime-dependencies.ts'; diff --git a/packages/provider-limrun/test/package-smoke.mjs b/packages/provider-limrun/test/package-smoke.mjs new file mode 100644 index 0000000000..1fd2970e03 --- /dev/null +++ b/packages/provider-limrun/test/package-smoke.mjs @@ -0,0 +1,115 @@ +import fs from 'node:fs'; +import path from 'node:path'; +import assert from 'node:assert/strict'; + +export const provider = 'limrun'; +export const primaryExport = { + types: './dist/agent-device.d.mts', + import: './dist/agent-device.mjs', +}; +export const additionalExports = { './package.json': './package.json' }; +// The Limrun SDK is the plugin's own dependency, so a user can update it without a core release. +export const dependencies = { '@limrun/api': '^0.69.1' }; +export const args = ['--platform', 'android']; +export const fetchRedirects = ['https://api.limrun.com']; + +export function environment() { + return { LIMRUN_API_KEY: 'lim_fixture_key' }; +} + +export function respond(url, rejectCredentials) { + const pathname = new URL(url, 'http://fixture').pathname; + if (pathname !== '/v1/android_instances') return { status: 404, body: { error: 'not-found' } }; + if (rejectCredentials) return { status: 401, body: { error: 'unauthorized' } }; + return { body: [] }; +} + +export async function verifyPacked({ core, contracts, plugin }) { + const limrun = plugin.default().contributes[0]; + assert.equal(limrun.kind, 'provider'); + assert.equal(limrun.provider, provider); + assert.deepEqual(limrun.credentials.byBackend['android-instance'], [ + 'LIMRUN_API_KEY', + 'LIMRUN_REGION', + 'LIM_ANDROID_INSTANCE_URL', + 'LIM_ANDROID_INSTANCE_TOKEN', + 'LIM_ANDROID_INSTANCE_ADB_URL', + ]); + assert.equal(limrun.connection.capabilities.leaseKind, 'direct-device-provider'); + assert.equal(limrun.connection.capabilities.supportsDeferredAppSelection, true); + assert.equal(limrun.connection.capabilities.supportsDirectPortReverse, true); + + const host = (env) => ({ + env, + options: {}, + clientVersion: '0.22.0', + createError: (code, message, details) => new core.AppError(code, message, details), + runHostCommand: async () => { + throw new Error('Limrun runs no host command to set up'); + }, + }); + const capture = async (run) => { + try { + await run(); + } catch (error) { + // The plugin bundles its own copy of the error class; the host recognizes it by brand. + assert.ok(error instanceof core.AppError); + return contracts.normalizeError(error); + } + assert.fail('Expected a Limrun failure'); + }; + const missingCredentials = await capture(() => limrun.setup(host({}))); + assert.equal(missingCredentials.code, 'INVALID_ARGS'); + assert.equal(missingCredentials.details.reason, 'missing_provider_credentials'); + assert.ok(missingCredentials.hint); + + // A host that supplies no device capabilities is refused before any instance is reached. + const missingCapabilities = await capture(() => + limrun.setup(host({ LIMRUN_API_KEY: 'lim_fixture_key' })), + ); + assert.equal(missingCapabilities.code, 'UNSUPPORTED_OPERATION'); + assert.equal(missingCapabilities.details.reason, 'provider_host_capability_missing'); + + const refusedDevice = await capture(() => + limrun.connection.resolve({ + flags: { platform: 'android', device: 'Pixel 9' }, + stateDir: '/state', + cwd: '/', + env: { LIMRUN_API_KEY: 'lim_fixture_key' }, + host: host({ LIMRUN_API_KEY: 'lim_fixture_key' }), + }), + ); + assert.equal(refusedDevice.code, 'INVALID_ARGS'); +} + +export async function verifyTypes({ consumer, run, root }) { + fs.writeFileSync( + path.join(consumer, 'consumer.mts'), + ` +import { startAgentDevice } from 'agent-device'; +import type { ProviderAgentDevicePlugin } from 'agent-device/plugins'; +import limrun from '@agent-device/limrun/agent-device'; +const plugin: ProviderAgentDevicePlugin = limrun(); +const runtime = await startAgentDevice({ stateDir: './state', plugins: [plugin] }); +await runtime.close(); +`, + ); + await run( + process.execPath, + [ + path.join(root, 'node_modules/typescript/bin/tsc'), + '--noEmit', + '--strict', + '--module', + 'NodeNext', + '--moduleResolution', + 'NodeNext', + '--target', + 'ES2022', + '--typeRoots', + path.join(root, 'node_modules/@types'), + 'consumer.mts', + ], + consumer, + ); +} diff --git a/packages/provider-limrun/tsconfig.json b/packages/provider-limrun/tsconfig.json index 66e2179ce9..c19b09fecf 100644 --- a/packages/provider-limrun/tsconfig.json +++ b/packages/provider-limrun/tsconfig.json @@ -6,31 +6,25 @@ "emitDeclarationOnly": true, "declaration": true, "declarationDir": "./dist-types", - "rootDir": "./src", - "tsBuildInfoFile": "./dist-types/index.tsbuildinfo" + "tsBuildInfoFile": "./dist-types/index.tsbuildinfo", + "rootDir": ".", + "paths": { + "agent-device/plugins": ["./node_modules/agent-device/src/sdk/plugins.ts"], + "agent-device/plugins/device-host": [ + "./node_modules/agent-device/src/sdk/plugin-device-host.ts" + ] + } }, "include": ["src"], "references": [ - { - "path": "../capture-kit" - }, - { - "path": "../contracts" - }, - { - "path": "../kernel" - }, - { - "path": "../platform-android" - }, - { - "path": "../platform-apple" - }, - { - "path": "../plugins" - }, - { - "path": "../test-kit" - } + { "path": "../build-config" }, + { "path": "../capture-kit" }, + { "path": "../contracts" }, + { "path": "../host-kit" }, + { "path": "../kernel" }, + { "path": "../platform-android" }, + { "path": "../platform-apple" }, + { "path": "../test-kit" }, + { "path": "../xml" } ] } diff --git a/packages/provider-limrun/tsdown.config.ts b/packages/provider-limrun/tsdown.config.ts new file mode 100644 index 0000000000..b12d31f418 --- /dev/null +++ b/packages/provider-limrun/tsdown.config.ts @@ -0,0 +1,12 @@ +import { defineConfig } from 'tsdown'; +import { providerPluginBuildConfig } from '@agent-device/build-config'; + +export default defineConfig({ + ...providerPluginBuildConfig, + dts: true, + tsconfig: '../../tsconfig.lib.json', + deps: { + ...providerPluginBuildConfig.deps, + neverBundle: ['agent-device/plugins', 'agent-device/plugins/device-host'], + }, +}); diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index ea43727f42..be0f11b861 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -80,6 +80,9 @@ importers: '@agent-device/kernel': specifier: workspace:* version: link:packages/kernel + '@agent-device/limrun': + specifier: workspace:* + version: link:packages/provider-limrun '@agent-device/platform-android': specifier: workspace:* version: link:packages/platform-android @@ -89,9 +92,6 @@ importers: '@agent-device/plugins': specifier: workspace:* version: link:packages/plugins - '@agent-device/provider-limrun': - specifier: workspace:* - version: link:packages/provider-limrun '@agent-device/provider-webdriver': specifier: workspace:* version: link:packages/provider-webdriver @@ -991,31 +991,40 @@ importers: packages/provider-limrun: dependencies: + '@limrun/api': + specifier: ^0.69.1 + version: 0.69.1(supports-color@7.2.0) + devDependencies: + '@agent-device/build-config': + specifier: workspace:* + version: link:../build-config '@agent-device/capture-kit': specifier: workspace:* version: link:../capture-kit '@agent-device/contracts': specifier: workspace:* version: link:../contracts + '@agent-device/host-kit': + specifier: workspace:* + version: link:../host-kit '@agent-device/kernel': specifier: workspace:* version: link:../kernel '@agent-device/platform-android': specifier: workspace:* version: link:../platform-android - '@agent-device/plugins': - specifier: workspace:* - version: link:../plugins - devDependencies: '@agent-device/platform-apple': specifier: workspace:* version: link:../platform-apple '@agent-device/test-kit': specifier: workspace:* version: link:../test-kit - '@limrun/api': - specifier: ^0.69.1 - version: 0.69.1(supports-color@7.2.0) + '@agent-device/xml': + specifier: workspace:* + version: link:../xml + agent-device: + specifier: workspace:* + version: link:../.. packages/provider-revyl: devDependencies: diff --git a/scripts/__tests__/bundled-license-notices.test.ts b/scripts/__tests__/bundled-license-notices.test.ts index 4d667d5e2c..b4c01da0b9 100644 --- a/scripts/__tests__/bundled-license-notices.test.ts +++ b/scripts/__tests__/bundled-license-notices.test.ts @@ -364,38 +364,3 @@ test('output overrides write notices beside the bundle without creating the defa ); await assert.rejects(fs.stat(path.join(root, 'dist')), { code: 'ENOENT' }); }); - -test.each([ - { version: '0.2.0', newline: '\n', lineEnding: 'LF' }, - { version: '0.2.0', newline: '\r\n', lineEnding: 'CRLF' }, - { version: '0.2.1', newline: '\n', lineEnding: 'LF' }, -])( - 'bundled xdelta WASM $version requires matching complete notices with $lineEnding line endings', - async ({ version, newline }) => { - const [sourceNotices, apacheLicense] = await Promise.all([ - fs.readFile(new URL('../../LICENSES/xdelta3-wasm.txt', import.meta.url), 'utf8'), - fs.readFile(new URL('../../LICENSES/Apache-2.0.txt', import.meta.url), 'utf8'), - ]); - const root = await fixture({ - 'input.ts': "export { value } from '@limrun/xdelta3-wasm';", - 'node_modules/@limrun/xdelta3-wasm/package.json': JSON.stringify({ - name: '@limrun/xdelta3-wasm', - version, - license: 'Apache-2.0', - main: 'index.js', - }), - 'node_modules/@limrun/xdelta3-wasm/index.js': - 'export const value = process.env.FIXTURE_NUMBER;', - 'LICENSES/xdelta3-wasm.txt': sourceNotices.replaceAll('\r\n', '\n').replaceAll('\n', newline), - 'LICENSES/Apache-2.0.txt': apacheLicense.replaceAll('\r\n', '\n').replaceAll('\n', newline), - }); - if (version !== '0.2.0') { - await assert.rejects(bundle(root), /Refresh LICENSES/); - return; - } - await bundle(root); - const notices = await fs.readFile(path.join(root, 'dist/THIRD_PARTY_NOTICES.txt'), 'utf8'); - assert.ok(notices.includes(sourceNotices.replaceAll('\r\n', '\n').trim())); - assert.ok(notices.includes(apacheLicense.replaceAll('\r\n', '\n').trim())); - }, -); diff --git a/scripts/__tests__/fixtures/bundled-license-build.mts b/scripts/__tests__/fixtures/bundled-license-build.mts index 1c24529d6b..69604fabd2 100644 --- a/scripts/__tests__/fixtures/bundled-license-build.mts +++ b/scripts/__tests__/fixtures/bundled-license-build.mts @@ -22,7 +22,6 @@ await build({ 'distinct', 'unused', 'jpeg-js', - '@limrun/xdelta3-wasm', 'included-extra', 'included.extra', 'included_extra', diff --git a/scripts/capability-matrix/collect.ts b/scripts/capability-matrix/collect.ts index 54c71240f8..ee7a4261f3 100644 --- a/scripts/capability-matrix/collect.ts +++ b/scripts/capability-matrix/collect.ts @@ -216,10 +216,11 @@ async function limrunSupport( ): Promise> { // The hooks must be in place before the provider's own `@limrun/api` import resolves. stubLimrunSdk(); - const { createLimrunRuntime } = await import('@agent-device/provider-limrun'); - const { createLimrunIosRunner } = await import('../../src/core/interactors/limrun-ios-runner.ts'); - const { createAppleApplicationTools } = - await import('../../src/platform-runtime-apple-application-tools.ts'); + const { createLimrunRuntime } = await import('@agent-device/limrun/runtime'); + const { createLimrunIosRunner } = await import('@agent-device/limrun/host'); + const { createProviderHostCapabilities } = + await import('../../src/provider-plugin-host-capabilities.ts'); + const capabilities = createProviderHostCapabilities({ env: {}, cwd: process.cwd() }); const runtime = createLimrunRuntime( { instances: { @@ -236,12 +237,14 @@ async function limrunSupport( android: { createPortReverse: async () => ({}) }, host: {}, ios: { - createRunner: (session: Parameters[0]) => - createLimrunIosRunner( - session, - { env: {}, cwd: process.cwd() }, - createAppleApplicationTools({}), - ), + createRunner: async (session: Parameters[0]) => + createLimrunIosRunner(session, { + apple: await capabilities.loadApple(), + kit: await capabilities.loadHostKit(), + env: {}, + clientVersion: '0.0.0', + emitDiagnostic: capabilities.emitDiagnostic, + }), }, } as never, { includePlatformModule: true }, diff --git a/scripts/lib/bundled-license-notices.ts b/scripts/lib/bundled-license-notices.ts index 3a633d78e2..460f6fe137 100644 --- a/scripts/lib/bundled-license-notices.ts +++ b/scripts/lib/bundled-license-notices.ts @@ -107,9 +107,7 @@ function attributableDependency( const version = typeof manifest.version === 'string' ? manifest.version.trim() : ''; if (!version) throw new Error(`Bundled dependency ${name} is missing its version.`); const license = typeof manifest.license === 'string' ? manifest.license.trim() : ''; - const licenseText = - readNamedFile(directory, /^licen[cs]e/i) ?? - (name === '@limrun/xdelta3-wasm' ? xdeltaLicenseText(root, version, license) : undefined); + const licenseText = readNamedFile(directory, /^licen[cs]e/i); if (!license || !licenseText) { throw new Error( `Bundled dependency ${name}@${version} is missing its license or license text.`, @@ -142,15 +140,3 @@ function deduplicate(dependencies: readonly NoticeDependency[]): NoticeDependenc ).values(), ]; } - -function xdeltaLicenseText(root: string, version: string, license: string): string { - const notices = fs.readFileSync(path.join(root, 'LICENSES/xdelta3-wasm.txt'), 'utf8'); - if ( - notices.split(/\r?\n/, 1)[0] !== `@limrun/xdelta3-wasm ${version} source-file notices` || - license !== 'Apache-2.0' - ) - throw new Error( - `Refresh LICENSES/xdelta3-wasm.txt for bundled @limrun/xdelta3-wasm@${version}.`, - ); - return notices + '\n' + fs.readFileSync(path.join(root, 'LICENSES/Apache-2.0.txt'), 'utf8'); -} diff --git a/src/__tests__/cli-config-limrun.test.ts b/src/__tests__/cli-config-limrun.test.ts index b957332d2b..0d54d40c19 100644 --- a/src/__tests__/cli-config-limrun.test.ts +++ b/src/__tests__/cli-config-limrun.test.ts @@ -1,4 +1,4 @@ -import { test } from 'vitest'; +import { test, vi } from 'vitest'; import assert from 'node:assert/strict'; import fs from 'node:fs'; import path from 'node:path'; @@ -10,6 +10,12 @@ import { import { runCliCapture } from './cli-capture.ts'; import { makeTempWorkspace } from '@agent-device/test-kit'; +vi.mock('@agent-device/plugins/store', async (importOriginal) => + (await import('./test-utils/limrun-plugin-store.ts')).storeWithLimrunInstalled( + importOriginal as () => Promise, + ), +); + test('Limrun apps lists uploaded assets without allocating an instance', async () => { const { root, home, project } = makeTempWorkspace(); const stateDir = path.join(root, 'state'); diff --git a/src/__tests__/cli-leased-session.test.ts b/src/__tests__/cli-leased-session.test.ts index db40b43e9b..79e71a8189 100644 --- a/src/__tests__/cli-leased-session.test.ts +++ b/src/__tests__/cli-leased-session.test.ts @@ -15,6 +15,12 @@ import { import { runCliCapture, type CapturedDaemonRequest } from './cli-capture.ts'; import { startPublicDaemonRuntime } from './test-utils/public-daemon-runtime.ts'; +vi.mock('@agent-device/plugins/store', async (importOriginal) => + (await import('./test-utils/limrun-plugin-store.ts')).storeWithLimrunInstalled( + importOriginal as () => Promise, + ), +); + const profileResolutions = vi.hoisted(() => ({ count: 0 })); vi.mock('@agent-device/remote/remote-config-core', async (importOriginal) => { diff --git a/src/__tests__/cli-run-transport.test.ts b/src/__tests__/cli-run-transport.test.ts index 37e229b3e2..7eb4f523fd 100644 --- a/src/__tests__/cli-run-transport.test.ts +++ b/src/__tests__/cli-run-transport.test.ts @@ -10,6 +10,12 @@ import { runCli } from '../cli.ts'; import type { DaemonRequest, DaemonResponse } from '@agent-device/daemon-client'; import { makeTempWorkspace } from '@agent-device/test-kit'; +vi.mock('@agent-device/plugins/store', async (importOriginal) => + (await import('./test-utils/limrun-plugin-store.ts')).storeWithLimrunInstalled( + importOriginal as () => Promise, + ), +); + afterEach(() => { vi.restoreAllMocks(); }); diff --git a/src/__tests__/cloud-connect-profile-fields.test.ts b/src/__tests__/cloud-connect-profile-fields.test.ts index a779ddd054..6fa6d2c6df 100644 --- a/src/__tests__/cloud-connect-profile-fields.test.ts +++ b/src/__tests__/cloud-connect-profile-fields.test.ts @@ -1,7 +1,13 @@ -import { test } from 'vitest'; +import { test, vi } from 'vitest'; import assert from 'node:assert/strict'; import { runCliCapture } from './cli-capture.ts'; +vi.mock('@agent-device/plugins/store', async (importOriginal) => + (await import('./test-utils/limrun-plugin-store.ts')).storeWithLimrunInstalled( + importOriginal as () => Promise, + ), +); + test('connect limrun refuses profile fields Limrun does not read', async () => { const result = await runCliCapture( [ @@ -60,3 +66,28 @@ test('connect limrun applies the same refusal when attaching to an existing inst assert.equal(payload.error.code, 'INVALID_ARGS'); assert.deepEqual(payload.error.details.flags, ['--provider-os-version']); }); + +test('connect limrun refuses the device type before saving a profile', async () => { + const result = await runCliCapture( + [ + 'connect', + 'limrun', + '--session', + 'ci', + '--platform', + 'ios', + '--provider-device-type', + 'real', + '--json', + ], + { + env: { LIMRUN_API_KEY: 'lim_test_key' }, + stateDirPrefix: 'agent-device-connect-limrun-device-type-', + }, + ); + assert.equal(result.code, 1); + const payload = JSON.parse(result.stdout); + assert.equal(payload.error.code, 'INVALID_ARGS'); + assert.match(payload.error.message, /^--provider-device-type is not supported by Limrun/); + assert.equal(payload.error.details.provider, 'limrun'); +}); diff --git a/src/__tests__/cloud-connect-profile.test.ts b/src/__tests__/cloud-connect-profile.test.ts index 3bbd8f3889..775a3e5c83 100644 --- a/src/__tests__/cloud-connect-profile.test.ts +++ b/src/__tests__/cloud-connect-profile.test.ts @@ -20,6 +20,12 @@ import { beginStdoutCapture, } from '@agent-device/test-kit'; +vi.mock('@agent-device/plugins/store', async (importOriginal) => + (await import('./test-utils/limrun-plugin-store.ts')).storeWithLimrunInstalled( + importOriginal as () => Promise, + ), +); + bindTestCommandHost(); // The Limrun SDK is the boundary this suite stubs: the provider's own connection verification is diff --git a/src/__tests__/cloud-connect-testmu.test.ts b/src/__tests__/cloud-connect-testmu.test.ts index 6ccb993fef..2245d2ebf2 100644 --- a/src/__tests__/cloud-connect-testmu.test.ts +++ b/src/__tests__/cloud-connect-testmu.test.ts @@ -2,7 +2,6 @@ import { afterEach, beforeEach, test, vi } from 'vitest'; import assert from 'node:assert/strict'; import fs from 'node:fs'; import path from 'node:path'; -import { runCliCapture } from './cli-capture.ts'; import { readActiveConnectionState, type RemoteConnectionState, @@ -274,59 +273,6 @@ test('connect testmu stores and verifies the real-device pool', async () => { } }); -test('providers other than TestMu refuse --provider-device-type before saving a profile', async () => { - const tempRoot = mkdtempForTestSync('agent-device-connect-device-type-reject-'); - const base = { json: false, help: false, version: false, platform: 'android' as const }; - - try { - for (const [provider, flags, env] of [ - ['limrun', { ...base, tenant: 'team-a', runId: 'run-a' }, { LIMRUN_API_KEY: 'lim_test_key' }], - ] as const) { - await assert.rejects( - resolveConnectProviderProfile({ - provider, - stateDir: path.join(tempRoot, '.state'), - cwd: tempRoot, - env, - flags: { ...flags, providerDeviceType: 'real' }, - }), - (error: unknown) => { - assert.ok(error instanceof AppError); - assert.equal(error.code, 'INVALID_ARGS'); - assert.match(error.message, /^--provider-device-type is not supported by /); - assert.equal(error.details?.provider, provider); - return true; - }, - ); - } - assert.equal(fs.existsSync(path.join(tempRoot, '.state')), false); - } finally { - fs.rmSync(tempRoot, { recursive: true, force: true }); - } -}); - -test('connect limrun refuses the device type', async () => { - const result = await runCliCapture( - [ - 'connect', - 'limrun', - '--session', - 'ci', - '--platform', - 'ios', - '--provider-device-type', - 'real', - '--json', - ], - { - env: { LIMRUN_API_KEY: 'lim_test_key' }, - stateDirPrefix: 'agent-device-connect-limrun-device-type-', - }, - ); - assert.equal(result.code, 1); - assert.match(result.stdout, /--provider-device-type is not supported by Limrun/); -}); - function readGeneratedConfig(configPath: string): { providerApp?: string; providerOsVersion?: string; diff --git a/src/__tests__/daemon-client-provider-credentials.test.ts b/src/__tests__/daemon-client-provider-credentials.test.ts index edc5db5567..8bb4bd249b 100644 --- a/src/__tests__/daemon-client-provider-credentials.test.ts +++ b/src/__tests__/daemon-client-provider-credentials.test.ts @@ -13,12 +13,12 @@ import { skipWhenLoopbackUnavailable, } from '@agent-device/test-kit'; import { providerCredentialFingerprint as fingerprintFor } from '@agent-device/plugins/credential-fingerprint'; -import { builtinPluginInventory } from './test-utils/builtin-plugin-inventory.ts'; +import { limrunPluginInventory } from './test-utils/limrun-plugin-inventory.ts'; import type { EnvMap } from '@agent-device/kernel/source-value'; import { pluginCredentialVariables } from '@agent-device/contracts/plugin-inventory'; import { readDaemonProviderCredentials } from '../provider-credential-fingerprint.ts'; -const inventory = await builtinPluginInventory(); +const inventory = await limrunPluginInventory(); const providerCredentialFingerprint = (provider: string, env: EnvMap, leaseBackend?: string) => fingerprintFor(provider, env, leaseBackend, inventory); diff --git a/src/__tests__/lease-provider-profile-fields.test.ts b/src/__tests__/lease-provider-profile-fields.test.ts index dd07a710d8..b953bb25a0 100644 --- a/src/__tests__/lease-provider-profile-fields.test.ts +++ b/src/__tests__/lease-provider-profile-fields.test.ts @@ -12,6 +12,12 @@ import { runCliCapture } from './cli-capture.ts'; import { makeTempWorkspace } from '@agent-device/test-kit'; import { startPublicDaemonRuntime } from './test-utils/public-daemon-runtime.ts'; +vi.mock('@agent-device/plugins/store', async (importOriginal) => + (await import('./test-utils/limrun-plugin-store.ts')).storeWithLimrunInstalled( + importOriginal as () => Promise, + ), +); + const limrunInstances = vi.hoisted(() => ({ iosCreate: vi.fn(async () => { throw new Error('a refused allocation must not create a Limrun instance'); diff --git a/src/__tests__/limrun-runtime.test.ts b/src/__tests__/limrun-runtime.test.ts index ee8e8df212..34a0bcaf5c 100644 --- a/src/__tests__/limrun-runtime.test.ts +++ b/src/__tests__/limrun-runtime.test.ts @@ -5,8 +5,8 @@ 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 { createLimrunRuntime, type LimrunRuntimeOptions } from '@agent-device/provider-limrun'; -import { createLimrunRuntimeDependencies } from '../sdk/limrun-runtime-dependencies.ts'; +import { createLimrunRuntime, type LimrunRuntimeOptions } from '@agent-device/limrun/runtime'; +import { limrunRuntimeDependencies } from '../provider-plugin-host-capabilities.fixtures.ts'; import type { DeviceLease } from '@agent-device/contracts/device'; import type { DeviceInfo } from '@agent-device/kernel/device'; import { AppError } from '@agent-device/kernel/errors'; @@ -16,11 +16,11 @@ import { readVersion } from '@agent-device/host-kit/version'; import { mkdtempForTestSync } from '@agent-device/test-kit'; // The daemon's own composition: the provider runtime over the host adapters the daemon builds. -function createTestRuntime( +async function createTestRuntime( options: LimrunRuntimeOptions, host: HostEnvironment = { env: process.env, cwd: process.cwd() }, -): ReturnType { - return createLimrunRuntime(options, createLimrunRuntimeDependencies(host)); +): Promise> { + return createLimrunRuntime(options, await limrunRuntimeDependencies(host)); } type LimrunInstancePage = { @@ -157,7 +157,7 @@ afterEach(() => { }); test('Limrun runtime identifies direct CLI usage when creating an instance', async () => { - const runtime = createTestRuntime({ + const runtime = await createTestRuntime({ apiKey: 'lim_test_key', }); @@ -194,7 +194,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 = createTestRuntime({ apiKey: 'lim_test_key' }); + const runtime = await createTestRuntime({ apiKey: 'lim_test_key' }); const lease = iosLease('lease-repeat'); try { const allocateLease = runtime.leaseLifecycle.allocate; @@ -214,7 +214,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 = createTestRuntime({ apiKey: 'lim_test_key' }); + const runtime = await createTestRuntime({ apiKey: 'lim_test_key' }); const metadata = new Map([ ['com.apple.Preferences', ''], [ @@ -273,7 +273,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 = createTestRuntime({ apiKey: 'lim_test_key' }); + const runtime = await createTestRuntime({ apiKey: 'lim_test_key' }); const lease = iosLease('lease-recovered-ios'); limrunMockState.iosList.mockResolvedValueOnce({ getPaginatedItems: () => [{ metadata: { id: 'ios-instance-recovered' } }], @@ -296,7 +296,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 = createTestRuntime({ + const runtime = await createTestRuntime({ apiKey: 'lim_test_key', }); @@ -323,7 +323,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 = createTestRuntime({ apiKey: 'lim_test_key', keepAlive: true }); + const runtime = await createTestRuntime({ apiKey: 'lim_test_key', keepAlive: true }); const lease = androidLease(); await allocateLimrunDevice(runtime, lease); await vi.advanceTimersByTimeAsync(60_000); @@ -340,7 +340,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 = createTestRuntime({ apiKey: 'lim_test_key' }); + const runtime = await createTestRuntime({ apiKey: 'lim_test_key' }); await allocateLimrunDevice(runtime, androidLease()); await vi.advanceTimersByTimeAsync(60_000); assert.equal(limrunMockState.androidKeepAlive.mock.calls.length, 0); @@ -356,7 +356,7 @@ test('Limrun keepAlive keeps pinging after the client throws', async () => { limrunMockState.androidKeepAlive.mockImplementationOnce(() => { throw new Error('socket closed'); }); - const runtime = createTestRuntime({ apiKey: 'lim_test_key', keepAlive: true }); + const runtime = await createTestRuntime({ apiKey: 'lim_test_key', keepAlive: true }); await allocateLimrunDevice(runtime, androidLease()); await vi.advanceTimersByTimeAsync(60_000); assert.equal(limrunMockState.androidKeepAlive.mock.calls.length, 2); @@ -439,7 +439,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 = createTestRuntime({ + const runtime = await createTestRuntime({ apiKey: 'lim_test_key', }); const lease = androidLease(); @@ -476,7 +476,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 = createTestRuntime({ apiKey: 'lim_test_key' }); + const runtime = await createTestRuntime({ apiKey: 'lim_test_key' }); try { await allocateLimrunDevice(runtime, androidLease()); @@ -505,7 +505,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 = createTestRuntime({ + const runtime = await createTestRuntime({ apiKey: 'lim_test_key', }); const lease = iosLease('lease-ios'); @@ -554,7 +554,7 @@ test('Limrun iOS reads the bundle display name before syncing an app bundle', as '', ].join(''), ); - const runtime = createTestRuntime({ apiKey: 'lim_test_key' }); + const runtime = await createTestRuntime({ apiKey: 'lim_test_key' }); try { const device = await allocateLimrunDevice(runtime, { @@ -572,7 +572,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 = createTestRuntime({ + const runtime = await createTestRuntime({ apiKey: 'lim_test_key', }); const lease = androidLease(); @@ -609,7 +609,7 @@ test('Limrun Android configures an explicit port reverse', async () => { }); test('Limrun Android preserves canonical ADB failure classification', async () => { - const runtime = createTestRuntime({ apiKey: 'lim_test_key' }); + const runtime = await createTestRuntime({ apiKey: 'lim_test_key' }); try { await allocateLimrunDevice(runtime, androidLease()); @@ -645,7 +645,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 = createTestRuntime({ + const runtime = await createTestRuntime({ apiKey: 'lim_test_key', }); const lease = iosLease('lease-ios'); @@ -668,7 +668,7 @@ test('Limrun deletes Android instance when post-create validation fails', async apiUrl: 'https://android.example', }, } as never); - const runtime = createTestRuntime({ + const runtime = await createTestRuntime({ apiKey: 'lim_test_key', }); const lease = androidLease(); @@ -684,7 +684,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 = createTestRuntime({ + const runtime = await createTestRuntime({ apiKey: 'lim_test_key', }); const lease = androidLease(); @@ -728,7 +728,7 @@ const ATTACHED_ANDROID = { }; test('Limrun drives existing instances without an API key and never deletes them', async () => { - const runtime = createTestRuntime({ + const runtime = await createTestRuntime({ instances: { ios: ATTACHED_IOS, android: ATTACHED_ANDROID }, }); const releaseLease = runtime.leaseLifecycle.release; @@ -768,7 +768,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 = createTestRuntime({ instances: { android: ATTACHED_ANDROID } }); + const runtime = await createTestRuntime({ instances: { android: ATTACHED_ANDROID } }); const lease = { ...androidLease(), leaseId: 'lease-attached-android' }; vi.mocked(runCmd).mockImplementation(async (_command, args) => ({ stdout: args.includes('--list') @@ -798,7 +798,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 = createTestRuntime({ instances: { android: ATTACHED_ANDROID } }); + const runtime = await createTestRuntime({ instances: { android: ATTACHED_ANDROID } }); const lease = { ...androidLease(), leaseId: 'lease-attached-android' }; vi.mocked(runCmd).mockImplementation(async (_command, args) => args.includes('--no-rebind') @@ -838,7 +838,10 @@ 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 = createTestRuntime({ apiKey: 'lim_test_key', instances: { ios: ATTACHED_IOS } }); + const runtime = await createTestRuntime({ + apiKey: 'lim_test_key', + instances: { ios: ATTACHED_IOS }, + }); await allocateLimrunDevice(runtime, iosLease('lease-attached-ios')); await allocateLimrunDevice(runtime, androidLease()); @@ -854,7 +857,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 = createTestRuntime({ instances: { ios: ATTACHED_IOS } }); + const runtime = await createTestRuntime({ instances: { ios: ATTACHED_IOS } }); try { await assert.rejects(allocateLimrunDevice(runtime, androidLease()), { @@ -864,11 +867,11 @@ test('Limrun without an API key refuses operations that need one', async () => { } finally { await runtime.shutdown(); } - assert.throws(() => createTestRuntime({}), /requires an apiKey or instance access/); + await assert.rejects(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 = createTestRuntime({ instances: { ios: ATTACHED_IOS } }); + const runtime = await createTestRuntime({ instances: { ios: ATTACHED_IOS } }); const allocateLease = runtime.leaseLifecycle.allocate; if (!allocateLease) throw new Error('Limrun runtime must provide lease allocation'); try { @@ -888,8 +891,8 @@ test('Limrun attaches an existing instance under a consumed field and refuses a test('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) => - createTestRuntime({ apiKey: 'lim_test_key' }, host(owner)), + const runtimes = await Promise.all( + ['first', 'second'].map((owner) => createTestRuntime({ apiKey: 'lim_test_key' }, host(owner))), ); vi.mocked(runCmd).mockImplementation(async () => ({ stdout: `mCurrentFocus=Window{1 u0 com.${commandHostEnvironment().env.SDK_OWNER}/.MainActivity}`, diff --git a/src/__tests__/provider-device-runtimes.test.ts b/src/__tests__/provider-device-runtimes.test.ts index 0088a0b21e..01175714c1 100644 --- a/src/__tests__/provider-device-runtimes.test.ts +++ b/src/__tests__/provider-device-runtimes.test.ts @@ -1,7 +1,11 @@ import { createPlatformPluginHost } from '../platform-runtime/plugin-host.ts'; import assert from 'node:assert/strict'; import { test } from 'vitest'; -import { createDaemonProviderRuntimeComposition as composeDaemonProviders } from '../provider-device-runtimes.ts'; +import { + createDaemonProviderRuntimeComposition as composeDaemonProviders, + createEmbeddedProviderRuntimeComposition, +} from '../provider-device-runtimes.ts'; +import { limrunPluginCandidate } from './test-utils/limrun-plugin-store.ts'; import fs from 'node:fs'; import path from 'node:path'; import { pluginHome, selectPlugin, pluginSource } from '@agent-device/test-kit'; @@ -12,6 +16,16 @@ function createDaemonProviderRuntimeComposition( return composeDaemonProviders(host, createPlatformPluginHost(host, host.cwd)); } +/** The daemon's composition with the Limrun plugin installed, without an on-disk store. */ +function composeWithLimrunInstalled(env: Record) { + const host = { env, cwd: process.cwd() }; + return createEmbeddedProviderRuntimeComposition( + host, + [limrunPluginCandidate()], + createPlatformPluginHost(host, host.cwd), + ); +} + test('daemon composition registers installed provider runtimes and their lazy platform modules', async () => { const { home, env } = pluginHome(); selectPlugin(home, 'example', pluginSource('example')); @@ -28,7 +42,7 @@ test('daemon composition registers installed provider runtimes and their lazy pl await composition.shutdown(); }); -test('an unconfigured Limrun stays dormant while the store provider registers', async () => { +test('core registers no Limrun provider of its own beside the store provider', async () => { const { home, env } = pluginHome(); selectPlugin(home, 'example', pluginSource('example')); const composition = await createDaemonProviderRuntimeComposition({ @@ -47,23 +61,15 @@ test('an unconfigured Limrun stays dormant while the store provider registers', await composition.shutdown(); }); -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', pluginSource('example')); - const composition = await createDaemonProviderRuntimeComposition({ - env: { - ...env, - LIMRUN_API_KEY: 'lim_test_key', - LIM_ANDROID_INSTANCE_URL: 'https://region.limrun.example/v1/android_x/api', - LIM_ANDROID_INSTANCE_TOKEN: 'android-instance-token', - }, - cwd: process.cwd(), +test('an installed Limrun is recorded as failed for a partial instance set', async () => { + const composition = await composeWithLimrunInstalled({ + ...pluginHome().env, + LIMRUN_API_KEY: 'lim_test_key', + LIM_ANDROID_INSTANCE_URL: 'https://region.limrun.example/v1/android_x/api', + LIM_ANDROID_INSTANCE_TOKEN: 'android-instance-token', }); - assert.deepEqual( - composition.runtimes.map((runtime) => runtime.provider), - ['example'], - ); + assert.deepEqual(composition.runtimes, []); const limrun = composition.inventory.find(({ provider }) => provider === 'limrun'); assert.equal(limrun?.state, 'failed'); assert.equal(limrun?.error?.code, 'INVALID_ARGS'); @@ -71,23 +77,6 @@ test('daemon composition records Limrun as failed for a partial instance set and await composition.shutdown(); }); -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']) { - const { home, env } = pluginHome(); - selectPlugin(home, 'example', pluginSource(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, 'duplicate_provider'); - // An unconfigured Limrun claims its id without registering a runtime. - assert.equal(composition.runtimes.filter((runtime) => runtime.provider === provider).length, 0); - await composition.shutdown(); - } -}); - test('BrowserStack registers as an ordinary store plugin, not a built-in', async () => { const { home, env } = pluginHome(); selectPlugin(home, '@agent-device/browserstack', pluginSource('browserstack')); @@ -137,55 +126,47 @@ test('a plugin claiming a routing identity is refused before the registry settle } }); -test('Limrun stays unregistered when only the removed API key alias is configured', async () => { - const { env } = pluginHome(); - const { runtimes, platformModules, inventory, shutdown } = - await createDaemonProviderRuntimeComposition({ - env: { - ...env, - LIM_API_KEY: 'lim_test_key', - }, - cwd: process.cwd(), - }); +test('an installed Limrun names the credentials it needs when only the removed API key alias is configured', async () => { + const { runtimes, platformModules, inventory, shutdown } = await composeWithLimrunInstalled({ + ...pluginHome().env, + LIM_API_KEY: 'lim_test_key', + }); assert.equal( runtimes.some((runtime) => runtime.provider === 'limrun'), false, ); - assert.equal( - inventory.some(({ provider }) => provider === 'limrun'), - false, - ); + const limrun = inventory.find(({ provider }) => provider === 'limrun'); + assert.equal(limrun?.state, 'failed'); + assert.equal(limrun?.error?.reason, 'missing_provider_credentials'); assertPlatformModuleCoverage(runtimes, platformModules); await shutdown(); }); -test('Limrun registers when a Limrun API key is configured', async () => { - const { env } = pluginHome(); - const { runtimes, platformModules, shutdown } = await createDaemonProviderRuntimeComposition({ - env: { - ...env, - LIMRUN_API_KEY: 'lim_test_key', - }, - cwd: process.cwd(), +test('an installed Limrun registers when a Limrun API key is configured', async () => { + const { runtimes, platformModules, inventory, shutdown } = await composeWithLimrunInstalled({ + ...pluginHome().env, + LIMRUN_API_KEY: 'lim_test_key', }); const limrun = runtimes.find((runtime) => runtime.provider === 'limrun'); assert.ok(limrun); assert.equal('loadRuntime' in limrun, false); + assert.deepEqual( + inventory + .filter(({ provider }) => provider === 'limrun') + .map(({ source, state, package: name }) => [source, state, name]), + [['store', 'active', '@agent-device/limrun']], + ); assertPlatformModuleCoverage(runtimes, platformModules, [limrun]); await shutdown(); }); -test('Limrun registers for an existing instance without an API key', async () => { - const { env } = pluginHome(); - const { runtimes, platformModules, shutdown } = await createDaemonProviderRuntimeComposition({ - env: { - ...env, - LIM_IOS_INSTANCE_URL: 'https://region.limrun.example/v1/ios_x/api', - LIM_IOS_INSTANCE_TOKEN: 'ios-instance-token', - }, - cwd: process.cwd(), +test('an installed Limrun registers for an existing instance without an API key', async () => { + const { runtimes, platformModules, shutdown } = await composeWithLimrunInstalled({ + ...pluginHome().env, + LIM_IOS_INSTANCE_URL: 'https://region.limrun.example/v1/ios_x/api', + LIM_IOS_INSTANCE_TOKEN: 'ios-instance-token', }); const limrun = runtimes.find((runtime) => runtime.provider === 'limrun'); diff --git a/src/__tests__/remote-connection.test.ts b/src/__tests__/remote-connection.test.ts index 301e6f80e1..81e3964b25 100644 --- a/src/__tests__/remote-connection.test.ts +++ b/src/__tests__/remote-connection.test.ts @@ -41,6 +41,12 @@ import { } from '@agent-device/remote/remote-connection-state'; import type { AgentDeviceClient } from '@agent-device/command-surface'; +vi.mock('@agent-device/plugins/store', async (importOriginal) => + (await import('./test-utils/limrun-plugin-store.ts')).storeWithLimrunInstalled( + importOriginal as () => Promise, + ), +); + afterEach(() => { vi.clearAllMocks(); vi.restoreAllMocks(); diff --git a/src/__tests__/test-utils/builtin-plugin-inventory.ts b/src/__tests__/test-utils/builtin-plugin-inventory.ts deleted file mode 100644 index 3065189bd0..0000000000 --- a/src/__tests__/test-utils/builtin-plugin-inventory.ts +++ /dev/null @@ -1,14 +0,0 @@ -import type { PluginInventoryEntry } from '@agent-device/contracts/plugin-inventory'; -import { resolveProviderPlugins } from '@agent-device/plugins/registry'; -import { builtinProviderCandidates } from '../../builtin-provider-plugins.ts'; - -/** - * The inventory the built-in providers have after load and validation, with every one of them - * configured. It does not include setup failures, which only a started registry records. - */ -export async function builtinPluginInventory(): Promise { - const resolved = await resolveProviderPlugins( - builtinProviderCandidates({ env: { LIMRUN_API_KEY: 'configured' }, cwd: process.cwd() }), - ); - return resolved.inventory(); -} diff --git a/src/__tests__/test-utils/limrun-plugin-inventory.ts b/src/__tests__/test-utils/limrun-plugin-inventory.ts new file mode 100644 index 0000000000..764ac627bb --- /dev/null +++ b/src/__tests__/test-utils/limrun-plugin-inventory.ts @@ -0,0 +1,9 @@ +import type { PluginInventoryEntry } from '@agent-device/contracts/plugin-inventory'; +import { resolveProviderPlugins } from '@agent-device/plugins/registry'; +import { limrunPluginCandidate } from './limrun-plugin-store.ts'; + +/** The inventory one installed Limrun plugin produces, the way the daemon reads it. */ +export async function limrunPluginInventory(): Promise { + const resolved = await resolveProviderPlugins([limrunPluginCandidate()]); + return resolved.inventory(); +} diff --git a/src/__tests__/test-utils/limrun-plugin-store.ts b/src/__tests__/test-utils/limrun-plugin-store.ts new file mode 100644 index 0000000000..bfc36aa4a7 --- /dev/null +++ b/src/__tests__/test-utils/limrun-plugin-store.ts @@ -0,0 +1,30 @@ +import type { PluginCandidate } from '@agent-device/plugins/registry'; + +type Store = typeof import('@agent-device/plugins/store'); + +/** The Limrun package as an installed store plugin, without touching the on-disk store. */ +export function limrunPluginCandidate(): PluginCandidate { + return { + source: 'store', + package: '@agent-device/limrun', + load: async () => (await import('@agent-device/limrun')).default(), + }; +} + +/** + * The plugin store with the workspace Limrun package installed, for a `vi.mock` of + * `@agent-device/plugins/store`: every reader of the store then sees what a user who ran + * `plugins add @agent-device/limrun` has. + */ +export async function storeWithLimrunInstalled( + importOriginal: () => Promise, +): Promise { + const original = await importOriginal(); + return { + ...original, + storePluginCandidates: async (env) => [ + ...(await original.storePluginCandidates(env)), + limrunPluginCandidate(), + ], + }; +} diff --git a/src/builtin-provider-ids.ts b/src/builtin-provider-ids.ts deleted file mode 100644 index e0d0b87a3a..0000000000 --- a/src/builtin-provider-ids.ts +++ /dev/null @@ -1,25 +0,0 @@ -import type { ConnectionProviderCapabilities } from '@agent-device/contracts/remote'; -import { ROUTING_PROVIDER_IDENTITIES } from '@agent-device/plugins/contract'; -import { LIMRUN_CONNECTION_CAPABILITIES } from '@agent-device/provider-limrun/internal'; - -export const LIMRUN_ID = 'limrun'; - -/** Every provider id agent-device registers itself; a plugin cannot claim any of them. */ -export const BUILTIN_PROVIDER_IDS: readonly string[] = [LIMRUN_ID]; - -/** Provider ids `connect` accepts without a plugin: the routing identities and the built-ins. */ -export const BUILTIN_CONNECT_PROVIDER_IDS: readonly string[] = [ - ...ROUTING_PROVIDER_IDENTITIES, - ...BUILTIN_PROVIDER_IDS, -]; - -/** - * The built-in provider's connect capabilities, read without loading its implementation. The - * provider package declares what its lease is; this names which built-in answers with that - * declaration, so a synchronous routing read never has to load the plugin registry. - */ -export function builtinConnectionCapabilities( - provider: string | undefined, -): ConnectionProviderCapabilities | undefined { - return provider === LIMRUN_ID ? LIMRUN_CONNECTION_CAPABILITIES : undefined; -} diff --git a/src/builtin-provider-plugins.test.ts b/src/builtin-provider-plugins.test.ts deleted file mode 100644 index d16c6a4b7f..0000000000 --- a/src/builtin-provider-plugins.test.ts +++ /dev/null @@ -1,212 +0,0 @@ -import { createPlatformPluginHost } from './platform-runtime/plugin-host.ts'; -import assert from 'node:assert/strict'; -import { afterEach, test, vi } from 'vitest'; -import { mkdtempForTestSync } from '@agent-device/test-kit'; -import { readVersion } from '@agent-device/host-kit/version'; -import { createEmbeddedProviderRuntimeComposition as composeEmbeddedProviders } from './provider-device-runtimes.ts'; -import { builtinLimrunConnection } from './builtin-provider-plugins.ts'; - -// The built-in candidate is composed by the daemon's own registry, so the case runs the real plugin -// contract with the Limrun SDK stubbed out: nothing here reaches the provider's API. -const limrunSdk = vi.hoisted(() => { - const clients: Array> = []; - const androidList = vi.fn(async () => ({ getPaginatedItems: () => [] })); - const iosList = vi.fn(async () => ({ getPaginatedItems: () => [] })); - return { clients, androidList, iosList }; -}); - -vi.mock('@limrun/api', () => ({ - default: class MockLimrun { - readonly iosInstances = { list: limrunSdk.iosList }; - readonly androidInstances = { list: limrunSdk.androidList }; - - constructor(options: Record) { - limrunSdk.clients.push(options); - } - }, -})); - -// The root's own runtime-adapter factory is the runtime half of the built-in composition. Spying on -// it in place, and answering with the real adapters, is what proves a `connect` composes the -// provider's callbacks without setting up a runtime. -const runtimeDependencies = vi.hoisted(() => ({ create: vi.fn() })); -vi.mock('./sdk/limrun-runtime-dependencies.ts', async (importOriginal) => { - const original = await importOriginal(); - return { - ...original, - createLimrunRuntimeDependencies: ( - ...args: Parameters - ) => { - runtimeDependencies.create(...args); - return original.createLimrunRuntimeDependencies(...args); - }, - }; -}); - -afterEach(() => { - limrunSdk.clients.length = 0; - limrunSdk.androidList.mockClear(); - limrunSdk.iosList.mockClear(); - runtimeDependencies.create.mockClear(); -}); - -function createEmbeddedProviderRuntimeComposition( - host: Parameters[0], - candidates: Parameters[1], -) { - return composeEmbeddedProviders(host, candidates, createPlatformPluginHost(host, host.cwd)); -} - -test('an unconfigured built-in Limrun claims its id without an inventory entry or a runtime', async () => { - const composition = await createEmbeddedProviderRuntimeComposition( - { env: {}, cwd: process.cwd() }, - [], - ); - - try { - assert.deepEqual( - composition.runtimes.map(({ provider }) => provider), - [], - ); - assert.deepEqual( - composition.inventory.map(({ provider }) => provider), - [], - ); - } finally { - await composition.shutdown(); - } -}); - -test('a configured built-in Limrun registers through the plugin contract with its per-backend credential narrowing', async () => { - const composition = await createEmbeddedProviderRuntimeComposition( - { - env: { - LIMRUN_API_KEY: 'lim_test_key', - AGENT_DEVICE_STATE_DIR: mkdtempForTestSync('agent-device-builtin-limrun-'), - }, - cwd: process.cwd(), - }, - [], - ); - - try { - assert.deepEqual( - composition.inventory - .filter(({ provider }) => provider === 'limrun') - .map(({ provider, source, state }) => [provider, source, state]), - [['limrun', 'builtin', 'active']], - ); - const registered = composition.runtimes.find(({ provider }) => provider === 'limrun'); - assert.ok(registered, 'a configured built-in registers its runtime'); - assert.deepEqual( - composition.platformModules - .filter(({ runtime }) => runtime === registered) - .map(({ module }) => [module.owner.kind, module.owner.provider]), - [['provider-runtime', 'limrun']], - ); - // The fingerprint the daemon and the client both read is the plugin's own declaration: the - // account variables plus only the leased platform's instance variables. - assert.deepEqual( - composition.inventory.find(({ provider }) => provider === 'limrun')?.credentials, - { - variables: [ - 'LIMRUN_API_KEY', - 'LIMRUN_REGION', - 'LIM_IOS_INSTANCE_URL', - 'LIM_IOS_INSTANCE_TOKEN', - 'LIM_ANDROID_INSTANCE_URL', - 'LIM_ANDROID_INSTANCE_TOKEN', - 'LIM_ANDROID_INSTANCE_ADB_URL', - ], - byBackend: { - 'ios-instance': [ - 'LIMRUN_API_KEY', - 'LIMRUN_REGION', - 'LIM_IOS_INSTANCE_URL', - 'LIM_IOS_INSTANCE_TOKEN', - ], - 'android-instance': [ - 'LIMRUN_API_KEY', - 'LIMRUN_REGION', - 'LIM_ANDROID_INSTANCE_URL', - 'LIM_ANDROID_INSTANCE_TOKEN', - 'LIM_ANDROID_INSTANCE_ADB_URL', - ], - }, - }, - ); - } finally { - await composition.shutdown(); - } -}); - -test('the built-in connection answers connect with the provider callbacks and its own verification', async () => { - const stateDir = mkdtempForTestSync('agent-device-builtin-limrun-connection-'); - const host = { - env: { LIMRUN_API_KEY: 'lim_test_key', AGENT_DEVICE_STATE_DIR: stateDir }, - cwd: process.cwd(), - }; - - const connection = await builtinLimrunConnection(); - // Composing the connection reads nothing about a runtime: the host adapters are what `setup` - // asks for, and `connect` never calls it. - assert.deepEqual(runtimeDependencies.create.mock.calls, []); - assert.deepEqual(limrunSdk.clients, []); - - // `resolve` runs the provider's own flag, backend, and credential rules. - const resolved = await connection.resolve({ - flags: { json: true, help: false, version: false, stateDir, platform: 'android' }, - stateDir, - cwd: host.cwd, - env: host.env, - }); - assert.equal(resolved.profile.leaseProvider, 'limrun'); - assert.equal(resolved.profile.leaseBackend, 'android-instance'); - assert.deepEqual(limrunSdk.clients, []); - - // `verify` runs the provider's own read-only account check through the SDK: the credentials of - // this call's env, this host's version, and only the platform this call selected. No instance is - // created, and no runtime is set up. - const verification = await connection.verify({ - flags: { json: true, help: false, version: false, stateDir, platform: 'android' }, - cwd: host.cwd, - env: host.env, - }); - assert.equal(verification.service, 'Limrun'); - assert.equal( - verification.verificationMessage, - 'Credentials and Android instance access verified.', - ); - assert.deepEqual(limrunSdk.clients, [ - { - apiKey: 'lim_test_key', - userAgent: `agent-device-cli/${readVersion()}`, - timeout: 15_000, - maxRetries: 0, - }, - ]); - assert.deepEqual(limrunSdk.androidList.mock.calls, [[{ limit: 1 }]]); - assert.deepEqual(limrunSdk.iosList.mock.calls, []); - assert.deepEqual(runtimeDependencies.create.mock.calls, []); -}); - -test('the built-in connection verifies the iOS platform another connect call selected', async () => { - const stateDir = mkdtempForTestSync('agent-device-builtin-limrun-connection-ios-'); - const host = { - env: { LIMRUN_API_KEY: 'lim_test_key', AGENT_DEVICE_STATE_DIR: stateDir }, - cwd: process.cwd(), - }; - const connection = await builtinLimrunConnection(); - const verification = await connection.verify({ - flags: { json: true, help: false, version: false, stateDir, platform: 'ios' }, - cwd: host.cwd, - env: { ...host.env, LIMRUN_REGION: 'eu', LIMRUN_API_KEY: ' lim_test_key ' }, - }); - - assert.equal(verification.verificationMessage, 'Credentials and iOS instance access verified.'); - // The key is read the provider reads it, the region narrows the query, and the platform decides - // which service is asked. - assert.equal(limrunSdk.clients[0]?.apiKey, 'lim_test_key'); - assert.deepEqual(limrunSdk.iosList.mock.calls, [[{ limit: 1, region: 'eu' }]]); - assert.deepEqual(limrunSdk.androidList.mock.calls, []); -}); diff --git a/src/builtin-provider-plugins.ts b/src/builtin-provider-plugins.ts deleted file mode 100644 index 6081e18825..0000000000 --- a/src/builtin-provider-plugins.ts +++ /dev/null @@ -1,71 +0,0 @@ -import type { PluginCandidate } from '@agent-device/plugins/registry'; -import type { PluginConnectionCallbacks } from '@agent-device/plugins/connection'; -import { LIMRUN_ID } from './builtin-provider-ids.ts'; -import type { HostEnvironment } from '@agent-device/kernel/source-value'; -import { resolveDaemonPaths } from '@agent-device/daemon-contracts/daemon-resolution'; -import { - LIMRUN_CONNECTION, - limrunPlugin, - readLimrunCredentials, - type LimrunPluginOptions, -} from '@agent-device/provider-limrun/internal'; - -/** - * The built-in providers as registry candidates, in the shape a plugin has. Their implementations - * load only when a runtime is set up; a candidate that needs configuration claims its id without - * registering until the environment holds it. - */ -export function builtinProviderCandidates(host: HostEnvironment): PluginCandidate[] { - return [limrunCandidate(host)]; -} - -function limrunCandidate(host: HostEnvironment): PluginCandidate { - const base = { - source: 'builtin' as const, - declaredClaims: [{ kind: 'provider' as const, id: LIMRUN_ID }], - }; - // The provider owns what counts as its credentials; the candidate only asks whether this host - // holds them, so an unconfigured process keeps the id dormant and never loads the runtime. - let configured: boolean; - try { - configured = readLimrunCredentials(host.env) !== undefined; - } catch (error) { - return { ...base, load: () => Promise.reject(error) }; - } - if (!configured) return { ...base, dormant: true, load: () => undefined }; - return { - ...base, - load: () => limrunPlugin(builtinLimrunPluginOptions(host)), - }; -} - -/** - * How the composing root answers what the built-in provider asks for: the platform's own host - * adapters build its runtime. - */ -function builtinLimrunPluginOptions(host: HostEnvironment): LimrunPluginOptions { - return { - // The host adapters are the root's own: the provider names what a runtime needs, and this - // composition answers with its platform owners and this host's env/cwd. - createDependencies: async () => - (await import('./sdk/limrun-runtime-dependencies.ts')).createLimrunRuntimeDependencies(host), - // HAR captures land beside the session files, under the daemon's own state dir. The state - // dir is resolved with the load, so an unconfigured process never probes for one. - stateDir: resolveDaemonPaths(host.env.AGENT_DEVICE_STATE_DIR, { - env: host.env, - cwd: host.cwd, - }).baseDir, - }; -} - -/** - * The built-in Limrun connection the CLI `connect` runs: the provider's own callbacks, wired to the - * calling invocation's host the same way the daemon's registry wires an installed plugin's. The - * read-only check is the provider's own, so both answers verify through one entry, and the SDK loads - * only when a callback runs. - */ -export async function builtinLimrunConnection(): Promise { - const { withConnectionHost } = await import('@agent-device/plugins/registry'); - const connection = withConnectionHost(LIMRUN_CONNECTION, undefined); - return { resolve: connection.resolve, verify: connection.verify }; -} diff --git a/src/cli/commands/connection-runtime-shutdown.test.ts b/src/cli/commands/connection-runtime-shutdown.test.ts index 430bdae03e..d3162e7093 100644 --- a/src/cli/commands/connection-runtime-shutdown.test.ts +++ b/src/cli/commands/connection-runtime-shutdown.test.ts @@ -1,6 +1,6 @@ import assert from 'node:assert/strict'; import fs from 'node:fs'; -import { test } from 'vitest'; +import { test, vi } from 'vitest'; import { createTestHostEnvironment } from '@agent-device/test-kit'; import { readRemoteConnectionState } from '@agent-device/remote/remote-connection-state'; import { @@ -12,6 +12,12 @@ import { } from '../../__tests__/remote-connection.fixtures.ts'; import { materializeRemoteConnectionForCommand } from './connection-runtime.ts'; +vi.mock('@agent-device/plugins/store', async (importOriginal) => + (await import('../../__tests__/test-utils/limrun-plugin-store.ts')).storeWithLimrunInstalled( + importOriginal as () => Promise, + ), +); + for (const platform of ['ios', 'android'] as const) { const leaseBackend = platform === 'ios' ? 'ios-instance' : 'android-instance'; for (const leaseId of [undefined, 'existing-lease']) { diff --git a/src/cli/commands/plugins.ts b/src/cli/commands/plugins.ts index 70168531f8..0e594b43d2 100644 --- a/src/cli/commands/plugins.ts +++ b/src/cli/commands/plugins.ts @@ -7,7 +7,6 @@ import { } from '@agent-device/daemon-contracts/daemon-registration'; import { AppError } from '@agent-device/kernel/errors'; import { addPluginArtifact, changePlugin, listPlugins } from '@agent-device/plugins/store'; -import { BUILTIN_PROVIDER_IDS } from '../../builtin-provider-ids.ts'; import { writeCommandOutput } from './shared.ts'; import type { ClientCommandHandler } from './router-types.ts'; @@ -30,7 +29,7 @@ export const pluginsCommand: ClientCommandHandler = async ({ host, positionals, if (action !== 'list' && !artifact && name) { await changePlugin(action as 'add' | 'update' | 'remove', name, host.env); } - const plugins = artifact ? [] : await listPlugins(host.env, BUILTIN_PROVIDER_IDS); + const plugins = artifact ? [] : await listPlugins(host.env, []); const daemon = readDaemonStatus(resolveDaemonPaths(flags.stateDir, host)); const daemonPlugins = readPluginInventory(daemon.plugins); const failedInDaemon = daemonPlugins.filter(({ state }) => state === 'failed'); diff --git a/src/cli/connection/connect-provider-adapters.ts b/src/cli/connection/connect-provider-adapters.ts index 10fc8afd16..a2ddec61f2 100644 --- a/src/cli/connection/connect-provider-adapters.ts +++ b/src/cli/connection/connect-provider-adapters.ts @@ -13,10 +13,8 @@ import { primeProviderConnection, type ConnectProvider, } from './provider-policy.ts'; -import { builtinLimrunConnection } from '../../builtin-provider-plugins.ts'; import { withPluginConnection } from '@agent-device/plugins/load'; import type { PluginConnectionCallbacks } from '@agent-device/plugins/connection'; -import { BUILTIN_PROVIDER_IDS } from '../../builtin-provider-ids.ts'; import { readMetroProfileFields } from './profile-fields.ts'; import { buildConnectClientId } from './client-id.ts'; import { persistAndResolveGeneratedProfile } from './generated-config.ts'; @@ -50,8 +48,8 @@ type ConnectProviderAdapter = { /** * The profiles the CLI composes itself: the routing identities answer with a saved connection's - * settings, not a provider's callbacks. Every real provider, built-in or installed, answers `resolve` - * and `verify` through connection callbacks. + * settings, not a provider's callbacks. Every provider is an installed plugin and answers `resolve` + * and `verify` through its connection callbacks. */ const CONNECT_PROVIDER_ADAPTERS: Readonly> = { cloud: { @@ -79,22 +77,12 @@ function builtinConnectAdapter(provider: string): ConnectProviderAdapter | undef : undefined; } -/** - * The connection callbacks one `connect` call runs: the built-in provider's own, composed by the - * root over the provider package's callbacks, or an installed plugin's through the registry. The - * built-in ids stay claimed against the store, so an installed plugin never answers for them. - */ +/** The connection callbacks one `connect` call runs: an installed plugin's, through the registry. */ async function providerConnection( provider: string, host: HostEnvironment, ): Promise { - if (provider === 'limrun') return await builtinLimrunConnection(); - return await withPluginConnection( - provider, - BUILTIN_PROVIDER_IDS, - host.env, - async (connection) => connection, - ); + return await withPluginConnection(provider, [], host.env, async (connection) => connection); } export async function resolveConnectProviderProfile(options: { diff --git a/src/cli/connection/ended-lease.test.ts b/src/cli/connection/ended-lease.test.ts index 59330ea328..31ded15a14 100644 --- a/src/cli/connection/ended-lease.test.ts +++ b/src/cli/connection/ended-lease.test.ts @@ -1,7 +1,7 @@ import { bindTestCommandHost, createTestHostEnvironment } from '@agent-device/test-kit'; import assert from 'node:assert/strict'; import fs from 'node:fs'; -import { test } from 'vitest'; +import { test, vi } from 'vitest'; import type { DaemonResponse } from '@agent-device/kernel/contracts'; import { connectionWorkspace, @@ -10,6 +10,13 @@ import { } from '../../__tests__/remote-connection.fixtures.ts'; import { readRemoteConnectionState } from '@agent-device/remote/remote-connection-state'; import { forgetEndedConnectionLease } from './ended-lease.ts'; +import { primeProviderConnection } from './provider-policy.ts'; + +vi.mock('@agent-device/plugins/store', async (importOriginal) => + (await import('../../__tests__/test-utils/limrun-plugin-store.ts')).storeWithLimrunInstalled( + importOriginal as () => Promise, + ), +); bindTestCommandHost(); @@ -74,7 +81,9 @@ test('the stored lease stays unless the reply ends that lease at response level' for (const reply of replies) assert.equal(storedLeaseIdAfter(reply), LEASE_ID); }); -test('an ended host-allocated lease stays stored', () => { +test('an ended host-allocated lease stays stored', async () => { + // A provider declares in code that it forgets an ended lease, so its plugin loads first. + await primeProviderConnection('limrun', createTestHostEnvironment().env); const reply: DaemonResponse = { ok: true, data: { endedLeases: [...ENDED] } }; assert.equal( storedLeaseIdAfter(reply, { leaseBackend: 'macos-app', platform: 'macos' }), diff --git a/src/cli/connection/provider-policy-limrun-absent.test.ts b/src/cli/connection/provider-policy-limrun-absent.test.ts new file mode 100644 index 0000000000..c7248a9e2b --- /dev/null +++ b/src/cli/connection/provider-policy-limrun-absent.test.ts @@ -0,0 +1,23 @@ +import { test } from 'vitest'; +import assert from 'node:assert/strict'; +import { runCliCapture } from '../../__tests__/cli-capture.ts'; + +test('connect limrun without the plugin answers plugin-not-installed with the install command', async () => { + const result = await runCliCapture( + ['connect', 'limrun', '--session', 'ci', '--platform', 'android', '--json'], + { + env: { LIMRUN_API_KEY: 'lim_test_key' }, + stateDirPrefix: 'agent-device-connect-limrun-absent-', + }, + ); + + assert.equal(result.code, 1); + assert.equal(result.calls.length, 0); + const { error } = JSON.parse(result.stdout); + assert.equal(error.code, 'UNSUPPORTED_OPERATION'); + assert.equal(error.message, 'Limrun requires the @agent-device/limrun plugin.'); + assert.equal(error.details.reason, 'plugin-not-installed'); + assert.equal(error.details.provider, 'limrun'); + assert.equal(error.details.package, '@agent-device/limrun'); + assert.match(error.hint, /agent-device plugins add @agent-device\/limrun/); +}); diff --git a/src/cli/connection/provider-policy.test.ts b/src/cli/connection/provider-policy.test.ts index f873c99af6..345397d614 100644 --- a/src/cli/connection/provider-policy.test.ts +++ b/src/cli/connection/provider-policy.test.ts @@ -12,9 +12,22 @@ import { primeProviderConnection, } from './provider-policy.ts'; import { pluginHome, selectPlugin, pluginSource } from '@agent-device/test-kit'; +import limrun from '@agent-device/limrun'; +import { declaredConnectionCapabilities } from '../../__tests__/test-utils/plugin-declaration.fixtures.ts'; -test('provider policy projects provider identity into semantic capabilities', () => { - assert.deepEqual(connectionProviderCapabilities('limrun', {}), { +test('provider policy projects provider identity into semantic capabilities', async () => { + const limrunStore = pluginHome(); + selectPlugin( + limrunStore.home, + '@agent-device/limrun', + pluginSource('limrun', { + extra: `connection: { capabilities: ${JSON.stringify(declaredConnectionCapabilities(limrun()))}, resolve() {}, verify() {} },`, + }), + ); + // Without the plugin nothing declares Limrun's capabilities; the installed one answers once primed. + assert.equal(connectionProviderCapabilities('limrun', {}).leaseKind, 'remote-provider'); + await primeProviderConnection('limrun', limrunStore.env); + assert.deepEqual(connectionProviderCapabilities('limrun', limrunStore.env), { leaseKind: 'direct-device-provider', requiresAppAttachment: false, requiresRemoteDaemon: false, diff --git a/src/cli/connection/provider-policy.ts b/src/cli/connection/provider-policy.ts index 9e2aeb4028..8fc1970373 100644 --- a/src/cli/connection/provider-policy.ts +++ b/src/cli/connection/provider-policy.ts @@ -13,11 +13,7 @@ import { getProviderPluginDeclaration, providerPluginRepairCommand, } from '../../commands/provider-plugin-catalog.ts'; -import { - BUILTIN_CONNECT_PROVIDER_IDS, - BUILTIN_PROVIDER_IDS, - builtinConnectionCapabilities, -} from '../../builtin-provider-ids.ts'; +import { ROUTING_PROVIDER_IDENTITIES } from '@agent-device/plugins/contract'; export type ConnectProvider = string; @@ -37,15 +33,15 @@ function remoteDaemonConnection( } /** - * Loads the plugin store before the first synchronous capability lookup for a provider that is not - * built in, because a v2 plugin declares its capabilities in code, not in its manifest. + * Loads the plugin store before the first synchronous capability lookup for a provider, because a + * plugin declares its capabilities in code, not in its manifest. */ export async function primeProviderConnection( provider: string | undefined, env: NodeJS.ProcessEnv = process.env, ): Promise { - if (provider === undefined || BUILTIN_CONNECT_PROVIDER_IDS.includes(provider)) return; - await primePluginConnections(env, BUILTIN_PROVIDER_IDS); + if (provider === undefined || ROUTING_PROVIDER_IDENTITIES.includes(provider)) return; + await primePluginConnections(env); if (pluginConnectionCapabilities(provider, env) !== undefined) return; const unavailable = unavailableConnectPluginError(provider, env); if (unavailable) throw unavailable; @@ -57,13 +53,13 @@ export function isConnectProviderName( ): value is ConnectProvider { return ( value !== undefined && - (BUILTIN_CONNECT_PROVIDER_IDS.includes(value) || + (ROUTING_PROVIDER_IDENTITIES.includes(value) || pluginConnectionCapabilities(value, env) !== undefined) ); } export function connectProviderNamesForError(env: NodeJS.ProcessEnv = process.env): string { - const names = [...BUILTIN_CONNECT_PROVIDER_IDS, ...pluginConnectionNames(env)].join(', '); + const names = [...ROUTING_PROVIDER_IDENTITIES, ...pluginConnectionNames(env)].join(', '); const failures = pluginLoadFailures(env).map( ({ package: name, provider, error }) => `${name ?? provider ?? 'plugin store'}: ${error.message}`, @@ -107,16 +103,15 @@ export function unavailableConnectPluginError( ); } -/** Bundled and installed providers declare their capabilities; the rest is the daemon's own routing. */ +/** Installed providers declare their capabilities; the rest is the daemon's own routing. */ export function connectionProviderCapabilities( provider: string | undefined, env: NodeJS.ProcessEnv, ): ConnectionProviderCapabilities { if (provider === 'proxy') return remoteDaemonConnection('proxy'); const declared = - builtinConnectionCapabilities(provider) ?? - (provider === undefined || provider === 'cloud' + provider === undefined || provider === 'cloud' ? undefined - : pluginConnectionCapabilities(provider, env)); + : pluginConnectionCapabilities(provider, env); return declared ?? remoteDaemonConnection('remote-provider'); } diff --git a/src/commands/provider-plugin-catalog.ts b/src/commands/provider-plugin-catalog.ts index 725ee80e12..50148f2d7c 100644 --- a/src/commands/provider-plugin-catalog.ts +++ b/src/commands/provider-plugin-catalog.ts @@ -26,9 +26,17 @@ export const BROWSERSTACK: ProviderPluginDeclaration = { nightlyTag: 'nightly-0.22', }; +export const LIMRUN: ProviderPluginDeclaration = { + provider: 'limrun', + package: '@agent-device/limrun', + label: 'Limrun', + nightlyTag: 'nightly-0.22', +}; + const PROVIDER_PLUGIN_CATALOG: readonly ProviderPluginDeclaration[] = [ AWS_DEVICE_FARM, BROWSERSTACK, + LIMRUN, { provider: 'revyl', package: '@agent-device/revyl', label: 'Revyl' }, { provider: 'testmu', package: '@agent-device/testmu', label: 'TestMu AI' }, { provider: 'webos', package: '@agent-device/webos', label: 'LG webOS' }, diff --git a/src/commands/schema/cli-help-topics.test.ts b/src/commands/schema/cli-help-topics.test.ts index 969eece653..349511fcc0 100644 --- a/src/commands/schema/cli-help-topics.test.ts +++ b/src/commands/schema/cli-help-topics.test.ts @@ -410,7 +410,8 @@ test('usageForCommand resolves remote help topic', async () => { help, /AWS Device Farm \(plugin, install separately\): install the @agent-device\/aws-device-farm plugin/, ); - assert.match(help, /Limrun: agent-device connect limrun/); + assert.match(help, /Limrun \(plugin, install separately\): agent-device connect limrun/); + assert.match(help, /agent-device plugins add @agent-device\/limrun/); assert.match(help, /It does not create an App Automate session/); assert.match(help, /It does not create a remote access session/); assert.match(help, /It does not create an instance/); diff --git a/src/commands/schema/cli-help.ts b/src/commands/schema/cli-help.ts index 7da78b3bbc..dfb6b1e2a4 100644 --- a/src/commands/schema/cli-help.ts +++ b/src/commands/schema/cli-help.ts @@ -29,6 +29,7 @@ import { TV_PLUGIN_FLOWS } from './cli-help-tv.ts'; import { AWS_DEVICE_FARM, BROWSERSTACK, + LIMRUN, providerPluginHelp, providerPluginInstallCommand, } from '../provider-plugin-catalog.ts'; @@ -484,7 +485,7 @@ Providers: BrowserStack (plugin, install separately): agent-device connect browserstack verifies credentials, the exact device, and a bs:// app reference, then stores a local provider profile. It does not create an App Automate session. AWS Device Farm (plugin, install separately): install the @agent-device/aws-device-farm plugin, then agent-device connect aws-device-farm verifies credentials and the exact project, device, and optional app upload, then stores a local provider profile. It does not create a remote access session. TestMu AI (plugin, install separately): agent-device connect testmu verifies credentials and the exact virtual device (emulator or simulator) or, with --provider-device-type real, real device and OS version, then stores a local provider profile. --provider-app takes an lt:// app reference, an https URL, or a local path: connect looks an lt:// id up among your uploads for that device pool, while URL and local sources are uploaded and validated when open creates the session. It does not create a hub session. - Limrun: agent-device connect limrun verifies access to the selected iOS or Android instance service, then stores a local provider profile. It does not create an instance. + Limrun (plugin, install separately): agent-device connect limrun verifies access to the selected iOS or Android instance service, then stores a local provider profile. It does not create an instance. Revyl (plugin, install separately): agent-device connect revyl verifies credentials against the Revyl backend, then stores a local provider profile with the platform, optional --device model and --provider-os-version, and a required --provider-app https URL: Revyl downloads and installs that build when it starts the device. It does not rent a device. Plugin installation: the lines below name the plugin each provider needs, and plugin help is available before installation. plugins list --json reports your installed plugins. A missing plugin returns reason plugin-not-installed with its installation command; a selected plugin that cannot supply the provider returns plugin-unavailable instead. After changing plugins, close sessions and stop an existing local daemon with the same --state-dir before the next device command. @@ -577,6 +578,7 @@ AWS Device Farm hosted-device flow: AWS Device Farm currently supports Android and iOS WebDriver sessions only; Vega OS and Vega Fire TV ARNs are not routed. Limrun direct-device flow: + ${providerPluginInstallCommand(LIMRUN, coreVersion)} export LIMRUN_API_KEY=... AGENT_DEVICE_SESSION=checkout-android agent-device connect limrun --platform android diff --git a/src/daemon-composition-credentials.test.ts b/src/daemon-composition-credentials.test.ts index 71dadac8b9..836dd83d0e 100644 --- a/src/daemon-composition-credentials.test.ts +++ b/src/daemon-composition-credentials.test.ts @@ -5,7 +5,7 @@ import { resolveDaemonPaths } from '@agent-device/daemon-contracts/daemon-resolu import { mkdtempForTestSync, createTestHostEnvironment } from '@agent-device/test-kit'; import { createDaemonRuntimeDeps } from './daemon-composition.ts'; import { providerCredentialFingerprint } from '@agent-device/plugins/credential-fingerprint'; -import { builtinPluginInventory } from './__tests__/test-utils/builtin-plugin-inventory.ts'; +import { limrunPluginInventory } from './__tests__/test-utils/limrun-plugin-inventory.ts'; import { browserstackPluginInventory } from './__tests__/test-utils/browserstack-plugin-inventory.ts'; vi.mock('./platform-runtime.ts', () => ({ @@ -48,8 +48,8 @@ vi.mock('./provider-device-runtimes.ts', async (importOriginal) => ({ shutdown: async () => [], inventory: [ ...(await ( - await import('./__tests__/test-utils/builtin-plugin-inventory.ts') - ).builtinPluginInventory()), + await import('./__tests__/test-utils/limrun-plugin-inventory.ts') + ).limrunPluginInventory()), ...(await ( await import('./__tests__/test-utils/browserstack-plugin-inventory.ts') ).browserstackPluginInventory()), @@ -59,7 +59,7 @@ vi.mock('./provider-device-runtimes.ts', async (importOriginal) => ({ test('daemon startup compares lease credentials with its own startup environment', async () => { const stateDir = mkdtempForTestSync('agent-device-daemon-credential-composition-'); - const inventory = [...(await builtinPluginInventory()), ...(await browserstackPluginInventory())]; + const inventory = [...(await limrunPluginInventory()), ...(await browserstackPluginInventory())]; const daemonEnv = { BROWSERSTACK_USERNAME: 'user', BROWSERSTACK_ACCESS_KEY: 'key-1' }; const runtime = await startDaemonRuntime({ host: createTestHostEnvironment({ diff --git a/src/daemon-runtime-limrun-public-http.test.ts b/src/daemon-runtime-limrun-public-http.test.ts index e3ca4e7e80..e469ccd271 100644 --- a/src/daemon-runtime-limrun-public-http.test.ts +++ b/src/daemon-runtime-limrun-public-http.test.ts @@ -4,7 +4,7 @@ import { test, vi } from 'vitest'; import { startDaemonRuntime } from '@agent-device/daemon'; import { resolveDaemonPaths } from '@agent-device/daemon-contracts/daemon-resolution'; import { createTestHostEnvironment, mkdtempForTestSync } from '@agent-device/test-kit'; -import { createLimrunRuntime } from '@agent-device/provider-limrun'; +import { createLimrunRuntime } from '@agent-device/limrun/runtime'; import { DAEMON_HTTP_NETWORK_ACCESS_HEADER, DAEMON_HTTP_PUBLIC_NETWORK_ACCESS, diff --git a/src/host.test.ts b/src/host.test.ts index ff83d1178e..25b3f40a23 100644 --- a/src/host.test.ts +++ b/src/host.test.ts @@ -12,7 +12,7 @@ import { readProcessStartTime } from '@agent-device/host-kit/process'; import { createTestHostEnvironment, mkdtempForTestSync } from '@agent-device/test-kit'; import type { PluginCandidate } from '@agent-device/plugins/registry'; import type { AgentDevicePlugin } from './sdk/plugins.ts'; -import { builtinPluginInventory } from './__tests__/test-utils/builtin-plugin-inventory.ts'; +import { limrunPluginInventory } from './__tests__/test-utils/limrun-plugin-inventory.ts'; import { stopRecordedDaemon } from '@agent-device/daemon-client'; import { startAgentDevice } from './host.ts'; @@ -82,8 +82,8 @@ vi.mock('./provider-device-runtimes.ts', async (importOriginal) => { shutdown: async () => [], inventory: [ ...(await ( - await import('./__tests__/test-utils/builtin-plugin-inventory.ts') - ).builtinPluginInventory()), + await import('./__tests__/test-utils/limrun-plugin-inventory.ts') + ).limrunPluginInventory()), ...resolved.inventory(), ], }; @@ -232,7 +232,7 @@ test('a host registers the plugins its embedder imported and reports the invento { source: 'embedder', load: expect.any(Function) }, ]); expect(JSON.parse(fs.readFileSync(paths.infoPath, 'utf8')).plugins).toEqual([ - ...(await builtinPluginInventory()), + ...(await limrunPluginInventory()), expect.objectContaining({ provider: 'embedder-plugin', state: 'active', source: 'embedder' }), ]); } finally { diff --git a/src/platform-runtime-gateway.fixtures.ts b/src/platform-runtime-gateway.fixtures.ts index 3c3763c3ce..d21d94257e 100644 --- a/src/platform-runtime-gateway.fixtures.ts +++ b/src/platform-runtime-gateway.fixtures.ts @@ -19,7 +19,7 @@ import type { } from '@agent-device/contracts/platform-runtime-operations'; import type { PlatformRequestScope } from '@agent-device/contracts/platform-runtime-host'; import type { DeviceInfo } from '@agent-device/kernel/device'; -import type { LimrunRuntimeDependencies } from '@agent-device/provider-limrun'; +import type { LimrunRuntimeDependencies } from '@agent-device/limrun/runtime'; import { createUnavailableRuntimeFactsForTest, unavailableDeploymentSnapshotAndShutdownOperationFacts, @@ -297,8 +297,7 @@ export async function createTestLimrunIosRunner( ): Promise>> { const { createAppleRunnerRuntime } = await import('@agent-device/platform-apple/runner/operations'); - const { createLimrunAppleApplicationTools } = - await import('./core/interactors/limrun-ios-application-tools.ts'); + const { createLimrunAppleApplicationTools } = await import('@agent-device/limrun/host'); const runner = await createAppleRunnerRuntime({ device, host: { env: {}, cwd: process.cwd() }, @@ -331,6 +330,7 @@ export async function createTestLimrunIosRunner( applyRuntimeHints: async () => {}, clearRuntimeHints: async () => {}, }, + () => {}, ); return { ...runner, diff --git a/src/platform-runtime-gateway.test.ts b/src/platform-runtime-gateway.test.ts index f5ff4255c5..5e2ed36461 100644 --- a/src/platform-runtime-gateway.test.ts +++ b/src/platform-runtime-gateway.test.ts @@ -16,7 +16,7 @@ import { viewportRuntimeOperationFacts } from '@agent-device/contracts/viewport- import type { DeviceInfo } from '@agent-device/kernel/device'; import { AppError, normalizeError } from '@agent-device/kernel/errors'; import { withDiagnosticsScope } from '@agent-device/host-kit/diagnostics'; -import { createLimrunRuntime } from '@agent-device/provider-limrun'; +import { createLimrunRuntime } from '@agent-device/limrun/runtime'; import { describe, expect, expectTypeOf, test, vi } from 'vitest'; import type { AgentDeviceHost } from './sdk/host-types.ts'; import { resolveDaemonPaths } from '@agent-device/daemon-contracts/daemon-resolution'; diff --git a/src/provider-credential-fingerprint.test.ts b/src/provider-credential-fingerprint.test.ts index 01be48d01d..ce4f4e5361 100644 --- a/src/provider-credential-fingerprint.test.ts +++ b/src/provider-credential-fingerprint.test.ts @@ -3,16 +3,15 @@ import { providerCredentialFingerprint as fingerprintFor } from '@agent-device/p 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 { limrunPluginInventory } from './__tests__/test-utils/limrun-plugin-inventory.ts'; import { browserstackPluginInventory } from './__tests__/test-utils/browserstack-plugin-inventory.ts'; import { awsDeviceFarmPluginInventory } from './__tests__/test-utils/aws-device-farm-plugin-inventory.ts'; import { pluginHome, selectPlugin, pluginSource } from '@agent-device/test-kit'; -import { BUILTIN_PROVIDER_IDS } from './builtin-provider-ids.ts'; // BrowserStack and AWS Device Farm are installed plugins, so their credential variables come // from their own inventory entries. const inventory = [ - ...(await builtinPluginInventory()), + ...(await limrunPluginInventory()), ...(await browserstackPluginInventory()), ...(await awsDeviceFarmPluginInventory()), ]; @@ -139,15 +138,11 @@ 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. */ +/** The inventory the daemon publishes for the plugin store. */ async function storeInventory(env: Record) { - const { claimProviderIds, resolveProviderPlugins } = - await import('@agent-device/plugins/registry'); + const { 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)), - ]); + const resolved = await resolveProviderPlugins(await storePluginCandidates(env)); return resolved.inventory(); } @@ -202,15 +197,6 @@ test('a plugin provider without declared credential variables has no fingerprint expect(providerCredentialFingerprint('other', env, undefined, inventory)).toBe(undefined); }); -test('a plugin declaration never adds a fingerprint to a bundled provider', async () => { - const { env: home } = pluginWithCredentialVariables(['AWS_ACCESS_KEY_ID'], 'limrun'); - const inventory = await storeInventory(home); - const env = { ...home, AWS_ACCESS_KEY_ID: 'id' }; - expect(providerCredentialFingerprint('limrun', env, undefined, inventory)).toBe(undefined); - // The built-in's own answer is unchanged by the store package that claims its id. - expect(providerCredentialFingerprint('limrun', env)).toBe(undefined); -}); - test('an installed AWS Device Farm plugin declares no credential variables', async () => { const env = { AWS_ACCESS_KEY_ID: 'id', AWS_SECRET_ACCESS_KEY: 'secret' }; // The package answers through the AWS CLI credential chain, so nothing is hashed. diff --git a/src/provider-device-runtimes.test.ts b/src/provider-device-runtimes.test.ts index 5ff9a3f553..ff307aa13f 100644 --- a/src/provider-device-runtimes.test.ts +++ b/src/provider-device-runtimes.test.ts @@ -17,6 +17,12 @@ const limrun = vi.hoisted(() => ({ iosDisconnect: vi.fn(), })); +vi.mock('@agent-device/plugins/store', async (importOriginal) => + (await import('./__tests__/test-utils/limrun-plugin-store.ts')).storeWithLimrunInstalled( + importOriginal as () => Promise, + ), +); + vi.mock('@limrun/api', () => ({ default: class MockLimrun { readonly iosInstances = { diff --git a/src/provider-device-runtimes.ts b/src/provider-device-runtimes.ts index 1d5b7d10a5..8c817d039d 100644 --- a/src/provider-device-runtimes.ts +++ b/src/provider-device-runtimes.ts @@ -11,7 +11,6 @@ import type { PluginInventoryEntry, } from '@agent-device/contracts/plugin-inventory'; import type { PlatformRuntimeProviderRegistration } from './platform-runtime-gateway.ts'; -import { builtinProviderCandidates } from './builtin-provider-plugins.ts'; import { PROVIDER_PLUGIN_POLICY } from './provider-plugin-policy.ts'; export type ProviderRuntimeComposition = Readonly<{ @@ -29,7 +28,7 @@ export type ProviderRuntimeComposition = Readonly<{ }>; /** - * The daemon's providers from one registry: built-in providers, then the plugin store. A plugin + * The daemon's providers from one registry: the built-in platforms, then the plugin store. A plugin * that cannot register is listed in the inventory; the others still register. */ export async function createDaemonProviderRuntimeComposition( @@ -46,7 +45,7 @@ export async function createDaemonProviderRuntimeComposition( }); } -/** Composes built-ins followed by supplied candidates without reading the plugin store. */ +/** Composes the built-in platforms followed by supplied candidates without reading the plugin store. */ export async function createEmbeddedProviderRuntimeComposition( host: HostEnvironment, candidates: readonly PluginCandidate[], @@ -66,11 +65,7 @@ async function composeProviderRuntime( const { resolveProviderPlugins, startProviderRegistry } = await import('@agent-device/plugins/registry'); const { builtinPlatformCandidates } = await import('./platform-runtime/platform-plugins.ts'); - const resolved = await resolveProviderPlugins([ - ...builtinPlatformCandidates(), - ...builtinProviderCandidates(host), - ...candidates, - ]); + const resolved = await resolveProviderPlugins([...builtinPlatformCandidates(), ...candidates]); const registry = await startProviderRegistry(resolved, host, policy); return Object.freeze({ platforms: registry.platforms, diff --git a/src/sdk/limrun-runtime-dependencies-android-performance.test.ts b/src/provider-plugin-host-capabilities-android-performance.test.ts similarity index 93% rename from src/sdk/limrun-runtime-dependencies-android-performance.test.ts rename to src/provider-plugin-host-capabilities-android-performance.test.ts index a7a54becd3..f98099247d 100644 --- a/src/sdk/limrun-runtime-dependencies-android-performance.test.ts +++ b/src/provider-plugin-host-capabilities-android-performance.test.ts @@ -1,8 +1,8 @@ import { readFile, writeFile } from 'node:fs/promises'; import { mkdtempForTest } from '@agent-device/test-kit'; import { expect, test, vi } from 'vitest'; -import { createLimrunRuntimeDependencies } from './limrun-runtime-dependencies.ts'; -import { createPerfRuntimeHost } from '../platform-runtime-perf-host.ts'; +import { limrunRuntimeDependencies } from './provider-plugin-host-capabilities.fixtures.ts'; +import { createPerfRuntimeHost } from './platform-runtime-perf-host.ts'; import type { DeviceInfo } from '@agent-device/kernel/device'; import { providerRuntimeOwner } from '@agent-device/contracts/platform-runtime'; @@ -24,7 +24,7 @@ vi.mock('@agent-device/host-kit/command', async (original) => ({ })); test('Limrun performance reads use the provider ADB and collect heap artifacts', async () => { - const dependencies = createLimrunRuntimeDependencies({ env: process.env, cwd: process.cwd() }); + const dependencies = await limrunRuntimeDependencies({ env: process.env, cwd: process.cwd() }); const host = createPerfRuntimeHost().android; const dir = await mkdtempForTest('limrun-perf-'); let remoteHeap: string | undefined; diff --git a/src/sdk/limrun-runtime-dependencies-host-scope.test.ts b/src/provider-plugin-host-capabilities-host-scope.test.ts similarity index 90% rename from src/sdk/limrun-runtime-dependencies-host-scope.test.ts rename to src/provider-plugin-host-capabilities-host-scope.test.ts index 89914cf7ef..2c25dec801 100644 --- a/src/sdk/limrun-runtime-dependencies-host-scope.test.ts +++ b/src/provider-plugin-host-capabilities-host-scope.test.ts @@ -4,7 +4,7 @@ import path from 'node:path'; import { beforeAll, test } from 'vitest'; import { mkdtempForTestSync } from '@agent-device/test-kit'; import { withCommandHost } from '@agent-device/host-kit/command'; -import { createLimrunRuntimeDependencies } from './limrun-runtime-dependencies.ts'; +import { limrunRuntimeDependencies } from './provider-plugin-host-capabilities.fixtures.ts'; beforeAll(async () => { if (process.platform !== 'win32') await import('@agent-device/platform-apple/install-artifact'); @@ -23,13 +23,13 @@ test.skipIf(process.platform === 'win32')( `process.stdout.write(JSON.stringify({args:process.argv.slice(2),host:process.env.LIMRUN_OWNER}));\n`, ); chmodSync(adb, 0o755); - const owner = (name: string) => - createLimrunRuntimeDependencies({ + const owner = async (name: string) => + await limrunRuntimeDependencies({ env: { ...process.env, PATH: bin, LIMRUN_OWNER: name }, cwd: root, }); - const first = owner('first'); - const second = owner('second'); + const first = await owner('first'); + const second = await owner('second'); const invocation = { target: { selector: { kind: 'unspecified' as const }, server: { kind: 'ambient' as const } }, command: ['devices'], @@ -72,7 +72,7 @@ test.skipIf(process.platform === 'win32')( `#!${process.execPath}\nprocess.stdout.write(JSON.stringify({CFBundleDisplayName:'Scoped App'}));\n`, ); chmodSync(plutil, 0o755); - const dependencies = createLimrunRuntimeDependencies({ + const dependencies = await limrunRuntimeDependencies({ env: { ...process.env, PATH: root }, cwd: root, }); diff --git a/src/core/interactors/limrun-ios-app-logs.test.ts b/src/provider-plugin-host-capabilities-limrun-ios-app-logs.test.ts similarity index 93% rename from src/core/interactors/limrun-ios-app-logs.test.ts rename to src/provider-plugin-host-capabilities-limrun-ios-app-logs.test.ts index a9138d8381..15e9f82cb0 100644 --- a/src/core/interactors/limrun-ios-app-logs.test.ts +++ b/src/provider-plugin-host-capabilities-limrun-ios-app-logs.test.ts @@ -1,8 +1,9 @@ import { EventEmitter } from 'node:events'; import { expect, test, vi } from 'vitest'; import type { InstanceClient, LogStream } from '@limrun/api/ios-client'; -import { fixture } from './limrun-ios-runner.fixtures.ts'; -import { createLimrunRuntimeDependencies } from '../../sdk/limrun-runtime-dependencies.ts'; +import { createLimrunRuntimeDependencies } from '@agent-device/limrun/host'; +import { fixture } from './provider-plugin-host-capabilities-limrun-ios.fixtures.ts'; +import { limrunPluginHost } from './provider-plugin-host-capabilities.fixtures.ts'; const plist = Buffer.from( 'CFBundleExecutableExample', @@ -29,7 +30,9 @@ async function logFixture(options: { holdFileDownload?: boolean; failFileStatus? streamSyslog: stream, appLogTail: vi.fn(async () => ''), } as unknown as InstanceClient; - const dependencies = createLimrunRuntimeDependencies({ env: {}, cwd: f.directory }); + const dependencies = await createLimrunRuntimeDependencies( + limrunPluginHost({ env: {}, cwd: f.directory }), + ); const reader = dependencies.ios.createAppLogReader({ ...f.session, client }); const read = () => reader.readLogs('com.example.app', 100, new AbortController().signal); return { reader, read, streams, storage: f.storage, client }; diff --git a/src/core/interactors/limrun-ios-files.fixtures.ts b/src/provider-plugin-host-capabilities-limrun-ios-files.fixtures.ts similarity index 100% rename from src/core/interactors/limrun-ios-files.fixtures.ts rename to src/provider-plugin-host-capabilities-limrun-ios-files.fixtures.ts diff --git a/src/core/interactors/limrun-ios-files.test.ts b/src/provider-plugin-host-capabilities-limrun-ios-files.test.ts similarity index 91% rename from src/core/interactors/limrun-ios-files.test.ts rename to src/provider-plugin-host-capabilities-limrun-ios-files.test.ts index bb2e7410ea..aff318e915 100644 --- a/src/core/interactors/limrun-ios-files.test.ts +++ b/src/provider-plugin-host-capabilities-limrun-ios-files.test.ts @@ -1,6 +1,6 @@ import { expect, test, vi } from 'vitest'; -import { fixture } from './limrun-ios-runner.fixtures.ts'; -import { createLimrunAppleToolProvider } from './limrun-ios-tools.ts'; +import { fixture } from './provider-plugin-host-capabilities-limrun-ios.fixtures.ts'; +import { createLimrunAppleToolProvider } from './provider-plugin-host-capabilities.fixtures.ts'; import { withAppleToolProvider } from '@agent-device/platform-apple/tool-provider'; import { resolveIosSimulatorDeepLinkBundleId } from '@agent-device/platform-apple/app-resolution'; import { promises as fs } from 'node:fs'; @@ -23,7 +23,8 @@ test('remote app metadata resolves Expo and deep-link ownership and rejects dupl { bundleId: 'com.example.app', name: 'Example', installType: 'User' }, ]); f.session.client.listApps = listApps; - const provider = () => createLimrunAppleToolProvider(f.session, new AbortController().signal); + const provider = () => + createLimrunAppleToolProvider(f.session, f.host, new AbortController().signal); await withAppleToolProvider(provider(), async () => { expect(await resolveIosSimulatorDeepLinkBundleId(f.device, 'exp+example://route')).toBe( 'com.example.app', @@ -59,7 +60,7 @@ test('clear state uses the shared reset and preserves container identity without { bundleId: 'com.example.app', name: 'Example', installType: 'User' }, ]; await withAppleToolProvider( - createLimrunAppleToolProvider(f.session, new AbortController().signal), + createLimrunAppleToolProvider(f.session, f.host, new AbortController().signal), async () => { await f.runner.createInteractor().setSetting('clear-app-state', 'clear', 'com.example.app'); }, @@ -88,7 +89,7 @@ test.each([false, true])( }); const payloadPath = path.join(f.directory, 'payload.apns'); const payload = { aps: { alert: 'hello' }, custom: 'value' }; - const { createAppleToolHost } = await import('../../platform-runtime-apple-tool-host.ts'); + const { createAppleToolHost } = await import('./platform-runtime-apple-tool-host.ts'); const host = { deviceReadiness: { appleAutomation: { @@ -188,7 +189,7 @@ test.each([ ])('clear state rejects invalid input before modifying files: %j', async ({ state, app }) => { const f = await fixture(); await withAppleToolProvider( - createLimrunAppleToolProvider(f.session, new AbortController().signal), + createLimrunAppleToolProvider(f.session, f.host, new AbortController().signal), async () => { await expect( f.runner.createInteractor().setSetting('clear-app-state', state, app), @@ -203,6 +204,7 @@ test('staged payload cleanup survives cancellation of its command', async () => const cancellation = new AbortController(); const provider = createLimrunAppleToolProvider( f.session, + f.host, new AbortController().signal, cancellation.signal, ); @@ -223,7 +225,7 @@ test('clear state reports file deletion failure without relaunching or recreatin { bundleId: 'com.example.app', name: 'Example', installType: 'User' }, ]; await withAppleToolProvider( - createLimrunAppleToolProvider(f.session, new AbortController().signal), + createLimrunAppleToolProvider(f.session, f.host, new AbortController().signal), async () => { await expect( f.runner.createInteractor().setSetting('clear-app-state', 'clear', 'com.example.app'), @@ -239,7 +241,7 @@ test('clear state reports file deletion failure without relaunching or recreatin test('clear state reports the shared no-data-container result without mutating files', async () => { const f = await fixture({ failFileMethod: 'GET', failFileStatus: 404 }); await withAppleToolProvider( - createLimrunAppleToolProvider(f.session, new AbortController().signal), + createLimrunAppleToolProvider(f.session, f.host, new AbortController().signal), async () => { await expect( f.runner.createInteractor().setSetting('clear-app-state', 'clear', 'com.apple.Preferences'), @@ -261,7 +263,7 @@ test('deep-link ownership ignores missing metadata for another installed app', a { bundleId: 'com.example.app', name: 'Example', installType: 'User' }, ]; await withAppleToolProvider( - createLimrunAppleToolProvider(f.session, new AbortController().signal), + createLimrunAppleToolProvider(f.session, f.host, new AbortController().signal), async () => { expect(await resolveIosSimulatorDeepLinkBundleId(f.device, 'exp+example://route')).toBe( 'com.example.app', @@ -272,7 +274,7 @@ test('deep-link ownership ignores missing metadata for another installed app', a test.each([401, 500])('app metadata HTTP %s is not treated as an absent plist', async (status) => { const f = await fixture({ failFileMethod: 'GET', failFileStatus: status }); - const tools = createLimrunAppleToolProvider(f.session, new AbortController().signal); + const tools = createLimrunAppleToolProvider(f.session, f.host, new AbortController().signal); await expect( tools.simulatorApps.readInfoPlist({ device: f.device, @@ -297,7 +299,7 @@ test('container operations receive fresh deadlines after earlier operations have deadline.abort(new DOMException('deadline expired', 'TimeoutError')); }; try { - const tools = createLimrunAppleToolProvider(f.session, new AbortController().signal); + const tools = createLimrunAppleToolProvider(f.session, f.host, new AbortController().signal); const container = await tools.simulatorFiles.openContainer({ device: f.device, bundleId: 'com.example.app', @@ -328,7 +330,7 @@ test('a container download deadline remains a typed timeout and removes the part const timeout = vi.spyOn(AbortSignal, 'timeout').mockReturnValue(deadline.signal); const destinationPath = path.join(f.directory, 'timed-out.bin'); try { - const tools = createLimrunAppleToolProvider(f.session, new AbortController().signal); + const tools = createLimrunAppleToolProvider(f.session, f.host, new AbortController().signal); await expect( tools.simulatorFiles.copyToHost({ device: f.device, @@ -349,7 +351,7 @@ test('a failed upload reply removes the staged file before rejecting', async () const f = await fixture({ invalidUploadReply: true }); const local = path.join(f.directory, 'push.apns'); await fs.writeFile(local, '{}'); - const tools = createLimrunAppleToolProvider(f.session, new AbortController().signal); + const tools = createLimrunAppleToolProvider(f.session, f.host, new AbortController().signal); await expect(tools.simulatorFiles.stageFile(local)).rejects.toThrow(); expect([...f.storage.files.keys()]).toEqual([]); expect(f.storage.calls.map((call) => call.method)).toEqual(['PUT', 'DELETE']); @@ -360,7 +362,7 @@ test('concurrent metadata reads do not inherit another caller cancellation', asy holdFileDownload: true, containers: { 'com.example.app': { app: { 'Info.plist': plist('exp+example') } } }, }); - const tools = createLimrunAppleToolProvider(f.session, new AbortController().signal); + const tools = createLimrunAppleToolProvider(f.session, f.host, new AbortController().signal); const canceled = new AbortController(); const input = { device: f.device, bundleId: 'com.example.app', timeoutMs: 5000 }; const first = tools.simulatorApps.readInfoPlist({ ...input, signal: canceled.signal }); diff --git a/src/core/interactors/limrun-ios-runner-parity.test.ts b/src/provider-plugin-host-capabilities-limrun-ios-runner-parity.test.ts similarity index 96% rename from src/core/interactors/limrun-ios-runner-parity.test.ts rename to src/provider-plugin-host-capabilities-limrun-ios-runner-parity.test.ts index e5b5fad170..00a92361e6 100644 --- a/src/core/interactors/limrun-ios-runner-parity.test.ts +++ b/src/provider-plugin-host-capabilities-limrun-ios-runner-parity.test.ts @@ -3,7 +3,7 @@ import { promises as fs } from 'node:fs'; import path from 'node:path'; import { PNG } from '@agent-device/capture-kit/png'; import { readPngSize } from '@agent-device/capture-kit/png-size'; -import { fixture } from './limrun-ios-runner.fixtures.ts'; +import { fixture } from './provider-plugin-host-capabilities-limrun-ios.fixtures.ts'; test('forwarded screenshots preserve PNG pixels and share density and status bar normalization', async () => { const png = new PNG({ width: 12, height: 18 }); @@ -135,9 +135,9 @@ test('remote tools execute the shared text-size, status bar and biometric settin test('shared deployment prepares before uninstalling and uploading a replacement', async () => { const f = await fixture(); - const { createAppleToolHost } = await import('../../platform-runtime-apple-tool-host.ts'); + const { createAppleToolHost } = await import('./platform-runtime-apple-tool-host.ts'); const { createAppleAppDeploymentExecutor } = - await import('../../platform-runtime-apple-deployment-executor.ts'); + await import('./platform-runtime-apple-deployment-executor.ts'); const order: string[] = []; const originalSimctl = f.session.client.simctl; f.session.client.simctl = vi.fn((args, options) => { diff --git a/src/core/interactors/limrun-ios-runner.test.ts b/src/provider-plugin-host-capabilities-limrun-ios-runner.test.ts similarity index 99% rename from src/core/interactors/limrun-ios-runner.test.ts rename to src/provider-plugin-host-capabilities-limrun-ios-runner.test.ts index da34e8238b..09231807f9 100644 --- a/src/core/interactors/limrun-ios-runner.test.ts +++ b/src/provider-plugin-host-capabilities-limrun-ios-runner.test.ts @@ -8,7 +8,7 @@ import { clearRequestAbortRegistration, } from '@agent-device/host-kit/request'; import { expect, test, vi } from 'vitest'; -import { fixture } from './limrun-ios-runner.fixtures.ts'; +import { fixture } from './provider-plugin-host-capabilities-limrun-ios.fixtures.ts'; test('stages a token-authenticated runner once and presents forwarded XCTest snapshots', async () => { const f = await fixture(); const snapshot = await f.runner.createInteractor().snapshot({ diff --git a/src/core/interactors/limrun-ios-tools.test.ts b/src/provider-plugin-host-capabilities-limrun-ios-tools.test.ts similarity index 94% rename from src/core/interactors/limrun-ios-tools.test.ts rename to src/provider-plugin-host-capabilities-limrun-ios-tools.test.ts index 1a8eeafa0c..de60e4cac0 100644 --- a/src/core/interactors/limrun-ios-tools.test.ts +++ b/src/provider-plugin-host-capabilities-limrun-ios-tools.test.ts @@ -1,12 +1,12 @@ import { SimctlExecution } from '@limrun/api/ios-client'; +import { createLimrunAppleToolProvider } from './provider-plugin-host-capabilities.fixtures.ts'; import { buildSimctlArgsForDevice } from '@agent-device/platform-apple/simctl'; import { runXcrun, withAppleToolProvider } from '@agent-device/platform-apple/tool-provider'; -import { createLimrunAppleToolProvider } from './limrun-ios-tools.ts'; import { expect, test, vi } from 'vitest'; import path from 'node:path'; import { promises as fs } from 'node:fs'; import { AppError } from '@agent-device/kernel/errors'; -import { fixture } from './limrun-ios-runner.fixtures.ts'; +import { fixture } from './provider-plugin-host-capabilities-limrun-ios.fixtures.ts'; async function sessionWithClient(result = { code: 0, stdout: '', stderr: '' }) { const f = await fixture({ simctlResult: result }); @@ -26,7 +26,7 @@ test('malformed successful device inventory preserves the remote command output' stderr: 'simulator warning', }); f.simctl.mockReturnValue(execution); - const tools = createLimrunAppleToolProvider(f.session, new AbortController().signal); + const tools = createLimrunAppleToolProvider(f.session, f.host, new AbortController().signal); await expect( withAppleToolProvider(tools, () => runXcrun(buildSimctlArgsForDevice(f.device, ['list', 'devices', '--json'])), @@ -205,7 +205,7 @@ test('a host timeout stops the remote command and preserves partial console outp const stopped = vi.fn(); const execution = new SimctlExecution(stopped); vi.mocked(f.session.client.simctl).mockReturnValue(execution); - const tools = createLimrunAppleToolProvider(f.session, new AbortController().signal); + const tools = createLimrunAppleToolProvider(f.session, f.host, new AbortController().signal); const deadline = new AbortController(); const timeout = vi.spyOn(AbortSignal, 'timeout').mockReturnValue(deadline.signal); try { @@ -237,7 +237,12 @@ for (const canceledBy of ['lease', 'deadline'] as const) { const deadline = new AbortController(); const timeout = vi.spyOn(AbortSignal, 'timeout').mockReturnValue(deadline.signal); try { - const tools = createLimrunAppleToolProvider(f.session, lease.signal, AbortSignal.abort()); + const tools = createLimrunAppleToolProvider( + f.session, + f.host, + lease.signal, + AbortSignal.abort(), + ); const pending = tools.runCommand('xcrun', ['simctl', 'status_bar', f.device.id, 'clear'], { requestCancellation: 'ignore', timeoutMs: 30_000, @@ -261,6 +266,7 @@ test('canceling an app catalog request releases the caller without waiting for t const abort = new AbortController(); const tools = createLimrunAppleToolProvider( f.session, + f.host, new AbortController().signal, abort.signal, ); @@ -303,7 +309,7 @@ test.each(['app', 'data', 'group.com.example.shared'])( const f = await fixture({ containers: { 'com.example.app': { [containerType]: { [sourcePath]: bytes } } }, }); - const tools = createLimrunAppleToolProvider(f.session, new AbortController().signal); + const tools = createLimrunAppleToolProvider(f.session, f.host, new AbortController().signal); const destinationPath = path.join(f.directory, 'download', 'file.bin'); await tools.simulatorFiles!.copyToHost({ device: f.device, @@ -325,7 +331,7 @@ test.each(['app', 'data', 'group.com.example.shared'])( test('a missing container file reports HTTP failure and leaves no local artifact', async () => { const f = await fixture(); - const tools = createLimrunAppleToolProvider(f.session, new AbortController().signal); + const tools = createLimrunAppleToolProvider(f.session, f.host, new AbortController().signal); const destinationPath = path.join(f.directory, 'missing.bin'); await expect( tools.simulatorFiles!.copyToHost({ @@ -353,6 +359,7 @@ test('canceling a container download stops the transfer and removes the partial const controller = new AbortController(); const tools = createLimrunAppleToolProvider( f.session, + f.host, new AbortController().signal, controller.signal, ); @@ -396,6 +403,7 @@ test.each(['timeout', 'request'] as const)( const timeout = vi.spyOn(AbortSignal, 'timeout').mockReturnValue(deadline.signal); const tools = createLimrunAppleToolProvider( f.session, + f.host, new AbortController().signal, request.signal, ); @@ -431,7 +439,7 @@ test.each([ ['list', 'devices', '--json'], ])('normalizes the remote device identity for %j', async (...args) => { const f = await fixture(); - const tools = createLimrunAppleToolProvider(f.session, new AbortController().signal); + const tools = createLimrunAppleToolProvider(f.session, f.host, new AbortController().signal); const result = await tools.runCommand('xcrun', ['simctl', ...args], {}); const inventory = JSON.parse(result.stdout); expect(inventory.devices.ios[0].udid).toBe(f.device.id); diff --git a/src/core/interactors/limrun-ios-runner.fixtures.ts b/src/provider-plugin-host-capabilities-limrun-ios.fixtures.ts similarity index 95% rename from src/core/interactors/limrun-ios-runner.fixtures.ts rename to src/provider-plugin-host-capabilities-limrun-ios.fixtures.ts index 0c235972e9..7105f3659f 100644 --- a/src/core/interactors/limrun-ios-runner.fixtures.ts +++ b/src/provider-plugin-host-capabilities-limrun-ios.fixtures.ts @@ -1,5 +1,8 @@ -import { fileStore, type FileStoreOptions } from './limrun-ios-files.fixtures.ts'; -import { createAppleApplicationTools } from '../../platform-runtime-apple-application-tools.ts'; +import { + fileStore, + type FileStoreOptions, +} from './provider-plugin-host-capabilities-limrun-ios-files.fixtures.ts'; +import { limrunIosHost } from './provider-plugin-host-capabilities.fixtures.ts'; import { EventEmitter } from 'node:events'; import { createServer, type IncomingMessage, type ServerResponse } from 'node:http'; import { promises as fs } from 'node:fs'; @@ -7,8 +10,9 @@ import path from 'node:path'; import { gunzipSync } from 'node:zlib'; import { afterEach, vi, type Mock } from 'vitest'; import { mkdtempForTest } from '@agent-device/test-kit'; -import type { LimrunRuntimeDependencies } from '@agent-device/provider-limrun'; -import { createLimrunIosRunner } from './limrun-ios-runner.ts'; +import type { LimrunRuntimeDependencies } from '@agent-device/limrun/runtime'; +import type { LimrunIosHost } from '@agent-device/limrun/host'; +import { createLimrunIosRunner } from '@agent-device/limrun/host'; const cleanups: Array<() => Promise> = []; afterEach(async () => { for (const cleanup of cleanups.reverse()) await cleanup(); @@ -24,6 +28,7 @@ type RunnerFixture = { runner: Awaited>; storage: ReturnType; session: Session; + host: LimrunIosHost; directory: string; admit(): void; readonly admissionClosed: boolean | undefined; @@ -306,11 +311,13 @@ export async function fixture( : { AGENT_DEVICE_IOS_RUNNER_IDLE_STOP_MS: String(options.idleMs) }), }, }; + const iosHost = await limrunIosHost(host); const runner: Awaited> = - await createLimrunIosRunner(session, host, createAppleApplicationTools(host.env)); + await createLimrunIosRunner(session, iosHost); cleanups.push(() => runner.dispose()); return { runner, + host: iosHost, storage, session, directory, diff --git a/src/provider-plugin-host-capabilities.fixtures.ts b/src/provider-plugin-host-capabilities.fixtures.ts new file mode 100644 index 0000000000..2614db7fd8 --- /dev/null +++ b/src/provider-plugin-host-capabilities.fixtures.ts @@ -0,0 +1,43 @@ +import type { HostEnvironment } from '@agent-device/kernel/source-value'; +import { createPluginHost } from '@agent-device/plugins/host'; +import { readVersion } from '@agent-device/host-kit/version'; +import { type LimrunRuntimeDependencies } from '@agent-device/limrun/runtime'; +import { + createLimrunAppleToolProvider as createToolProvider, + createLimrunRuntimeDependencies, + type LimrunIosHost, +} from '@agent-device/limrun/host'; +import { createProviderHostCapabilities } from './provider-plugin-host-capabilities.ts'; +import type { DeviceProviderPluginHost } from './sdk/plugin-device-host.ts'; + +/** The `setup` host the daemon hands an installed provider plugin, built for `host`. */ +export function limrunPluginHost(host: HostEnvironment): DeviceProviderPluginHost { + return createPluginHost(host, undefined, createProviderHostCapabilities(host)); +} + +/** The host the Limrun iOS runner modules read, loaded from the root's own Apple owners. */ +export async function limrunIosHost(host: HostEnvironment): Promise { + const capabilities = createProviderHostCapabilities(host); + const [apple, kit] = await Promise.all([capabilities.loadApple(), capabilities.loadHostKit()]); + return { + apple, + kit, + env: host.env, + clientVersion: readVersion(), + emitDiagnostic: capabilities.emitDiagnostic, + }; +} + +/** The runtime adapters the installed plugin builds from the daemon's host, for `host`. */ +export async function limrunRuntimeDependencies( + host: HostEnvironment, +): Promise { + return await createLimrunRuntimeDependencies(limrunPluginHost(host)); +} + +/** The tool provider that reaches a leased Limrun simulator, for suites that scope the Apple tools to it. */ +export function createLimrunAppleToolProvider( + ...args: Parameters +): ReturnType { + return createToolProvider(...args); +} diff --git a/src/sdk/limrun-runtime-dependencies.test.ts b/src/provider-plugin-host-capabilities.test.ts similarity index 88% rename from src/sdk/limrun-runtime-dependencies.test.ts rename to src/provider-plugin-host-capabilities.test.ts index 2313b2cbb4..3a1c421886 100644 --- a/src/sdk/limrun-runtime-dependencies.test.ts +++ b/src/provider-plugin-host-capabilities.test.ts @@ -1,4 +1,5 @@ import assert from 'node:assert/strict'; +import { limrunRuntimeDependencies } from './provider-plugin-host-capabilities.fixtures.ts'; import { expect, test, vi } from 'vitest'; const moduleLoads = vi.hoisted(() => ({ @@ -35,11 +36,10 @@ vi.mock('@agent-device/platform-apple/install-artifact', async (importOriginal) })); test('Limrun construction defers operation and opposite-platform helper modules', async () => { - const { createLimrunRuntime } = await import('@agent-device/provider-limrun'); - const { createLimrunRuntimeDependencies } = await import('./limrun-runtime-dependencies.ts'); + const { createLimrunRuntime } = await import('@agent-device/limrun/runtime'); const runtime = createLimrunRuntime( { apiKey: 'lim_test_key' }, - createLimrunRuntimeDependencies({ env: process.env, cwd: process.cwd() }), + await limrunRuntimeDependencies({ env: process.env, cwd: process.cwd() }), ); assert.deepEqual(moduleLoads, { @@ -49,7 +49,7 @@ test('Limrun construction defers operation and opposite-platform helper modules' }); await runtime.shutdown(); - const dependencies = createLimrunRuntimeDependencies({ env: process.env, cwd: process.cwd() }); + const dependencies = await limrunRuntimeDependencies({ env: process.env, cwd: process.cwd() }); const device = { platform: 'android' as const, id: 'limrun:android:lease-a', @@ -92,8 +92,7 @@ test('Limrun construction defers operation and opposite-platform helper modules' }); test('Limrun appstate forwards an in-flight abort through the provider ADB executor', async () => { - const { createLimrunRuntimeDependencies } = await import('./limrun-runtime-dependencies.ts'); - const dependencies = createLimrunRuntimeDependencies({ env: process.env, cwd: process.cwd() }); + const dependencies = await limrunRuntimeDependencies({ env: process.env, cwd: process.cwd() }); const device = { platform: 'android' as const, id: 'limrun:android:lease-abort', @@ -124,14 +123,13 @@ test('Limrun appstate forwards an in-flight abort through the provider ADB execu }); test('host.runAdb carries addressing apart from payload and routes through the host transport', async () => { - const { createLimrunRuntimeDependencies } = await import('./limrun-runtime-dependencies.ts'); const { androidAdbInvocation, androidAdbSerialTarget, serializeAndroidAdbInvocation, withAndroidHostAdbTransport, } = await import('@agent-device/platform-android/mechanics'); - const dependencies = createLimrunRuntimeDependencies({ env: process.env, cwd: process.cwd() }); + const dependencies = await limrunRuntimeDependencies({ env: process.env, cwd: process.cwd() }); const seen: Array<{ args: string[]; payload: readonly string[]; @@ -171,10 +169,9 @@ test('host.runAdb carries addressing apart from payload and routes through the h }); test('adbError names the failed command with the platform serializer', async () => { - const { createLimrunRuntimeDependencies } = await import('./limrun-runtime-dependencies.ts'); const { androidAdbInvocation, androidAdbSerialTarget } = await import('@agent-device/platform-android/mechanics'); - const dependencies = createLimrunRuntimeDependencies({ env: process.env, cwd: process.cwd() }); + const dependencies = await limrunRuntimeDependencies({ env: process.env, cwd: process.cwd() }); const failure = await dependencies.android.adbError( 'Limrun Android ADB command failed', @@ -193,14 +190,13 @@ test('adbError names the failed command with the platform serializer', async () }); test('the adb invocation adapters address through the platform builders', async () => { - const { createLimrunRuntimeDependencies } = await import('./limrun-runtime-dependencies.ts'); const { androidAdbHostTarget, androidAdbInvocation, androidAdbSerialTarget, serializeAndroidAdbInvocation, } = await import('@agent-device/platform-android/mechanics'); - const dependencies = createLimrunRuntimeDependencies({ env: process.env, cwd: process.cwd() }); + const dependencies = await limrunRuntimeDependencies({ env: process.env, cwd: process.cwd() }); const device = dependencies.android.deviceAdbInvocation('127.0.0.1:62001', [ 'shell', diff --git a/src/provider-plugin-host-capabilities.ts b/src/provider-plugin-host-capabilities.ts new file mode 100644 index 0000000000..05af33b211 --- /dev/null +++ b/src/provider-plugin-host-capabilities.ts @@ -0,0 +1,160 @@ +import type { DeviceInfo } from '@agent-device/kernel/device'; +import type { HostEnvironment } from '@agent-device/kernel/source-value'; +import { withMethodScope } from '@agent-device/kernel/scoped-provider'; +import { execFailureDetails, withCommandHost } from '@agent-device/host-kit/command'; +import { emitDiagnostic } from '@agent-device/host-kit/diagnostics'; +import { resolveDaemonPaths } from '@agent-device/daemon-contracts/daemon-resolution'; +import type { + ProviderAndroidHost, + ProviderAppleHost, + ProviderHostCapabilities, +} from './sdk/plugin-device-host.ts'; + +type AndroidAdbProvider = import('@agent-device/platform-android/mechanics').AndroidAdbProvider; + +type RunOnHost = (task: () => Promise) => Promise; + +function once(load: () => Promise): () => Promise { + let loading: Promise | undefined; + return () => (loading ??= load()); +} + +/** + * The device capabilities every provider plugin `setup` host carries, built for `host`. + */ +export function createProviderHostCapabilities(host: HostEnvironment): ProviderHostCapabilities { + const runOnHost: RunOnHost = (task) => withCommandHost({ host, requestEnv: undefined }, task); + return Object.freeze({ + stateDir: resolveDaemonPaths(host.env.AGENT_DEVICE_STATE_DIR, { + env: host.env, + cwd: host.cwd, + }).baseDir, + emitDiagnostic, + loadAndroid: once(async () => await createProviderAndroidHost(runOnHost)), + loadApple: once(async () => await createProviderAppleHost(host, runOnHost)), + loadHostKit: once(async () => { + const [{ retryWithPolicy, Deadline }, { extractArchiveSafely }] = await Promise.all([ + import('@agent-device/host-kit/retry'), + import('@agent-device/host-kit/archive'), + ]); + return Object.freeze({ retryWithPolicy, Deadline, extractArchiveSafely, execFailureDetails }); + }), + } satisfies ProviderHostCapabilities); +} + +async function createProviderAndroidHost(runOnHost: RunOnHost): Promise { + // The host adb port refuses an unbound host; this wiring binds it and loads no device state. + await import('./platform-runtime-android-adb-host.ts'); + const [mechanics, { createAndroidInteractor }, { getAndroidAppStateWithAdb }] = await Promise.all( + [ + import('@agent-device/platform-android/mechanics'), + // `getInteractor` is synchronous, so the factory is loaded with the facet. + import('./core/interactors/android.ts'), + import('./platform-runtime.ts'), + ], + ); + const scoped = (device: DeviceInfo, adb: AndroidAdbProvider) => (task: () => Promise) => + runOnHost(() => mechanics.withAndroidAdbProvider(adb, { serial: device.id }, task)); + return Object.freeze({ + runAdb: async (invocation, options) => + await runOnHost(() => mechanics.runAndroidHostAdb(invocation, options)), + deviceAdbInvocation: (serial, command) => + mechanics.androidAdbInvocation(mechanics.androidAdbSerialTarget(serial), command), + hostAdbInvocation: (command) => + mechanics.androidAdbInvocation(mechanics.androidAdbHostTarget(), command), + adbError: (message, result, invocation) => + mechanics.androidAdbResultError( + message, + result, + invocation + ? { command: `adb ${mechanics.serializeAndroidAdbInvocation(invocation).join(' ')}` } + : undefined, + ), + createLeaseInteractor: (device, adb) => + withMethodScope(createAndroidInteractor(device, adb), runOnHost), + bindPerformance: async (device, adb, runtimeHost, owner) => { + const scopedHost = withMethodScope({ ...runtimeHost }, scoped(device, adb) as RunOnHost); + const { perfFrames, perfMemorySample, perfMemorySnapshot } = + await mechanics.createAndroidPerfOperations({ + device, + owner, + resolveHost: () => scopedHost, + }); + return { perfFrames, perfMemorySample, perfMemorySnapshot }; + }, + bindDeployment: async (device, adb, request) => { + const operations = await mechanics.createAndroidAppDeploymentOperations({ + ...request, + device, + }); + return withMethodScope({ ...operations }, scoped(device, adb) as RunOnHost); + }, + createPortReverse: mechanics.createAndroidPortReverseManager, + inferAppName: mechanics.inferAndroidAppName, + listApps: async (adb, filter) => + (await mechanics.listAndroidAppsWithAdb(adb, { filter, target: 'mobile' })).map((app) => ({ + id: app.package, + name: app.name, + })), + getForegroundApp: async (adb, signal) => { + const app = await getAndroidAppStateWithAdb( + async (args, options) => await adb(args, { ...options, signal }), + signal, + ); + return app.package ? { appId: app.package, activity: app.activity } : undefined; + }, + getKeyboardState: mechanics.getAndroidKeyboardStatusWithAdb, + dismissKeyboard: mechanics.dismissAndroidKeyboardWithAdb, + readLogs: async (adb, lineLimit) => + await mechanics.captureAndroidLogcatWithAdb(adb, { lines: lineLimit, timeoutMs: 5_000 }), + forceStopApp: async (adb, packageName, signal) => { + await mechanics.runAdbShell( + async (args, options) => await adb(args, { ...options, signal }), + ['am', 'force-stop', packageName], + { allowFailure: true }, + ); + }, + } satisfies ProviderAndroidHost); +} + +async function createProviderAppleHost( + host: HostEnvironment, + runOnHost: RunOnHost, +): Promise { + const [runner, tools, { buildSimctlArgsForDevice }, { createAppleApplicationTools }] = + await Promise.all([ + import('@agent-device/platform-apple/runner/operations'), + import('@agent-device/platform-apple/tool-provider'), + import('@agent-device/platform-apple/simctl'), + import('./platform-runtime-apple-application-tools.ts'), + ]); + const { resolveOpenTarget, applyRuntimeHints, clearRuntimeHints } = createAppleApplicationTools( + host.env, + ); + return Object.freeze({ + applicationTools: Object.freeze({ resolveOpenTarget, applyRuntimeHints, clearRuntimeHints }), + runner: Object.freeze({ + // Both are built under this host, so no enclosing request's environment reaches the runner. + createRuntime: async (options) => + await runOnHost(() => runner.createAppleRunnerRuntime({ ...options, host })), + createLaunchedProvider: async (device, options) => + await runOnHost(() => runner.createLaunchedAppleRunnerProvider(device, options, host.env)), + mintToken: runner.mintRunnerToken, + listenerEnv: runner.runnerListenerEnv, + startupTimeoutMs: runner.RUNNER_STARTUP_TIMEOUT_MS, + xctestrunCaptureOptions: runner.RUNNER_XCTESTRUN_CAPTURE_OPTIONS, + }), + tools: Object.freeze({ + withProvider: tools.withAppleToolProvider, + hasScopedProvider: tools.hasScopedAppleToolProvider, + runXcrun: tools.runXcrun, + simctlArgsForDevice: buildSimctlArgsForDevice, + parsePlist: tools.parseApplePlist, + }), + readBundleAppName: async (appPath) => + await runOnHost(async () => { + const { readIosBundleInfo } = await import('@agent-device/platform-apple/install-artifact'); + return (await readIosBundleInfo(appPath)).appName; + }), + } satisfies ProviderAppleHost); +} diff --git a/src/provider-plugin-policy.ts b/src/provider-plugin-policy.ts index 03602ea9dc..3d4779796d 100644 --- a/src/provider-plugin-policy.ts +++ b/src/provider-plugin-policy.ts @@ -4,9 +4,12 @@ import type { CloudWebDriverRuntimeOptions } from '@agent-device/provider-webdri /** * The policy every provider registry in this process runs under. A plugin that returns a - * `{ webDriver }` descriptor gets the shared WebDriver engine, loaded only then. + * `{ webDriver }` descriptor gets the shared WebDriver engine, loaded only then. Every provider + * `setup` host carries the platform facets, each loaded when a plugin first asks for it. */ export const PROVIDER_PLUGIN_POLICY: PluginRegistryPolicy = Object.freeze({ + hostCapabilities: async (host) => + (await import('./provider-plugin-host-capabilities.ts')).createProviderHostCapabilities(host), adaptWebDriver: async (descriptor, { clientVersion }) => { const options = readWebDriverOptions(descriptor); const { createCloudWebDriverRuntime } = await import('@agent-device/provider-webdriver/plugin'); diff --git a/src/sdk/limrun-runtime-dependencies.ts b/src/sdk/limrun-runtime-dependencies.ts deleted file mode 100644 index 471650d0e3..0000000000 --- a/src/sdk/limrun-runtime-dependencies.ts +++ /dev/null @@ -1,150 +0,0 @@ -import { createLimrunIosAppLogReader } from '../core/interactors/limrun-ios-app-logs.ts'; -import type { HostEnvironment } from '@agent-device/kernel/source-value'; -import { withMethodScope } from '@agent-device/kernel/scoped-provider'; -import type { LimrunRuntimeDependencies } from '@agent-device/provider-limrun'; -import '../platform-runtime-android-adb-host.ts'; -// ProviderDeviceRuntime.getInteractor is synchronous, so this factory is the deliberate static edge; -// making it lazy would require a proxy interactor rather than this seam. -import { createAndroidInteractor } from '../core/interactors/android.ts'; -import { - androidAdbHostTarget, - androidAdbInvocation, - androidAdbSerialTarget, - runAndroidHostAdb, -} from '@agent-device/platform-android/mechanics'; -import { withCommandHost } from '@agent-device/host-kit/command'; -import { readVersion } from '@agent-device/host-kit/version'; - -export function createLimrunRuntimeDependencies(host: HostEnvironment): LimrunRuntimeDependencies { - const runOnHost = (task: () => Promise) => - withCommandHost({ host, requestEnv: undefined }, task); - return { - clientVersion: readVersion(), - android: { - bindPerformance: async (device, adb, runtimeHost, owner) => { - const { createAndroidPerfOperations, withAndroidAdbProvider } = - await import('@agent-device/platform-android/mechanics'); - const scopedHost = withMethodScope({ ...runtimeHost }, (task) => - runOnHost(() => withAndroidAdbProvider(adb, { serial: device.id }, task)), - ); - const { perfFrames, perfMemorySample, perfMemorySnapshot } = - await createAndroidPerfOperations({ device, owner, resolveHost: () => scopedHost }); - return { perfFrames, perfMemorySample, perfMemorySnapshot }; - }, - bindDeployment: async (device, adb, request) => { - const { createAndroidAppDeploymentOperations, withAndroidAdbProvider } = - await import('@agent-device/platform-android/mechanics'); - const operations = await createAndroidAppDeploymentOperations({ ...request, device }); - return withMethodScope({ ...operations }, (task) => - runOnHost(() => withAndroidAdbProvider(adb, { serial: device.id }, task)), - ); - }, - createInteractor: (device, adb) => - withMethodScope(createAndroidInteractor(device, adb), runOnHost), - createPortReverse: async (adb, options) => { - const { createAndroidPortReverseManager } = - await import('@agent-device/platform-android/mechanics'); - return createAndroidPortReverseManager(adb, options); - }, - inferAppName: async (packageName) => { - const { inferAndroidAppName } = await import('@agent-device/platform-android/mechanics'); - return inferAndroidAppName(packageName); - }, - listApps: async (adb, filter) => { - const { listAndroidAppsWithAdb } = await import('@agent-device/platform-android/mechanics'); - return ( - await listAndroidAppsWithAdb(adb, { - filter, - target: 'mobile', - }) - ).map((app) => ({ id: app.package, name: app.name })); - }, - getForegroundApp: async (_device, adb, signal) => { - const { getAndroidAppStateWithAdb } = await import('../platform-runtime.ts'); - const app = await getAndroidAppStateWithAdb( - async (args, options) => await adb(args, { ...options, signal }), - signal, - ); - return app.package ? { appId: app.package, activity: app.activity } : undefined; - }, - getKeyboardState: async (adb) => { - const { getAndroidKeyboardStatusWithAdb } = - await import('@agent-device/platform-android/mechanics'); - return await getAndroidKeyboardStatusWithAdb(adb); - }, - dismissKeyboard: async (adb) => { - const { dismissAndroidKeyboardWithAdb } = - await import('@agent-device/platform-android/mechanics'); - return await dismissAndroidKeyboardWithAdb(adb); - }, - readLogs: async (adb, lineLimit) => { - const { captureAndroidLogcatWithAdb } = - await import('@agent-device/platform-android/mechanics'); - return await captureAndroidLogcatWithAdb(adb, { - lines: lineLimit, - timeoutMs: 5_000, - }); - }, - forceStopApp: async (adb, packageName, signal) => { - const { runAdbShell } = await import('@agent-device/platform-android/mechanics'); - await runAdbShell( - async (args, options) => await adb(args, { ...options, signal }), - ['am', 'force-stop', packageName], - { allowFailure: true }, - ); - }, - deviceAdbInvocation: (serial, command) => - androidAdbInvocation(androidAdbSerialTarget(serial), command), - hostAdbInvocation: (command) => androidAdbInvocation(androidAdbHostTarget(), command), - adbError: async (message, result, invocation) => { - // Error construction is async so the platform helper remains lazy until an ADB failure. - const { androidAdbResultError, serializeAndroidAdbInvocation } = - await import('@agent-device/platform-android/mechanics'); - return androidAdbResultError( - message, - result, - invocation - ? { command: `adb ${serializeAndroidAdbInvocation(invocation).join(' ')}` } - : undefined, - ); - }, - }, - host: withMethodScope( - { - runAdb: async (invocation, options) => await runAndroidHostAdb(invocation, options), - downloadFile: async (options) => { - const { downloadLimrunFile } = await import('../core/limrun-download-file.ts'); - await downloadLimrunFile(options); - }, - }, - runOnHost, - ), - ios: { - // The scoped wrapper returns promises; this factory must return its reader synchronously. - createAppLogReader: createLimrunIosAppLogReader, - ...withMethodScope>( - { - createRunner: async (session) => { - const { createLimrunIosRunner } = - await import('../core/interactors/limrun-ios-runner.ts'); - const { createAppleApplicationTools } = - await import('../platform-runtime-apple-application-tools.ts'); - const { resolveOpenTarget, applyRuntimeHints, clearRuntimeHints } = - createAppleApplicationTools(host.env); - return createLimrunIosRunner(session, host, { - resolveOpenTarget, - applyRuntimeHints, - clearRuntimeHints, - }); - }, - readBundleAppName: async (appPath) => { - const { readIosBundleInfo } = - await import('@agent-device/platform-apple/install-artifact'); - return (await readIosBundleInfo(appPath)).appName; - }, - }, - runOnHost, - ), - }, - }; -} diff --git a/src/sdk/plugin-device-host.ts b/src/sdk/plugin-device-host.ts new file mode 100644 index 0000000000..aef9f6d4c9 --- /dev/null +++ b/src/sdk/plugin-device-host.ts @@ -0,0 +1,148 @@ +import type { AndroidPerfHost } from '@agent-device/contracts/perf-runtime-host'; +import type { + AppDeploymentInstaller, + AppDeploymentRuntimeOperations, +} from '@agent-device/contracts/app-deployment-runtime'; +import type { AppleApplicationTools } from '@agent-device/contracts/application-lifecycle-runtime'; +import type { AppsFilter } from '@agent-device/contracts/device'; +import type { Interactor } from '@agent-device/contracts/interactor-types'; +import type { PlatformRuntimeHost } from '@agent-device/contracts/platform-runtime-operations'; +import type { RuntimeOwnerRef } from '@agent-device/contracts/platform-runtime'; +import type { DiagnosticEventInput } from '@agent-device/host-kit/diagnostics'; +import type { DeviceInfo } from '@agent-device/kernel/device'; +import type { AppError } from '@agent-device/kernel/errors'; +import type { ProviderPluginHost } from '@agent-device/plugins/host'; + +// This entry is not a published export. A provider plugin built in this repository reads these +// types through a workspace path; publishing them would place the platform declarations in the +// shared chunk every `agent-device/plugins` consumer loads. + +type AndroidMechanics = typeof import('@agent-device/platform-android/mechanics'); +type AndroidAdbProvider = import('@agent-device/platform-android/mechanics').AndroidAdbProvider; +type AndroidAdbInvocation = import('@agent-device/platform-android/mechanics').AndroidAdbInvocation; +type AndroidAdbExecutor = Parameters[0]; +type AndroidPerfOperations = Awaited>; +type AppleRunnerOperations = typeof import('@agent-device/platform-apple/runner/operations'); +type AppleToolProviderModule = typeof import('@agent-device/platform-apple/tool-provider'); +type HostRetry = typeof import('@agent-device/host-kit/retry'); + +/** What a provider asks of an Android install: the request's host, its signal and its installer. */ +export type ProviderAndroidDeploymentRequest = Readonly<{ + host: PlatformRuntimeHost; + signal: AbortSignal; + install: AppDeploymentInstaller; +}>; + +/** + * The Android host a provider plugin drives its leased devices through. Every operation takes the + * provider's own ADB executor, so the provider decides how a command reaches its device and the + * platform decides what the command is. Commands run under the host these capabilities were built + * for; an enclosing request's environment is not added. + */ +export type ProviderAndroidHost = Readonly<{ + /** Runs one addressed invocation over the host ADB transport. */ + runAdb: AndroidMechanics['runAndroidHostAdb']; + /** Addresses one device command at `serial`. */ + deviceAdbInvocation(serial: string, command: readonly string[]): AndroidAdbInvocation; + /** Addresses one server-level command, which selects no device. */ + hostAdbInvocation(command: readonly string[]): AndroidAdbInvocation; + adbError( + message: string, + result: Parameters[1], + invocation?: AndroidAdbInvocation, + ): AppError; + /** + * The Android interactor for one leased device, bound to that lease's executor. The platform owns + * the interactor; the provider owns only the executor it answers through. + */ + createLeaseInteractor(device: DeviceInfo, adb: AndroidAdbProvider): Interactor; + bindPerformance( + device: DeviceInfo, + adb: AndroidAdbProvider, + host: AndroidPerfHost, + owner: RuntimeOwnerRef, + ): Promise>; + bindDeployment( + device: DeviceInfo, + adb: AndroidAdbProvider, + request: ProviderAndroidDeploymentRequest, + ): Promise>; + createPortReverse: AndroidMechanics['createAndroidPortReverseManager']; + inferAppName: AndroidMechanics['inferAndroidAppName']; + listApps( + adb: AndroidAdbExecutor, + filter: AppsFilter, + ): Promise>; + getForegroundApp( + adb: AndroidAdbExecutor, + signal?: AbortSignal, + ): Promise<{ appId?: string; activity?: string } | undefined>; + getKeyboardState: AndroidMechanics['getAndroidKeyboardStatusWithAdb']; + dismissKeyboard: AndroidMechanics['dismissAndroidKeyboardWithAdb']; + readLogs(adb: AndroidAdbExecutor, lineLimit: number): Promise; + /** Stops the app. Tolerates a device that refuses. */ + forceStopApp(adb: AndroidAdbExecutor, packageName: string, signal?: AbortSignal): Promise; +}>; + +/** + * The Apple host a provider plugin drives a leased simulator through: the shared XCTest runner, the + * tool-provider scope its commands answer in, and the application tools that resolve an open target + * and write runtime hints. A provider supplies the tool provider that reaches its simulator. + */ +export type ProviderAppleHost = Readonly<{ + applicationTools: Pick< + AppleApplicationTools, + 'resolveOpenTarget' | 'applyRuntimeHints' | 'clearRuntimeHints' + >; + runner: Readonly<{ + /** Builds the runner runtime for `device` under this host. */ + createRuntime( + options: Omit[0], 'host'>, + ): ReturnType; + /** Builds a runner provider whose XCTest run the caller launches. */ + createLaunchedProvider( + device: Parameters[0], + options: Parameters[1], + ): ReturnType; + mintToken: AppleRunnerOperations['mintRunnerToken']; + listenerEnv: AppleRunnerOperations['runnerListenerEnv']; + startupTimeoutMs: number; + xctestrunCaptureOptions: AppleRunnerOperations['RUNNER_XCTESTRUN_CAPTURE_OPTIONS']; + }>; + tools: Readonly<{ + withProvider: AppleToolProviderModule['withAppleToolProvider']; + hasScopedProvider: AppleToolProviderModule['hasScopedAppleToolProvider']; + runXcrun: AppleToolProviderModule['runXcrun']; + simctlArgsForDevice: typeof import('@agent-device/platform-apple/simctl').buildSimctlArgsForDevice; + parsePlist: AppleToolProviderModule['parseApplePlist']; + }>; + readBundleAppName(appPath: string): Promise; +}>; + +/** Host mechanics whose diagnostics and budgets belong to this process. */ +export type ProviderHostKit = Readonly<{ + retryWithPolicy: HostRetry['retryWithPolicy']; + Deadline: HostRetry['Deadline']; + extractArchiveSafely: typeof import('@agent-device/host-kit/archive').extractArchiveSafely; + execFailureDetails: typeof import('@agent-device/host-kit/command').execFailureDetails; +}>; + +/** + * What the composing root adds to every provider plugin `setup` host. Each loader imports its + * platform owner on first use, so a plugin that needs none of them loads none of them. + */ +export type ProviderHostCapabilities = Readonly<{ + /** The daemon's own state directory. */ + stateDir: string; + /** Records one event in the diagnostics of the request that is running. */ + emitDiagnostic(event: DiagnosticEventInput): void; + loadAndroid(): Promise; + loadApple(): Promise; + loadHostKit(): Promise; +}>; + +/** + * The host a provider `setup` receives from the daemon or `startAgentDevice`: the plugin host plus + * the device capabilities. A `connect` callback's host carries none of them, so each is optional. + */ +export type DeviceProviderPluginHost = ProviderPluginHost & Partial; diff --git a/test/integration/installed-package-metro.test.ts b/test/integration/installed-package-metro.test.ts index 692098d184..da70c0dffb 100644 --- a/test/integration/installed-package-metro.test.ts +++ b/test/integration/installed-package-metro.test.ts @@ -440,7 +440,7 @@ const a = await startAgentDevice({ host: supplied, plugins: [ fixture('fixture-a'), - fixture('limrun'), + fixture('cloud'), null, { ...fixture('wrong-version'), apiVersion: 1 }, fixture('broken', () => { @@ -467,8 +467,8 @@ try { const inventory = JSON.parse(fs.readFileSync(path.join(a.clientConfig.stateDir, 'daemon.json'), 'utf8')).plugins; assert.equal(inventory.find((p) => p.provider === 'fixture-a').state, 'active'); assert.equal( - inventory.filter((p) => p.provider === 'limrun' && p.source === 'embedder')[0].state, - 'failed', + inventory.filter((p) => p.provider === 'cloud' && p.source === 'embedder')[0].error.reason, + 'reserved_provider', ); assert.equal(inventory.find((p) => p.provider === 'broken').state, 'failed'); assert.equal(inventory.find((p) => p.source === 'embedder' && p.provider === undefined).error.reason, 'invalid_plugin'); diff --git a/test/integration/provider-scenarios/limrun-android-performance.test.ts b/test/integration/provider-scenarios/limrun-android-performance.test.ts index 9dd1a4e0dc..1a24eb7107 100644 --- a/test/integration/provider-scenarios/limrun-android-performance.test.ts +++ b/test/integration/provider-scenarios/limrun-android-performance.test.ts @@ -1,7 +1,7 @@ import { expect, test, vi } from 'vitest'; import type { DeviceLease } from '@agent-device/contracts/device'; -import { createLimrunRuntime } from '@agent-device/provider-limrun'; -import { createLimrunRuntimeDependencies } from '../../../src/sdk/limrun-runtime-dependencies.ts'; +import { createLimrunRuntime } from '@agent-device/limrun/runtime'; +import { limrunRuntimeDependencies } from '../../../src/provider-plugin-host-capabilities.fixtures.ts'; import { createProviderDeviceRuntimeRequestProviders } from '../../../src/provider-device-runtime.ts'; import { assertRpcOk } from './assertions.ts'; import { createProviderScenarioHarness } from './harness.ts'; @@ -41,7 +41,7 @@ vi.mock('@agent-device/host-kit/command', async (original) => ({ })); test('Limrun Android memory sampling reaches the allocated session ADB through daemon dispatch', async () => { - const dependencies = createLimrunRuntimeDependencies({ env: {}, cwd: process.cwd() }); + const dependencies = await limrunRuntimeDependencies({ env: {}, cwd: process.cwd() }); // Plain close stops the session app; the fake device then reports it gone. let settingsStopped = false; const sessionExec = vi.fn(async (invocation) => { diff --git a/test/integration/provider-scenarios/limrun-deployment-cancellation.fixtures.ts b/test/integration/provider-scenarios/limrun-deployment-cancellation.fixtures.ts index 66a597827b..764a84981e 100644 --- a/test/integration/provider-scenarios/limrun-deployment-cancellation.fixtures.ts +++ b/test/integration/provider-scenarios/limrun-deployment-cancellation.fixtures.ts @@ -2,7 +2,7 @@ import fs from 'node:fs'; import path from 'node:path'; import type { DeviceLease } from '@agent-device/contracts/device'; import type { PlatformRuntimeHost } from '@agent-device/contracts/platform-runtime-operations'; -import { createLimrunRuntime, type LimrunRuntimeDependencies } from '@agent-device/provider-limrun'; +import { createLimrunRuntime, type LimrunRuntimeDependencies } from '@agent-device/limrun/runtime'; import { limrunTestDependencies } from '../../../src/platform-runtime-gateway.fixtures.ts'; import type { DeviceInfo } from '@agent-device/kernel/device'; import { mkdtempForTestSync } from '@agent-device/test-kit'; diff --git a/test/integration/provider-scenarios/limrun-ios-appstate.test.ts b/test/integration/provider-scenarios/limrun-ios-appstate.test.ts index f02aebca1f..8c4e171a5f 100644 --- a/test/integration/provider-scenarios/limrun-ios-appstate.test.ts +++ b/test/integration/provider-scenarios/limrun-ios-appstate.test.ts @@ -1,10 +1,13 @@ import { withMethodScope } from '@agent-device/kernel/scoped-provider'; import { withAppleToolProvider } from '@agent-device/platform-apple/tool-provider'; -import { createLimrunAppleToolProvider } from '../../../src/core/interactors/limrun-ios-tools.ts'; +import { + createLimrunAppleToolProvider, + limrunIosHost, +} from '../../../src/provider-plugin-host-capabilities.fixtures.ts'; import assert from 'node:assert/strict'; import { beforeEach, test, vi } from 'vitest'; import type { DeviceLease } from '@agent-device/contracts/device'; -import { createLimrunRuntime, type LimrunRuntimeDependencies } from '@agent-device/provider-limrun'; +import { createLimrunRuntime, type LimrunRuntimeDependencies } from '@agent-device/limrun/runtime'; import { limrunTestDependencies, createTestLimrunIosRunner, @@ -158,12 +161,13 @@ function limrunRuntimeDependencies(): LimrunRuntimeDependencies { createRunner: async (session) => { const runner = await createTestLimrunIosRunner(session.device); const lifetime = new AbortController(); + const iosHost = await limrunIosHost({ env: {}, cwd: process.cwd() }); return { ...runner, createInteractor: (context) => withMethodScope(runner.createInteractor(context), (task) => withAppleToolProvider( - createLimrunAppleToolProvider(session, lifetime.signal, context?.signal), + createLimrunAppleToolProvider(session, iosHost, lifetime.signal, context?.signal), task, ), ), diff --git a/test/integration/provider-scenarios/limrun-ios-settings.test.ts b/test/integration/provider-scenarios/limrun-ios-settings.test.ts index c17a788c93..147dd759da 100644 --- a/test/integration/provider-scenarios/limrun-ios-settings.test.ts +++ b/test/integration/provider-scenarios/limrun-ios-settings.test.ts @@ -1,5 +1,5 @@ import { EventEmitter } from 'node:events'; -import { createLimrunRuntimeDependencies } from '../../../src/sdk/limrun-runtime-dependencies.ts'; +import { limrunRuntimeDependencies } from '../../../src/provider-plugin-host-capabilities.fixtures.ts'; import { afterEach, expect, test, vi } from 'vitest'; import { bindLimrunDeployment } from './limrun-deployment-cancellation.fixtures.ts'; @@ -66,7 +66,7 @@ test('a Limrun iOS permission the runtime refuses reports the local unsupported const { binding, dispose } = await bindLimrunDeployment( 'ios', new AbortController().signal, - createLimrunRuntimeDependencies({ env: {}, cwd: process.cwd() }).ios, + (await limrunRuntimeDependencies({ env: {}, cwd: process.cwd() })).ios, ); try { const refusal = binding.operations.setSetting!({ @@ -97,7 +97,7 @@ test('a Limrun iOS simctl failure that is not a refusal stays a command failure' const { binding, dispose } = await bindLimrunDeployment( 'ios', new AbortController().signal, - createLimrunRuntimeDependencies({ env: {}, cwd: process.cwd() }).ios, + (await limrunRuntimeDependencies({ env: {}, cwd: process.cwd() })).ios, ); try { await expect( @@ -123,7 +123,7 @@ test('a Limrun iOS permission resolves an app display name through the remote ap const { binding, dispose } = await bindLimrunDeployment( 'ios', new AbortController().signal, - createLimrunRuntimeDependencies({ env: {}, cwd: process.cwd() }).ios, + (await limrunRuntimeDependencies({ env: {}, cwd: process.cwd() })).ios, ); try { await binding.operations.setSetting!({ diff --git a/test/integration/provider-scenarios/limrun-ios-snapshot-owner.test.ts b/test/integration/provider-scenarios/limrun-ios-snapshot-owner.test.ts index 001fbf058e..d936b6c089 100644 --- a/test/integration/provider-scenarios/limrun-ios-snapshot-owner.test.ts +++ b/test/integration/provider-scenarios/limrun-ios-snapshot-owner.test.ts @@ -1,11 +1,14 @@ import { withMethodScope } from '@agent-device/kernel/scoped-provider'; import { withAppleToolProvider } from '@agent-device/platform-apple/tool-provider'; -import { createLimrunAppleToolProvider } from '../../../src/core/interactors/limrun-ios-tools.ts'; +import { + createLimrunAppleToolProvider, + limrunIosHost, +} from '../../../src/provider-plugin-host-capabilities.fixtures.ts'; import assert from 'node:assert/strict'; import { beforeEach, test, vi } from 'vitest'; import type { CaptureSnapshotResult } from '@agent-device/contracts/client'; import type { DeviceLease } from '@agent-device/contracts/device'; -import { createLimrunRuntime, type LimrunRuntimeDependencies } from '@agent-device/provider-limrun'; +import { createLimrunRuntime, type LimrunRuntimeDependencies } from '@agent-device/limrun/runtime'; import { limrunTestDependencies, createTestLimrunIosRunner, @@ -273,12 +276,13 @@ function limrunRuntimeDependencies(): LimrunRuntimeDependencies { limrunApiState.runnerCommand(command), ); const lifetime = new AbortController(); + const iosHost = await limrunIosHost({ env: {}, cwd: process.cwd() }); return { ...runner, createInteractor: (context) => withMethodScope(runner.createInteractor(context), (task) => withAppleToolProvider( - createLimrunAppleToolProvider(session, lifetime.signal, context?.signal), + createLimrunAppleToolProvider(session, iosHost, lifetime.signal, context?.signal), task, ), ), diff --git a/test/integration/provider-scenarios/stale-provider-runtime-admission.test.ts b/test/integration/provider-scenarios/stale-provider-runtime-admission.test.ts index d64e9e4085..ab5496f36b 100644 --- a/test/integration/provider-scenarios/stale-provider-runtime-admission.test.ts +++ b/test/integration/provider-scenarios/stale-provider-runtime-admission.test.ts @@ -5,7 +5,7 @@ import { expect, test, vi } from 'vitest'; import type { DeviceLease } from '@agent-device/contracts/device'; import { createBundledCloudWebDriverRuntimes } from './bundled-cloud-webdriver-runtimes.ts'; import { BROWSERSTACK_PROVIDER, createBrowserStackRuntime } from './browserstack-runtime.ts'; -import { createLimrunRuntime, type LimrunRuntimeDependencies } from '@agent-device/provider-limrun'; +import { createLimrunRuntime, type LimrunRuntimeDependencies } from '@agent-device/limrun/runtime'; import { limrunTestDependencies } from '../../../src/platform-runtime-gateway.fixtures.ts'; import type { DeviceInfo } from '@agent-device/kernel/device'; import { bindTestCommandHost, mkdtempForTestSync } from '@agent-device/test-kit'; diff --git a/tsconfig.json b/tsconfig.json index d321a0026b..3b35ba0343 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -19,7 +19,8 @@ "noEmit": true, "paths": { "agent-device/plugins": ["./src/sdk/plugins.ts"], - "agent-device/plugins/webdriver": ["./src/sdk/plugin-webdriver.ts"] + "agent-device/plugins/webdriver": ["./src/sdk/plugin-webdriver.ts"], + "agent-device/plugins/device-host": ["./src/sdk/plugin-device-host.ts"] } }, "include": ["src", "test", "scripts/**/*.ts", "packages/command-registry/src/global.d.ts"] diff --git a/tsdown.config.ts b/tsdown.config.ts index d60b1bb7fc..795387485c 100644 --- a/tsdown.config.ts +++ b/tsdown.config.ts @@ -2,7 +2,7 @@ import { buildEntries } from './scripts/build-entries.ts'; import fs from 'node:fs'; import { createRequire } from 'node:module'; import { pathToFileURL } from 'node:url'; -import { defineConfig, type TsdownPluginOption } from 'tsdown'; +import { defineConfig } from 'tsdown'; import { bundledLicenseNotices } from './scripts/lib/bundled-license-notices.ts'; const typeScriptPackageJsonUrl = pathToFileURL( @@ -57,42 +57,11 @@ const publicSdkChunkGroups = [ ['sdk-selectors', /src[\\/]sdk[\\/]selectors\.d\.[cm]?ts$/, /src[\\/]sdk[\\/]selectors\.ts$/], ] as const; -/** - * Drops the ambient `import '...'` marker `deps.dts.neverBundle` leaves behind, which a - * published install cannot resolve. Safe only while the name appears nowhere else. - */ -function dropAmbientDeclarationImport( - fileName: string, - code: string, - packageName = '@limrun/api', -): string | null { - const ambientImport = new RegExp(`^import ["']${packageName}["'];\\n`, 'm'); - if (!ambientImport.test(code)) return null; - const declarationChunk = code.replace(ambientImport, ''); - if (declarationChunk.includes(packageName)) { - throw new Error( - `${fileName} keeps a type reference to ${packageName}, which is dev-bundled and absent from a published install.`, - ); - } - return declarationChunk; -} - -const dropAmbientDeclarationImports: TsdownPluginOption = { - name: 'agent-device:drop-ambient-declaration-imports', - renderChunk(code, chunk) { - return chunk.fileName.endsWith('.d.ts') - ? dropAmbientDeclarationImport(chunk.fileName, code) - : null; - }, -}; - export default defineConfig({ entry: buildEntries, deps: { alwaysBundle: [/^@agent-device\//], onlyBundle: [ - '@limrun/api', - '@limrun/xdelta3-wasm', '@xmldom/xmldom', 'agent-base', 'b4a', @@ -122,11 +91,6 @@ export default defineConfig({ 'yaml', 'yauzl', ], - // The Limrun SDK is dev-bundled, so a published install has no `@limrun/api` to resolve: - // the limrun facade declares the session and runtime types consumers may use. - dts: { - neverBundle: ['@limrun/api'], - }, }, inputOptions: { // A build with missing workspace links resolves nothing under `alwaysBundle` and emits the @@ -173,7 +137,7 @@ export default defineConfig({ }, outExtensions: () => ({ js: '.js', dts: '.d.ts' }), minify: true, - plugins: [dropAmbientDeclarationImports, bundledLicenseNotices(import.meta.dirname)], + plugins: [bundledLicenseNotices(import.meta.dirname)], dts: { tsgo: { path: getTypeScript7ExePath(), diff --git a/website/docs/docs/device-clouds.md b/website/docs/docs/device-clouds.md index 80d7bfdf22..f92d7aed8c 100644 --- a/website/docs/docs/device-clouds.md +++ b/website/docs/docs/device-clouds.md @@ -8,7 +8,7 @@ Use a device cloud or farm when an agent needs to drive a hosted mobile device w - [BrowserStack](/docs/browserstack): Android and iOS App Automate sessions over WebDriver. Install the `@agent-device/browserstack` plugin first. - [AWS Device Farm](/docs/aws-device-farm): Android and iOS remote-access sessions through AWS. Install the `@agent-device/aws-device-farm` plugin first. - [TestMu AI](/docs/testmu): Android emulator, iOS simulator, and real-device sessions over WebDriver. -- [Limrun](/docs/limrun): direct iOS simulator and Android emulator instances. +- [Limrun](/docs/limrun): direct iOS simulator and Android emulator instances. Install the `@agent-device/limrun` plugin first. - [Revyl](/docs/revyl): iOS simulators and Android emulators rented from Revyl's execution API. ## Compare providers @@ -16,7 +16,7 @@ Use a device cloud or farm when an agent needs to drive a hosted mobile device w | | BrowserStack | AWS Device Farm | TestMu AI | Limrun | Revyl | | --- | --- | --- | --- | --- | --- | | Devices | Android and iOS real devices | Android and iOS real devices | Android emulators and iOS simulators by default; real devices with `--provider-device-type real` | Android emulators and iOS simulators | Android emulators and iOS simulators | -| Ships as | The `@agent-device/browserstack` plugin | The `@agent-device/aws-device-farm` plugin; needs the AWS CLI | The `@agent-device/testmu` plugin | Built in | The `@agent-device/revyl` plugin | +| Ships as | The `@agent-device/browserstack` plugin | The `@agent-device/aws-device-farm` plugin; needs the AWS CLI | The `@agent-device/testmu` plugin | The `@agent-device/limrun` plugin | The `@agent-device/revyl` plugin | | Credentials | `BROWSERSTACK_USERNAME`, `BROWSERSTACK_ACCESS_KEY` | The AWS CLI credential chain, such as `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`, `AWS_REGION` | `LT_USERNAME`, `LT_ACCESS_KEY` | `LIMRUN_API_KEY` (optional `LIMRUN_REGION`), or `LIM_*_INSTANCE_*` for an existing instance | `REVYL_API_KEY` (optional `REVYL_API_URL` for another Revyl backend) | | Device allocated on | `open` | `open` | `open` | First device command, such as `install` or `open` | First device command, such as `open` | | App source | `--provider-app`: `bs://` reference, HTTP(S) URL, or local path | `--aws-app-arn` upload ARN; no install after allocation | `--provider-app`: `lt://` reference, HTTP(S) URL, or local path | `install `, or `open ` for an uploaded asset | `--provider-app`: a public HTTPS URL only, installed when the device starts | diff --git a/website/docs/docs/limrun.md b/website/docs/docs/limrun.md index 5da589edd8..6e4520690c 100644 --- a/website/docs/docs/limrun.md +++ b/website/docs/docs/limrun.md @@ -5,6 +5,31 @@ description: Drive Limrun iOS simulators and Android emulators with agent-device Use Limrun to run agent-device on remote iOS simulators and Android emulators. You need a Limrun API key, or the URL and token of an instance someone else created. Limrun does not use local or physical-device selectors such as `--udid`, `--serial`, or `--device`. +## Install the plugin + +Install the plugin on the host that runs the daemon. + +```bash +agent-device plugins add @agent-device/limrun@nightly-0.22 +``` + +If the CLI prints an install command in a missing-plugin error, use that command. + +After installing or changing a plugin, finish sessions and run `agent-device daemon stop --state-dir ` for the matching detached daemon, then retry the command. + +For an embedded runtime, import the factory and pass it to `startAgentDevice`. The embedded runtime does not read the CLI plugin store. After changing plugins, close and recreate the runtime. + +```ts +import { startAgentDevice } from "agent-device"; +import limrun from "@agent-device/limrun/agent-device"; + +const runtime = await startAgentDevice({ stateDir: "./.agent-device-state", plugins: [limrun()] }); +// Close the runtime when its owner is finished. +await runtime.close(); +``` + +The plugin installs the Limrun SDK (`@limrun/api`) as its own dependency. Run `agent-device plugins update @agent-device/limrun` to pick up SDK fixes. + ## Set credentials and connect Export your Limrun API key, for example from CI secrets. Set `LIMRUN_REGION` to pick a region. @@ -44,7 +69,7 @@ An agent in a sandbox can drive an instance that someone else created, such as t | iOS | `LIM_IOS_INSTANCE_URL` (`status.apiUrl`), `LIM_IOS_INSTANCE_TOKEN` (`status.token`) | | Android | `LIM_ANDROID_INSTANCE_URL` (`status.apiUrl`), `LIM_ANDROID_INSTANCE_TOKEN` (`status.token`), `LIM_ANDROID_INSTANCE_ADB_URL` (`status.adbWebSocketUrl`) | -The `lim` CLI reads the same variables, so one set works for both tools. Set all of a platform's variables or none. With a partial set, `connect` fails, and the daemon registers without Limrun, lists it as `failed` in `agent-device daemon status`, and records `provider_plugin_failed` in `daemon.log`. +The `lim` CLI reads the same variables, so one set works for both tools. Set all of a platform's variables or none. With a partial set, `connect` fails, and the daemon registers without Limrun, lists it as `failed` in `agent-device daemon status`, and records `provider_plugin_failed` in `daemon.log`. A daemon started with none of the Limrun variables lists the plugin as `failed` with `reason: missing_provider_credentials` and still serves every other provider. ```bash export LIM_IOS_INSTANCE_URL=... diff --git a/website/docs/docs/plugins.md b/website/docs/docs/plugins.md index 3eb967e1c7..163496a7fe 100644 --- a/website/docs/docs/plugins.md +++ b/website/docs/docs/plugins.md @@ -2,7 +2,7 @@ title: Plugins --- -Provider plugins add device providers that agent-device does not bundle, such as [BrowserStack](/docs/browserstack), [AWS Device Farm](/docs/aws-device-farm), [TestMu AI](/docs/testmu), [LG webOS](/docs/webos), and [Samsung Tizen](/docs/tizen). Installing one requires npm on your host: +Provider plugins add device providers that agent-device does not bundle, such as [BrowserStack](/docs/browserstack), [AWS Device Farm](/docs/aws-device-farm), [Limrun](/docs/limrun), [TestMu AI](/docs/testmu), [LG webOS](/docs/webos), and [Samsung Tizen](/docs/tizen). Installing one requires npm on your host: ```bash agent-device plugins add @example/agent-device-provider @@ -15,7 +15,7 @@ agent-device plugins remove @example/agent-device-provider `plugin, install separately` and show their installation commands, even before you install them. Use the install command shown for your provider. TestMu AI uses `agent-device plugins add @agent-device/testmu`. -If you run `agent-device connect browserstack`, `agent-device connect aws-device-farm`, or `agent-device connect testmu` without its plugin, the error gives that installation +If you run `agent-device connect browserstack`, `agent-device connect aws-device-farm`, `agent-device connect limrun`, or `agent-device connect testmu` without its plugin, the error gives that installation command and tells you to retry your original command. With `--json`, the error has `details.reason: plugin-not-installed`, `details.package`, and `details.installCommand`. If the plugin is selected but unavailable, the reason is `plugin-unavailable`; run @@ -47,7 +47,7 @@ A missing installation returns `plugin-not-installed` with the package and insta ## See which providers are registered -`agent-device daemon status` lists every provider the running daemon registered: bundled Limrun when configured, then installed plugins such as BrowserStack and AWS Device Farm. With `--json`, each entry has: +`agent-device daemon status` lists every provider the running daemon registered from the installed plugins, such as BrowserStack, AWS Device Farm, and Limrun. With `--json`, each entry has: ```json { @@ -136,7 +136,7 @@ Incompatible contract changes require a new `apiVersion`; there is no compatibil ### Credentials -List the environment variables the provider reads in `credentials.variables`. A local daemon keeps the values it started with; when the shell holds different ones, the first command that allocates a lease refuses with reason `provider-credentials-changed` until the daemon is stopped. The check treats a whitespace-only value as unset. If a lease reads fewer variables on one backend, narrow them with `credentials.byBackend`, for example `{ "android-instance": ["EXAMPLE_API_KEY"] }`. Credentials the caller passes as factory options are not in the environment, so list no variable for them. +List the environment variables the provider reads in `credentials.variables`. A local daemon keeps the values it started with; when the shell holds different ones, the first command that allocates a lease refuses with reason `provider-credentials-changed` until the daemon is stopped. The check treats a whitespace-only value as unset. If a lease reads fewer variables on one backend, narrow them with `credentials.byBackend`, for example `{ "android-instance": ["EXAMPLE_API_KEY"] }`. The Limrun plugin declares its account variables and each platform's instance variables this way, so a change to the iOS instance variables does not invalidate an Android lease. Credentials the caller passes as factory options are not in the environment, so list no variable for them. ### Connect From 486d98efd4b578792048bb3568389ba2e6ab7c18 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Fri, 20 Nov 2026 17:52:40 +0100 Subject: [PATCH 02/26] chore(gates): admit the Limrun plugin package and its own SDK dependency The Limrun package publishes its own artifact and installs `@limrun/api` itself, so the root matches only the dependency ranges it also declares. The packed-plugin check reads a plugin's own dependencies from its fixture. The root module zones drop the removed built-in provider modules and place the provider host capabilities with the platform runtime host. --- .fallowrc.json | 5 ++- scripts/check-provider-plugin.mjs | 3 +- scripts/layering/check.ts | 4 +-- ...package-boundaries-node-resolution.test.ts | 6 ++-- scripts/layering/package-boundaries.test.ts | 31 ++++++++++++++----- .../layering/package-entry-surface.test.ts | 2 +- scripts/layering/root-module-zones.ts | 3 +- 7 files changed, 35 insertions(+), 19 deletions(-) diff --git a/.fallowrc.json b/.fallowrc.json index 979cc3a6d7..6db5023ede 100644 --- a/.fallowrc.json +++ b/.fallowrc.json @@ -9,6 +9,7 @@ // which dependency analysis cannot follow from the exec's path string. "scripts/release-install-hints.ts", "packages/provider-aws-device-farm/test/package-smoke.mjs", + "packages/provider-limrun/test/package-smoke.mjs", "packages/provider-browserstack/test/package-smoke.mjs", "packages/provider-browserstack/tsdown.config.ts", "packages/provider-testmu/test/package-smoke.mjs", @@ -40,6 +41,7 @@ "src/sdk/install-source.ts", "src/sdk/plugins.ts", "src/sdk/plugin-webdriver.ts", + "src/sdk/plugin-device-host.ts", "src/sdk/android-adb.ts", "src/sdk/contracts.ts", "src/sdk/selectors.ts", @@ -113,9 +115,6 @@ // @agent-device/maestro owns the source import, while the published root // build externalizes yaml and retains runtime imports in packed chunks. "yaml", - // @agent-device/provider-limrun owns the source import, while the published - // root build externalizes @limrun/api and retains runtime imports in packed chunks. - "@limrun/api", // @agent-device/browserstack and @agent-device/testmu import agent-device type-only, and their // tsconfigs map those specifiers through this workspace link to core source so typecheck needs // no build; Fallow then credits the source files rather than the package. diff --git a/scripts/check-provider-plugin.mjs b/scripts/check-provider-plugin.mjs index 2868fb0367..22ab3bad6b 100644 --- a/scripts/check-provider-plugin.mjs +++ b/scripts/check-provider-plugin.mjs @@ -81,7 +81,8 @@ try { '.': fixture.primaryExport ?? { import: './dist/agent-device.mjs' }, './agent-device': fixture.primaryExport ?? { import: './dist/agent-device.mjs' }, }); - assert.equal(installed.dependencies, undefined); + // A plugin bundles its workspace code; it declares only what the fixture names as its own. + assert.deepEqual(installed.dependencies, fixture.dependencies); assert.equal(installed.peerDependencies, undefined); await assert.rejects(fs.stat(path.join(project, 'node_modules', 'agent-device')), { code: 'ENOENT', diff --git a/scripts/layering/check.ts b/scripts/layering/check.ts index 44b7f4da25..b2f5f3fa61 100644 --- a/scripts/layering/check.ts +++ b/scripts/layering/check.ts @@ -287,8 +287,8 @@ function checkRecordRuntimeOwnership(sources: ReadonlyMap): Laye * (#3280). An `import()` target never joins the importer's eager closure, so a lazy edge cannot * cost what a value back-edge costs, and the code places lazy seams exactly where a module * defers one ranked above it or one that depends back on it: `cli/process-entry.ts` loads - * `cli.ts`, the MCP tools load the typed client, the daemon's provider registry loads the - * Limrun runtime from `src/sdk/`, and the platform runtime loads its operation host + * `cli.ts`, the MCP tools load the typed client, the provider plugin policy loads the host + * capabilities a plugin's `setup` receives, and the platform runtime loads its operation host * (`loadHost`), which reads daemon session artifacts. Ranking them would reject that pattern * rather than a mistake; what a lazy edge may load is owned by R13's laziness policy and the * eager-closure budgets. diff --git a/scripts/layering/package-boundaries-node-resolution.test.ts b/scripts/layering/package-boundaries-node-resolution.test.ts index 581e52a69b..1b76e775b0 100644 --- a/scripts/layering/package-boundaries-node-resolution.test.ts +++ b/scripts/layering/package-boundaries-node-resolution.test.ts @@ -25,8 +25,8 @@ test('Node resolution enforces the exports map at runtime', () => { '@agent-device/contracts/src/facades/snapshot.ts', '@agent-device/provider-webdriver/runtime', '@agent-device/provider-webdriver/src/runtime.ts', - '@agent-device/provider-limrun/runtime', - '@agent-device/provider-limrun/src/runtime.ts', + '@agent-device/limrun/internal', + '@agent-device/limrun/src/runtime.ts', '@agent-device/xml/internal/parser', '@agent-device/xml/src/index.ts', '@agent-device/ad-script/codec', @@ -70,7 +70,7 @@ test('Node resolution enforces the exports map at runtime', () => { providerWebDriverResolved.endsWith('packages/provider-webdriver/src/plugin.ts'), providerWebDriverResolved, ); - const providerLimrunResolved = import.meta.resolve('@agent-device/provider-limrun'); + const providerLimrunResolved = import.meta.resolve('@agent-device/limrun'); assert.ok( providerLimrunResolved.endsWith('packages/provider-limrun/src/index.ts'), providerLimrunResolved, diff --git a/scripts/layering/package-boundaries.test.ts b/scripts/layering/package-boundaries.test.ts index 380aba66ac..1874b61826 100644 --- a/scripts/layering/package-boundaries.test.ts +++ b/scripts/layering/package-boundaries.test.ts @@ -822,24 +822,37 @@ test('the real tree parses, declares, and passes R11', () => { '@agent-device/kernel', '@agent-device/xml', ]); - const providerLimrunPackage = packages.find( - (pkg) => pkg.name === '@agent-device/provider-limrun', - ); + const providerLimrunPackage = packages.find((pkg) => pkg.name === '@agent-device/limrun'); assert.ok(providerLimrunPackage, 'provider-limrun package must exist'); assert.deepEqual( [...providerLimrunPackage.exportTargets.keys()], - ['@agent-device/provider-limrun', '@agent-device/provider-limrun/internal'], + [ + '@agent-device/limrun', + '@agent-device/limrun/agent-device', + '@agent-device/limrun/runtime', + '@agent-device/limrun/host', + '@agent-device/limrun/package.json', + ], ); assert.deepEqual([...providerLimrunPackage.workspaceDependencies].sort(), [ + '@agent-device/build-config', '@agent-device/capture-kit', '@agent-device/contracts', + '@agent-device/host-kit', '@agent-device/kernel', '@agent-device/platform-android', - '@agent-device/plugins', + '@agent-device/platform-apple', + '@agent-device/test-kit', + '@agent-device/xml', + 'agent-device', ]); const rootExternalDependencies = rootExternalDependencyRanges(repoRoot); for (const pkg of packages) { for (const [name, range] of pkg.externalDependencies) { + // A package that publishes its own artifact installs its own dependencies, so the root + // matches only the ranges it also declares. + if (pkg.workspaceDependencyField === 'devDependencies' && !rootExternalDependencies.has(name)) + continue; assert.equal( rootExternalDependencies.get(name), range, @@ -847,6 +860,10 @@ test('the real tree parses, declares, and passes R11', () => { ); } } + assert.ok( + !rootExternalDependencies.has('@limrun/api'), + 'core must not depend on the Limrun SDK; the Limrun plugin installs it', + ); const xmlPackage = packages.find((pkg) => pkg.name === '@agent-device/xml'); assert.ok(xmlPackage, 'xml package must exist'); assert.deepEqual([...xmlPackage.exportTargets.keys()], ['@agent-device/xml']); @@ -885,8 +902,8 @@ test('the real tree parses, declares, and passes R11', () => { 'root must declare the provider-webdriver workspace dependency', ); assert.ok( - rootWorkspaceDependencyNames(repoRoot).has('@agent-device/provider-limrun'), - 'root must declare the provider-limrun workspace dependency', + rootWorkspaceDependencyNames(repoRoot).has('@agent-device/limrun'), + 'root must declare the Limrun plugin workspace dependency for its own suites', ); assert.ok( rootWorkspaceDependencyNames(repoRoot).has('@agent-device/xml'), diff --git a/scripts/layering/package-entry-surface.test.ts b/scripts/layering/package-entry-surface.test.ts index c0b41a26bc..21d830af9e 100644 --- a/scripts/layering/package-entry-surface.test.ts +++ b/scripts/layering/package-entry-surface.test.ts @@ -25,7 +25,7 @@ function workspace(overrides: Record = {}): Map> = { // construction, which names these same runtime families and keeps the same value-free direction // toward `packages/daemon/src/` (PR 6 of #3276's daemon extraction). 'platform-runtime': [ - 'src/builtin-provider-ids.ts', - 'src/builtin-provider-plugins.ts', 'src/daemon-composition.ts', 'src/platform-runtime-android-mechanics.ts', 'src/platform-runtime-android-observation-host.ts', @@ -65,6 +63,7 @@ export const ROOT_MODULE_ZONES: Readonly> = { 'src/platform-runtime-app-log-output.ts', 'src/platform-runtime-app-log-process.ts', 'src/platform-runtime-apple-application-tools.ts', + 'src/provider-plugin-host-capabilities.ts', 'src/platform-runtime-apple-automation-keep-hot.ts', 'src/platform-runtime-apple-deployment-executor.ts', 'src/platform-runtime-apple-physical-readiness.ts', From 457d9f52ac09941acc0f55f66af23ee079e53af7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Fri, 20 Nov 2026 19:09:31 +0100 Subject: [PATCH 03/26] fix(connection): forget an ended lease without loading the provider plugin `close` and `session` skip connection materialization, so they never load the plugin store. The ended-lease check read the provider's declaration from that store and kept the stored lease of an installed Limrun plugin. `connect` and connection materialization now record the declaration on the stored connection. The ended-lease check reads the recorded value, so it needs no plugin, installed or not. Part of #3311 --- .../remote/src/remote-connection-state.ts | 6 ++ src/__tests__/cli-config-limrun.test.ts | 2 + src/__tests__/cloud-connect-profile.test.ts | 2 + src/cli/commands/connection-runtime.ts | 7 +- src/cli/commands/connection.ts | 18 +++-- .../ended-lease-unprimed-store.test.ts | 80 +++++++++++++++++++ src/cli/connection/ended-lease.ts | 23 +++++- 7 files changed, 127 insertions(+), 11 deletions(-) create mode 100644 src/cli/connection/ended-lease-unprimed-store.test.ts diff --git a/packages/remote/src/remote-connection-state.ts b/packages/remote/src/remote-connection-state.ts index be0875dbf8..00ebf49c09 100644 --- a/packages/remote/src/remote-connection-state.ts +++ b/packages/remote/src/remote-connection-state.ts @@ -48,6 +48,11 @@ export type RemoteConnectionState = { leaseId?: string; leaseBackend?: LeaseBackend; leaseProvider?: string; + /** + * The provider's declaration that an ended lease is forgotten, recorded while its plugin is + * loaded. A command that never loads the plugin store reads this instead of the plugin. + */ + forgetsEndedLease?: boolean; deviceKey?: string; clientId?: string; platform?: CliFlags['platform']; @@ -624,6 +629,7 @@ function isRemoteConnectionState(value: unknown): value is RemoteConnectionState 'deviceKey', 'clientId', ]) && + (record.forgetsEndedLease === undefined || typeof record.forgetsEndedLease === 'boolean') && isOptionalRemoteConnectionDaemonState(record.daemon) && isOptionalRecord(record.leaseDeviceSpec) ); diff --git a/src/__tests__/cli-config-limrun.test.ts b/src/__tests__/cli-config-limrun.test.ts index 0d54d40c19..7da9e509cf 100644 --- a/src/__tests__/cli-config-limrun.test.ts +++ b/src/__tests__/cli-config-limrun.test.ts @@ -54,6 +54,8 @@ test('Limrun apps lists uploaded assets without allocating an instance', async ( assert.equal(result.calls[0]?.flags?.leaseId, undefined); assert.equal(result.calls[0]?.flags?.leaseProvider, 'limrun'); assert.equal(readActiveConnectionState({ stateDir })?.leaseId, undefined); + // A connection stored without the provider's ended-lease policy gains it on the next command. + assert.equal(readActiveConnectionState({ stateDir })?.forgetsEndedLease, true); fs.rmSync(root, { recursive: true, force: true }); }); diff --git a/src/__tests__/cloud-connect-profile.test.ts b/src/__tests__/cloud-connect-profile.test.ts index 775a3e5c83..3e224f4b21 100644 --- a/src/__tests__/cloud-connect-profile.test.ts +++ b/src/__tests__/cloud-connect-profile.test.ts @@ -161,6 +161,8 @@ test('connect limrun generates a local daemon remote profile', async () => { assert.equal(state.runId, 'run-a'); assert.equal(state.leaseBackend, 'android-instance'); assert.equal(state.leaseProvider, 'limrun'); + // Recorded while the plugin is loaded, so a later `close` needs no plugin to forget the lease. + assert.equal(state.forgetsEndedLease, true); assert.equal(state.platform, 'android'); assert.equal(state.daemon?.baseUrl, undefined); assert.match( diff --git a/src/cli/commands/connection-runtime.ts b/src/cli/commands/connection-runtime.ts index 4285f74e2c..dbc01ee0b0 100644 --- a/src/cli/commands/connection-runtime.ts +++ b/src/cli/commands/connection-runtime.ts @@ -20,6 +20,7 @@ import { connectionProviderCapabilities, primeProviderConnection, } from '../connection/provider-policy.ts'; +import { withEndedLeasePolicy } from '../connection/ended-lease.ts'; import { profileToCliFlags } from '../remote-config-flags.ts'; import { acquireConnectionLease, @@ -86,7 +87,7 @@ export async function materializeRemoteConnectionForCommand(options: { } await primeProviderConnection(providerOf(existingState, remoteConfig.profile), host.env); - const state = + const storedState = existingState ?? createRemoteConnectionStateFromFlags( mergedFlags, @@ -94,10 +95,12 @@ export async function materializeRemoteConnectionForCommand(options: { remoteConfig.profile, host.env, ); + // The plugin store is loaded here, so the connection records its provider's ended-lease policy. + const state = withEndedLeasePolicy(storedState, host.env); const nextFlags = { ...mergedFlags, session: state.session }; let nextRuntime = selectCompatibleRuntime(state.runtime, nextFlags.platform) ?? options.runtime; let nextState = state; - let changed = !existingState; + let changed = !existingState || state !== storedState; // Unknown creation evidence permits discard before binding, but only confirmed creation permits // rollback after a later failure. A committed session record takes over either lease. diff --git a/src/cli/commands/connection.ts b/src/cli/commands/connection.ts index a17cc42c66..f51c5ba721 100644 --- a/src/cli/commands/connection.ts +++ b/src/cli/commands/connection.ts @@ -27,6 +27,7 @@ import { unavailableConnectPluginError, type ConnectProvider, } from '../connection/provider-policy.ts'; +import { withEndedLeasePolicy } from '../connection/ended-lease.ts'; import { resolveConnectProviderProfile, verifyResolvedConnectProvider, @@ -97,13 +98,16 @@ export const connectCommand: ClientCommandHandler = async ({ daemon: context.daemon, }); const verification = await verifyResolvedConnectProvider(resolved, host); - const state = buildConnectedState({ - flags: connectFlags, - scope, - connectionMetadata, - context, - remoteConfigPath: resolved.remoteConfigPath, - }); + const state = withEndedLeasePolicy( + buildConnectedState({ + flags: connectFlags, + scope, + connectionMetadata, + context, + remoteConfigPath: resolved.remoteConfigPath, + }), + host.env, + ); writeRemoteConnectionState({ stateDir, state }); const previousLeaseNotice = await cleanupForcedPreviousConnection( client, diff --git a/src/cli/connection/ended-lease-unprimed-store.test.ts b/src/cli/connection/ended-lease-unprimed-store.test.ts new file mode 100644 index 0000000000..612eebd801 --- /dev/null +++ b/src/cli/connection/ended-lease-unprimed-store.test.ts @@ -0,0 +1,80 @@ +import { test } from 'vitest'; +import assert from 'node:assert/strict'; +import fs from 'node:fs'; +import path from 'node:path'; +import { + hashRemoteConfigFile, + readRemoteConnectionState, + writeRemoteConnectionState, +} from '@agent-device/remote/remote-connection-state'; +import { makeTempWorkspace } from '@agent-device/test-kit'; +import { runCliCapture } from '../../__tests__/cli-capture.ts'; + +const LEASE_ID = 'abc123abc123abc1'; + +// No plugin is installed in this file, and `close` and `disconnect` load no plugin store. The +// stored connection is what a `connect limrun` with the plugin installed wrote. +function storedLimrunConnection() { + const { root, home, project } = makeTempWorkspace(); + const stateDir = path.join(root, 'state'); + const remoteConfig = path.join(project, 'limrun.remote.json'); + fs.writeFileSync(remoteConfig, '{}', 'utf8'); + const now = new Date().toISOString(); + writeRemoteConnectionState({ + stateDir, + state: { + version: 1, + session: 'limrun-close', + remoteConfigPath: remoteConfig, + remoteConfigHash: hashRemoteConfigFile(remoteConfig), + tenant: 'limrun', + runId: 'run-close', + leaseId: LEASE_ID, + leaseBackend: 'android-instance', + leaseProvider: 'limrun', + forgetsEndedLease: true, + platform: 'android', + connectedAt: now, + updatedAt: now, + }, + }); + return { root, home, project, stateDir }; +} + +test('close forgets an ended Limrun lease without loading the plugin store', async () => { + const { root, home, project, stateDir } = storedLimrunConnection(); + const result = await runCliCapture( + ['close', '--session', 'limrun-close', '--state-dir', stateDir, '--json'], + { + cwd: project, + env: { HOME: home }, + defaultResponse: { + ok: true, + data: { + session: 'limrun-close', + endedLeases: [{ leaseId: LEASE_ID, outcome: 'released' }], + }, + }, + }, + ); + + assert.equal(result.code, null, result.stdout + result.stderr); + assert.equal(result.calls[0]?.command, 'close'); + const stored = readRemoteConnectionState({ stateDir, session: 'limrun-close' }); + assert.equal(stored?.leaseProvider, 'limrun'); + assert.equal(stored?.leaseId, undefined); + fs.rmSync(root, { recursive: true, force: true }); +}); + +test('disconnect removes a stored Limrun connection after the plugin is uninstalled', async () => { + const { root, home, project, stateDir } = storedLimrunConnection(); + const result = await runCliCapture( + ['disconnect', '--session', 'limrun-close', '--state-dir', stateDir, '--json'], + { cwd: project, env: { HOME: home } }, + ); + + assert.equal(result.code, null, result.stdout + result.stderr); + assert.equal(JSON.parse(result.stdout).data.connected, false); + assert.equal(readRemoteConnectionState({ stateDir, session: 'limrun-close' }), null); + fs.rmSync(root, { recursive: true, force: true }); +}); diff --git a/src/cli/connection/ended-lease.ts b/src/cli/connection/ended-lease.ts index 87455b4f14..0b1e695e33 100644 --- a/src/cli/connection/ended-lease.ts +++ b/src/cli/connection/ended-lease.ts @@ -6,10 +6,25 @@ import { resolveDaemonPaths } from '@agent-device/daemon-contracts/daemon-resolu import { readRemoteConnectionState, writeRemoteConnectionState, + type RemoteConnectionState, } from '@agent-device/remote/remote-connection-state'; import { connectionProviderCapabilities } from './provider-policy.ts'; import { isHostAllocatedLease } from '../commands/connection-lease-transaction.ts'; +/** + * Records on a connection whether its provider forgets an ended lease. Call it where the provider's + * plugin is loaded: `connect` and connection materialization. `close` and `session` load no plugin, + * so they read the recorded value. + */ +export function withEndedLeasePolicy( + state: RemoteConnectionState, + env: NodeJS.ProcessEnv, +): RemoteConnectionState { + const forgetsEndedLease = + connectionProviderCapabilities(state.leaseProvider, env).forgetsEndedConnectionLease === true; + return state.forgetsEndedLease === forgetsEndedLease ? state : { ...state, forgetsEndedLease }; +} + /** * Forgets the stored connection lease once a daemon reply says its request ended that lease, so the next * `open` allocates instead of heartbeating a lease that no longer exists. @@ -29,8 +44,12 @@ export function forgetEndedConnectionLease( const state = readRemoteConnectionState({ stateDir, session: flags.session ?? 'default' }); if (!state?.leaseId || !endedLeaseIds.includes(state.leaseId)) return; if (isHostAllocatedLease(state)) return; - if (!connectionProviderCapabilities(state.leaseProvider, host.env).forgetsEndedConnectionLease) - return; + // The recorded declaration needs no plugin. A connection stored without one reads what this + // process can answer without loading the plugin store. + const forgetsEndedLease = + state.forgetsEndedLease ?? + connectionProviderCapabilities(state.leaseProvider, host.env).forgetsEndedConnectionLease; + if (!forgetsEndedLease) return; writeRemoteConnectionState({ stateDir, state: { ...state, leaseId: undefined, updatedAt: new Date().toISOString() }, From 9debd88e22dbba3e6da37d547db2d5ee50c9ddcd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Fri, 20 Nov 2026 19:26:24 +0100 Subject: [PATCH 04/26] fix(connection): keep a recorded ended-lease policy as the authority A device command after the provider's plugin was uninstalled read the plugin-less default and persisted `false` over a recorded `true`. The policy is now recorded once, from the provider's own declaration, and a provider whose plugin is not loaded records nothing. Part of #3311 --- src/cli/connection/ended-lease.test.ts | 27 +++++++++++++++++++++++++- src/cli/connection/ended-lease.ts | 15 +++++++++----- src/cli/connection/provider-policy.ts | 21 ++++++++++++++------ 3 files changed, 51 insertions(+), 12 deletions(-) diff --git a/src/cli/connection/ended-lease.test.ts b/src/cli/connection/ended-lease.test.ts index 31ded15a14..fc107dc89e 100644 --- a/src/cli/connection/ended-lease.test.ts +++ b/src/cli/connection/ended-lease.test.ts @@ -9,7 +9,7 @@ import { type StoredConnectionSeed, } from '../../__tests__/remote-connection.fixtures.ts'; import { readRemoteConnectionState } from '@agent-device/remote/remote-connection-state'; -import { forgetEndedConnectionLease } from './ended-lease.ts'; +import { forgetEndedConnectionLease, withEndedLeasePolicy } from './ended-lease.ts'; import { primeProviderConnection } from './provider-policy.ts'; vi.mock('@agent-device/plugins/store', async (importOriginal) => @@ -94,3 +94,28 @@ test('an ended host-allocated lease stays stored', async () => { assert.equal(storedLeaseIdAfter(reply, { leaseProvider }), LEASE_ID); } }); + +test('a provider whose plugin is not loaded leaves the recorded ended-lease policy as it is', () => { + const now = new Date().toISOString(); + const recorded = { + version: 1 as const, + session: 'adc-custom', + remoteConfigPath: '/unused/remote.json', + remoteConfigHash: 'hash', + tenant: 'custom', + runId: 'run', + leaseProvider: 'custom-provider', + forgetsEndedLease: true, + connectedAt: now, + updatedAt: now, + }; + // The plugin was uninstalled after `connect`: nothing declares the policy, so nothing rewrites it. + assert.equal(withEndedLeasePolicy(recorded, createTestHostEnvironment().env), recorded); + const unrecorded = { ...recorded, forgetsEndedLease: undefined }; + assert.equal(withEndedLeasePolicy(unrecorded, createTestHostEnvironment().env), unrecorded); + // The daemon's own routing always declares it, and the first record is the authority. + const proxy = withEndedLeasePolicy({ ...unrecorded, leaseProvider: 'proxy' }, {}); + assert.equal(proxy.forgetsEndedLease, true); + const recordedFalse = { ...proxy, forgetsEndedLease: false }; + assert.equal(withEndedLeasePolicy(recordedFalse, {}), recordedFalse); +}); diff --git a/src/cli/connection/ended-lease.ts b/src/cli/connection/ended-lease.ts index 0b1e695e33..d782a9d25f 100644 --- a/src/cli/connection/ended-lease.ts +++ b/src/cli/connection/ended-lease.ts @@ -8,21 +8,26 @@ import { writeRemoteConnectionState, type RemoteConnectionState, } from '@agent-device/remote/remote-connection-state'; -import { connectionProviderCapabilities } from './provider-policy.ts'; +import { + connectionProviderCapabilities, + declaredConnectionCapabilities, +} from './provider-policy.ts'; import { isHostAllocatedLease } from '../commands/connection-lease-transaction.ts'; /** * Records on a connection whether its provider forgets an ended lease. Call it where the provider's * plugin is loaded: `connect` and connection materialization. `close` and `session` load no plugin, - * so they read the recorded value. + * so they read the recorded value. A recorded value is the authority and is not computed again. A + * provider whose plugin is not loaded declares nothing, so nothing is recorded for it. */ export function withEndedLeasePolicy( state: RemoteConnectionState, env: NodeJS.ProcessEnv, ): RemoteConnectionState { - const forgetsEndedLease = - connectionProviderCapabilities(state.leaseProvider, env).forgetsEndedConnectionLease === true; - return state.forgetsEndedLease === forgetsEndedLease ? state : { ...state, forgetsEndedLease }; + if (state.forgetsEndedLease !== undefined) return state; + const declared = declaredConnectionCapabilities(state.leaseProvider, env); + if (!declared) return state; + return { ...state, forgetsEndedLease: declared.forgetsEndedConnectionLease === true }; } /** diff --git a/src/cli/connection/provider-policy.ts b/src/cli/connection/provider-policy.ts index 8fc1970373..295a3256bc 100644 --- a/src/cli/connection/provider-policy.ts +++ b/src/cli/connection/provider-policy.ts @@ -103,15 +103,24 @@ export function unavailableConnectPluginError( ); } +/** + * The capabilities a provider declares: the daemon's own routing for `proxy`, `cloud` and no + * provider, or a loaded plugin's declaration. Undefined when the provider's plugin is not loaded. + */ +export function declaredConnectionCapabilities( + provider: string | undefined, + env: NodeJS.ProcessEnv, +): ConnectionProviderCapabilities | undefined { + if (provider === 'proxy') return remoteDaemonConnection('proxy'); + if (provider === undefined || provider === 'cloud') + return remoteDaemonConnection('remote-provider'); + return pluginConnectionCapabilities(provider, env); +} + /** Installed providers declare their capabilities; the rest is the daemon's own routing. */ export function connectionProviderCapabilities( provider: string | undefined, env: NodeJS.ProcessEnv, ): ConnectionProviderCapabilities { - if (provider === 'proxy') return remoteDaemonConnection('proxy'); - const declared = - provider === undefined || provider === 'cloud' - ? undefined - : pluginConnectionCapabilities(provider, env); - return declared ?? remoteDaemonConnection('remote-provider'); + return declaredConnectionCapabilities(provider, env) ?? remoteDaemonConnection('remote-provider'); } From c5cfe466219e5367f3675f50e86210efdf225f63 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Fri, 20 Nov 2026 19:39:04 +0100 Subject: [PATCH 05/26] fix(connection): read an unrecorded ended-lease policy from the plugin catalog A connection stored before the policy was recorded has no value, and `close` loads no plugin store, so it kept an ended Limrun lease. The plugin catalog now carries a copy of the plugin's declaration. One lookup answers without loading a plugin: the provider's own declaration, then the catalog. A recorded value stays the authority. A test holds the catalog equal to the declarations of the workspace plugins. Part of #3311 --- .../ended-lease-unprimed-store.test.ts | 55 +++++++++++++++++-- src/cli/connection/ended-lease.ts | 9 ++- src/cli/connection/provider-policy.test.ts | 19 +++++++ src/cli/connection/provider-policy.ts | 15 +++++ src/commands/provider-plugin-catalog.ts | 6 ++ 5 files changed, 94 insertions(+), 10 deletions(-) diff --git a/src/cli/connection/ended-lease-unprimed-store.test.ts b/src/cli/connection/ended-lease-unprimed-store.test.ts index 612eebd801..eb824d6998 100644 --- a/src/cli/connection/ended-lease-unprimed-store.test.ts +++ b/src/cli/connection/ended-lease-unprimed-store.test.ts @@ -14,7 +14,12 @@ const LEASE_ID = 'abc123abc123abc1'; // No plugin is installed in this file, and `close` and `disconnect` load no plugin store. The // stored connection is what a `connect limrun` with the plugin installed wrote. -function storedLimrunConnection() { +function storedConnection( + policy: { leaseProvider: string; forgetsEndedLease?: boolean } = { + leaseProvider: 'limrun', + forgetsEndedLease: true, + }, +) { const { root, home, project } = makeTempWorkspace(); const stateDir = path.join(root, 'state'); const remoteConfig = path.join(project, 'limrun.remote.json'); @@ -31,8 +36,7 @@ function storedLimrunConnection() { runId: 'run-close', leaseId: LEASE_ID, leaseBackend: 'android-instance', - leaseProvider: 'limrun', - forgetsEndedLease: true, + ...policy, platform: 'android', connectedAt: now, updatedAt: now, @@ -42,7 +46,7 @@ function storedLimrunConnection() { } test('close forgets an ended Limrun lease without loading the plugin store', async () => { - const { root, home, project, stateDir } = storedLimrunConnection(); + const { root, home, project, stateDir } = storedConnection(); const result = await runCliCapture( ['close', '--session', 'limrun-close', '--state-dir', stateDir, '--json'], { @@ -66,8 +70,49 @@ test('close forgets an ended Limrun lease without loading the plugin store', asy fs.rmSync(root, { recursive: true, force: true }); }); +async function closeWithEndedLease(stateDir: string, project: string, home: string) { + const result = await runCliCapture( + ['close', '--session', 'limrun-close', '--state-dir', stateDir, '--json'], + { + cwd: project, + env: { HOME: home }, + defaultResponse: { + ok: true, + data: { + session: 'limrun-close', + endedLeases: [{ leaseId: LEASE_ID, outcome: 'released' }], + }, + }, + }, + ); + assert.equal(result.code, null, result.stdout + result.stderr); + return readRemoteConnectionState({ stateDir, session: 'limrun-close' }); +} + +test('close forgets an ended Limrun lease on a connection that records no policy', async () => { + // A connection stored before the policy was recorded: the plugin catalog answers for Limrun. + const { root, home, project, stateDir } = storedConnection({ leaseProvider: 'limrun' }); + assert.equal((await closeWithEndedLease(stateDir, project, home))?.leaseId, undefined); + fs.rmSync(root, { recursive: true, force: true }); +}); + +test('close keeps the lease of a provider neither a loaded plugin nor the catalog knows', async () => { + const { root, home, project, stateDir } = storedConnection({ leaseProvider: 'custom-provider' }); + assert.equal((await closeWithEndedLease(stateDir, project, home))?.leaseId, LEASE_ID); + fs.rmSync(root, { recursive: true, force: true }); +}); + +test('a recorded policy wins over the catalog on close', async () => { + const { root, home, project, stateDir } = storedConnection({ + leaseProvider: 'limrun', + forgetsEndedLease: false, + }); + assert.equal((await closeWithEndedLease(stateDir, project, home))?.leaseId, LEASE_ID); + fs.rmSync(root, { recursive: true, force: true }); +}); + test('disconnect removes a stored Limrun connection after the plugin is uninstalled', async () => { - const { root, home, project, stateDir } = storedLimrunConnection(); + const { root, home, project, stateDir } = storedConnection(); const result = await runCliCapture( ['disconnect', '--session', 'limrun-close', '--state-dir', stateDir, '--json'], { cwd: project, env: { HOME: home } }, diff --git a/src/cli/connection/ended-lease.ts b/src/cli/connection/ended-lease.ts index d782a9d25f..c85be20ef6 100644 --- a/src/cli/connection/ended-lease.ts +++ b/src/cli/connection/ended-lease.ts @@ -9,8 +9,8 @@ import { type RemoteConnectionState, } from '@agent-device/remote/remote-connection-state'; import { - connectionProviderCapabilities, declaredConnectionCapabilities, + providerForgetsEndedConnectionLease, } from './provider-policy.ts'; import { isHostAllocatedLease } from '../commands/connection-lease-transaction.ts'; @@ -49,11 +49,10 @@ export function forgetEndedConnectionLease( const state = readRemoteConnectionState({ stateDir, session: flags.session ?? 'default' }); if (!state?.leaseId || !endedLeaseIds.includes(state.leaseId)) return; if (isHostAllocatedLease(state)) return; - // The recorded declaration needs no plugin. A connection stored without one reads what this - // process can answer without loading the plugin store. + // The recorded policy is the authority. A connection stored without one reads what this process + // answers without loading the plugin store. const forgetsEndedLease = - state.forgetsEndedLease ?? - connectionProviderCapabilities(state.leaseProvider, host.env).forgetsEndedConnectionLease; + state.forgetsEndedLease ?? providerForgetsEndedConnectionLease(state.leaseProvider, host.env); if (!forgetsEndedLease) return; writeRemoteConnectionState({ stateDir, diff --git a/src/cli/connection/provider-policy.test.ts b/src/cli/connection/provider-policy.test.ts index 345397d614..02357a0992 100644 --- a/src/cli/connection/provider-policy.test.ts +++ b/src/cli/connection/provider-policy.test.ts @@ -13,6 +13,9 @@ import { } from './provider-policy.ts'; import { pluginHome, selectPlugin, pluginSource } from '@agent-device/test-kit'; import limrun from '@agent-device/limrun'; +import awsDeviceFarm from '@agent-device/aws-device-farm'; +import browserstack from '@agent-device/browserstack'; +import { getProviderPluginDeclaration } from '../../commands/provider-plugin-catalog.ts'; import { declaredConnectionCapabilities } from '../../__tests__/test-utils/plugin-declaration.fixtures.ts'; test('provider policy projects provider identity into semantic capabilities', async () => { @@ -134,3 +137,19 @@ test('a plugin that fails to load supplies no connection name even after priming ['dup', 'duplicate_provider'], ]); }); + +test('the plugin catalog copies the ended-lease declaration of each plugin', () => { + // The catalog answers for a connection that records no policy when no plugin is loaded, so its + // copy must equal what the plugin declares. + for (const [provider, plugin] of [ + ['limrun', limrun()], + ['aws-device-farm', awsDeviceFarm()], + ['browserstack', browserstack()], + ] as const) { + assert.equal( + getProviderPluginDeclaration(provider)?.forgetsEndedConnectionLease === true, + declaredConnectionCapabilities(plugin)?.forgetsEndedConnectionLease === true, + provider, + ); + } +}); diff --git a/src/cli/connection/provider-policy.ts b/src/cli/connection/provider-policy.ts index 295a3256bc..c57bb0697c 100644 --- a/src/cli/connection/provider-policy.ts +++ b/src/cli/connection/provider-policy.ts @@ -117,6 +117,21 @@ export function declaredConnectionCapabilities( return pluginConnectionCapabilities(provider, env); } +/** + * Whether a provider forgets an ended connection lease, answered without loading any plugin: the + * provider's own declaration when this process has it, then the plugin catalog's copy of it. A + * provider that neither knows keeps its lease. + */ +export function providerForgetsEndedConnectionLease( + provider: string | undefined, + env: NodeJS.ProcessEnv, +): boolean { + const declared = declaredConnectionCapabilities(provider, env); + if (declared) return declared.forgetsEndedConnectionLease === true; + if (provider === undefined) return false; + return getProviderPluginDeclaration(provider)?.forgetsEndedConnectionLease === true; +} + /** Installed providers declare their capabilities; the rest is the daemon's own routing. */ export function connectionProviderCapabilities( provider: string | undefined, diff --git a/src/commands/provider-plugin-catalog.ts b/src/commands/provider-plugin-catalog.ts index 50148f2d7c..f43b9c7b06 100644 --- a/src/commands/provider-plugin-catalog.ts +++ b/src/commands/provider-plugin-catalog.ts @@ -10,6 +10,11 @@ type ProviderPluginDeclaration = PluginReleaseDeclaration & Readonly<{ provider: string; label: string; + /** + * The plugin's own `forgetsEndedConnectionLease` declaration, readable without loading the + * plugin. A command that loads no plugin store reads it for a connection that records no policy. + */ + forgetsEndedConnectionLease?: boolean; }>; export const AWS_DEVICE_FARM: ProviderPluginDeclaration = { @@ -31,6 +36,7 @@ export const LIMRUN: ProviderPluginDeclaration = { package: '@agent-device/limrun', label: 'Limrun', nightlyTag: 'nightly-0.22', + forgetsEndedConnectionLease: true, }; const PROVIDER_PLUGIN_CATALOG: readonly ProviderPluginDeclaration[] = [ From 605fba130971e27501efc61dd7a45d3342c88080 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Fri, 20 Nov 2026 20:08:55 +0100 Subject: [PATCH 06/26] fix(connection): answer the ended-lease policy at the point of use Recording the policy on the stored connection made materialization write a named connection and repoint the active-session pointer on an upgraded state directory. The stored field, its writer and the extra state write are removed. The ended-lease check asks the one lookup that needs no plugin: the provider's loaded declaration, then the plugin catalog. A record that still carries the field reads as before. Part of #3311 --- .../remote/src/remote-connection-state.ts | 6 -- src/__tests__/cli-config-limrun.test.ts | 67 ++++++++++++++++++- src/__tests__/cloud-connect-profile.test.ts | 2 - src/cli/commands/connection-runtime.ts | 7 +- src/cli/commands/connection.ts | 18 ++--- .../ended-lease-unprimed-store.test.ts | 35 +++++----- src/cli/connection/ended-lease.test.ts | 27 +------- src/cli/connection/ended-lease.ts | 30 ++------- src/cli/connection/provider-policy.ts | 2 +- 9 files changed, 95 insertions(+), 99 deletions(-) diff --git a/packages/remote/src/remote-connection-state.ts b/packages/remote/src/remote-connection-state.ts index 00ebf49c09..be0875dbf8 100644 --- a/packages/remote/src/remote-connection-state.ts +++ b/packages/remote/src/remote-connection-state.ts @@ -48,11 +48,6 @@ export type RemoteConnectionState = { leaseId?: string; leaseBackend?: LeaseBackend; leaseProvider?: string; - /** - * The provider's declaration that an ended lease is forgotten, recorded while its plugin is - * loaded. A command that never loads the plugin store reads this instead of the plugin. - */ - forgetsEndedLease?: boolean; deviceKey?: string; clientId?: string; platform?: CliFlags['platform']; @@ -629,7 +624,6 @@ function isRemoteConnectionState(value: unknown): value is RemoteConnectionState 'deviceKey', 'clientId', ]) && - (record.forgetsEndedLease === undefined || typeof record.forgetsEndedLease === 'boolean') && isOptionalRemoteConnectionDaemonState(record.daemon) && isOptionalRecord(record.leaseDeviceSpec) ); diff --git a/src/__tests__/cli-config-limrun.test.ts b/src/__tests__/cli-config-limrun.test.ts index 7da9e509cf..cf3e2ccf9d 100644 --- a/src/__tests__/cli-config-limrun.test.ts +++ b/src/__tests__/cli-config-limrun.test.ts @@ -54,8 +54,71 @@ test('Limrun apps lists uploaded assets without allocating an instance', async ( assert.equal(result.calls[0]?.flags?.leaseId, undefined); assert.equal(result.calls[0]?.flags?.leaseProvider, 'limrun'); assert.equal(readActiveConnectionState({ stateDir })?.leaseId, undefined); - // A connection stored without the provider's ended-lease policy gains it on the next command. - assert.equal(readActiveConnectionState({ stateDir })?.forgetsEndedLease, true); + + fs.rmSync(root, { recursive: true, force: true }); +}); + +test('materializing a named Limrun connection leaves the newer active connection active and writes nothing', async () => { + const { root, home, project } = makeTempWorkspace(); + const stateDir = path.join(root, 'state'); + const limrunConfig = path.join(project, 'limrun.remote.json'); + fs.writeFileSync(limrunConfig, '{}', 'utf8'); + const otherConfig = path.join(project, 'other.remote.json'); + fs.writeFileSync(otherConfig, JSON.stringify({ daemonBaseUrl: 'https://daemon.example' })); + const now = new Date().toISOString(); + const base = { version: 1 as const, connectedAt: now, updatedAt: now }; + // A is a pending Limrun connection; B, saved after it, is providerless and holds the pointer. + writeRemoteConnectionState({ + stateDir, + state: { + ...base, + session: 'limrun-a', + remoteConfigPath: limrunConfig, + remoteConfigHash: hashRemoteConfigFile(limrunConfig), + tenant: 'limrun', + runId: 'run-a', + leaseBackend: 'android-instance', + leaseProvider: 'limrun', + platform: 'android', + }, + }); + writeRemoteConnectionState({ + stateDir, + state: { + ...base, + session: 'other-b', + remoteConfigPath: otherConfig, + remoteConfigHash: hashRemoteConfigFile(otherConfig), + tenant: 'team-b', + runId: 'run-b', + }, + }); + const connections = path.join(stateDir, 'remote-connections'); + const snapshot = () => + Object.fromEntries( + fs + .readdirSync(connections, { recursive: true, withFileTypes: true }) + .filter((entry) => entry.isFile()) + .map((entry) => [ + path.relative(connections, path.join(entry.parentPath, entry.name)), + fs.readFileSync(path.join(entry.parentPath, entry.name), 'utf8'), + ]), + ); + const before = snapshot(); + + const result = await runCliCapture( + ['apps', '--session', 'limrun-a', '--state-dir', stateDir, '--json'], + { + cwd: project, + env: { HOME: home }, + defaultResponse: { ok: true, data: { apps: ['Example.apk'] } }, + }, + ); + + assert.equal(result.code, null, result.stdout + result.stderr); + assert.equal(result.calls[0]?.flags?.leaseProvider, 'limrun'); + assert.equal(readActiveConnectionState({ stateDir })?.session, 'other-b'); + assert.deepEqual(snapshot(), before); fs.rmSync(root, { recursive: true, force: true }); }); diff --git a/src/__tests__/cloud-connect-profile.test.ts b/src/__tests__/cloud-connect-profile.test.ts index 3e224f4b21..775a3e5c83 100644 --- a/src/__tests__/cloud-connect-profile.test.ts +++ b/src/__tests__/cloud-connect-profile.test.ts @@ -161,8 +161,6 @@ test('connect limrun generates a local daemon remote profile', async () => { assert.equal(state.runId, 'run-a'); assert.equal(state.leaseBackend, 'android-instance'); assert.equal(state.leaseProvider, 'limrun'); - // Recorded while the plugin is loaded, so a later `close` needs no plugin to forget the lease. - assert.equal(state.forgetsEndedLease, true); assert.equal(state.platform, 'android'); assert.equal(state.daemon?.baseUrl, undefined); assert.match( diff --git a/src/cli/commands/connection-runtime.ts b/src/cli/commands/connection-runtime.ts index dbc01ee0b0..4285f74e2c 100644 --- a/src/cli/commands/connection-runtime.ts +++ b/src/cli/commands/connection-runtime.ts @@ -20,7 +20,6 @@ import { connectionProviderCapabilities, primeProviderConnection, } from '../connection/provider-policy.ts'; -import { withEndedLeasePolicy } from '../connection/ended-lease.ts'; import { profileToCliFlags } from '../remote-config-flags.ts'; import { acquireConnectionLease, @@ -87,7 +86,7 @@ export async function materializeRemoteConnectionForCommand(options: { } await primeProviderConnection(providerOf(existingState, remoteConfig.profile), host.env); - const storedState = + const state = existingState ?? createRemoteConnectionStateFromFlags( mergedFlags, @@ -95,12 +94,10 @@ export async function materializeRemoteConnectionForCommand(options: { remoteConfig.profile, host.env, ); - // The plugin store is loaded here, so the connection records its provider's ended-lease policy. - const state = withEndedLeasePolicy(storedState, host.env); const nextFlags = { ...mergedFlags, session: state.session }; let nextRuntime = selectCompatibleRuntime(state.runtime, nextFlags.platform) ?? options.runtime; let nextState = state; - let changed = !existingState || state !== storedState; + let changed = !existingState; // Unknown creation evidence permits discard before binding, but only confirmed creation permits // rollback after a later failure. A committed session record takes over either lease. diff --git a/src/cli/commands/connection.ts b/src/cli/commands/connection.ts index f51c5ba721..a17cc42c66 100644 --- a/src/cli/commands/connection.ts +++ b/src/cli/commands/connection.ts @@ -27,7 +27,6 @@ import { unavailableConnectPluginError, type ConnectProvider, } from '../connection/provider-policy.ts'; -import { withEndedLeasePolicy } from '../connection/ended-lease.ts'; import { resolveConnectProviderProfile, verifyResolvedConnectProvider, @@ -98,16 +97,13 @@ export const connectCommand: ClientCommandHandler = async ({ daemon: context.daemon, }); const verification = await verifyResolvedConnectProvider(resolved, host); - const state = withEndedLeasePolicy( - buildConnectedState({ - flags: connectFlags, - scope, - connectionMetadata, - context, - remoteConfigPath: resolved.remoteConfigPath, - }), - host.env, - ); + const state = buildConnectedState({ + flags: connectFlags, + scope, + connectionMetadata, + context, + remoteConfigPath: resolved.remoteConfigPath, + }); writeRemoteConnectionState({ stateDir, state }); const previousLeaseNotice = await cleanupForcedPreviousConnection( client, diff --git a/src/cli/connection/ended-lease-unprimed-store.test.ts b/src/cli/connection/ended-lease-unprimed-store.test.ts index eb824d6998..9f148afc62 100644 --- a/src/cli/connection/ended-lease-unprimed-store.test.ts +++ b/src/cli/connection/ended-lease-unprimed-store.test.ts @@ -12,14 +12,8 @@ import { runCliCapture } from '../../__tests__/cli-capture.ts'; const LEASE_ID = 'abc123abc123abc1'; -// No plugin is installed in this file, and `close` and `disconnect` load no plugin store. The -// stored connection is what a `connect limrun` with the plugin installed wrote. -function storedConnection( - policy: { leaseProvider: string; forgetsEndedLease?: boolean } = { - leaseProvider: 'limrun', - forgetsEndedLease: true, - }, -) { +// No plugin is installed in this file, and `close` and `disconnect` load no plugin store. +function storedConnection(leaseProvider = 'limrun') { const { root, home, project } = makeTempWorkspace(); const stateDir = path.join(root, 'state'); const remoteConfig = path.join(project, 'limrun.remote.json'); @@ -36,12 +30,22 @@ function storedConnection( runId: 'run-close', leaseId: LEASE_ID, leaseBackend: 'android-instance', - ...policy, + leaseProvider, platform: 'android', connectedAt: now, updatedAt: now, }, }); + // An earlier build of this branch recorded a policy field on the connection. It is ignored now, + // and a record that still carries it reads as before. + const connections = path.join(stateDir, 'remote-connections'); + for (const name of fs.readdirSync(connections)) { + const file = path.join(connections, name); + if (!fs.statSync(file).isFile()) continue; + const record = JSON.parse(fs.readFileSync(file, 'utf8')); + if (record.leaseProvider === undefined) continue; + fs.writeFileSync(file, JSON.stringify({ ...record, forgetsEndedLease: false })); + } return { root, home, project, stateDir }; } @@ -91,22 +95,13 @@ async function closeWithEndedLease(stateDir: string, project: string, home: stri test('close forgets an ended Limrun lease on a connection that records no policy', async () => { // A connection stored before the policy was recorded: the plugin catalog answers for Limrun. - const { root, home, project, stateDir } = storedConnection({ leaseProvider: 'limrun' }); + const { root, home, project, stateDir } = storedConnection(); assert.equal((await closeWithEndedLease(stateDir, project, home))?.leaseId, undefined); fs.rmSync(root, { recursive: true, force: true }); }); test('close keeps the lease of a provider neither a loaded plugin nor the catalog knows', async () => { - const { root, home, project, stateDir } = storedConnection({ leaseProvider: 'custom-provider' }); - assert.equal((await closeWithEndedLease(stateDir, project, home))?.leaseId, LEASE_ID); - fs.rmSync(root, { recursive: true, force: true }); -}); - -test('a recorded policy wins over the catalog on close', async () => { - const { root, home, project, stateDir } = storedConnection({ - leaseProvider: 'limrun', - forgetsEndedLease: false, - }); + const { root, home, project, stateDir } = storedConnection('custom-provider'); assert.equal((await closeWithEndedLease(stateDir, project, home))?.leaseId, LEASE_ID); fs.rmSync(root, { recursive: true, force: true }); }); diff --git a/src/cli/connection/ended-lease.test.ts b/src/cli/connection/ended-lease.test.ts index fc107dc89e..31ded15a14 100644 --- a/src/cli/connection/ended-lease.test.ts +++ b/src/cli/connection/ended-lease.test.ts @@ -9,7 +9,7 @@ import { type StoredConnectionSeed, } from '../../__tests__/remote-connection.fixtures.ts'; import { readRemoteConnectionState } from '@agent-device/remote/remote-connection-state'; -import { forgetEndedConnectionLease, withEndedLeasePolicy } from './ended-lease.ts'; +import { forgetEndedConnectionLease } from './ended-lease.ts'; import { primeProviderConnection } from './provider-policy.ts'; vi.mock('@agent-device/plugins/store', async (importOriginal) => @@ -94,28 +94,3 @@ test('an ended host-allocated lease stays stored', async () => { assert.equal(storedLeaseIdAfter(reply, { leaseProvider }), LEASE_ID); } }); - -test('a provider whose plugin is not loaded leaves the recorded ended-lease policy as it is', () => { - const now = new Date().toISOString(); - const recorded = { - version: 1 as const, - session: 'adc-custom', - remoteConfigPath: '/unused/remote.json', - remoteConfigHash: 'hash', - tenant: 'custom', - runId: 'run', - leaseProvider: 'custom-provider', - forgetsEndedLease: true, - connectedAt: now, - updatedAt: now, - }; - // The plugin was uninstalled after `connect`: nothing declares the policy, so nothing rewrites it. - assert.equal(withEndedLeasePolicy(recorded, createTestHostEnvironment().env), recorded); - const unrecorded = { ...recorded, forgetsEndedLease: undefined }; - assert.equal(withEndedLeasePolicy(unrecorded, createTestHostEnvironment().env), unrecorded); - // The daemon's own routing always declares it, and the first record is the authority. - const proxy = withEndedLeasePolicy({ ...unrecorded, leaseProvider: 'proxy' }, {}); - assert.equal(proxy.forgetsEndedLease, true); - const recordedFalse = { ...proxy, forgetsEndedLease: false }; - assert.equal(withEndedLeasePolicy(recordedFalse, {}), recordedFalse); -}); diff --git a/src/cli/connection/ended-lease.ts b/src/cli/connection/ended-lease.ts index c85be20ef6..d3a3e3a58b 100644 --- a/src/cli/connection/ended-lease.ts +++ b/src/cli/connection/ended-lease.ts @@ -6,30 +6,10 @@ import { resolveDaemonPaths } from '@agent-device/daemon-contracts/daemon-resolu import { readRemoteConnectionState, writeRemoteConnectionState, - type RemoteConnectionState, } from '@agent-device/remote/remote-connection-state'; -import { - declaredConnectionCapabilities, - providerForgetsEndedConnectionLease, -} from './provider-policy.ts'; +import { providerForgetsEndedConnectionLease } from './provider-policy.ts'; import { isHostAllocatedLease } from '../commands/connection-lease-transaction.ts'; -/** - * Records on a connection whether its provider forgets an ended lease. Call it where the provider's - * plugin is loaded: `connect` and connection materialization. `close` and `session` load no plugin, - * so they read the recorded value. A recorded value is the authority and is not computed again. A - * provider whose plugin is not loaded declares nothing, so nothing is recorded for it. - */ -export function withEndedLeasePolicy( - state: RemoteConnectionState, - env: NodeJS.ProcessEnv, -): RemoteConnectionState { - if (state.forgetsEndedLease !== undefined) return state; - const declared = declaredConnectionCapabilities(state.leaseProvider, env); - if (!declared) return state; - return { ...state, forgetsEndedLease: declared.forgetsEndedConnectionLease === true }; -} - /** * Forgets the stored connection lease once a daemon reply says its request ended that lease, so the next * `open` allocates instead of heartbeating a lease that no longer exists. @@ -49,11 +29,9 @@ export function forgetEndedConnectionLease( const state = readRemoteConnectionState({ stateDir, session: flags.session ?? 'default' }); if (!state?.leaseId || !endedLeaseIds.includes(state.leaseId)) return; if (isHostAllocatedLease(state)) return; - // The recorded policy is the authority. A connection stored without one reads what this process - // answers without loading the plugin store. - const forgetsEndedLease = - state.forgetsEndedLease ?? providerForgetsEndedConnectionLease(state.leaseProvider, host.env); - if (!forgetsEndedLease) return; + // `close` and `session` load no plugin store, so this reads what answers without one: the + // provider's loaded declaration, then the plugin catalog. + if (!providerForgetsEndedConnectionLease(state.leaseProvider, host.env)) return; writeRemoteConnectionState({ stateDir, state: { ...state, leaseId: undefined, updatedAt: new Date().toISOString() }, diff --git a/src/cli/connection/provider-policy.ts b/src/cli/connection/provider-policy.ts index c57bb0697c..5c6d05a5a6 100644 --- a/src/cli/connection/provider-policy.ts +++ b/src/cli/connection/provider-policy.ts @@ -107,7 +107,7 @@ export function unavailableConnectPluginError( * The capabilities a provider declares: the daemon's own routing for `proxy`, `cloud` and no * provider, or a loaded plugin's declaration. Undefined when the provider's plugin is not loaded. */ -export function declaredConnectionCapabilities( +function declaredConnectionCapabilities( provider: string | undefined, env: NodeJS.ProcessEnv, ): ConnectionProviderCapabilities | undefined { From 4b7035bb2a13a47ac3b6093c8da85523979ece9a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Fri, 20 Nov 2026 20:08:55 +0100 Subject: [PATCH 07/26] fix(connect): admit the provider plugin before authentication and before cloud state `connect cloud` saved a Limrun session when the control plane chose Limrun and the plugin was missing. The provider the cloud response names is now admitted after the fetch and before the profile or any state is written. `connect --remote-config` and device commands that materialize a connection started remote authentication before the provider check. The provider is now admitted first, so a missing plugin answers with its install command and no login starts. Cleanup commands admit no provider. Part of #3311 --- .../cloud-connect-profile-fields.test.ts | 16 +- src/cli.ts | 12 ++ src/cli/connection/cloud-profile.ts | 4 + src/cli/connection/provider-admission.test.ts | 201 ++++++++++++++++++ src/cli/connection/provider-admission.ts | 38 ++++ 5 files changed, 267 insertions(+), 4 deletions(-) create mode 100644 src/cli/connection/provider-admission.test.ts create mode 100644 src/cli/connection/provider-admission.ts diff --git a/src/__tests__/cloud-connect-profile-fields.test.ts b/src/__tests__/cloud-connect-profile-fields.test.ts index 6fa6d2c6df..4f3f48ed12 100644 --- a/src/__tests__/cloud-connect-profile-fields.test.ts +++ b/src/__tests__/cloud-connect-profile-fields.test.ts @@ -1,5 +1,8 @@ import { test, vi } from 'vitest'; import assert from 'node:assert/strict'; +import fs from 'node:fs'; +import path from 'node:path'; +import { mkdtempForTestSync } from '@agent-device/test-kit'; import { runCliCapture } from './cli-capture.ts'; vi.mock('@agent-device/plugins/store', async (importOriginal) => @@ -68,6 +71,10 @@ test('connect limrun applies the same refusal when attaching to an existing inst }); test('connect limrun refuses the device type before saving a profile', async () => { + const stateDir = path.join( + mkdtempForTestSync('agent-device-connect-limrun-device-type-'), + 'state', + ); const result = await runCliCapture( [ 'connect', @@ -78,13 +85,14 @@ test('connect limrun refuses the device type before saving a profile', async () 'ios', '--provider-device-type', 'real', + '--state-dir', + stateDir, '--json', ], - { - env: { LIMRUN_API_KEY: 'lim_test_key' }, - stateDirPrefix: 'agent-device-connect-limrun-device-type-', - }, + { env: { LIMRUN_API_KEY: 'lim_test_key' } }, ); + // No generated profile and no connection state exist after the refusal. + assert.equal(fs.existsSync(path.join(stateDir, 'remote-connections')), false); assert.equal(result.code, 1); const payload = JSON.parse(result.stdout); assert.equal(payload.error.code, 'INVALID_ARGS'); diff --git a/src/cli.ts b/src/cli.ts index c5e54c426f..e0cf5e8280 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -344,6 +344,8 @@ type CliRunContext = { daemonPaths: ReturnType; sessionName: string; connectionDefaults: ReturnType; + /** The lease provider an explicit remote config profile names; the flags do not carry it. */ + remoteConfigLeaseProvider: string | undefined; explicitFlagKeys: Set; // Mutated in place by resolveRemoteContext (auth, materialization) so the // failure handler always sees the same state the throwing phase saw. @@ -417,6 +419,7 @@ async function resolveRunContextOrExit( daemonPaths, sessionName, connectionDefaults, + remoteConfigLeaseProvider: parsed.remoteConfigLeaseProvider, explicitFlagKeys, effectiveFlags, resolvedRuntime: connectionDefaults?.runtime, @@ -462,6 +465,15 @@ async function resolveRemoteContext( ctx.parsedBatchSteps = readBatchSteps(ctx.flags); } + // A missing provider plugin answers with its install command before any login or auth state. + if (ctx.command === 'connect' || ctx.effectiveFlags.remoteConfig) { + const { admitConnectionProvider } = await import('./cli/connection/provider-admission.ts'); + await admitConnectionProvider({ + ...ctx, + materializes: shouldMaterializeRemoteConnection(ctx.command), + }); + } + if (shouldResolveRemoteAuth(ctx.command)) { const authResolution = await resolveRemoteAuthForCli({ command: ctx.command, diff --git a/src/cli/connection/cloud-profile.ts b/src/cli/connection/cloud-profile.ts index fe58324e96..9087317da3 100644 --- a/src/cli/connection/cloud-profile.ts +++ b/src/cli/connection/cloud-profile.ts @@ -7,6 +7,7 @@ import { resolveCloudAccessForConnect } from '../auth-session.ts'; import { readCloudJsonResponse } from '../cloud-response.ts'; import { persistAndResolveGeneratedProfile } from './generated-config.ts'; import { buildConnectClientId } from './client-id.ts'; +import { primeProviderConnection } from './provider-policy.ts'; const CONNECTION_PROFILE_PATH = '/api/control-plane/connection-profile'; const HTTP_TIMEOUT_MS = 15_000; @@ -40,6 +41,9 @@ export async function resolveCloudConnectProfile(options: { accessToken: auth.accessToken, fetchImpl: options.fetchImpl, }); + // The control plane chooses the provider. Its plugin is admitted before anything is written, so + // a missing plugin leaves no profile and no connection state behind. + await primeProviderConnection(profile.leaseProvider, options.env); const clientId = buildConnectClientId( options.stateDir, auth.cloudBaseUrl, diff --git a/src/cli/connection/provider-admission.test.ts b/src/cli/connection/provider-admission.test.ts new file mode 100644 index 0000000000..3992ac8af1 --- /dev/null +++ b/src/cli/connection/provider-admission.test.ts @@ -0,0 +1,201 @@ +import { afterEach, test, vi } from 'vitest'; +import assert from 'node:assert/strict'; +import fs from 'node:fs'; +import path from 'node:path'; +import { + hashRemoteConfigFile, + readActiveConnectionState, + readRemoteConnectionState, + writeRemoteConnectionState, +} from '@agent-device/remote/remote-connection-state'; +import { makeTempWorkspace } from '@agent-device/test-kit'; +import { runCliCapture } from '../../__tests__/cli-capture.ts'; +import { resolveCloudAccessForConnect, resolveRemoteAuthForCli } from '../auth-session.ts'; + +// No plugin is installed in this file. Authentication is the seam: a refusal that precedes it never +// calls it, so no login starts and no auth state is written. +vi.mock('../auth-session.ts', async (importOriginal) => ({ + ...(await importOriginal()), + resolveRemoteAuthForCli: vi.fn(async (options: { flags: unknown }) => ({ + flags: options.flags, + source: 'none', + })), + resolveCloudAccessForConnect: vi.fn(), +})); + +afterEach(() => { + vi.clearAllMocks(); + vi.unstubAllGlobals(); +}); + +const CLOUD_DAEMON = 'https://bridge.agent-device.dev/agent-device'; + +/** Every file under `directory` with its content, so a test can assert that nothing was written. */ +function snapshotTree(directory: string): Record { + if (!fs.existsSync(directory)) return {}; + const files: Record = {}; + for (const entry of fs.readdirSync(directory, { recursive: true, withFileTypes: true })) { + if (!entry.isFile()) continue; + const file = path.join(entry.parentPath, entry.name); + files[path.relative(directory, file)] = fs.readFileSync(file, 'utf8'); + } + return files; +} + +function limrunProfile(project: string): string { + const remoteConfig = path.join(project, 'limrun.remote.json'); + fs.writeFileSync( + remoteConfig, + JSON.stringify({ + daemonBaseUrl: CLOUD_DAEMON, + tenant: 'team-a', + runId: 'run-a', + leaseProvider: 'limrun', + leaseBackend: 'android-instance', + platform: 'android', + }), + ); + return remoteConfig; +} + +function assertLimrunPluginMissing(stdout: string): void { + const { error } = JSON.parse(stdout); + assert.equal(error.code, 'UNSUPPORTED_OPERATION'); + assert.equal(error.details.reason, 'plugin-not-installed'); + assert.equal(error.details.package, '@agent-device/limrun'); + assert.match(error.details.installCommand, /agent-device plugins add @agent-device\/limrun/); +} + +test.each([ + { route: 'non-interactive', extra: ['--no-login'] }, + { route: 'interactive', extra: [] }, +])( + 'connect --remote-config with a Limrun profile refuses the missing plugin before $route authentication', + async ({ extra }) => { + const { root, home, project } = makeTempWorkspace(); + const stateDir = path.join(root, 'state'); + const remoteConfig = limrunProfile(project); + + const result = await runCliCapture( + ['connect', '--remote-config', remoteConfig, '--session', 'ci', ...extra, '--json'], + { cwd: project, env: { HOME: home, AGENT_DEVICE_STATE_DIR: stateDir } }, + ); + + assert.equal(result.code, 1); + assertLimrunPluginMissing(result.stdout); + assert.equal(vi.mocked(resolveRemoteAuthForCli).mock.calls.length, 0); + assert.equal(result.calls.length, 0); + assert.deepEqual(snapshotTree(path.join(stateDir, 'remote-connections')), {}); + assert.deepEqual(snapshotTree(path.join(stateDir, 'auth')), {}); + fs.rmSync(root, { recursive: true, force: true }); + }, +); + +function storedLimrunConnection() { + const { root, home, project } = makeTempWorkspace(); + const stateDir = path.join(root, 'state'); + const remoteConfig = limrunProfile(project); + const now = new Date().toISOString(); + writeRemoteConnectionState({ + stateDir, + state: { + version: 1, + session: 'limrun-a', + remoteConfigPath: remoteConfig, + remoteConfigHash: hashRemoteConfigFile(remoteConfig), + daemon: { baseUrl: CLOUD_DAEMON }, + tenant: 'team-a', + runId: 'run-a', + leaseBackend: 'android-instance', + leaseProvider: 'limrun', + platform: 'android', + connectedAt: now, + updatedAt: now, + }, + }); + return { root, home, project, stateDir }; +} + +test('a device command on a stored Limrun connection refuses the missing plugin before authentication', async () => { + const { root, home, project, stateDir } = storedLimrunConnection(); + const before = snapshotTree(stateDir); + + const result = await runCliCapture( + ['apps', '--session', 'limrun-a', '--state-dir', stateDir, '--json'], + { cwd: project, env: { HOME: home } }, + ); + + assert.equal(result.code, 1); + assertLimrunPluginMissing(result.stdout); + assert.equal(vi.mocked(resolveRemoteAuthForCli).mock.calls.length, 0); + assert.equal(result.calls.length, 0); + assert.deepEqual(snapshotTree(stateDir), before); + fs.rmSync(root, { recursive: true, force: true }); +}); + +test('disconnect stays outside provider admission after the plugin is removed', async () => { + const { root, home, project, stateDir } = storedLimrunConnection(); + + const result = await runCliCapture( + ['disconnect', '--session', 'limrun-a', '--state-dir', stateDir, '--json'], + { cwd: project, env: { HOME: home } }, + ); + + assert.equal(result.code, null, result.stdout + result.stderr); + assert.equal(readRemoteConnectionState({ stateDir, session: 'limrun-a' }), null); + fs.rmSync(root, { recursive: true, force: true }); +}); + +test('connect cloud refuses a Limrun profile from the control plane before anything is written', async () => { + const { root, home, project } = makeTempWorkspace(); + const stateDir = path.join(root, 'state'); + // A providerless connection is active before the refused connect. + const activeConfig = path.join(project, 'active.remote.json'); + fs.writeFileSync(activeConfig, JSON.stringify({ daemonBaseUrl: 'https://daemon.example' })); + const now = new Date().toISOString(); + writeRemoteConnectionState({ + stateDir, + state: { + version: 1, + session: 'active-b', + remoteConfigPath: activeConfig, + remoteConfigHash: hashRemoteConfigFile(activeConfig), + tenant: 'team-b', + runId: 'run-b', + connectedAt: now, + updatedAt: now, + }, + }); + const before = snapshotTree(stateDir); + vi.mocked(resolveCloudAccessForConnect).mockResolvedValue({ + accessToken: 'adc_agent_cloud', + cloudBaseUrl: 'https://cloud.example', + }); + vi.stubGlobal( + 'fetch', + vi.fn( + async () => + new Response( + JSON.stringify({ + ok: true, + connection: { + remoteConfigProfile: { tenant: 'acme', runId: 'run-1', leaseProvider: 'limrun' }, + }, + }), + { status: 200, headers: { 'content-type': 'application/json' } }, + ), + ), + ); + + const result = await runCliCapture( + ['connect', 'cloud', '--session', 'cloud-limrun', '--state-dir', stateDir, '--json'], + { cwd: project, env: { HOME: home } }, + ); + + assert.equal(result.code, 1); + assertLimrunPluginMissing(result.stdout); + assert.equal(readRemoteConnectionState({ stateDir, session: 'cloud-limrun' }), null); + assert.equal(readActiveConnectionState({ stateDir })?.session, 'active-b'); + assert.deepEqual(snapshotTree(stateDir), before); + fs.rmSync(root, { recursive: true, force: true }); +}); diff --git a/src/cli/connection/provider-admission.ts b/src/cli/connection/provider-admission.ts new file mode 100644 index 0000000000..df5242b3ea --- /dev/null +++ b/src/cli/connection/provider-admission.ts @@ -0,0 +1,38 @@ +import type { CliFlags } from '@agent-device/contracts/command'; +import type { RemoteConnectionRequestMetadata } from '@agent-device/remote/remote-connection-state'; +import type { HostEnvironment } from '@agent-device/kernel/source-value'; +import { primeProviderConnection } from './provider-policy.ts'; + +type AdmissionContext = Readonly<{ + host: HostEnvironment; + command: string; + positionals: readonly string[]; + flags: CliFlags; + /** The lease provider an explicit remote config profile names. */ + remoteConfigLeaseProvider: string | undefined; + connectionDefaults: { connection?: RemoteConnectionRequestMetadata } | null; + /** Whether the command materializes its remote connection. Cleanup commands do not. */ + materializes: boolean; +}>; + +/** + * Admits the provider `connect` or a materializing command is about to use, before remote + * authentication runs: a missing plugin refuses with its install command, so no login starts and no + * auth state is written. Cleanup commands admit no provider, so they work after a plugin is removed. + */ +export async function admitConnectionProvider(context: AdmissionContext): Promise { + const provider = connectionProviderToAdmit(context); + if (provider !== undefined) await primeProviderConnection(provider, context.host.env); +} + +function connectionProviderToAdmit(context: AdmissionContext): string | undefined { + if (context.command === 'connect') { + // `connect ` names it; `connect --remote-config` reads it from the profile. + return ( + context.remoteConfigLeaseProvider ?? + (context.flags.remoteConfig ? undefined : context.positionals[0]) + ); + } + if (!context.materializes) return undefined; + return context.remoteConfigLeaseProvider ?? context.connectionDefaults?.connection?.leaseProvider; +} From 9dd0535500e4c9334627cc2c40d3865dc691058e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Fri, 20 Nov 2026 21:06:17 +0100 Subject: [PATCH 08/26] fix(auth): keep a new connect login in memory until its provider is admitted `connect` approved a device login and wrote `auth/cli-session.json` before cloud profile discovery named the provider. With Limrun chosen and its plugin missing, the refused route left new auth state behind. A login `connect` approves is now pending in the auth-session owner. The cloud profile route stores it after it admits the discovered provider, and `connect` stores it after its provider profile resolves. This covers `connect cloud`, plain `connect`, and the route where `--daemon-base-url` starts login in the generic auth step. `auth login` stores at once, as before. Part of #3311 --- .../auth-session-connect-admission.test.ts | 139 ++++++++++++++++++ src/cli/auth-session.ts | 28 +++- src/cli/commands/connection.ts | 3 + src/cli/connection/cloud-profile.ts | 4 +- 4 files changed, 172 insertions(+), 2 deletions(-) create mode 100644 src/cli/__tests__/auth-session-connect-admission.test.ts diff --git a/src/cli/__tests__/auth-session-connect-admission.test.ts b/src/cli/__tests__/auth-session-connect-admission.test.ts new file mode 100644 index 0000000000..4902d86606 --- /dev/null +++ b/src/cli/__tests__/auth-session-connect-admission.test.ts @@ -0,0 +1,139 @@ +import { afterEach, beforeEach, test, vi } from 'vitest'; +import assert from 'node:assert/strict'; +import fs from 'node:fs'; +import path from 'node:path'; +import { makeTempWorkspace } from '@agent-device/test-kit'; +import { runCliCapture } from '../../__tests__/cli-capture.ts'; +import { resolveCliSessionPath } from '../auth-session.ts'; + +// No plugin is installed in this file. Each case approves a device login and then lets the control +// plane name the provider, so the login is new when the provider is admitted or refused. +const CLOUD = 'https://cloud.example'; +const terminals = [process.stdin, process.stdout] as const; +const originalTty = terminals.map((stream) => Object.getOwnPropertyDescriptor(stream, 'isTTY')); + +beforeEach(() => { + for (const stream of terminals) { + Object.defineProperty(stream, 'isTTY', { value: true, configurable: true }); + } +}); + +afterEach(() => { + terminals.forEach((stream, index) => { + const descriptor = originalTty[index]; + if (descriptor) Object.defineProperty(stream, 'isTTY', descriptor); + else delete (stream as { isTTY?: boolean }).isTTY; + }); + vi.unstubAllGlobals(); +}); + +/** The control plane: an approved device login, then a connection profile naming `leaseProvider`. */ +function stubControlPlane(leaseProvider: string | undefined): ReturnType { + const json = (body: unknown) => + new Response(JSON.stringify(body), { + status: 200, + headers: { 'content-type': 'application/json' }, + }); + const fetchMock = vi.fn(async (input: RequestInfo | URL) => { + const { pathname } = new URL(String(input)); + if (pathname === '/api/control-plane/device-auth/start') { + return json({ deviceCode: 'device', userCode: 'USER', verificationUri: `${CLOUD}/verify` }); + } + if (pathname === '/api/control-plane/device-auth/poll') { + return json({ + status: 'approved', + accessToken: 'adc_agent_login', + cliSession: { id: 'cli-1', refreshCredential: 'refresh-1' }, + }); + } + if (pathname === '/api/control-plane/connection-profile') { + return json({ + ok: true, + connection: { + remoteConfigProfile: { + daemonBaseUrl: 'https://bridge.example.com/agent-device', + tenant: 'acme', + runId: 'run-1', + ...(leaseProvider ? { leaseProvider } : {}), + }, + }, + }); + } + throw new Error(`unexpected request: ${pathname}`); + }); + vi.stubGlobal('fetch', fetchMock); + return fetchMock; +} + +async function connect(argv: string[]) { + const { root, home, project } = makeTempWorkspace(); + const stateDir = path.join(root, 'state'); + const result = await runCliCapture( + ['connect', ...argv, '--session', 'ci', '--state-dir', stateDir, '--json'], + { + cwd: project, + env: { + HOME: home, + AGENT_DEVICE_CLOUD_BASE_URL: CLOUD, + // A remote shell prints the verification URL and opens no browser. + SSH_TTY: '/dev/ttys001', + CI: '', + GITHUB_ACTIONS: '', + BUILDKITE: '', + }, + }, + ); + return { root, stateDir, result }; +} + +test.each([ + { route: 'connect cloud', argv: ['cloud'] }, + { route: 'plain connect', argv: [] }, + { + route: 'connect --daemon-base-url, where the generic auth step logs in', + argv: ['--daemon-base-url', 'https://bridge.agent-device.dev/api', '--tenant', 'acme'], + }, +])( + '$route writes no auth state when the approved login discovers Limrun without its plugin', + async ({ argv }) => { + const fetchMock = stubControlPlane('limrun'); + const { root, stateDir, result } = await connect(argv); + + assert.equal(result.code, 1, result.stdout + result.stderr); + const { error } = JSON.parse(result.stdout); + assert.equal(error.details.reason, 'plugin-not-installed'); + assert.match(error.details.installCommand, /agent-device plugins add @agent-device\/limrun/); + // The login was approved and the profile was fetched with it, so the refusal came after both. + const paths = fetchMock.mock.calls.map(([input]) => new URL(String(input)).pathname); + assert.deepEqual(paths, [ + '/api/control-plane/device-auth/start', + '/api/control-plane/device-auth/poll', + '/api/control-plane/connection-profile', + ]); + assert.equal(fs.existsSync(resolveCliSessionPath(stateDir)), false); + assert.equal(fs.existsSync(path.join(stateDir, 'auth')), false); + assert.equal(fs.existsSync(path.join(stateDir, 'remote-connections')), false); + fs.rmSync(root, { recursive: true, force: true }); + }, +); + +test('connect cloud stores the approved login once when the provider is admitted', async () => { + stubControlPlane(undefined); + const writes: string[] = []; + const rename = fs.renameSync; + const spy = vi.spyOn(fs, 'renameSync').mockImplementation((from, to) => { + writes.push(String(to)); + rename(from, to); + }); + + const { root, stateDir, result } = await connect(['cloud']); + spy.mockRestore(); + + assert.equal(result.code, null, result.stdout + result.stderr); + const session = JSON.parse(fs.readFileSync(resolveCliSessionPath(stateDir), 'utf8')); + assert.equal(session.id, 'cli-1'); + assert.equal(session.refreshCredential, 'refresh-1'); + assert.equal(session.cloudBaseUrl, CLOUD); + assert.equal(writes.filter((file) => file === resolveCliSessionPath(stateDir)).length, 1); + fs.rmSync(root, { recursive: true, force: true }); +}); diff --git a/src/cli/auth-session.ts b/src/cli/auth-session.ts index 3ba76c43d0..7fa699ccfe 100644 --- a/src/cli/auth-session.ts +++ b/src/cli/auth-session.ts @@ -76,17 +76,35 @@ type AuthIo = { openBrowser?: (url: string) => Promise; }; +/** + * A login `connect` approved and has not stored yet. `connect` discovers its provider after login, + * so the session stays in memory until that provider is admitted: a refused route writes no auth + * state. One CLI process runs one command, so one pending login is enough. + */ +let pendingCliLogin: { stateDir: string; session: CliSessionRecord } | undefined; + +/** Stores the login `connect` approved, once its provider is admitted. Does nothing without one. */ +export function commitPendingCliLogin(): void { + const pending = pendingCliLogin; + if (!pending) return; + pendingCliLogin = undefined; + writeCliSession(pending); +} + export async function resolveRemoteAuthForCli(options: { command: string; flags: CliFlags; stateDir: string; env: EnvMap; }): Promise { + pendingCliLogin = undefined; return await resolveRemoteAuth({ command: options.command, flags: options.flags, stateDir: options.stateDir, allowInteractiveLogin: options.command === 'connect' && !options.flags.noLogin, + // `connect` stores a new login itself, after it admits the provider it discovers. + deferLoginWrite: options.command === 'connect', env: options.env, }); } @@ -96,6 +114,8 @@ export async function resolveRemoteAuth(options: { flags: CliFlags; stateDir: string; allowInteractiveLogin: boolean; + /** Keeps a new login pending for {@link commitPendingCliLogin} instead of storing it. */ + deferLoginWrite?: boolean; env: EnvMap; io?: AuthIo; }): Promise { @@ -136,6 +156,7 @@ export async function resolveRemoteAuth(options: { flags: options.flags, env, io: options.io, + deferSessionWrite: options.deferLoginWrite, }); return { flags: { ...options.flags, daemonAuthToken: login.accessToken }, @@ -188,6 +209,8 @@ export async function resolveCloudAccessForConnect(options: { env, io: options.io, commandLabel: 'agent-device connect', + // The profile this login fetches names the provider; the caller commits after admitting it. + deferSessionWrite: true, }); return { accessToken: login.accessToken, @@ -201,6 +224,8 @@ export async function loginWithDeviceAuth(options: { env: EnvMap; io?: AuthIo; commandLabel?: string; + /** Keeps the session pending for {@link commitPendingCliLogin} instead of storing it. */ + deferSessionWrite?: boolean; }): Promise<{ accessToken: string; expiresAt?: string; @@ -265,7 +290,8 @@ export async function loginWithDeviceAuth(options: { createdAt: nowIso, expiresAt: approved.cliSession?.expiresAt, }; - writeCliSession({ stateDir: options.stateDir, session }); + if (options.deferSessionWrite) pendingCliLogin = { stateDir: options.stateDir, session }; + else writeCliSession({ stateDir: options.stateDir, session }); return { accessToken: approved.accessToken, expiresAt: approved.expiresAt, diff --git a/src/cli/commands/connection.ts b/src/cli/commands/connection.ts index a17cc42c66..8f991e24a6 100644 --- a/src/cli/commands/connection.ts +++ b/src/cli/commands/connection.ts @@ -27,6 +27,7 @@ import { unavailableConnectPluginError, type ConnectProvider, } from '../connection/provider-policy.ts'; +import { commitPendingCliLogin } from '../auth-session.ts'; import { resolveConnectProviderProfile, verifyResolvedConnectProvider, @@ -76,6 +77,8 @@ export const connectCommand: ClientCommandHandler = async ({ cwd: host.cwd, env: host.env, }); + // The provider is admitted. A login the generic auth step approved for this `connect` is stored now. + commitPendingCliLogin(); const { flags: connectFlags, connection: connectionMetadata } = scopeConnectProfile( flags, resolved, diff --git a/src/cli/connection/cloud-profile.ts b/src/cli/connection/cloud-profile.ts index 9087317da3..8f12f218e9 100644 --- a/src/cli/connection/cloud-profile.ts +++ b/src/cli/connection/cloud-profile.ts @@ -3,7 +3,7 @@ import { AppError } from '@agent-device/kernel/errors'; import type { CliFlags } from '@agent-device/contracts/command'; import { CLOUD_LEASE_PROVIDER } from '@agent-device/contracts/lease-scope'; import { type EnvMap } from '@agent-device/kernel/source-value'; -import { resolveCloudAccessForConnect } from '../auth-session.ts'; +import { commitPendingCliLogin, resolveCloudAccessForConnect } from '../auth-session.ts'; import { readCloudJsonResponse } from '../cloud-response.ts'; import { persistAndResolveGeneratedProfile } from './generated-config.ts'; import { buildConnectClientId } from './client-id.ts'; @@ -44,6 +44,8 @@ export async function resolveCloudConnectProfile(options: { // The control plane chooses the provider. Its plugin is admitted before anything is written, so // a missing plugin leaves no profile and no connection state behind. await primeProviderConnection(profile.leaseProvider, options.env); + // A login this command approved is stored only now that its provider is admitted. + commitPendingCliLogin(); const clientId = buildConnectClientId( options.stateDir, auth.cloudBaseUrl, From 29eec20951ca9ca19f02235d91511f37e7b4dcad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Fri, 20 Nov 2026 21:06:17 +0100 Subject: [PATCH 09/26] refactor(connection): read the connection provider from one helper Admission read the remote config profile's provider first and materialization read the stored connection's first. Both now call `connectionLeaseProvider`: the stored connection's provider, then the profile's. The unprimed `close` test no longer rewrites records with a field no released build wrote, and its name states the catalog route. Part of #3311 --- src/cli/commands/connection-runtime.ts | 14 +++++--------- .../ended-lease-unprimed-store.test.ts | 19 +------------------ src/cli/connection/provider-admission.ts | 7 +++++-- src/cli/connection/provider-policy.ts | 11 +++++++++++ 4 files changed, 22 insertions(+), 29 deletions(-) diff --git a/src/cli/commands/connection-runtime.ts b/src/cli/commands/connection-runtime.ts index 4285f74e2c..b6e51cb3cb 100644 --- a/src/cli/commands/connection-runtime.ts +++ b/src/cli/commands/connection-runtime.ts @@ -17,6 +17,7 @@ import type { SessionRuntimeHints } from '@agent-device/kernel/contracts'; import type { CliFlags } from '@agent-device/contracts/command'; import type { AgentDeviceClient } from '@agent-device/command-surface'; import { + connectionLeaseProvider, connectionProviderCapabilities, primeProviderConnection, } from '../connection/provider-policy.ts'; @@ -85,7 +86,10 @@ export async function materializeRemoteConnectionForCommand(options: { ); } - await primeProviderConnection(providerOf(existingState, remoteConfig.profile), host.env); + await primeProviderConnection( + connectionLeaseProvider(existingState, remoteConfig.profile.leaseProvider), + host.env, + ); const state = existingState ?? createRemoteConnectionStateFromFlags( @@ -183,14 +187,6 @@ async function persistMaterializedConnection(options: { await stopMetroCleanup(options.metroCleanupToStop); } -// A stored connection names its provider; before one exists, the remote config profile does. -function providerOf( - existingState: Pick | null | undefined, - profile: Pick, -): string | undefined { - return existingState?.leaseProvider ?? profile.leaseProvider; -} - function createRemoteConnectionStateFromFlags( flags: CliFlags, remoteConfigPath: string, diff --git a/src/cli/connection/ended-lease-unprimed-store.test.ts b/src/cli/connection/ended-lease-unprimed-store.test.ts index 9f148afc62..90e6caf73f 100644 --- a/src/cli/connection/ended-lease-unprimed-store.test.ts +++ b/src/cli/connection/ended-lease-unprimed-store.test.ts @@ -36,20 +36,10 @@ function storedConnection(leaseProvider = 'limrun') { updatedAt: now, }, }); - // An earlier build of this branch recorded a policy field on the connection. It is ignored now, - // and a record that still carries it reads as before. - const connections = path.join(stateDir, 'remote-connections'); - for (const name of fs.readdirSync(connections)) { - const file = path.join(connections, name); - if (!fs.statSync(file).isFile()) continue; - const record = JSON.parse(fs.readFileSync(file, 'utf8')); - if (record.leaseProvider === undefined) continue; - fs.writeFileSync(file, JSON.stringify({ ...record, forgetsEndedLease: false })); - } return { root, home, project, stateDir }; } -test('close forgets an ended Limrun lease without loading the plugin store', async () => { +test('close forgets an ended Limrun lease through the plugin catalog', async () => { const { root, home, project, stateDir } = storedConnection(); const result = await runCliCapture( ['close', '--session', 'limrun-close', '--state-dir', stateDir, '--json'], @@ -93,13 +83,6 @@ async function closeWithEndedLease(stateDir: string, project: string, home: stri return readRemoteConnectionState({ stateDir, session: 'limrun-close' }); } -test('close forgets an ended Limrun lease on a connection that records no policy', async () => { - // A connection stored before the policy was recorded: the plugin catalog answers for Limrun. - const { root, home, project, stateDir } = storedConnection(); - assert.equal((await closeWithEndedLease(stateDir, project, home))?.leaseId, undefined); - fs.rmSync(root, { recursive: true, force: true }); -}); - test('close keeps the lease of a provider neither a loaded plugin nor the catalog knows', async () => { const { root, home, project, stateDir } = storedConnection('custom-provider'); assert.equal((await closeWithEndedLease(stateDir, project, home))?.leaseId, LEASE_ID); diff --git a/src/cli/connection/provider-admission.ts b/src/cli/connection/provider-admission.ts index df5242b3ea..82dea0bfc2 100644 --- a/src/cli/connection/provider-admission.ts +++ b/src/cli/connection/provider-admission.ts @@ -1,7 +1,7 @@ import type { CliFlags } from '@agent-device/contracts/command'; import type { RemoteConnectionRequestMetadata } from '@agent-device/remote/remote-connection-state'; import type { HostEnvironment } from '@agent-device/kernel/source-value'; -import { primeProviderConnection } from './provider-policy.ts'; +import { connectionLeaseProvider, primeProviderConnection } from './provider-policy.ts'; type AdmissionContext = Readonly<{ host: HostEnvironment; @@ -34,5 +34,8 @@ function connectionProviderToAdmit(context: AdmissionContext): string | undefine ); } if (!context.materializes) return undefined; - return context.remoteConfigLeaseProvider ?? context.connectionDefaults?.connection?.leaseProvider; + return connectionLeaseProvider( + context.connectionDefaults?.connection, + context.remoteConfigLeaseProvider, + ); } diff --git a/src/cli/connection/provider-policy.ts b/src/cli/connection/provider-policy.ts index 5c6d05a5a6..17a4a7ad28 100644 --- a/src/cli/connection/provider-policy.ts +++ b/src/cli/connection/provider-policy.ts @@ -32,6 +32,17 @@ function remoteDaemonConnection( }; } +/** + * The provider a command on a remote connection uses: the stored connection's, then the remote + * config profile's. Admission and materialization both read it here, so they agree. + */ +export function connectionLeaseProvider( + stored: { leaseProvider?: string } | null | undefined, + profileLeaseProvider: string | undefined, +): string | undefined { + return stored?.leaseProvider ?? profileLeaseProvider; +} + /** * Loads the plugin store before the first synchronous capability lookup for a provider, because a * plugin declares its capabilities in code, not in its manifest. From a91b0cb92101e7a25cc3c298d739306cc9c16331 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Fri, 20 Nov 2026 21:18:47 +0100 Subject: [PATCH 10/26] fix(auth): store a pending login unless the provider plugin is refused A `connect` that approved a device login and then failed for any reason other than provider admission, such as a failed profile fetch, stored no login, so every retry started device auth again. The login-bearing part of a command now runs in one login scope. A login approved inside it is stored when the command ends, on success or on failure. Only the typed `plugin-not-installed` refusal discards it. The scope is per command invocation, so a pending login cannot reach another command in the same process. The per-site commits are removed. Part of #3311 --- src/cli.ts | 63 ++++++++++--------- .../auth-session-connect-admission.test.ts | 49 ++++++++++++++- src/cli/auth-session.ts | 54 +++++++++------- src/cli/commands/connection.ts | 3 - src/cli/connection/cloud-profile.ts | 4 +- 5 files changed, 112 insertions(+), 61 deletions(-) diff --git a/src/cli.ts b/src/cli.ts index e0cf5e8280..50dad7c72b 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -59,7 +59,7 @@ import { resolveRemoteConnectionDefaults, type RemoteConnectionRequestMetadata, } from '@agent-device/remote/remote-connection-state'; -import { resolveRemoteAuthForCli } from './cli/auth-session.ts'; +import { resolveRemoteAuthForCli, withCommandLogin } from './cli/auth-session.ts'; import type { FlagKey } from '@agent-device/command-registry/flag-types'; import type { CliFlags } from '@agent-device/contracts/command'; import type { SessionRuntimeHints } from '@agent-device/kernel/contracts'; @@ -181,7 +181,7 @@ async function runCliOnHost(argv: string[], deps: CliDeps, host: HostEnvironment debugOutputEnabled, }); registerDaemonAuthDiagnosticValue(ctx.effectiveFlags); - let logTailStopper: (() => void) | null = null; + const logTail: { stop: (() => void) | null } = { stop: null }; try { if (command === 'react-devtools') { await exitAfterFlush(await runReactDevtoolsCli(ctx)); @@ -204,39 +204,42 @@ async function runCliOnHost(argv: string[], deps: CliDeps, host: HostEnvironment stateDir: ctx.daemonPaths.baseDir, flags: ctx.effectiveFlags, }); - await resolveRemoteContext(ctx, transport); - registerDaemonAuthDiagnosticValue(ctx.effectiveFlags); - if (command === 'cdp') { - await exitAfterFlush( - await runAgentCdpCommand(positionals, { + // A login approved in here is stored when the command ends, unless a provider plugin is refused. + await withCommandLogin(async () => { + await resolveRemoteContext(ctx, transport); + registerDaemonAuthDiagnosticValue(ctx.effectiveFlags); + if (command === 'cdp') { + await exitAfterFlush( + await runAgentCdpCommand(positionals, { + flags: ctx.effectiveFlags, + runtime: ctx.resolvedRuntime, + cwd: host.cwd, + env: host.env, + }), + ); + return; + } + logTail.stop = maybeStartDaemonLogTail(ctx); + const replayTestReporterRuntime = await createReplayReporterForTest(ctx); + const commandProgress = createCommandProgressState(); + const client = createAgentDeviceClient(buildClientConfig(ctx), { + host: ctx.host, + devicePin: ctx.devicePin, + transport: createCliDaemonTransport({ + host, + command, flags: ctx.effectiveFlags, - runtime: ctx.resolvedRuntime, - cwd: host.cwd, - env: host.env, + replayTestReporterRuntime, + commandProgress, + transport, }), - ); - return; - } - logTailStopper = maybeStartDaemonLogTail(ctx); - const replayTestReporterRuntime = await createReplayReporterForTest(ctx); - const commandProgress = createCommandProgressState(); - const client = createAgentDeviceClient(buildClientConfig(ctx), { - host: ctx.host, - devicePin: ctx.devicePin, - transport: createCliDaemonTransport({ - host, - command, - flags: ctx.effectiveFlags, - replayTestReporterRuntime, - commandProgress, - transport, - }), + }); + await dispatchCliCommand(ctx, client, replayTestReporterRuntime, commandProgress); }); - await dispatchCliCommand(ctx, client, replayTestReporterRuntime, commandProgress); } catch (error) { - await handleRunCliFailure(error, ctx, logTailStopper); + await handleRunCliFailure(error, ctx, logTail.stop); } finally { - if (logTailStopper) logTailStopper(); + logTail.stop?.(); } }, ); diff --git a/src/cli/__tests__/auth-session-connect-admission.test.ts b/src/cli/__tests__/auth-session-connect-admission.test.ts index 4902d86606..049781f05f 100644 --- a/src/cli/__tests__/auth-session-connect-admission.test.ts +++ b/src/cli/__tests__/auth-session-connect-admission.test.ts @@ -28,7 +28,10 @@ afterEach(() => { }); /** The control plane: an approved device login, then a connection profile naming `leaseProvider`. */ -function stubControlPlane(leaseProvider: string | undefined): ReturnType { +function stubControlPlane( + leaseProvider: string | undefined, + options: { profileStatus?: number } = {}, +): ReturnType { const json = (body: unknown) => new Response(JSON.stringify(body), { status: 200, @@ -47,6 +50,8 @@ function stubControlPlane(leaseProvider: string | undefined): ReturnType file === resolveCliSessionPath(stateDir)).length, 1); fs.rmSync(root, { recursive: true, force: true }); }); + +function assertStoredLogin(stateDir: string): void { + const session = JSON.parse(fs.readFileSync(resolveCliSessionPath(stateDir), 'utf8')); + assert.equal(session.id, 'cli-1'); + assert.equal(session.refreshCredential, 'refresh-1'); +} + +test('connect cloud stores the approved login when the profile fetch fails afterward', async () => { + stubControlPlane(undefined, { profileStatus: 503 }); + const { root, stateDir, result } = await connect(['cloud']); + + assert.equal(result.code, 1, result.stdout + result.stderr); + const { error } = JSON.parse(result.stdout); + assert.equal(error.message, 'Cloud connection profile endpoint rejected the request.'); + assert.notEqual(error.details?.reason, 'plugin-not-installed'); + // The failure is not a provider refusal, so a retry does not start device auth again. + assertStoredLogin(stateDir); + fs.rmSync(root, { recursive: true, force: true }); +}); + +test('connect --remote-config stores the login of the generic auth step when the command fails afterward', async () => { + // The profile names no provider, so admission passes and the generic auth step logs in. The + // profile lacks a tenant, so the command then fails for a reason that is not a provider refusal. + stubControlPlane(undefined); + const workspace = makeTempWorkspace(); + const remoteConfig = path.join(workspace.project, 'remote.json'); + fs.writeFileSync( + remoteConfig, + JSON.stringify({ daemonBaseUrl: 'https://bridge.agent-device.dev/api', runId: 'run-1' }), + ); + const { root, stateDir, result } = await connect(['--remote-config', remoteConfig], workspace); + + assert.equal(result.code, 1, result.stdout + result.stderr); + const { error } = JSON.parse(result.stdout); + assert.notEqual(error.details?.reason, 'plugin-not-installed'); + assertStoredLogin(stateDir); + fs.rmSync(root, { recursive: true, force: true }); +}); diff --git a/src/cli/auth-session.ts b/src/cli/auth-session.ts index 7fa699ccfe..0400c24bb8 100644 --- a/src/cli/auth-session.ts +++ b/src/cli/auth-session.ts @@ -1,3 +1,4 @@ +import { AsyncLocalStorage } from 'node:async_hooks'; import fs from 'node:fs'; import path from 'node:path'; import { publishFileSync } from '@agent-device/host-kit/file'; @@ -76,19 +77,37 @@ type AuthIo = { openBrowser?: (url: string) => Promise; }; +/** One command's login scope: a login approved inside it is pending until the command ends. */ +const commandLoginScope = new AsyncLocalStorage<{ + pending?: { stateDir: string; session: CliSessionRecord }; +}>(); + /** - * A login `connect` approved and has not stored yet. `connect` discovers its provider after login, - * so the session stays in memory until that provider is admitted: a refused route writes no auth - * state. One CLI process runs one command, so one pending login is enough. + * Runs one command with its login pending. A command can approve a device login before it learns + * which provider it uses. The login is stored when the command ends, on success or on failure, + * except when the command ends with the provider-admission refusal `plugin-not-installed`: that + * route writes no auth state. A login approved outside a scope is stored at once. */ -let pendingCliLogin: { stateDir: string; session: CliSessionRecord } | undefined; - -/** Stores the login `connect` approved, once its provider is admitted. Does nothing without one. */ -export function commitPendingCliLogin(): void { - const pending = pendingCliLogin; - if (!pending) return; - pendingCliLogin = undefined; - writeCliSession(pending); +export async function withCommandLogin(run: () => Promise): Promise { + const scope: { pending?: { stateDir: string; session: CliSessionRecord } } = {}; + let refused = false; + try { + return await commandLoginScope.run(scope, run); + } catch (error) { + refused = scope.pending !== undefined && (await isProviderAdmissionRefusal(error)); + throw error; + } finally { + if (scope.pending && !refused) writeCliSession(scope.pending); + } +} + +/** Whether a command failed with the typed refusal for a provider plugin that is not installed. */ +async function isProviderAdmissionRefusal(error: unknown): Promise { + if (!(error instanceof AppError)) return false; + // The reason table loads only for a failed command that holds a pending login. + const { PLUGIN_INSTALLATION_REASONS } = + await import('@agent-device/contracts/plugin-installation'); + return error.details?.reason === PLUGIN_INSTALLATION_REASONS.notInstalled; } export async function resolveRemoteAuthForCli(options: { @@ -97,14 +116,11 @@ export async function resolveRemoteAuthForCli(options: { stateDir: string; env: EnvMap; }): Promise { - pendingCliLogin = undefined; return await resolveRemoteAuth({ command: options.command, flags: options.flags, stateDir: options.stateDir, allowInteractiveLogin: options.command === 'connect' && !options.flags.noLogin, - // `connect` stores a new login itself, after it admits the provider it discovers. - deferLoginWrite: options.command === 'connect', env: options.env, }); } @@ -114,8 +130,6 @@ export async function resolveRemoteAuth(options: { flags: CliFlags; stateDir: string; allowInteractiveLogin: boolean; - /** Keeps a new login pending for {@link commitPendingCliLogin} instead of storing it. */ - deferLoginWrite?: boolean; env: EnvMap; io?: AuthIo; }): Promise { @@ -156,7 +170,6 @@ export async function resolveRemoteAuth(options: { flags: options.flags, env, io: options.io, - deferSessionWrite: options.deferLoginWrite, }); return { flags: { ...options.flags, daemonAuthToken: login.accessToken }, @@ -209,8 +222,6 @@ export async function resolveCloudAccessForConnect(options: { env, io: options.io, commandLabel: 'agent-device connect', - // The profile this login fetches names the provider; the caller commits after admitting it. - deferSessionWrite: true, }); return { accessToken: login.accessToken, @@ -224,8 +235,6 @@ export async function loginWithDeviceAuth(options: { env: EnvMap; io?: AuthIo; commandLabel?: string; - /** Keeps the session pending for {@link commitPendingCliLogin} instead of storing it. */ - deferSessionWrite?: boolean; }): Promise<{ accessToken: string; expiresAt?: string; @@ -290,7 +299,8 @@ export async function loginWithDeviceAuth(options: { createdAt: nowIso, expiresAt: approved.cliSession?.expiresAt, }; - if (options.deferSessionWrite) pendingCliLogin = { stateDir: options.stateDir, session }; + const scope = commandLoginScope.getStore(); + if (scope) scope.pending = { stateDir: options.stateDir, session }; else writeCliSession({ stateDir: options.stateDir, session }); return { accessToken: approved.accessToken, diff --git a/src/cli/commands/connection.ts b/src/cli/commands/connection.ts index 8f991e24a6..a17cc42c66 100644 --- a/src/cli/commands/connection.ts +++ b/src/cli/commands/connection.ts @@ -27,7 +27,6 @@ import { unavailableConnectPluginError, type ConnectProvider, } from '../connection/provider-policy.ts'; -import { commitPendingCliLogin } from '../auth-session.ts'; import { resolveConnectProviderProfile, verifyResolvedConnectProvider, @@ -77,8 +76,6 @@ export const connectCommand: ClientCommandHandler = async ({ cwd: host.cwd, env: host.env, }); - // The provider is admitted. A login the generic auth step approved for this `connect` is stored now. - commitPendingCliLogin(); const { flags: connectFlags, connection: connectionMetadata } = scopeConnectProfile( flags, resolved, diff --git a/src/cli/connection/cloud-profile.ts b/src/cli/connection/cloud-profile.ts index 8f12f218e9..9087317da3 100644 --- a/src/cli/connection/cloud-profile.ts +++ b/src/cli/connection/cloud-profile.ts @@ -3,7 +3,7 @@ import { AppError } from '@agent-device/kernel/errors'; import type { CliFlags } from '@agent-device/contracts/command'; import { CLOUD_LEASE_PROVIDER } from '@agent-device/contracts/lease-scope'; import { type EnvMap } from '@agent-device/kernel/source-value'; -import { commitPendingCliLogin, resolveCloudAccessForConnect } from '../auth-session.ts'; +import { resolveCloudAccessForConnect } from '../auth-session.ts'; import { readCloudJsonResponse } from '../cloud-response.ts'; import { persistAndResolveGeneratedProfile } from './generated-config.ts'; import { buildConnectClientId } from './client-id.ts'; @@ -44,8 +44,6 @@ export async function resolveCloudConnectProfile(options: { // The control plane chooses the provider. Its plugin is admitted before anything is written, so // a missing plugin leaves no profile and no connection state behind. await primeProviderConnection(profile.leaseProvider, options.env); - // A login this command approved is stored only now that its provider is admitted. - commitPendingCliLogin(); const clientId = buildConnectClientId( options.stateDir, auth.cloudBaseUrl, From 175e020916cdd40d489f90fa7de948c07abc3b44 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 21 Nov 2026 15:10:52 +0100 Subject: [PATCH 11/26] fix(connect): hold a login only until its provider is admitted A `connect` saved a login it approved before it knew the provider that login was for, so a run whose Limrun plugin was missing reported success and kept a session it could not use. A pending login now exists only between its approval and the provider admission of that same run: the cloud-discovery route saves it right after the provider check, and a route whose provider is already known saves it in its auth step. No command-wide finalizer defers anything else, so explicit `auth login` saves before it reports success. The plugin store is read through `@agent-device/contracts` reasons, so both `plugin-not-installed` and `plugin-unavailable` discard the pending login and keep the install or store-repair diagnostic. The core ships no Limrun runtime, so Limrun is the only provider the CLI admits itself: it answers from the positional or the `--remote-config` profile before that run resolves a credential-bearing option or registers one for redaction. A named provider the core can supply, such as BrowserStack, keeps the admission of its connect handler, and a discovered profile keeps the cloud adapter that reads it. Part of #3311 --- packages/contracts/src/plugin-installation.ts | 15 ++ src/__tests__/test-utils/cli-json-outputs.ts | 27 +++ src/cli.ts | 92 ++++----- .../__tests__/auth-login-write-timing.test.ts | 178 ++++++++++++++++ src/cli/auth-session.ts | 65 +++--- src/cli/connect-preflight.ts | 40 ++++ .../cloud-profile-store-refusal.test.ts | 194 ++++++++++++++++++ src/cli/connection/cloud-profile.ts | 38 +++- .../connection/connect-provider-adapters.ts | 15 +- .../connect-provider-credential-order.test.ts | 154 ++++++++++++++ .../provider-admission-scoping.test.ts | 168 +++++++++++++++ src/cli/connection/provider-admission.ts | 105 ++++++++-- src/cli/connection/provider-policy.ts | 35 +++- src/cli/pre-command-failure.ts | 48 +++++ 14 files changed, 1063 insertions(+), 111 deletions(-) create mode 100644 src/__tests__/test-utils/cli-json-outputs.ts create mode 100644 src/cli/__tests__/auth-login-write-timing.test.ts create mode 100644 src/cli/connect-preflight.ts create mode 100644 src/cli/connection/cloud-profile-store-refusal.test.ts create mode 100644 src/cli/connection/connect-provider-credential-order.test.ts create mode 100644 src/cli/connection/provider-admission-scoping.test.ts create mode 100644 src/cli/pre-command-failure.ts diff --git a/packages/contracts/src/plugin-installation.ts b/packages/contracts/src/plugin-installation.ts index 1705409d26..c769f6e997 100644 --- a/packages/contracts/src/plugin-installation.ts +++ b/packages/contracts/src/plugin-installation.ts @@ -137,8 +137,23 @@ export const MACOS_PLATFORM_PLUGIN_DECLARATION = Object.freeze({ /** The `error.details.reason` a caller reads when a capability needs a plugin that is not installed. */ export const PLUGIN_INSTALLATION_REASONS = { notInstalled: 'plugin-not-installed', + /** The plugin is selected but cannot supply its provider, so its configuration is repaired. */ + unavailable: 'plugin-unavailable', } as const satisfies Record; +/** + * Whether an error is one of the typed refusals a provider plugin admission answers with. A route + * that failed with either keeps no cloud auth state: the user installs or repairs the plugin first. + */ +export function isProviderPluginRefusal(error: unknown): boolean { + if (!(error instanceof AppError)) return false; + const reason = error.details?.reason; + return ( + reason === PLUGIN_INSTALLATION_REASONS.notInstalled || + reason === PLUGIN_INSTALLATION_REASONS.unavailable + ); +} + /** * The typed outcome for a platform family a composition does not have (ADR 0034). An optional family * reports `plugin-not-installed` with the package that provides it and its installation command, diff --git a/src/__tests__/test-utils/cli-json-outputs.ts b/src/__tests__/test-utils/cli-json-outputs.ts new file mode 100644 index 0000000000..c6c627f3c5 --- /dev/null +++ b/src/__tests__/test-utils/cli-json-outputs.ts @@ -0,0 +1,27 @@ +/** + * The JSON objects one CLI run printed, in order. A run that reports success and then fails prints one + * object each, so a test that reads only the first of them never sees the second. + */ +export function parseJsonOutputs(stdout: string): unknown[] { + const outputs: unknown[] = []; + let lines: string[] = []; + for (const line of stdout.split('\n')) { + lines.push(line); + // `printJson` pretty-prints with two spaces, so a `}` at column 0 closes the top-level object. + if (line === '}') { + outputs.push(JSON.parse(lines.join('\n')) as unknown); + lines = []; + } + } + return outputs; +} + +/** The objects that reported success. */ +export function successfulOutputs(outputs: unknown[]): unknown[] { + return outputs.filter( + (output) => + typeof output === 'object' && + output !== null && + (output as { success?: unknown }).success === true, + ); +} diff --git a/src/cli.ts b/src/cli.ts index 50dad7c72b..abe80ff12b 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -59,7 +59,12 @@ import { resolveRemoteConnectionDefaults, type RemoteConnectionRequestMetadata, } from '@agent-device/remote/remote-connection-state'; -import { resolveRemoteAuthForCli, withCommandLogin } from './cli/auth-session.ts'; +import { resolveRemoteAuthForCli, withDeferredLogin } from './cli/auth-session.ts'; +import { exitBeforeCommand } from './cli/pre-command-failure.ts'; +import { + admitConnectProviderOrExit, + defersLoginUntilProviderAdmission, +} from './cli/connect-preflight.ts'; import type { FlagKey } from '@agent-device/command-registry/flag-types'; import type { CliFlags } from '@agent-device/contracts/command'; import type { SessionRuntimeHints } from '@agent-device/kernel/contracts'; @@ -166,6 +171,9 @@ async function runCliOnHost(argv: string[], deps: CliDeps, host: HostEnvironment debug: debugEnabled, }, async () => { + // A provider this route cannot supply is refused here: before this run resolves an option that + // can carry a credential, and before any credential value is registered for redaction. + await admitConnectProviderOrExit(argv, host, { jsonRequested, debugEnabled }); const { parsed, command, positionals } = await parseCliInputOrExit(argv, { host, version, @@ -204,38 +212,42 @@ async function runCliOnHost(argv: string[], deps: CliDeps, host: HostEnvironment stateDir: ctx.daemonPaths.baseDir, flags: ctx.effectiveFlags, }); - // A login approved in here is stored when the command ends, unless a provider plugin is refused. - await withCommandLogin(async () => { - await resolveRemoteContext(ctx, transport); - registerDaemonAuthDiagnosticValue(ctx.effectiveFlags); - if (command === 'cdp') { - await exitAfterFlush( - await runAgentCdpCommand(positionals, { + // A `connect` that learns its provider from the profile it fetches holds a login it approves + // until that provider is admitted; every other command saves a login as soon as it is approved. + await withDeferredLogin( + { defersLogin: await defersLoginUntilProviderAdmission(ctx) }, + async () => { + await resolveRemoteContext(ctx, transport); + registerDaemonAuthDiagnosticValue(ctx.effectiveFlags); + if (command === 'cdp') { + await exitAfterFlush( + await runAgentCdpCommand(positionals, { + flags: ctx.effectiveFlags, + runtime: ctx.resolvedRuntime, + cwd: host.cwd, + env: host.env, + }), + ); + return; + } + logTail.stop = maybeStartDaemonLogTail(ctx); + const replayTestReporterRuntime = await createReplayReporterForTest(ctx); + const commandProgress = createCommandProgressState(); + const client = createAgentDeviceClient(buildClientConfig(ctx), { + host: ctx.host, + devicePin: ctx.devicePin, + transport: createCliDaemonTransport({ + host, + command, flags: ctx.effectiveFlags, - runtime: ctx.resolvedRuntime, - cwd: host.cwd, - env: host.env, + replayTestReporterRuntime, + commandProgress, + transport, }), - ); - return; - } - logTail.stop = maybeStartDaemonLogTail(ctx); - const replayTestReporterRuntime = await createReplayReporterForTest(ctx); - const commandProgress = createCommandProgressState(); - const client = createAgentDeviceClient(buildClientConfig(ctx), { - host: ctx.host, - devicePin: ctx.devicePin, - transport: createCliDaemonTransport({ - host, - command, - flags: ctx.effectiveFlags, - replayTestReporterRuntime, - commandProgress, - transport, - }), - }); - await dispatchCliCommand(ctx, client, replayTestReporterRuntime, commandProgress); - }); + }); + await dispatchCliCommand(ctx, client, replayTestReporterRuntime, commandProgress); + }, + ); } catch (error) { await handleRunCliFailure(error, ctx, logTail.stop); } finally { @@ -315,23 +327,7 @@ async function exitOnParseFailure( argv: string[], options: { jsonRequested: boolean; debugEnabled: boolean }, ): Promise { - emitDiagnostic({ - level: 'error', - phase: 'cli_parse_failed', - data: { - error: error instanceof Error ? error.message : String(error), - }, - }); - const normalized = normalizeError(error, { - diagnosticId: getDiagnosticsMeta().diagnosticId, - logPath: flushDiagnosticsToSessionFile({ force: true })?.path, - }); - if (options.jsonRequested) { - await printJson({ success: false, error: normalized }); - } else { - await printHumanError(normalized, { debugTier: options.debugEnabled, argv }); - } - return await exitAfterFlush(1); + return await exitBeforeCommand(error, argv, options, 'cli_parse_failed'); } type CliRunContext = { diff --git a/src/cli/__tests__/auth-login-write-timing.test.ts b/src/cli/__tests__/auth-login-write-timing.test.ts new file mode 100644 index 0000000000..169cbeda26 --- /dev/null +++ b/src/cli/__tests__/auth-login-write-timing.test.ts @@ -0,0 +1,178 @@ +import { afterEach, beforeEach, test, vi } from 'vitest'; +import assert from 'node:assert/strict'; +import fs from 'node:fs'; +import path from 'node:path'; +import { makeTempWorkspace } from '@agent-device/test-kit'; +import { runCliCapture } from '../../__tests__/cli-capture.ts'; +import { storeWithLimrunInstalled } from '../../__tests__/test-utils/limrun-plugin-store.ts'; +import { parseJsonOutputs } from '../../__tests__/test-utils/cli-json-outputs.ts'; +import { resolveCliSessionPath } from '../auth-session.ts'; + +// A state root whose CLI session name is a directory cannot receive the login: the publish rename +// fails. Each case approves a device login in a route that must save it before it generates or +// publishes connection state, or reports success, so that failed write is what the command answers +// with — one error result, and no saved connection. +const CLOUD = 'https://cloud.example'; +const CLOUD_DAEMON = 'https://bridge.agent-device.dev/api'; +const terminals = [process.stdin, process.stdout] as const; +const originalTty = terminals.map((stream) => Object.getOwnPropertyDescriptor(stream, 'isTTY')); + +// The route that names a provider admits its plugin before it authenticates, so Limrun is installed. +vi.mock( + '@agent-device/plugins/store', + async (importOriginal) => + await storeWithLimrunInstalled( + importOriginal as () => Promise, + ), +); + +beforeEach(() => { + for (const stream of terminals) { + Object.defineProperty(stream, 'isTTY', { value: true, configurable: true }); + } +}); + +afterEach(() => { + terminals.forEach((stream, index) => { + const descriptor = originalTty[index]; + if (descriptor) Object.defineProperty(stream, 'isTTY', descriptor); + else delete (stream as { isTTY?: boolean }).isTTY; + }); + vi.unstubAllGlobals(); +}); + +/** The control plane: an approved device login, then a providerless connection profile. */ +function stubApprovedDeviceLogin(): void { + const json = (body: unknown) => + new Response(JSON.stringify(body), { + status: 200, + headers: { 'content-type': 'application/json' }, + }); + vi.stubGlobal( + 'fetch', + vi.fn(async (input: RequestInfo | URL) => { + const { pathname } = new URL(String(input)); + if (pathname === '/api/control-plane/device-auth/start') { + return json({ deviceCode: 'device', userCode: 'USER', verificationUri: `${CLOUD}/verify` }); + } + if (pathname === '/api/control-plane/device-auth/poll') { + return json({ + status: 'approved', + accessToken: 'adc_agent_login', + cliSession: { id: 'cli-1', refreshCredential: 'refresh-1' }, + }); + } + if (pathname === '/api/control-plane/connection-profile') { + return json({ + ok: true, + connection: { + remoteConfigProfile: { + daemonBaseUrl: 'https://bridge.example.com/agent-device', + tenant: 'acme', + runId: 'run-1', + }, + }, + }); + } + throw new Error(`unexpected request: ${pathname}`); + }), + ); +} + +/** + * Approves a device login in `argv` where the CLI session name is a directory, and requires the one + * result to be the failed write: the login the run could not save stopped it before it published + * connection state or reported success. + */ +async function expectOneFailureWhenTheLoginCannotBeSaved( + argv: string[], + prepare?: (project: string) => void, +): Promise { + stubApprovedDeviceLogin(); + const workspace = makeTempWorkspace(); + const { root, home, project } = workspace; + const stateDir = path.join(root, 'state'); + fs.mkdirSync(resolveCliSessionPath(stateDir), { recursive: true }); + prepare?.(project); + try { + const result = await runCliCapture([...argv, '--state-dir', stateDir, '--json'], { + cwd: project, + env: { + HOME: home, + AGENT_DEVICE_CLOUD_BASE_URL: CLOUD, + // A remote shell prints the verification URL and opens no browser. + SSH_TTY: '/dev/ttys001', + CI: '', + GITHUB_ACTIONS: '', + BUILDKITE: '', + }, + }); + + assert.equal(result.code, 1, result.stdout + result.stderr); + const outputs = parseJsonOutputs(result.stdout); + assert.equal(outputs.length, 1, result.stdout); + const output = outputs[0] as { success?: unknown; error?: { message?: string } }; + assert.equal(output.success, false, result.stdout); + assert.match(String(output.error?.message), /cli-session\.json/); + assert.equal(fs.existsSync(path.join(stateDir, 'remote-connections')), false); + } finally { + fs.rmSync(root, { recursive: true, force: true }); + } +} + +// Cloud discovery names the provider only after the login, so the login is saved where that provider +// is checked: before the profile is generated. +test.each([ + { route: 'connect cloud', argv: ['connect', 'cloud'] }, + { route: 'plain connect', argv: ['connect'] }, + { + route: 'connect --daemon-base-url, which discovers its profile too', + argv: ['connect', '--daemon-base-url', CLOUD_DAEMON, '--tenant', 'acme'], + }, +])( + '$route stops before it generates a profile when its login cannot be saved', + async ({ argv }) => { + await expectOneFailureWhenTheLoginCannotBeSaved([...argv, '--session', 'ci']); + }, +); + +// These routes already know their provider where they authenticate, so the auth step saves the login +// it approves: before the profile and connection record of the command that follows. +test.each([ + { + route: 'connect --remote-config', + argv: ['connect', '--remote-config', 'remote.json'], + prepare: (project: string) => { + fs.writeFileSync( + path.join(project, 'remote.json'), + JSON.stringify({ + daemonBaseUrl: CLOUD_DAEMON, + tenant: 'acme', + runId: 'run-1', + }), + ); + }, + }, + { + route: 'connect proxy', + argv: ['connect', 'proxy', '--daemon-base-url', 'https://bridge.agent-device.dev/agent-device'], + }, + { + route: 'connect through the proxy endpoint shortcut', + argv: ['connect', '--daemon-base-url', 'https://bridge.agent-device.dev/agent-device'], + }, + { + route: 'connect limrun', + argv: ['connect', 'limrun', '--daemon-base-url', CLOUD_DAEMON, '--provider-app', 'app.apk'], + }, +])( + '$route stops before it saves a connection record when its login cannot be saved', + async ({ argv, prepare }) => { + await expectOneFailureWhenTheLoginCannotBeSaved([...argv, '--session', 'ci'], prepare); + }, +); + +test('auth login answers one error when the approved login cannot be saved', async () => { + // Explicit `auth login` is outside any deferral: it saves before it reports success. + await expectOneFailureWhenTheLoginCannotBeSaved(['auth', 'login']); +}); diff --git a/src/cli/auth-session.ts b/src/cli/auth-session.ts index 0400c24bb8..ad309b84b7 100644 --- a/src/cli/auth-session.ts +++ b/src/cli/auth-session.ts @@ -77,37 +77,54 @@ type AuthIo = { openBrowser?: (url: string) => Promise; }; -/** One command's login scope: a login approved inside it is pending until the command ends. */ -const commandLoginScope = new AsyncLocalStorage<{ - pending?: { stateDir: string; session: CliSessionRecord }; -}>(); +/** + * A login of one `connect` run, held between its approval and the admission of the provider that run + * discovers. + */ +type PendingLogin = { stateDir: string; session: CliSessionRecord }; + +const pendingLoginScope = new AsyncLocalStorage<{ pending?: PendingLogin }>(); /** - * Runs one command with its login pending. A command can approve a device login before it learns - * which provider it uses. The login is stored when the command ends, on success or on failure, - * except when the command ends with the provider-admission refusal `plugin-not-installed`: that - * route writes no auth state. A login approved outside a scope is stored at once. + * Runs one command, holding a login it approves until that run's provider is admitted. Only + * `defersLogin` defers, and the CLI sets it for the one `connect` that learns its provider from the + * cloud control plane, which is the only route that can approve a login before it knows the provider. + * That route saves the pending login with {@link savePendingLoginAtAdmission} once the provider is + * admitted, or drops it with {@link discardPendingLoginAtRefusal} when the provider's plugin is + * refused. A run that ends with its login still pending, because discovery failed before any provider + * was named, saves it, so a failure unrelated to a provider does not cost the login. Every other + * route, including explicit `auth login`, saves a login as soon as it is approved. */ -export async function withCommandLogin(run: () => Promise): Promise { - const scope: { pending?: { stateDir: string; session: CliSessionRecord } } = {}; - let refused = false; +export async function withDeferredLogin( + options: { defersLogin: boolean }, + run: () => Promise, +): Promise { + if (!options.defersLogin) return await run(); + const scope: { pending?: PendingLogin } = {}; try { - return await commandLoginScope.run(scope, run); - } catch (error) { - refused = scope.pending !== undefined && (await isProviderAdmissionRefusal(error)); - throw error; + return await pendingLoginScope.run(scope, run); } finally { - if (scope.pending && !refused) writeCliSession(scope.pending); + // Only a run that ended before it named a provider gets here with a pending login. + if (scope.pending) writeCliSession(scope.pending); } } -/** Whether a command failed with the typed refusal for a provider plugin that is not installed. */ -async function isProviderAdmissionRefusal(error: unknown): Promise { - if (!(error instanceof AppError)) return false; - // The reason table loads only for a failed command that holds a pending login. - const { PLUGIN_INSTALLATION_REASONS } = - await import('@agent-device/contracts/plugin-installation'); - return error.details?.reason === PLUGIN_INSTALLATION_REASONS.notInstalled; +/** + * Saves the login this run holds because its provider was just admitted. A route saves before it + * generates or publishes connection state, so a login it cannot save stops the command there. + */ +export function savePendingLoginAtAdmission(): void { + const scope = pendingLoginScope.getStore(); + const pending = scope?.pending; + if (scope === undefined) return; + scope.pending = undefined; + if (pending) writeCliSession(pending); +} + +/** Drops the login this run holds: its provider plugin was refused, so the route keeps no auth state. */ +export function discardPendingLoginAtRefusal(): void { + const scope = pendingLoginScope.getStore(); + if (scope) scope.pending = undefined; } export async function resolveRemoteAuthForCli(options: { @@ -299,7 +316,7 @@ export async function loginWithDeviceAuth(options: { createdAt: nowIso, expiresAt: approved.cliSession?.expiresAt, }; - const scope = commandLoginScope.getStore(); + const scope = pendingLoginScope.getStore(); if (scope) scope.pending = { stateDir: options.stateDir, session }; else writeCliSession({ stateDir: options.stateDir, session }); return { diff --git a/src/cli/connect-preflight.ts b/src/cli/connect-preflight.ts new file mode 100644 index 0000000000..0cc4e0c6f0 --- /dev/null +++ b/src/cli/connect-preflight.ts @@ -0,0 +1,40 @@ +import type { CliFlags } from '@agent-device/contracts/command'; +import type { HostEnvironment } from '@agent-device/kernel/source-value'; +import { exitBeforeCommand } from './pre-command-failure.ts'; + +type LoginTimingContext = { + command: string; + positionals: readonly string[]; + /** The run's flags, after every source that can carry one was resolved. */ + flags: CliFlags; +}; + +/** + * What the CLI answers about a `connect` before it runs that command: whether the command holds its + * login, and whether the provider it names is already refused. Both are answered from the plugin + * admission owner, which loads only when a `connect` needs it. + */ +const connectAdmission = () => import('./connection/provider-admission.ts'); + +/** Whether this run holds its login until the provider it discovers is admitted. */ +export async function defersLoginUntilProviderAdmission( + context: LoginTimingContext, +): Promise { + if (context.command !== 'connect') return false; + const { defersConnectLogin } = await connectAdmission(); + return defersConnectLogin(context); +} + +/** Refuses a provider `connect` names before this run reads a credential, or goes on to its parse. */ +export async function admitConnectProviderOrExit( + argv: readonly string[], + host: HostEnvironment, + options: { jsonRequested: boolean; debugEnabled: boolean }, +): Promise { + const { admitConnectProviderNamedInArguments } = await connectAdmission(); + try { + await admitConnectProviderNamedInArguments(argv, host); + } catch (error) { + await exitBeforeCommand(error, [...argv], options, 'cli_plugin_refused'); + } +} diff --git a/src/cli/connection/cloud-profile-store-refusal.test.ts b/src/cli/connection/cloud-profile-store-refusal.test.ts new file mode 100644 index 0000000000..68408c6305 --- /dev/null +++ b/src/cli/connection/cloud-profile-store-refusal.test.ts @@ -0,0 +1,194 @@ +import { afterEach, beforeEach, test, vi } from 'vitest'; +import assert from 'node:assert/strict'; +import fs from 'node:fs'; +import path from 'node:path'; +import { makeTempWorkspace } from '@agent-device/test-kit'; +import { runCliCapture } from '../../__tests__/cli-capture.ts'; +import { parseJsonOutputs } from '../../__tests__/test-utils/cli-json-outputs.ts'; +import { resolveCliSessionPath } from '../auth-session.ts'; + +// Limrun answers no case here as an installed plugin. Each case makes the plugin store refuse the +// provider, or select a Limrun package that cannot load, so the control plane's +// `leaseProvider: "limrun"` is refused when the cloud route admits it — after the login was approved. +const CLOUD = 'https://cloud.example'; +const LIMRUN_PACKAGE = '@agent-device/limrun'; +const terminals = [process.stdin, process.stdout] as const; +const originalTty = terminals.map((stream) => Object.getOwnPropertyDescriptor(stream, 'isTTY')); + +beforeEach(() => { + for (const stream of terminals) { + Object.defineProperty(stream, 'isTTY', { value: true, configurable: true }); + } +}); + +afterEach(() => { + terminals.forEach((stream, index) => { + const descriptor = originalTty[index]; + if (descriptor) Object.defineProperty(stream, 'isTTY', descriptor); + else delete (stream as { isTTY?: boolean }).isTTY; + }); + vi.unstubAllGlobals(); +}); + +/** The control plane: an approved device login, then a connection profile naming Limrun. */ +function stubControlPlaneNamingLimrun(): void { + const json = (body: unknown) => + new Response(JSON.stringify(body), { + status: 200, + headers: { 'content-type': 'application/json' }, + }); + vi.stubGlobal( + 'fetch', + vi.fn(async (input: RequestInfo | URL) => { + const { pathname } = new URL(String(input)); + if (pathname === '/api/control-plane/device-auth/start') { + return json({ deviceCode: 'device', userCode: 'USER', verificationUri: `${CLOUD}/verify` }); + } + if (pathname === '/api/control-plane/device-auth/poll') { + return json({ + status: 'approved', + accessToken: 'adc_agent_login', + cliSession: { id: 'cli-1', refreshCredential: 'refresh-1' }, + }); + } + if (pathname === '/api/control-plane/connection-profile') { + return json({ + ok: true, + connection: { + remoteConfigProfile: { + daemonBaseUrl: 'https://bridge.example.com/agent-device', + tenant: 'acme', + runId: 'run-1', + leaseProvider: 'limrun', + }, + }, + }); + } + throw new Error(`unexpected request: ${pathname}`); + }), + ); +} + +/** The user config the plugin store cannot read, which the CLI flag reader ignores. */ +function writeUnreadablePluginStore(pluginHome: string): void { + fs.writeFileSync(path.join(pluginHome, 'config.json'), JSON.stringify({ plugins: [] })); +} + +/** A Limrun selection whose entry throws as the store loads it. */ +function selectUnusableLimrunPackage(pluginHome: string): void { + const installation = '11111111-1111-4111-8111-111111111111'; + const directory = path.join(pluginHome, 'plugins', installation, 'node_modules', LIMRUN_PACKAGE); + fs.mkdirSync(directory, { recursive: true }); + fs.writeFileSync( + path.join(directory, 'package.json'), + JSON.stringify({ + name: LIMRUN_PACKAGE, + version: '2.0.0', + type: 'module', + engines: { node: '>=22.12' }, + 'agent-device': { apiVersion: 3, provider: 'limrun' }, + exports: { './agent-device': { import: './plugin.mjs' } }, + }), + ); + fs.writeFileSync(path.join(directory, 'plugin.mjs'), 'throw new Error("Limrun is not ready.");'); + fs.writeFileSync( + path.join(pluginHome, 'config.json'), + JSON.stringify({ plugins: { [LIMRUN_PACKAGE]: { installation } } }), + ); +} + +const CLOUD_ROUTES = [ + { route: 'connect cloud', argv: ['cloud'] }, + { route: 'plain connect', argv: [] }, + { + route: 'connect --daemon-base-url, where the generic auth step logs in', + argv: ['--daemon-base-url', 'https://bridge.agent-device.dev/api', '--tenant', 'acme'], + }, +]; + +async function connectOnCloudRoute(argv: string[], preparePluginHome: (home: string) => void) { + const { root, home, project } = makeTempWorkspace(); + const pluginHome = path.join(root, 'plugin-home'); + fs.mkdirSync(pluginHome, { recursive: true }); + preparePluginHome(pluginHome); + const stateDir = path.join(root, 'state'); + const result = await runCliCapture( + ['connect', ...argv, '--session', 'ci', '--state-dir', stateDir, '--json'], + { + cwd: project, + env: { + HOME: home, + AGENT_DEVICE_HOME: pluginHome, + AGENT_DEVICE_CLOUD_BASE_URL: CLOUD, + // A remote shell prints the verification URL and opens no browser. + SSH_TTY: '/dev/ttys001', + CI: '', + GITHUB_ACTIONS: '', + BUILDKITE: '', + }, + }, + ); + return { root, stateDir, result }; +} + +/** The one JSON result the run printed, as a provider-plugin refusal. */ +function refusalDetails( + stdout: string, + reason: string, +): { + package?: string; + failedPlugins: Array<{ error?: { message?: string } }>; +} { + const outputs = parseJsonOutputs(stdout); + assert.equal(outputs.length, 1, stdout); + const { error } = outputs[0] as { + error: { code: string; details: Record }; + }; + assert.equal(error.code, 'UNSUPPORTED_OPERATION'); + assert.equal(error.details.reason, reason); + return error.details as unknown as { + package?: string; + failedPlugins: Array<{ error?: { message?: string } }>; + }; +} + +/** The refused route wrote nothing: no CLI session, no `auth` directory, no connection state. */ +function assertKeptNoConnectionOrAuthState(stateDir: string): void { + assert.equal(fs.existsSync(resolveCliSessionPath(stateDir)), false, 'auth/cli-session.json'); + assert.equal(fs.existsSync(path.join(stateDir, 'auth')), false, 'auth directory'); + assert.equal( + fs.existsSync(path.join(stateDir, 'remote-connections')), + false, + 'remote-connections directory', + ); +} + +test.each(CLOUD_ROUTES)( + '$route with an unreadable plugin store discards the login Limrun discovery refused', + async ({ argv }) => { + stubControlPlaneNamingLimrun(); + const { root, stateDir, result } = await connectOnCloudRoute(argv, writeUnreadablePluginStore); + + assert.equal(result.code, 1, result.stdout + result.stderr); + const details = refusalDetails(result.stdout, 'plugin-unavailable'); + // The store's own repair instruction, kept over the generic install guidance. + assert.ok(details.failedPlugins.length > 0, result.stdout); + assert.match(String(details.failedPlugins[0]?.error?.message), /Plugin config/); + assertKeptNoConnectionOrAuthState(stateDir); + fs.rmSync(root, { recursive: true, force: true }); + }, +); + +test.each(CLOUD_ROUTES)( + '$route with a Limrun package that fails to load discards the refused login', + async ({ argv }) => { + stubControlPlaneNamingLimrun(); + const { root, stateDir, result } = await connectOnCloudRoute(argv, selectUnusableLimrunPackage); + + assert.equal(result.code, 1, result.stdout + result.stderr); + const details = refusalDetails(result.stdout, 'plugin-unavailable'); + assert.equal(details.package, LIMRUN_PACKAGE); + assertKeptNoConnectionOrAuthState(stateDir); + fs.rmSync(root, { recursive: true, force: true }); + }, +); diff --git a/src/cli/connection/cloud-profile.ts b/src/cli/connection/cloud-profile.ts index 9087317da3..e6afff2265 100644 --- a/src/cli/connection/cloud-profile.ts +++ b/src/cli/connection/cloud-profile.ts @@ -2,12 +2,17 @@ import type { RemoteConfigProfile } from '@agent-device/remote/remote-config-sch import { AppError } from '@agent-device/kernel/errors'; import type { CliFlags } from '@agent-device/contracts/command'; import { CLOUD_LEASE_PROVIDER } from '@agent-device/contracts/lease-scope'; +import { isProviderPluginRefusal } from '@agent-device/contracts/plugin-installation'; import { type EnvMap } from '@agent-device/kernel/source-value'; -import { resolveCloudAccessForConnect } from '../auth-session.ts'; +import { + discardPendingLoginAtRefusal, + resolveCloudAccessForConnect, + savePendingLoginAtAdmission, +} from '../auth-session.ts'; import { readCloudJsonResponse } from '../cloud-response.ts'; import { persistAndResolveGeneratedProfile } from './generated-config.ts'; import { buildConnectClientId } from './client-id.ts'; -import { primeProviderConnection } from './provider-policy.ts'; +import { primeProviderConnection, requiresOwnProviderAdmission } from './provider-policy.ts'; const CONNECTION_PROFILE_PATH = '/api/control-plane/connection-profile'; const HTTP_TIMEOUT_MS = 15_000; @@ -41,9 +46,10 @@ export async function resolveCloudConnectProfile(options: { accessToken: auth.accessToken, fetchImpl: options.fetchImpl, }); - // The control plane chooses the provider. Its plugin is admitted before anything is written, so - // a missing plugin leaves no profile and no connection state behind. - await primeProviderConnection(profile.leaseProvider, options.env); + // The control plane chose the provider. It is admitted here, before this route generates or writes + // any profile or connection record, so a provider whose plugin is missing or broken leaves nothing + // behind, and so does a login this run approved but cannot save. + await admitDiscoveredProvider(profile.leaseProvider, options.env); const clientId = buildConnectClientId( options.stateDir, auth.cloudBaseUrl, @@ -68,6 +74,28 @@ export async function resolveCloudConnectProfile(options: { }); } +/** + * Checks the provider the connection profile names, right after the control plane answers with it. + * Limrun is checked here: the core ships no Limrun runtime, so only its plugin can supply it, and a + * route that has no working plugin for it writes nothing. Any other provider name keeps the base + * behavior of this route, which saves the profile and verifies it as the cloud service does. A run + * that approved a login saves it at this point, before any profile or connection record is generated, + * so a login it cannot save stops the command there; a run whose Limrun plugin is refused keeps no + * auth state. + */ +async function admitDiscoveredProvider( + provider: string | undefined, + env: NodeJS.ProcessEnv, +): Promise { + try { + if (requiresOwnProviderAdmission(provider)) await primeProviderConnection(provider, env); + } catch (error) { + if (isProviderPluginRefusal(error)) discardPendingLoginAtRefusal(); + throw error; + } + savePendingLoginAtAdmission(); +} + async function fetchConnectionProfile(options: { cloudBaseUrl: string; accessToken: string; diff --git a/src/cli/connection/connect-provider-adapters.ts b/src/cli/connection/connect-provider-adapters.ts index a2ddec61f2..60fc8b5cc1 100644 --- a/src/cli/connection/connect-provider-adapters.ts +++ b/src/cli/connection/connect-provider-adapters.ts @@ -11,6 +11,7 @@ import { profileToCliFlags } from '../remote-config-flags.ts'; import { isConnectProviderName, primeProviderConnection, + usesProxyConnectShortcut, type ConnectProvider, } from './provider-policy.ts'; import { withPluginConnection } from '@agent-device/plugins/load'; @@ -112,7 +113,7 @@ export async function resolveConnectProviderProfile(options: { }; } const provider = - options.provider ?? (shouldUseProxyConnectShortcut(options.flags) ? 'proxy' : 'cloud'); + options.provider ?? (usesProxyConnectShortcut(options.flags) ? 'proxy' : 'cloud'); const context = { flags: options.flags, stateDir: options.stateDir, @@ -193,15 +194,3 @@ export async function verifyResolvedConnectProvider( const connection = await providerConnection(resolved.provider, host); return await connection.verify(context); } - -function shouldUseProxyConnectShortcut(flags: CliFlags): boolean { - if (!flags.daemonBaseUrl || flags.tenant || flags.runId || flags.leaseId || flags.leaseBackend) { - return false; - } - try { - const url = new URL(flags.daemonBaseUrl); - return url.pathname.replace(/\/+$/, '').endsWith('/agent-device'); - } catch { - return false; - } -} diff --git a/src/cli/connection/connect-provider-credential-order.test.ts b/src/cli/connection/connect-provider-credential-order.test.ts new file mode 100644 index 0000000000..caae6c1d32 --- /dev/null +++ b/src/cli/connection/connect-provider-credential-order.test.ts @@ -0,0 +1,154 @@ +import { afterEach, test, vi } from 'vitest'; +import assert from 'node:assert/strict'; +import fs from 'node:fs'; +import path from 'node:path'; +import { makeTempWorkspace } from '@agent-device/test-kit'; +import { runCliCapture } from '../../__tests__/cli-capture.ts'; +import type { CapturedCliRun } from '../../__tests__/cli-capture.ts'; +import { parseJsonOutputs } from '../../__tests__/test-utils/cli-json-outputs.ts'; +import { resolveCliSessionPath } from '../auth-session.ts'; + +// A known Limrun provider is refused before this run resolves the options that can carry a +// credential. Registering a value for redaction is the first thing that happens to a resolved +// credential, so a refused route that registers nothing never read one — and a provider the core +// cannot supply is not worth a credential read. +const CLOUD_DAEMON = 'https://bridge.agent-device.dev/api'; +const TOKEN = 'adc_live_secret_token_1348'; + +vi.mock('@agent-device/host-kit/diagnostics', async (importOriginal) => ({ + ...(await importOriginal()), + registerDiagnosticSensitiveValue: vi.fn(), +})); + +import { registerDiagnosticSensitiveValue } from '@agent-device/host-kit/diagnostics'; + +afterEach(() => { + vi.clearAllMocks(); +}); + +async function connectWithToken( + argv: string[], + options: { + env?: Record; + /** Writes a user config that carries the same token and daemon URL. */ + tokenInUserConfig?: boolean; + /** Writes a remote config profile and appends `--remote-config ` to the command. */ + remoteConfigProfile?: Record; + } = {}, +): Promise<{ result: CapturedCliRun; registered: unknown[]; stateDir: string }> { + const { root, home, project } = makeTempWorkspace(); + const stateDir = path.join(root, 'state'); + const configDir = path.join(home, '.agent-device'); + fs.mkdirSync(configDir, { recursive: true }); + fs.writeFileSync( + path.join(configDir, 'config.json'), + options.tokenInUserConfig + ? JSON.stringify({ daemonAuthToken: TOKEN, daemonBaseUrl: CLOUD_DAEMON }) + : JSON.stringify({}), + ); + let profilePath: string | undefined; + if (options.remoteConfigProfile) { + profilePath = path.join(project, 'remote.json'); + fs.writeFileSync(profilePath, JSON.stringify(options.remoteConfigProfile)); + } + try { + const result = await runCliCapture( + [ + ...argv, + ...(profilePath ? ['--remote-config', profilePath] : []), + '--state-dir', + stateDir, + '--json', + ], + { + cwd: project, + env: { HOME: home, LIMRUN_API_KEY: 'lim_test_key', ...(options.env ?? {}) }, + }, + ); + return { + result, + registered: vi.mocked(registerDiagnosticSensitiveValue).mock.calls.flat(), + stateDir, + }; + } finally { + fs.rmSync(root, { recursive: true, force: true }); + } +} + +/** The one result of a run whose provider plugin the core cannot supply. */ +function assertProviderPluginRefusal(result: CapturedCliRun, provider: string): void { + assert.equal(result.code, 1, result.stdout + result.stderr); + assert.equal(result.calls.length, 0); + const outputs = parseJsonOutputs(result.stdout); + assert.equal(outputs.length, 1, result.stdout); + const { error } = outputs[0] as { error: { code: string; details: Record } }; + assert.equal(error.code, 'UNSUPPORTED_OPERATION'); + assert.equal(error.details.reason, 'plugin-not-installed'); + assert.equal(error.details.provider, provider); +} + +const LIMRUN_COMMAND = ['connect', 'limrun', '--session', 'ci', '--platform', 'android']; + +test.each([ + { + source: 'the environment', + argv: LIMRUN_COMMAND, + options: { env: { AGENT_DEVICE_DAEMON_AUTH_TOKEN: TOKEN } }, + }, + { + source: 'a flag', + argv: [...LIMRUN_COMMAND, '--daemon-base-url', CLOUD_DAEMON, '--daemon-auth-token', TOKEN], + options: {}, + }, + { + source: 'the user config', + argv: LIMRUN_COMMAND, + options: { tokenInUserConfig: true }, + }, +])( + 'connect limrun with a token from $source refuses the plugin without reading it', + async ({ argv, options }) => { + const { result, registered, stateDir } = await connectWithToken(argv, options); + + assertProviderPluginRefusal(result, 'limrun'); + assert.deepEqual(registered, [], 'a refused route must not register a credential value'); + assert.equal(fs.existsSync(resolveCliSessionPath(stateDir)), false); + }, +); + +test('connect --remote-config with a Limrun profile refuses the plugin before reading the token', async () => { + const { result, registered } = await connectWithToken(['connect', '--session', 'ci'], { + env: { AGENT_DEVICE_DAEMON_AUTH_TOKEN: TOKEN }, + remoteConfigProfile: { + daemonBaseUrl: CLOUD_DAEMON, + tenant: 'team-a', + runId: 'run-a', + leaseProvider: 'limrun', + platform: 'android', + }, + }); + + assertProviderPluginRefusal(result, 'limrun'); + assert.deepEqual(registered, [], 'a refused route must not register a credential value'); +}); + +test('connect browserstack resolves and registers this run token before its own admission', async () => { + // The closest negative: a provider this release admits in its connect handler still resolves and + // registers the run's credential, as it did before the Limrun admission. + const { result, registered } = await connectWithToken( + [ + 'connect', + 'browserstack', + '--session', + 'ci', + '--platform', + 'android', + '--daemon-base-url', + CLOUD_DAEMON, + ], + { env: { AGENT_DEVICE_DAEMON_AUTH_TOKEN: TOKEN } }, + ); + + assertProviderPluginRefusal(result, 'browserstack'); + assert.ok(registered.includes(TOKEN), result.stdout); +}); diff --git a/src/cli/connection/provider-admission-scoping.test.ts b/src/cli/connection/provider-admission-scoping.test.ts new file mode 100644 index 0000000000..2712ab9be7 --- /dev/null +++ b/src/cli/connection/provider-admission-scoping.test.ts @@ -0,0 +1,168 @@ +import { afterEach, test, vi } from 'vitest'; +import assert from 'node:assert/strict'; +import fs from 'node:fs'; +import path from 'node:path'; +import { makeTempWorkspace } from '@agent-device/test-kit'; +import { runCliCapture } from '../../__tests__/cli-capture.ts'; +import { parseJsonOutputs } from '../../__tests__/test-utils/cli-json-outputs.ts'; + +// Only Limrun is admitted early: the core ships no Limrun runtime. Every other provider keeps this +// release's starting behavior, where the connect handler admits a named provider after the run has +// authenticated, and the cloud adapter verifies a profile-selected provider instead of the route that +// reads it. These cases hold that line from both sides. +const CLOUD = 'https://cloud.example'; +const CLOUD_DAEMON = 'https://bridge.agent-device.dev/api'; +const CLOUD_TOKEN = 'adc_agent_cloud_1348'; + +afterEach(() => { + vi.unstubAllGlobals(); +}); + +/** The control plane answering a connection profile for the provider the cloud chooses. */ +function stubCloudProfile(provider: string): void { + vi.stubGlobal( + 'fetch', + vi.fn( + async () => + new Response( + JSON.stringify({ + ok: true, + connection: { + remoteConfigProfile: { + daemonBaseUrl: 'https://bridge.example.com/agent-device', + tenant: 'acme', + runId: 'run-1', + leaseProvider: provider, + }, + }, + }), + { status: 200, headers: { 'content-type': 'application/json' } }, + ), + ), + ); +} + +async function connect(argv: string[]): Promise<{ code: number | null; stdout: string }> { + const { root, home, project } = makeTempWorkspace(); + const stateDir = path.join(root, 'state'); + try { + const result = await runCliCapture([...argv, '--state-dir', stateDir, '--json'], { + cwd: project, + env: { HOME: home, AGENT_DEVICE_CLOUD_BASE_URL: CLOUD }, + }); + return { code: result.code, stdout: result.stdout }; + } finally { + fs.rmSync(root, { recursive: true, force: true }); + } +} + +function onlyOutput(stdout: string): { + success?: unknown; + data?: Record; + error?: { code?: string; details?: Record }; +} { + const outputs = parseJsonOutputs(stdout); + assert.equal(outputs.length, 1, stdout); + return outputs[0] as ReturnType; +} + +test('connect browserstack answers the auth requirement before its own provider admission', async () => { + // The named provider is admitted by the connect handler, which runs after the run authenticated: + // a run that cannot authenticate answers with its auth refusal, as it did before this release. + const { code, stdout } = await connect([ + 'connect', + 'browserstack', + '--session', + 'ci', + '--daemon-base-url', + CLOUD_DAEMON, + '--no-login', + ]); + + assert.equal(code, 1, stdout); + const output = onlyOutput(stdout); + assert.equal(output.error?.code, 'UNAUTHORIZED', stdout); + assert.equal(output.error?.details?.installCommand, undefined, stdout); +}); + +test('connect cloud saves a BrowserStack profile the control plane names', async () => { + // The provider of a discovered profile is checked here only when the core cannot supply it. A + // provider the cloud adapter reads is kept: this route saves the profile and verifies it the way it + // did before this release, without loading that provider's plugin. + stubCloudProfile('browserstack'); + const { root, home, project } = makeTempWorkspace(); + const stateDir = path.join(root, 'state'); + try { + const result = await runCliCapture( + ['connect', 'cloud', '--session', 'ci', '--state-dir', stateDir, '--json'], + { + cwd: project, + env: { + HOME: home, + AGENT_DEVICE_CLOUD_BASE_URL: CLOUD, + AGENT_DEVICE_DAEMON_AUTH_TOKEN: CLOUD_TOKEN, + }, + }, + ); + + assert.equal(result.code, null, result.stdout + result.stderr); + const output = onlyOutput(result.stdout); + assert.equal(output.success, true, result.stdout); + assert.equal(output.data?.leaseProvider, 'browserstack'); + const written = JSON.parse( + fs.readFileSync(String(output.data?.remoteConfig), 'utf8'), + ) as Record; + assert.equal(written.leaseProvider, 'browserstack'); + } finally { + fs.rmSync(root, { recursive: true, force: true }); + } +}); + +test('a device command on a stored BrowserStack connection authenticates before its provider is admitted', async () => { + // A stored connection names a provider the core can read through its adapter, so a device command on + // it is not refused for a plugin it never needs: it answers with the daemon's own transport failure. + const { root, home, project } = makeTempWorkspace(); + const stateDir = path.join(root, 'state'); + const remoteConfig = path.join(project, 'browserstack.remote.json'); + const now = new Date().toISOString(); + fs.writeFileSync( + remoteConfig, + JSON.stringify({ + daemonBaseUrl: 'http://127.0.0.1:1', + tenant: 'team-a', + runId: 'run-a', + leaseProvider: 'browserstack', + platform: 'android', + }), + ); + fs.mkdirSync(path.join(stateDir, 'remote-connections'), { recursive: true }); + fs.writeFileSync( + path.join(stateDir, 'remote-connections', 'browserstack-a.json'), + JSON.stringify({ + version: 1, + session: 'browserstack-a', + remoteConfigPath: remoteConfig, + remoteConfigHash: '0'.repeat(64), + daemon: { baseUrl: 'http://127.0.0.1:1' }, + tenant: 'team-a', + runId: 'run-a', + leaseProvider: 'browserstack', + platform: 'android', + connectedAt: now, + updatedAt: now, + }), + ); + + try { + const result = await runCliCapture( + ['apps', '--session', 'browserstack-a', '--state-dir', stateDir, '--no-login', '--json'], + { cwd: project, env: { HOME: home } }, + ); + + const output = onlyOutput(result.stdout); + assert.equal(output.error?.details?.reason, undefined, result.stdout); + assert.equal(output.error?.details?.installCommand, undefined, result.stdout); + } finally { + fs.rmSync(root, { recursive: true, force: true }); + } +}); diff --git a/src/cli/connection/provider-admission.ts b/src/cli/connection/provider-admission.ts index 82dea0bfc2..d307a6e4be 100644 --- a/src/cli/connection/provider-admission.ts +++ b/src/cli/connection/provider-admission.ts @@ -1,12 +1,19 @@ import type { CliFlags } from '@agent-device/contracts/command'; import type { RemoteConnectionRequestMetadata } from '@agent-device/remote/remote-connection-state'; import type { HostEnvironment } from '@agent-device/kernel/source-value'; -import { connectionLeaseProvider, primeProviderConnection } from './provider-policy.ts'; +import { CLOUD_LEASE_PROVIDER } from '@agent-device/contracts/lease-scope'; +import { readRemoteConfigFile } from '@agent-device/remote/remote-config-core'; +import { parseRawArgs } from '../parser/args.ts'; +import { + connectionLeaseProvider, + primeProviderConnection, + requiresOwnProviderAdmission, + usesProxyConnectShortcut, +} from './provider-policy.ts'; type AdmissionContext = Readonly<{ host: HostEnvironment; command: string; - positionals: readonly string[]; flags: CliFlags; /** The lease provider an explicit remote config profile names. */ remoteConfigLeaseProvider: string | undefined; @@ -16,26 +23,86 @@ type AdmissionContext = Readonly<{ }>; /** - * Admits the provider `connect` or a materializing command is about to use, before remote - * authentication runs: a missing plugin refuses with its install command, so no login starts and no - * auth state is written. Cleanup commands admit no provider, so they work after a plugin is removed. + * Admits the provider a materializing command is about to attach to, before that command + * authenticates: a provider whose plugin cannot supply it refuses with its install or repair + * guidance, so no login starts and no auth state is written. Cleanup commands admit no provider, so + * they work after a plugin is removed. `connect` admits its own provider earlier, where it names it. */ export async function admitConnectionProvider(context: AdmissionContext): Promise { - const provider = connectionProviderToAdmit(context); - if (provider !== undefined) await primeProviderConnection(provider, context.host.env); -} - -function connectionProviderToAdmit(context: AdmissionContext): string | undefined { - if (context.command === 'connect') { - // `connect ` names it; `connect --remote-config` reads it from the profile. - return ( - context.remoteConfigLeaseProvider ?? - (context.flags.remoteConfig ? undefined : context.positionals[0]) - ); - } - if (!context.materializes) return undefined; - return connectionLeaseProvider( + if (!context.materializes) return; + const provider = connectionLeaseProvider( context.connectionDefaults?.connection, context.remoteConfigLeaseProvider, ); + if (requiresOwnProviderAdmission(provider)) { + await primeProviderConnection(provider, context.host.env); + } +} + +/** + * Admits the provider `connect` names in its own arguments: its positional, or the provider its + * explicit profile file declares. The CLI calls this before it resolves any option that can carry a + * credential, so a route that cannot supply that provider refuses without reading or registering one. + * The command line and that file are read directly, with no flag, config, or environment defaults. + * An arity violation, such as two positionals, is left to the ordinary parse. + */ +export async function admitConnectProviderNamedInArguments( + argv: readonly string[], + host: HostEnvironment, +): Promise { + const provider = connectProviderNamedInArguments(argv, host); + if (!requiresOwnProviderAdmission(provider)) return; + await primeProviderConnection(provider, host.env); +} + +/** + * Whether `connect` holds a login it approves until the provider it discovers is admitted. + * + * Only the route that reads its profile from the cloud control plane learns its provider after it + * authenticates, and so is the one that can approve a login that provider then refuses. A `connect` + * that names a provider, or passes an explicit profile, admits that provider before it authenticates, + * so neither can hold a refused login. + */ +export function defersConnectLogin(context: { + command: string; + flags: CliFlags; + positionals: readonly string[]; +}): boolean { + if (context.command !== 'connect') return false; + const namedProvider = context.positionals[0]; + if (namedProvider !== undefined) return namedProvider === CLOUD_LEASE_PROVIDER; + if (context.flags.remoteConfig !== undefined) return false; + // A daemon whose URL is its own proxy endpoint is connected directly, without a profile. + return !usesProxyConnectShortcut(context.flags); +} + +function connectProviderNamedInArguments( + argv: readonly string[], + host: HostEnvironment, +): string | undefined { + let parsed: ReturnType; + try { + parsed = parseRawArgs([...argv]); + } catch { + // A command line the parser refuses is answered by the ordinary parse, with its own diagnostic. + return undefined; + } + if (parsed.command !== 'connect') return undefined; + // Help and version answer from the command line alone and load no plugin. + if (parsed.flags.help || parsed.flags.version) return undefined; + const profilePath = parsed.flags.remoteConfig; + if (typeof profilePath === 'string') return providerOfProfileFile(profilePath, host); + return parsed.positionals[0]; +} + +/** The provider an explicit profile file declares, or undefined when it cannot be read yet. */ +function providerOfProfileFile(configPath: string, host: HostEnvironment): string | undefined { + try { + // `readRemoteConfigFile`, not the env-merged resolver: only what the file itself declares is read. + const { profile } = readRemoteConfigFile({ configPath, cwd: host.cwd, env: host.env }); + return profile.leaseProvider; + } catch { + // An unreadable profile is answered by the ordinary read of it, which names the file. + return undefined; + } } diff --git a/src/cli/connection/provider-policy.ts b/src/cli/connection/provider-policy.ts index 17a4a7ad28..78019c21bf 100644 --- a/src/cli/connection/provider-policy.ts +++ b/src/cli/connection/provider-policy.ts @@ -1,4 +1,5 @@ import type { ConnectionProviderCapabilities } from '@agent-device/contracts/remote'; +import type { CliFlags } from '@agent-device/contracts/command'; import { pluginConnectionInventory, pluginConnectionCapabilities, @@ -6,12 +7,16 @@ import { pluginConnectionNames, primePluginConnections, } from '@agent-device/plugins/connection'; -import { pluginInstallationHint } from '@agent-device/contracts/plugin-installation'; +import { + PLUGIN_INSTALLATION_REASONS, + pluginInstallationHint, +} from '@agent-device/contracts/plugin-installation'; import { readVersion } from '@agent-device/host-kit/version'; import { AppError } from '@agent-device/kernel/errors'; import { getProviderPluginDeclaration, providerPluginRepairCommand, + LIMRUN, } from '../../commands/provider-plugin-catalog.ts'; import { ROUTING_PROVIDER_IDENTITIES } from '@agent-device/plugins/contract'; @@ -80,6 +85,32 @@ export function connectProviderNamesForError(env: NodeJS.ProcessEnv = process.en : `${names}. Plugins that failed to load: ${failures.join('; ')}`; } +/** + * The `connect` shortcut that connects straight to a named proxy daemon through its own proxy + * endpoint, instead of reading a connection profile from the cloud control plane. + */ +export function usesProxyConnectShortcut(flags: CliFlags): boolean { + if (!flags.daemonBaseUrl || flags.tenant || flags.runId || flags.leaseId || flags.leaseBackend) { + return false; + } + try { + const url = new URL(flags.daemonBaseUrl); + return url.pathname.replace(/\/+$/, '').endsWith('/agent-device'); + } catch { + return false; + } +} + +/** + * Whether a route admits `provider` itself before it authenticates or writes anything. The core ships + * no Limrun runtime, so only the plugin supplies that provider, and a route that selects it refuses + * it early. Every other provider name keeps this release's starting behavior: the connect handler + * admits a named provider, and the adapter that reads a profile verifies the provider it names. + */ +export function requiresOwnProviderAdmission(provider: string | undefined): boolean { + return provider === LIMRUN.provider; +} + export function unavailableConnectPluginError( provider: string, env: NodeJS.ProcessEnv, @@ -95,7 +126,7 @@ export function unavailableConnectPluginError( ); if (selected || failures.length > 0) { return new AppError('UNSUPPORTED_OPERATION', `${declaration.label} plugin is unavailable.`, { - reason: 'plugin-unavailable', + reason: PLUGIN_INSTALLATION_REASONS.unavailable, provider, package: declaration.package, ...(failures.length > 0 ? { failedPlugins: failures } : {}), diff --git a/src/cli/pre-command-failure.ts b/src/cli/pre-command-failure.ts new file mode 100644 index 0000000000..8d318b4d1a --- /dev/null +++ b/src/cli/pre-command-failure.ts @@ -0,0 +1,48 @@ +import { + emitDiagnostic, + flushDiagnosticsToSessionFile, + getDiagnosticsMeta, +} from '@agent-device/host-kit/diagnostics'; +import { normalizeError } from '@agent-device/kernel/errors'; +import { exitAfterFlush } from './process-exit.ts'; + +const printHumanError = async ( + ...args: Parameters +): Promise => (await import('./failure-output.ts')).printHumanError(...args); + +const printJson = ( + result: + | { success: true; data?: unknown } + | { success: false; error: ReturnType }, +): Promise => + import('../commands/output/json.ts').then(({ printJson: write }) => write(result)); + +/** + * Prints one failure the CLI answers before it runs a command — a refused parse, or a provider + * plugin refused before any option was resolved — and ends the process. The failure owns its + * diagnostic phase, so each pre-command refusal stays distinguishable in the log. + */ +export async function exitBeforeCommand( + error: unknown, + argv: string[], + options: { jsonRequested: boolean; debugEnabled: boolean }, + phase: string, +): Promise { + emitDiagnostic({ + level: 'error', + phase, + data: { + error: error instanceof Error ? error.message : String(error), + }, + }); + const normalized = normalizeError(error, { + diagnosticId: getDiagnosticsMeta().diagnosticId, + logPath: flushDiagnosticsToSessionFile({ force: true })?.path, + }); + if (options.jsonRequested) { + await printJson({ success: false, error: normalized }); + } else { + await printHumanError(normalized, { debugTier: options.debugEnabled, argv }); + } + return await exitAfterFlush(1); +} From e49a029b8d1507c06b39ea766533e8a188454bd0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 21 Nov 2026 15:18:32 +0100 Subject: [PATCH 12/26] test(connect): name the new tests for the modules they pin R84 test-colocation judges a unit test against the modules beside it. `auth-login-write-timing.test.ts` sits in `src/cli/__tests__`, where no module is named `auth-login-write-timing`, and `connect-provider-credential-order.test.ts` sits in `src/cli/connection` with no such module either. Each is renamed for the module whose behavior it pins: `auth-session.ts` holds the login save timing, and `provider-admission.ts` owns the admission that precedes the credential. Part of #3311 --- ...gin-write-timing.test.ts => auth-session-write-timing.test.ts} | 0 ...-order.test.ts => provider-admission-credential-order.test.ts} | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename src/cli/__tests__/{auth-login-write-timing.test.ts => auth-session-write-timing.test.ts} (100%) rename src/cli/connection/{connect-provider-credential-order.test.ts => provider-admission-credential-order.test.ts} (100%) diff --git a/src/cli/__tests__/auth-login-write-timing.test.ts b/src/cli/__tests__/auth-session-write-timing.test.ts similarity index 100% rename from src/cli/__tests__/auth-login-write-timing.test.ts rename to src/cli/__tests__/auth-session-write-timing.test.ts diff --git a/src/cli/connection/connect-provider-credential-order.test.ts b/src/cli/connection/provider-admission-credential-order.test.ts similarity index 100% rename from src/cli/connection/connect-provider-credential-order.test.ts rename to src/cli/connection/provider-admission-credential-order.test.ts From 73f9941efe0932b358c97761fb8111e23d8dc167 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 21 Nov 2026 15:23:19 +0100 Subject: [PATCH 13/26] test(cli): drop an unused helper export --- src/__tests__/test-utils/cli-json-outputs.ts | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/src/__tests__/test-utils/cli-json-outputs.ts b/src/__tests__/test-utils/cli-json-outputs.ts index c6c627f3c5..e4cba7e89d 100644 --- a/src/__tests__/test-utils/cli-json-outputs.ts +++ b/src/__tests__/test-utils/cli-json-outputs.ts @@ -15,13 +15,3 @@ export function parseJsonOutputs(stdout: string): unknown[] { } return outputs; } - -/** The objects that reported success. */ -export function successfulOutputs(outputs: unknown[]): unknown[] { - return outputs.filter( - (output) => - typeof output === 'object' && - output !== null && - (output as { success?: unknown }).success === true, - ); -} From 8e72bdc07ce221c420948ce4e536ba5f65b0f8cb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 21 Nov 2026 15:28:51 +0100 Subject: [PATCH 14/26] perf(cli): load the connect preflight and pre-command failure modules on demand --- src/cli.ts | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/src/cli.ts b/src/cli.ts index abe80ff12b..4c5311ca4c 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -60,11 +60,6 @@ import { type RemoteConnectionRequestMetadata, } from '@agent-device/remote/remote-connection-state'; import { resolveRemoteAuthForCli, withDeferredLogin } from './cli/auth-session.ts'; -import { exitBeforeCommand } from './cli/pre-command-failure.ts'; -import { - admitConnectProviderOrExit, - defersLoginUntilProviderAdmission, -} from './cli/connect-preflight.ts'; import type { FlagKey } from '@agent-device/command-registry/flag-types'; import type { CliFlags } from '@agent-device/contracts/command'; import type { SessionRuntimeHints } from '@agent-device/kernel/contracts'; @@ -173,6 +168,7 @@ async function runCliOnHost(argv: string[], deps: CliDeps, host: HostEnvironment async () => { // A provider this route cannot supply is refused here: before this run resolves an option that // can carry a credential, and before any credential value is registered for redaction. + const { admitConnectProviderOrExit } = await import('./cli/connect-preflight.ts'); await admitConnectProviderOrExit(argv, host, { jsonRequested, debugEnabled }); const { parsed, command, positionals } = await parseCliInputOrExit(argv, { host, @@ -214,6 +210,7 @@ async function runCliOnHost(argv: string[], deps: CliDeps, host: HostEnvironment }); // A `connect` that learns its provider from the profile it fetches holds a login it approves // until that provider is admitted; every other command saves a login as soon as it is approved. + const { defersLoginUntilProviderAdmission } = await import('./cli/connect-preflight.ts'); await withDeferredLogin( { defersLogin: await defersLoginUntilProviderAdmission(ctx) }, async () => { @@ -327,6 +324,7 @@ async function exitOnParseFailure( argv: string[], options: { jsonRequested: boolean; debugEnabled: boolean }, ): Promise { + const { exitBeforeCommand } = await import('./cli/pre-command-failure.ts'); return await exitBeforeCommand(error, argv, options, 'cli_parse_failed'); } From e8a45c797efcc52b0bb004329cdf312aa9b9a3a0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 21 Nov 2026 20:44:54 +0100 Subject: [PATCH 15/26] chore(release): make @agent-device/limrun public --- packages/provider-limrun/package.json | 1 - 1 file changed, 1 deletion(-) diff --git a/packages/provider-limrun/package.json b/packages/provider-limrun/package.json index 2e08d700c2..fe14708ee5 100644 --- a/packages/provider-limrun/package.json +++ b/packages/provider-limrun/package.json @@ -8,7 +8,6 @@ "apiVersion": 3, "provider": "limrun" }, - "private": true, "type": "module", "description": "Limrun Android instance and iOS simulator plugin for agent-device.", "files": [ From d0b77b84e4cb182048dfbc33d670b9a6d73de9c1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 21 Nov 2026 23:57:08 +0100 Subject: [PATCH 16/26] fix(cli): keep a deferred cloud login from overwriting newer auth state A `connect` that learns its provider from the control plane holds the login it approves until that provider is admitted. An explicit `auth login` or `auth logout` completed in that gap was overwritten when the connect resumed, so the older approval won and a logout left the state directory signed in. Every write of one state directory's auth state now passes one guard: a revision record beside the session it governs, republished by each write. A held login reads that revision before its device authorization and saves only while it still stands, which logs the stand-down rather than failing the command. The record counts writes rather than reading the stored session, because a logout leaves no session, which is what a first login finds too. Name the Limrun plugin in the README Cloud / remote install instruction, since a clean core install refuses a Limrun profile without it. Refs #4846 (review 7068516663) --- README.md | 2 +- ...auth-session-deferred-supersession.test.ts | 253 ++++++++++++++++++ src/cli/__tests__/auth-session.test.ts | 7 +- src/cli/auth-session.ts | 174 +++++++++++- 4 files changed, 421 insertions(+), 15 deletions(-) create mode 100644 src/cli/__tests__/auth-session-deferred-supersession.test.ts diff --git a/README.md b/README.md index 7fc16eb7f5..e2d2460c2f 100644 --- a/README.md +++ b/README.md @@ -153,7 +153,7 @@ The same session and evidence model works at every step: the agent explores the | --- | --- | --- | | Local | Trying commands and debugging apps on simulators, emulators, physical devices, macOS, and Linux. | Follow the Quick Start. | | CI/CD | Automated pull request and merge validation with replay scripts and captured artifacts. | Try the [EAS workflow template](https://github.com/callstackincubator/eas-agent-device/blob/main/.eas/workflows/agent-qa-mobile.yml). | -| Cloud / remote | Linux runners, managed devices, and remote jobs. | Set up a [remote proxy](https://agent-device.dev/docs/remote-proxy), connect a [device cloud](https://agent-device.dev/docs/device-clouds) (BrowserStack, AWS Device Farm, and TestMu AI through `agent-device plugins add`, or Limrun), or [contact Callstack](mailto:hello@callstack.com) for team QA. | +| Cloud / remote | Linux runners, managed devices, and remote jobs. | Set up a [remote proxy](https://agent-device.dev/docs/remote-proxy), connect a [device cloud](https://agent-device.dev/docs/device-clouds) (BrowserStack, AWS Device Farm, TestMu AI, and Limrun through `agent-device plugins add`), or [contact Callstack](mailto:hello@callstack.com) for team QA. | ## How it works diff --git a/src/cli/__tests__/auth-session-deferred-supersession.test.ts b/src/cli/__tests__/auth-session-deferred-supersession.test.ts new file mode 100644 index 0000000000..bc2b8f9bc2 --- /dev/null +++ b/src/cli/__tests__/auth-session-deferred-supersession.test.ts @@ -0,0 +1,253 @@ +import { afterEach, beforeEach, test, vi } from 'vitest'; +import assert from 'node:assert/strict'; +import fs from 'node:fs'; +import path from 'node:path'; +import { makeTempWorkspace } from '@agent-device/test-kit'; +import { runCliCapture } from '../../__tests__/cli-capture.ts'; +import { parseJsonOutputs } from '../../__tests__/test-utils/cli-json-outputs.ts'; +import { readCliSession, resolveCliSessionPath } from '../auth-session.ts'; + +// A `connect` that learns its provider from the control plane holds the login it approves until that +// provider is admitted, so another auth command can answer for the same state directory while the +// connection-profile request is open. Each case holds that request open, runs an explicit `auth login` +// or `auth logout` in the gap, and then lets the connect resume: the explicit command is the newer +// answer, and the login the connect holds may not overwrite it. +const CLOUD = 'https://cloud.example'; +const terminals = [process.stdin, process.stdout] as const; +const originalTty = terminals.map((stream) => Object.getOwnPropertyDescriptor(stream, 'isTTY')); + +beforeEach(() => { + for (const stream of terminals) { + Object.defineProperty(stream, 'isTTY', { value: true, configurable: true }); + } +}); + +afterEach(() => { + terminals.forEach((stream, index) => { + const descriptor = originalTty[index]; + if (descriptor) Object.defineProperty(stream, 'isTTY', descriptor); + else delete (stream as { isTTY?: boolean }).isTTY; + }); + vi.unstubAllGlobals(); +}); + +const CLI_ENV = { + AGENT_DEVICE_CLOUD_BASE_URL: CLOUD, + // A remote shell prints the verification URL and opens no browser. + SSH_TTY: '/dev/ttys001', + CI: '', + GITHUB_ACTIONS: '', + BUILDKITE: '', +}; + +/** + * The open connection-profile request of the pending connect. `hold` is what its handler awaits, so the + * request stays in flight until the test releases it, and `arrived` says when it got there. + */ +type ProfileGate = { + hold: () => Promise; + arrived: Promise; + release: () => void; +}; + +function createProfileGate(): ProfileGate { + let markArrived: () => void = () => {}; + let letGo: () => void = () => {}; + const arrived = new Promise((resolve) => { + markArrived = resolve; + }); + const released = new Promise((resolve) => { + letGo = resolve; + }); + return { + hold: async () => { + markArrived(); + await released; + }, + arrived, + release: letGo, + }; +} + +/** + * The control plane: each device login is approved with the next id of `sessionIds`, and the connection + * profile the connect asks for is held at `gate` before it answers. + */ +function stubControlPlane(options: { gate: ProfileGate; sessionIds: readonly string[] }): void { + let approvals = 0; + const json = (body: unknown) => + new Response(JSON.stringify(body), { + status: 200, + headers: { 'content-type': 'application/json' }, + }); + vi.stubGlobal( + 'fetch', + vi.fn(async (input: RequestInfo | URL) => { + const { pathname } = new URL(String(input)); + if (pathname === '/api/control-plane/device-auth/start') { + return json({ deviceCode: 'device', userCode: 'USER', verificationUri: `${CLOUD}/verify` }); + } + if (pathname === '/api/control-plane/device-auth/poll') { + const id = options.sessionIds[Math.min(approvals++, options.sessionIds.length - 1)]!; + return json({ + status: 'approved', + accessToken: `adc_agent_${id}`, + cliSession: { id, refreshCredential: `refresh-${id}` }, + }); + } + if (pathname === '/api/control-plane/connection-profile') { + await options.gate.hold(); + return json({ + ok: true, + connection: { + remoteConfigProfile: { + daemonBaseUrl: 'https://bridge.example.com/agent-device', + tenant: 'acme', + runId: 'run-1', + }, + }, + }); + } + throw new Error(`unexpected request: ${pathname}`); + }), + ); +} + +/** A stored session whose access has expired, which is what sends a connect to a fresh device login. */ +function writeExpiredCliSession(stateDir: string, id: string): void { + fs.mkdirSync(path.dirname(resolveCliSessionPath(stateDir)), { recursive: true, mode: 0o700 }); + fs.writeFileSync( + resolveCliSessionPath(stateDir), + JSON.stringify({ + version: 1, + id, + cloudBaseUrl: CLOUD, + refreshCredential: `refresh-${id}`, + createdAt: '2026-01-01T00:00:00.000Z', + expiresAt: '2026-01-02T00:00:00.000Z', + }), + ); +} + +function connectWorkspaces() { + const { root, home, project } = makeTempWorkspace(); + return { root, stateDir: path.join(root, 'state'), home, project }; +} + +/** Runs one CLI command in this workspace. Used while another command is already in flight. */ +function runInWorkspace( + argv: string[], + workspace: { stateDir: string; home: string; project: string }, +) { + return runCliCapture([...argv, '--state-dir', workspace.stateDir, '--json'], { + cwd: workspace.project, + env: { HOME: workspace.home, ...CLI_ENV }, + }); +} + +function assertOneSuccess(stdout: string): void { + const outputs = parseJsonOutputs(stdout) as Array<{ success?: unknown }>; + assert.equal(outputs.length, 1, stdout); + assert.equal(outputs[0]?.success, true, stdout); +} + +test('an explicit auth login completed while the profile request is open keeps its session', async () => { + const gate = createProfileGate(); + stubControlPlane({ gate, sessionIds: ['cli-pending', 'cli-explicit'] }); + const workspace = connectWorkspaces(); + + try { + const pending = runInWorkspace(['connect', 'cloud', '--session', 'ci'], workspace); + await gate.arrived; + + const login = await runInWorkspace(['auth', 'login'], workspace); + assert.equal(login.code, null, login.stdout + login.stderr); + assert.equal(readCliSession({ stateDir: workspace.stateDir })?.id, 'cli-explicit'); + + gate.release(); + const connect = await pending; + + assertOneSuccess(connect.stdout); + // The login the explicit command saved is still the stored session: the older approval stood down. + assert.equal(readCliSession({ stateDir: workspace.stateDir })?.id, 'cli-explicit'); + } finally { + gate.release(); + fs.rmSync(workspace.root, { recursive: true, force: true }); + } +}); + +test('an auth logout completed while the profile request is open leaves the state directory signed out', async () => { + const gate = createProfileGate(); + stubControlPlane({ gate, sessionIds: ['cli-pending'] }); + const workspace = connectWorkspaces(); + // The stored session has expired, which is why the connect goes to a fresh device login at all. + writeExpiredCliSession(workspace.stateDir, 'cli-expired'); + + try { + const pending = runInWorkspace(['connect', 'cloud', '--session', 'ci'], workspace); + await gate.arrived; + + const logout = await runInWorkspace(['auth', 'logout'], workspace); + assert.equal(logout.code, null, logout.stdout + logout.stderr); + assert.equal(fs.existsSync(resolveCliSessionPath(workspace.stateDir)), false); + + gate.release(); + const connect = await pending; + + assertOneSuccess(connect.stdout); + // The logout is the newer answer, so the resumed connect writes no session back. + assert.equal(readCliSession({ stateDir: workspace.stateDir }), null); + } finally { + gate.release(); + fs.rmSync(workspace.root, { recursive: true, force: true }); + } +}); + +test('a connect with no other auth command in flight saves the login it was approved', async () => { + const gate = createProfileGate(); + stubControlPlane({ gate, sessionIds: ['cli-pending'] }); + const workspace = connectWorkspaces(); + + try { + const pending = runInWorkspace(['connect', 'cloud', '--session', 'ci'], workspace); + await gate.arrived; + gate.release(); + const connect = await pending; + + assert.equal(connect.code, null, connect.stdout + connect.stderr); + assert.equal(readCliSession({ stateDir: workspace.stateDir })?.id, 'cli-pending'); + } finally { + gate.release(); + fs.rmSync(workspace.root, { recursive: true, force: true }); + } +}); + +test('a connect whose auth revision cannot be read saves no login', async () => { + const gate = createProfileGate(); + stubControlPlane({ gate, sessionIds: ['cli-pending'] }); + const workspace = connectWorkspaces(); + // A record of another version cannot say what this state directory's auth state is, and unknown is + // not proof that nothing changed since, so the held login is not saved on it. + writeUnreadableAuthRevision(workspace.stateDir); + + try { + const pending = runInWorkspace(['connect', 'cloud', '--session', 'ci'], workspace); + await gate.arrived; + gate.release(); + const connect = await pending; + + assertOneSuccess(connect.stdout); + assert.equal(readCliSession({ stateDir: workspace.stateDir }), null); + } finally { + gate.release(); + fs.rmSync(workspace.root, { recursive: true, force: true }); + } +}); + +function writeUnreadableAuthRevision(stateDir: string): void { + fs.mkdirSync(path.dirname(resolveCliSessionPath(stateDir)), { recursive: true, mode: 0o700 }); + fs.writeFileSync( + path.join(path.dirname(resolveCliSessionPath(stateDir)), 'cli-session.revision.json'), + JSON.stringify({ version: 2, generation: 1 }), + ); +} diff --git a/src/cli/__tests__/auth-session.test.ts b/src/cli/__tests__/auth-session.test.ts index 1b4d87193c..42599c628e 100644 --- a/src/cli/__tests__/auth-session.test.ts +++ b/src/cli/__tests__/auth-session.test.ts @@ -598,7 +598,12 @@ test('a rewritten CLI session replaces the file, so a reader never sees a partia } assert.equal(readCliSession({ stateDir: tempRoot })?.id, 'session-second'); if (process.platform !== 'win32') assert.equal(fs.statSync(sessionPath).mode & 0o077, 0); - assert.deepEqual(fs.readdirSync(path.dirname(sessionPath)), [path.basename(sessionPath)]); + // The auth guard's own revision record stands beside the session it governs, so that directory + // holds exactly those two names and nothing else. + assert.deepEqual(fs.readdirSync(path.dirname(sessionPath)).sort(), [ + 'cli-session.json', + 'cli-session.revision.json', + ]); } finally { fs.rmSync(tempRoot, { recursive: true, force: true }); } diff --git a/src/cli/auth-session.ts b/src/cli/auth-session.ts index ad309b84b7..11fb4d9e7b 100644 --- a/src/cli/auth-session.ts +++ b/src/cli/auth-session.ts @@ -2,6 +2,7 @@ import { AsyncLocalStorage } from 'node:async_hooks'; import fs from 'node:fs'; import path from 'node:path'; import { publishFileSync } from '@agent-device/host-kit/file'; +import { emitDiagnostic } from '@agent-device/host-kit/diagnostics'; import { AppError } from '@agent-device/kernel/errors'; import type { CliFlags } from '@agent-device/contracts/command'; import { type EnvMap } from '@agent-device/kernel/source-value'; @@ -77,11 +78,47 @@ type AuthIo = { openBrowser?: (url: string) => Promise; }; +/** + * The one guard over one state directory's auth state, shared by every write of it: an explicit + * `auth login`, an `auth logout`, and the deferred save of a `connect` login this run holds while the + * cloud names its provider. The guard is a revision record beside the session it governs, republished by + * every write of that session. An explicit auth command writes what it approves and republishes the + * revision. A held login reads the revision before its device authorization and saves only while that + * revision still stands, so the newest auth command wins: an explicit login or logout that completed + * while a connect held its login approved is never overwritten by that connect's later save. A counter is + * used rather than the stored session itself, because a logout leaves the state directory holding no + * session, which is what a first login finds too, and the two cannot tell a newer write from no write. + * + * The compare and the publish of a held login are separate filesystem calls, so an auth write landing + * between them is still overwritten. What this guard rules out is the reported shape: a write that + * finished before a held login read the revision is always seen by that read. + */ +const AUTH_REVISION_FILE_NAME = 'cli-session.revision.json'; +/** The shape of a revision record. A record of another version is unreadable, not absent. */ +const AUTH_REVISION_RECORD_VERSION = 1; + +type AuthRevisionRecord = Readonly<{ version: 1; generation: number }>; + +/** + * The auth revision of one state directory, as the guard answers it: no auth write recorded yet, a + * recorded generation, or a record the reader cannot parse. An unreadable record is unknown evidence, + * so a held login is not saved on it rather than concluding nothing changed. + */ +type AuthRevision = + | Readonly<{ state: 'absent' }> + | Readonly<{ state: 'recorded'; generation: number }> + | Readonly<{ state: 'unreadable' }>; + /** * A login of one `connect` run, held between its approval and the admission of the provider that run - * discovers. + * discovers. `revision` is the auth revision this state directory carried when the cloud approved the + * login, and the held session is saved only while that revision still stands. */ -type PendingLogin = { stateDir: string; session: CliSessionRecord }; +type PendingLogin = { + stateDir: string; + session: CliSessionRecord; + revision: AuthRevision; +}; const pendingLoginScope = new AsyncLocalStorage<{ pending?: PendingLogin }>(); @@ -93,7 +130,9 @@ const pendingLoginScope = new AsyncLocalStorage<{ pending?: PendingLogin }>(); * admitted, or drops it with {@link discardPendingLoginAtRefusal} when the provider's plugin is * refused. A run that ends with its login still pending, because discovery failed before any provider * was named, saves it, so a failure unrelated to a provider does not cost the login. Every other - * route, including explicit `auth login`, saves a login as soon as it is approved. + * route, including explicit `auth login`, saves a login as soon as it is approved. A held login is + * published only while the auth revision it captured still stands, so it never overwrites auth state + * an explicit `auth login` or `auth logout` wrote meanwhile: see {@link publishHeldLogin}. */ export async function withDeferredLogin( options: { defersLogin: boolean }, @@ -104,21 +143,23 @@ export async function withDeferredLogin( try { return await pendingLoginScope.run(scope, run); } finally { - // Only a run that ended before it named a provider gets here with a pending login. - if (scope.pending) writeCliSession(scope.pending); + // Only a run that ended before it names a provider gets here with a pending login. + if (scope.pending) publishHeldLogin(scope.pending); } } /** * Saves the login this run holds because its provider was just admitted. A route saves before it - * generates or publishes connection state, so a login it cannot save stops the command there. + * generates or publishes connection state, so a login it cannot save stops the command there. A login + * an explicit `auth login` or `auth logout` superseded while it was held is not saved and is not an + * error: the state directory already holds the auth state its caller asked for last. */ export function savePendingLoginAtAdmission(): void { const scope = pendingLoginScope.getStore(); const pending = scope?.pending; if (scope === undefined) return; scope.pending = undefined; - if (pending) writeCliSession(pending); + if (pending) publishHeldLogin(pending); } /** Drops the login this run holds: its provider plugin was refused, so the route keeps no auth state. */ @@ -262,6 +303,9 @@ export async function loginWithDeviceAuth(options: { if (authMode === 'non-interactive') { throw buildNonInteractiveLoginError(options.commandLabel ?? 'agent-device connect', env); } + // The revision is read before the control plane is asked, so it is the answer this state directory + // gave when this login started, which is what a held login is compared with when it is saved. + const revisionAtStart = readAuthRevision(options.stateDir); const cloudBaseUrl = resolveCloudBaseUrl(env); const start = await postJson({ baseUrl: cloudBaseUrl, @@ -317,7 +361,7 @@ export async function loginWithDeviceAuth(options: { expiresAt: approved.cliSession?.expiresAt, }; const scope = pendingLoginScope.getStore(); - if (scope) scope.pending = { stateDir: options.stateDir, session }; + if (scope) scope.pending = { stateDir: options.stateDir, session, revision: revisionAtStart }; else writeCliSession({ stateDir: options.stateDir, session }); return { accessToken: approved.accessToken, @@ -346,7 +390,55 @@ export function readCliSession(options: { stateDir: string }): CliSessionRecord } } +/** + * Saves the session an explicit auth command approved. The write is unconditional: an explicit login is + * the newest answer for this state directory, and recording its revision is what makes a login another + * run still holds stand down. + */ export function writeCliSession(options: { stateDir: string; session: CliSessionRecord }): void { + writeCliSessionRecord(options); + recordAuthRevision(options.stateDir); +} + +/** + * Removes the stored session on an explicit `auth logout`, and records that revision so a login another + * run holds stands down instead of signing this state directory back in. Nothing is removed and nothing + * is recorded when no session was stored, since that command changed nothing here. + */ +export function removeCliSession(options: { stateDir: string }): boolean { + const filePath = resolveCliSessionPath(options.stateDir); + if (!fs.existsSync(filePath)) return false; + fs.rmSync(filePath, { force: true }); + recordAuthRevision(options.stateDir); + return true; +} + +/** + * Saves a login this run held, only while the auth revision it read before its device authorization + * still stands. A login that no longer stands is not saved, and is not a failure of this command: the + * state directory holds the auth state its caller asked for last, which is why the stand-down is logged + * rather than thrown. The revision is recorded after the session is written, so a reader that finds the + * newer session always finds its revision too. + */ +function publishHeldLogin(pending: PendingLogin): void { + const current = readAuthRevision(pending.stateDir); + if (!sameAuthRevision(pending.revision, current)) { + emitDiagnostic({ + level: 'info', + phase: 'cli_deferred_login_superseded', + data: { + reason: current.state === 'unreadable' ? 'auth-revision-unreadable' : 'newer-auth-revision', + held: pending.revision, + current, + }, + }); + return; + } + writeCliSessionRecord({ stateDir: pending.stateDir, session: pending.session }); + recordAuthRevision(pending.stateDir); +} + +function writeCliSessionRecord(options: { stateDir: string; session: CliSessionRecord }): void { const filePath = resolveCliSessionPath(options.stateDir); fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 }); publishFileSync({ @@ -357,11 +449,67 @@ export function writeCliSession(options: { stateDir: string; session: CliSession }); } -export function removeCliSession(options: { stateDir: string }): boolean { - const filePath = resolveCliSessionPath(options.stateDir); - if (!fs.existsSync(filePath)) return false; - fs.rmSync(filePath, { force: true }); - return true; +/** + * The auth revision this state directory's guard holds: the number of auth writes it has recorded. A + * record that cannot be read is its own answer, so a caller never mistakes unknown for unchanged. + */ +function readAuthRevision(stateDir: string): AuthRevision { + let contents: string; + try { + contents = fs.readFileSync(resolveAuthRevisionPath(stateDir), 'utf8'); + } catch (error) { + const code = (error as NodeJS.ErrnoException | null)?.code; + return code === 'ENOENT' || code === 'ENOTDIR' ? { state: 'absent' } : { state: 'unreadable' }; + } + const generation = parseAuthRevisionGeneration(contents); + return generation === undefined ? { state: 'unreadable' } : { state: 'recorded', generation }; +} + +/** Publishes the revision that follows the one held, so the newest auth write of this directory owns it. */ +function recordAuthRevision(stateDir: string): void { + const current = readAuthRevision(stateDir); + const marker: AuthRevisionRecord = { + version: AUTH_REVISION_RECORD_VERSION, + generation: current.state === 'recorded' ? current.generation + 1 : 1, + }; + publishFileSync({ + destination: resolveAuthRevisionPath(stateDir), + contents: `${JSON.stringify(marker, null, 2)}\n`, + mode: 0o600, + exactMode: true, + }); +} + +/** + * Whether a held login's reading is still the reading the guard holds. An unreadable reading on either + * side answers no: a record that cannot be read says nothing about what was written since, which is not + * proof that nothing was, so a held login is not saved on it. + */ +function sameAuthRevision(left: AuthRevision, right: AuthRevision): boolean { + if (left.state === 'absent') return right.state === 'absent'; + return ( + left.state === 'recorded' && right.state === 'recorded' && right.generation === left.generation + ); +} + +function parseAuthRevisionGeneration(contents: string): number | undefined { + let parsed: unknown; + try { + parsed = JSON.parse(contents); + } catch { + return undefined; + } + const marker = parsed as Record | null; + if (marker === null || typeof marker !== 'object') return undefined; + if (marker.version !== AUTH_REVISION_RECORD_VERSION) return undefined; + const generation = marker.generation; + return typeof generation === 'number' && Number.isSafeInteger(generation) && generation > 0 + ? generation + : undefined; +} + +function resolveAuthRevisionPath(stateDir: string): string { + return path.join(stateDir, 'auth', AUTH_REVISION_FILE_NAME); } export function resolveCliSessionPath(stateDir: string): string { From b32c9d93f9acf7195eee02d82581ec454a54e9e6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sun, 22 Nov 2026 08:19:04 +0100 Subject: [PATCH 17/26] refactor(cli): save a connect login when it is approved, as on the base Remove the deferred-login scope and the auth revision record. A login is written when the cloud approves it, so explicit auth commands and concurrent connects keep the base ordering. The cloud route still admits a discovered Limrun provider before it generates a profile or connection record. --- packages/contracts/src/plugin-installation.ts | 13 - src/cli.ts | 74 +++-- .../auth-session-connect-admission.test.ts | 182 ------------- ...auth-session-deferred-supersession.test.ts | 253 ------------------ .../auth-session-write-timing.test.ts | 178 ------------ src/cli/__tests__/auth-session.test.ts | 7 +- src/cli/auth-session.ts | 213 +-------------- src/cli/connect-preflight.ts | 27 +- .../cloud-profile-store-refusal.test.ts | 194 -------------- src/cli/connection/cloud-profile.ts | 24 +- .../connection/connect-provider-adapters.ts | 15 +- src/cli/connection/provider-admission.ts | 23 -- src/cli/connection/provider-policy.ts | 17 -- 13 files changed, 60 insertions(+), 1160 deletions(-) delete mode 100644 src/cli/__tests__/auth-session-connect-admission.test.ts delete mode 100644 src/cli/__tests__/auth-session-deferred-supersession.test.ts delete mode 100644 src/cli/__tests__/auth-session-write-timing.test.ts delete mode 100644 src/cli/connection/cloud-profile-store-refusal.test.ts diff --git a/packages/contracts/src/plugin-installation.ts b/packages/contracts/src/plugin-installation.ts index c769f6e997..d4b563a858 100644 --- a/packages/contracts/src/plugin-installation.ts +++ b/packages/contracts/src/plugin-installation.ts @@ -141,19 +141,6 @@ export const PLUGIN_INSTALLATION_REASONS = { unavailable: 'plugin-unavailable', } as const satisfies Record; -/** - * Whether an error is one of the typed refusals a provider plugin admission answers with. A route - * that failed with either keeps no cloud auth state: the user installs or repairs the plugin first. - */ -export function isProviderPluginRefusal(error: unknown): boolean { - if (!(error instanceof AppError)) return false; - const reason = error.details?.reason; - return ( - reason === PLUGIN_INSTALLATION_REASONS.notInstalled || - reason === PLUGIN_INSTALLATION_REASONS.unavailable - ); -} - /** * The typed outcome for a platform family a composition does not have (ADR 0034). An optional family * reports `plugin-not-installed` with the package that provides it and its installation command, diff --git a/src/cli.ts b/src/cli.ts index 4c5311ca4c..8fe31712d3 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -59,7 +59,7 @@ import { resolveRemoteConnectionDefaults, type RemoteConnectionRequestMetadata, } from '@agent-device/remote/remote-connection-state'; -import { resolveRemoteAuthForCli, withDeferredLogin } from './cli/auth-session.ts'; +import { resolveRemoteAuthForCli } from './cli/auth-session.ts'; import type { FlagKey } from '@agent-device/command-registry/flag-types'; import type { CliFlags } from '@agent-device/contracts/command'; import type { SessionRuntimeHints } from '@agent-device/kernel/contracts'; @@ -185,7 +185,7 @@ async function runCliOnHost(argv: string[], deps: CliDeps, host: HostEnvironment debugOutputEnabled, }); registerDaemonAuthDiagnosticValue(ctx.effectiveFlags); - const logTail: { stop: (() => void) | null } = { stop: null }; + let logTailStopper: (() => void) | null = null; try { if (command === 'react-devtools') { await exitAfterFlush(await runReactDevtoolsCli(ctx)); @@ -208,47 +208,39 @@ async function runCliOnHost(argv: string[], deps: CliDeps, host: HostEnvironment stateDir: ctx.daemonPaths.baseDir, flags: ctx.effectiveFlags, }); - // A `connect` that learns its provider from the profile it fetches holds a login it approves - // until that provider is admitted; every other command saves a login as soon as it is approved. - const { defersLoginUntilProviderAdmission } = await import('./cli/connect-preflight.ts'); - await withDeferredLogin( - { defersLogin: await defersLoginUntilProviderAdmission(ctx) }, - async () => { - await resolveRemoteContext(ctx, transport); - registerDaemonAuthDiagnosticValue(ctx.effectiveFlags); - if (command === 'cdp') { - await exitAfterFlush( - await runAgentCdpCommand(positionals, { - flags: ctx.effectiveFlags, - runtime: ctx.resolvedRuntime, - cwd: host.cwd, - env: host.env, - }), - ); - return; - } - logTail.stop = maybeStartDaemonLogTail(ctx); - const replayTestReporterRuntime = await createReplayReporterForTest(ctx); - const commandProgress = createCommandProgressState(); - const client = createAgentDeviceClient(buildClientConfig(ctx), { - host: ctx.host, - devicePin: ctx.devicePin, - transport: createCliDaemonTransport({ - host, - command, - flags: ctx.effectiveFlags, - replayTestReporterRuntime, - commandProgress, - transport, - }), - }); - await dispatchCliCommand(ctx, client, replayTestReporterRuntime, commandProgress); - }, - ); + await resolveRemoteContext(ctx, transport); + registerDaemonAuthDiagnosticValue(ctx.effectiveFlags); + if (command === 'cdp') { + await exitAfterFlush( + await runAgentCdpCommand(positionals, { + flags: ctx.effectiveFlags, + runtime: ctx.resolvedRuntime, + cwd: host.cwd, + env: host.env, + }), + ); + return; + } + logTailStopper = maybeStartDaemonLogTail(ctx); + const replayTestReporterRuntime = await createReplayReporterForTest(ctx); + const commandProgress = createCommandProgressState(); + const client = createAgentDeviceClient(buildClientConfig(ctx), { + host: ctx.host, + devicePin: ctx.devicePin, + transport: createCliDaemonTransport({ + host, + command, + flags: ctx.effectiveFlags, + replayTestReporterRuntime, + commandProgress, + transport, + }), + }); + await dispatchCliCommand(ctx, client, replayTestReporterRuntime, commandProgress); } catch (error) { - await handleRunCliFailure(error, ctx, logTail.stop); + await handleRunCliFailure(error, ctx, logTailStopper); } finally { - logTail.stop?.(); + if (logTailStopper) logTailStopper(); } }, ); diff --git a/src/cli/__tests__/auth-session-connect-admission.test.ts b/src/cli/__tests__/auth-session-connect-admission.test.ts deleted file mode 100644 index 049781f05f..0000000000 --- a/src/cli/__tests__/auth-session-connect-admission.test.ts +++ /dev/null @@ -1,182 +0,0 @@ -import { afterEach, beforeEach, test, vi } from 'vitest'; -import assert from 'node:assert/strict'; -import fs from 'node:fs'; -import path from 'node:path'; -import { makeTempWorkspace } from '@agent-device/test-kit'; -import { runCliCapture } from '../../__tests__/cli-capture.ts'; -import { resolveCliSessionPath } from '../auth-session.ts'; - -// No plugin is installed in this file. Each case approves a device login and then lets the control -// plane name the provider, so the login is new when the provider is admitted or refused. -const CLOUD = 'https://cloud.example'; -const terminals = [process.stdin, process.stdout] as const; -const originalTty = terminals.map((stream) => Object.getOwnPropertyDescriptor(stream, 'isTTY')); - -beforeEach(() => { - for (const stream of terminals) { - Object.defineProperty(stream, 'isTTY', { value: true, configurable: true }); - } -}); - -afterEach(() => { - terminals.forEach((stream, index) => { - const descriptor = originalTty[index]; - if (descriptor) Object.defineProperty(stream, 'isTTY', descriptor); - else delete (stream as { isTTY?: boolean }).isTTY; - }); - vi.unstubAllGlobals(); -}); - -/** The control plane: an approved device login, then a connection profile naming `leaseProvider`. */ -function stubControlPlane( - leaseProvider: string | undefined, - options: { profileStatus?: number } = {}, -): ReturnType { - const json = (body: unknown) => - new Response(JSON.stringify(body), { - status: 200, - headers: { 'content-type': 'application/json' }, - }); - const fetchMock = vi.fn(async (input: RequestInfo | URL) => { - const { pathname } = new URL(String(input)); - if (pathname === '/api/control-plane/device-auth/start') { - return json({ deviceCode: 'device', userCode: 'USER', verificationUri: `${CLOUD}/verify` }); - } - if (pathname === '/api/control-plane/device-auth/poll') { - return json({ - status: 'approved', - accessToken: 'adc_agent_login', - cliSession: { id: 'cli-1', refreshCredential: 'refresh-1' }, - }); - } - if (pathname === '/api/control-plane/connection-profile') { - if (options.profileStatus) - return new Response('unavailable', { status: options.profileStatus }); - return json({ - ok: true, - connection: { - remoteConfigProfile: { - daemonBaseUrl: 'https://bridge.example.com/agent-device', - tenant: 'acme', - runId: 'run-1', - ...(leaseProvider ? { leaseProvider } : {}), - }, - }, - }); - } - throw new Error(`unexpected request: ${pathname}`); - }); - vi.stubGlobal('fetch', fetchMock); - return fetchMock; -} - -async function connect(argv: string[], workspace = makeTempWorkspace()) { - const { root, home, project } = workspace; - const stateDir = path.join(root, 'state'); - const result = await runCliCapture( - ['connect', ...argv, '--session', 'ci', '--state-dir', stateDir, '--json'], - { - cwd: project, - env: { - HOME: home, - AGENT_DEVICE_CLOUD_BASE_URL: CLOUD, - // A remote shell prints the verification URL and opens no browser. - SSH_TTY: '/dev/ttys001', - CI: '', - GITHUB_ACTIONS: '', - BUILDKITE: '', - }, - }, - ); - return { root, stateDir, result }; -} - -test.each([ - { route: 'connect cloud', argv: ['cloud'] }, - { route: 'plain connect', argv: [] }, - { - route: 'connect --daemon-base-url, where the generic auth step logs in', - argv: ['--daemon-base-url', 'https://bridge.agent-device.dev/api', '--tenant', 'acme'], - }, -])( - '$route writes no auth state when the approved login discovers Limrun without its plugin', - async ({ argv }) => { - const fetchMock = stubControlPlane('limrun'); - const { root, stateDir, result } = await connect(argv); - - assert.equal(result.code, 1, result.stdout + result.stderr); - const { error } = JSON.parse(result.stdout); - assert.equal(error.details.reason, 'plugin-not-installed'); - assert.match(error.details.installCommand, /agent-device plugins add @agent-device\/limrun/); - // The login was approved and the profile was fetched with it, so the refusal came after both. - const paths = fetchMock.mock.calls.map(([input]) => new URL(String(input)).pathname); - assert.deepEqual(paths, [ - '/api/control-plane/device-auth/start', - '/api/control-plane/device-auth/poll', - '/api/control-plane/connection-profile', - ]); - assert.equal(fs.existsSync(resolveCliSessionPath(stateDir)), false); - assert.equal(fs.existsSync(path.join(stateDir, 'auth')), false); - assert.equal(fs.existsSync(path.join(stateDir, 'remote-connections')), false); - fs.rmSync(root, { recursive: true, force: true }); - }, -); - -test('connect cloud stores the approved login once when the provider is admitted', async () => { - stubControlPlane(undefined); - const writes: string[] = []; - const rename = fs.renameSync; - const spy = vi.spyOn(fs, 'renameSync').mockImplementation((from, to) => { - writes.push(String(to)); - rename(from, to); - }); - - const { root, stateDir, result } = await connect(['cloud']); - spy.mockRestore(); - - assert.equal(result.code, null, result.stdout + result.stderr); - const session = JSON.parse(fs.readFileSync(resolveCliSessionPath(stateDir), 'utf8')); - assert.equal(session.id, 'cli-1'); - assert.equal(session.refreshCredential, 'refresh-1'); - assert.equal(session.cloudBaseUrl, CLOUD); - assert.equal(writes.filter((file) => file === resolveCliSessionPath(stateDir)).length, 1); - fs.rmSync(root, { recursive: true, force: true }); -}); - -function assertStoredLogin(stateDir: string): void { - const session = JSON.parse(fs.readFileSync(resolveCliSessionPath(stateDir), 'utf8')); - assert.equal(session.id, 'cli-1'); - assert.equal(session.refreshCredential, 'refresh-1'); -} - -test('connect cloud stores the approved login when the profile fetch fails afterward', async () => { - stubControlPlane(undefined, { profileStatus: 503 }); - const { root, stateDir, result } = await connect(['cloud']); - - assert.equal(result.code, 1, result.stdout + result.stderr); - const { error } = JSON.parse(result.stdout); - assert.equal(error.message, 'Cloud connection profile endpoint rejected the request.'); - assert.notEqual(error.details?.reason, 'plugin-not-installed'); - // The failure is not a provider refusal, so a retry does not start device auth again. - assertStoredLogin(stateDir); - fs.rmSync(root, { recursive: true, force: true }); -}); - -test('connect --remote-config stores the login of the generic auth step when the command fails afterward', async () => { - // The profile names no provider, so admission passes and the generic auth step logs in. The - // profile lacks a tenant, so the command then fails for a reason that is not a provider refusal. - stubControlPlane(undefined); - const workspace = makeTempWorkspace(); - const remoteConfig = path.join(workspace.project, 'remote.json'); - fs.writeFileSync( - remoteConfig, - JSON.stringify({ daemonBaseUrl: 'https://bridge.agent-device.dev/api', runId: 'run-1' }), - ); - const { root, stateDir, result } = await connect(['--remote-config', remoteConfig], workspace); - - assert.equal(result.code, 1, result.stdout + result.stderr); - const { error } = JSON.parse(result.stdout); - assert.notEqual(error.details?.reason, 'plugin-not-installed'); - assertStoredLogin(stateDir); - fs.rmSync(root, { recursive: true, force: true }); -}); diff --git a/src/cli/__tests__/auth-session-deferred-supersession.test.ts b/src/cli/__tests__/auth-session-deferred-supersession.test.ts deleted file mode 100644 index bc2b8f9bc2..0000000000 --- a/src/cli/__tests__/auth-session-deferred-supersession.test.ts +++ /dev/null @@ -1,253 +0,0 @@ -import { afterEach, beforeEach, test, vi } from 'vitest'; -import assert from 'node:assert/strict'; -import fs from 'node:fs'; -import path from 'node:path'; -import { makeTempWorkspace } from '@agent-device/test-kit'; -import { runCliCapture } from '../../__tests__/cli-capture.ts'; -import { parseJsonOutputs } from '../../__tests__/test-utils/cli-json-outputs.ts'; -import { readCliSession, resolveCliSessionPath } from '../auth-session.ts'; - -// A `connect` that learns its provider from the control plane holds the login it approves until that -// provider is admitted, so another auth command can answer for the same state directory while the -// connection-profile request is open. Each case holds that request open, runs an explicit `auth login` -// or `auth logout` in the gap, and then lets the connect resume: the explicit command is the newer -// answer, and the login the connect holds may not overwrite it. -const CLOUD = 'https://cloud.example'; -const terminals = [process.stdin, process.stdout] as const; -const originalTty = terminals.map((stream) => Object.getOwnPropertyDescriptor(stream, 'isTTY')); - -beforeEach(() => { - for (const stream of terminals) { - Object.defineProperty(stream, 'isTTY', { value: true, configurable: true }); - } -}); - -afterEach(() => { - terminals.forEach((stream, index) => { - const descriptor = originalTty[index]; - if (descriptor) Object.defineProperty(stream, 'isTTY', descriptor); - else delete (stream as { isTTY?: boolean }).isTTY; - }); - vi.unstubAllGlobals(); -}); - -const CLI_ENV = { - AGENT_DEVICE_CLOUD_BASE_URL: CLOUD, - // A remote shell prints the verification URL and opens no browser. - SSH_TTY: '/dev/ttys001', - CI: '', - GITHUB_ACTIONS: '', - BUILDKITE: '', -}; - -/** - * The open connection-profile request of the pending connect. `hold` is what its handler awaits, so the - * request stays in flight until the test releases it, and `arrived` says when it got there. - */ -type ProfileGate = { - hold: () => Promise; - arrived: Promise; - release: () => void; -}; - -function createProfileGate(): ProfileGate { - let markArrived: () => void = () => {}; - let letGo: () => void = () => {}; - const arrived = new Promise((resolve) => { - markArrived = resolve; - }); - const released = new Promise((resolve) => { - letGo = resolve; - }); - return { - hold: async () => { - markArrived(); - await released; - }, - arrived, - release: letGo, - }; -} - -/** - * The control plane: each device login is approved with the next id of `sessionIds`, and the connection - * profile the connect asks for is held at `gate` before it answers. - */ -function stubControlPlane(options: { gate: ProfileGate; sessionIds: readonly string[] }): void { - let approvals = 0; - const json = (body: unknown) => - new Response(JSON.stringify(body), { - status: 200, - headers: { 'content-type': 'application/json' }, - }); - vi.stubGlobal( - 'fetch', - vi.fn(async (input: RequestInfo | URL) => { - const { pathname } = new URL(String(input)); - if (pathname === '/api/control-plane/device-auth/start') { - return json({ deviceCode: 'device', userCode: 'USER', verificationUri: `${CLOUD}/verify` }); - } - if (pathname === '/api/control-plane/device-auth/poll') { - const id = options.sessionIds[Math.min(approvals++, options.sessionIds.length - 1)]!; - return json({ - status: 'approved', - accessToken: `adc_agent_${id}`, - cliSession: { id, refreshCredential: `refresh-${id}` }, - }); - } - if (pathname === '/api/control-plane/connection-profile') { - await options.gate.hold(); - return json({ - ok: true, - connection: { - remoteConfigProfile: { - daemonBaseUrl: 'https://bridge.example.com/agent-device', - tenant: 'acme', - runId: 'run-1', - }, - }, - }); - } - throw new Error(`unexpected request: ${pathname}`); - }), - ); -} - -/** A stored session whose access has expired, which is what sends a connect to a fresh device login. */ -function writeExpiredCliSession(stateDir: string, id: string): void { - fs.mkdirSync(path.dirname(resolveCliSessionPath(stateDir)), { recursive: true, mode: 0o700 }); - fs.writeFileSync( - resolveCliSessionPath(stateDir), - JSON.stringify({ - version: 1, - id, - cloudBaseUrl: CLOUD, - refreshCredential: `refresh-${id}`, - createdAt: '2026-01-01T00:00:00.000Z', - expiresAt: '2026-01-02T00:00:00.000Z', - }), - ); -} - -function connectWorkspaces() { - const { root, home, project } = makeTempWorkspace(); - return { root, stateDir: path.join(root, 'state'), home, project }; -} - -/** Runs one CLI command in this workspace. Used while another command is already in flight. */ -function runInWorkspace( - argv: string[], - workspace: { stateDir: string; home: string; project: string }, -) { - return runCliCapture([...argv, '--state-dir', workspace.stateDir, '--json'], { - cwd: workspace.project, - env: { HOME: workspace.home, ...CLI_ENV }, - }); -} - -function assertOneSuccess(stdout: string): void { - const outputs = parseJsonOutputs(stdout) as Array<{ success?: unknown }>; - assert.equal(outputs.length, 1, stdout); - assert.equal(outputs[0]?.success, true, stdout); -} - -test('an explicit auth login completed while the profile request is open keeps its session', async () => { - const gate = createProfileGate(); - stubControlPlane({ gate, sessionIds: ['cli-pending', 'cli-explicit'] }); - const workspace = connectWorkspaces(); - - try { - const pending = runInWorkspace(['connect', 'cloud', '--session', 'ci'], workspace); - await gate.arrived; - - const login = await runInWorkspace(['auth', 'login'], workspace); - assert.equal(login.code, null, login.stdout + login.stderr); - assert.equal(readCliSession({ stateDir: workspace.stateDir })?.id, 'cli-explicit'); - - gate.release(); - const connect = await pending; - - assertOneSuccess(connect.stdout); - // The login the explicit command saved is still the stored session: the older approval stood down. - assert.equal(readCliSession({ stateDir: workspace.stateDir })?.id, 'cli-explicit'); - } finally { - gate.release(); - fs.rmSync(workspace.root, { recursive: true, force: true }); - } -}); - -test('an auth logout completed while the profile request is open leaves the state directory signed out', async () => { - const gate = createProfileGate(); - stubControlPlane({ gate, sessionIds: ['cli-pending'] }); - const workspace = connectWorkspaces(); - // The stored session has expired, which is why the connect goes to a fresh device login at all. - writeExpiredCliSession(workspace.stateDir, 'cli-expired'); - - try { - const pending = runInWorkspace(['connect', 'cloud', '--session', 'ci'], workspace); - await gate.arrived; - - const logout = await runInWorkspace(['auth', 'logout'], workspace); - assert.equal(logout.code, null, logout.stdout + logout.stderr); - assert.equal(fs.existsSync(resolveCliSessionPath(workspace.stateDir)), false); - - gate.release(); - const connect = await pending; - - assertOneSuccess(connect.stdout); - // The logout is the newer answer, so the resumed connect writes no session back. - assert.equal(readCliSession({ stateDir: workspace.stateDir }), null); - } finally { - gate.release(); - fs.rmSync(workspace.root, { recursive: true, force: true }); - } -}); - -test('a connect with no other auth command in flight saves the login it was approved', async () => { - const gate = createProfileGate(); - stubControlPlane({ gate, sessionIds: ['cli-pending'] }); - const workspace = connectWorkspaces(); - - try { - const pending = runInWorkspace(['connect', 'cloud', '--session', 'ci'], workspace); - await gate.arrived; - gate.release(); - const connect = await pending; - - assert.equal(connect.code, null, connect.stdout + connect.stderr); - assert.equal(readCliSession({ stateDir: workspace.stateDir })?.id, 'cli-pending'); - } finally { - gate.release(); - fs.rmSync(workspace.root, { recursive: true, force: true }); - } -}); - -test('a connect whose auth revision cannot be read saves no login', async () => { - const gate = createProfileGate(); - stubControlPlane({ gate, sessionIds: ['cli-pending'] }); - const workspace = connectWorkspaces(); - // A record of another version cannot say what this state directory's auth state is, and unknown is - // not proof that nothing changed since, so the held login is not saved on it. - writeUnreadableAuthRevision(workspace.stateDir); - - try { - const pending = runInWorkspace(['connect', 'cloud', '--session', 'ci'], workspace); - await gate.arrived; - gate.release(); - const connect = await pending; - - assertOneSuccess(connect.stdout); - assert.equal(readCliSession({ stateDir: workspace.stateDir }), null); - } finally { - gate.release(); - fs.rmSync(workspace.root, { recursive: true, force: true }); - } -}); - -function writeUnreadableAuthRevision(stateDir: string): void { - fs.mkdirSync(path.dirname(resolveCliSessionPath(stateDir)), { recursive: true, mode: 0o700 }); - fs.writeFileSync( - path.join(path.dirname(resolveCliSessionPath(stateDir)), 'cli-session.revision.json'), - JSON.stringify({ version: 2, generation: 1 }), - ); -} diff --git a/src/cli/__tests__/auth-session-write-timing.test.ts b/src/cli/__tests__/auth-session-write-timing.test.ts deleted file mode 100644 index 169cbeda26..0000000000 --- a/src/cli/__tests__/auth-session-write-timing.test.ts +++ /dev/null @@ -1,178 +0,0 @@ -import { afterEach, beforeEach, test, vi } from 'vitest'; -import assert from 'node:assert/strict'; -import fs from 'node:fs'; -import path from 'node:path'; -import { makeTempWorkspace } from '@agent-device/test-kit'; -import { runCliCapture } from '../../__tests__/cli-capture.ts'; -import { storeWithLimrunInstalled } from '../../__tests__/test-utils/limrun-plugin-store.ts'; -import { parseJsonOutputs } from '../../__tests__/test-utils/cli-json-outputs.ts'; -import { resolveCliSessionPath } from '../auth-session.ts'; - -// A state root whose CLI session name is a directory cannot receive the login: the publish rename -// fails. Each case approves a device login in a route that must save it before it generates or -// publishes connection state, or reports success, so that failed write is what the command answers -// with — one error result, and no saved connection. -const CLOUD = 'https://cloud.example'; -const CLOUD_DAEMON = 'https://bridge.agent-device.dev/api'; -const terminals = [process.stdin, process.stdout] as const; -const originalTty = terminals.map((stream) => Object.getOwnPropertyDescriptor(stream, 'isTTY')); - -// The route that names a provider admits its plugin before it authenticates, so Limrun is installed. -vi.mock( - '@agent-device/plugins/store', - async (importOriginal) => - await storeWithLimrunInstalled( - importOriginal as () => Promise, - ), -); - -beforeEach(() => { - for (const stream of terminals) { - Object.defineProperty(stream, 'isTTY', { value: true, configurable: true }); - } -}); - -afterEach(() => { - terminals.forEach((stream, index) => { - const descriptor = originalTty[index]; - if (descriptor) Object.defineProperty(stream, 'isTTY', descriptor); - else delete (stream as { isTTY?: boolean }).isTTY; - }); - vi.unstubAllGlobals(); -}); - -/** The control plane: an approved device login, then a providerless connection profile. */ -function stubApprovedDeviceLogin(): void { - const json = (body: unknown) => - new Response(JSON.stringify(body), { - status: 200, - headers: { 'content-type': 'application/json' }, - }); - vi.stubGlobal( - 'fetch', - vi.fn(async (input: RequestInfo | URL) => { - const { pathname } = new URL(String(input)); - if (pathname === '/api/control-plane/device-auth/start') { - return json({ deviceCode: 'device', userCode: 'USER', verificationUri: `${CLOUD}/verify` }); - } - if (pathname === '/api/control-plane/device-auth/poll') { - return json({ - status: 'approved', - accessToken: 'adc_agent_login', - cliSession: { id: 'cli-1', refreshCredential: 'refresh-1' }, - }); - } - if (pathname === '/api/control-plane/connection-profile') { - return json({ - ok: true, - connection: { - remoteConfigProfile: { - daemonBaseUrl: 'https://bridge.example.com/agent-device', - tenant: 'acme', - runId: 'run-1', - }, - }, - }); - } - throw new Error(`unexpected request: ${pathname}`); - }), - ); -} - -/** - * Approves a device login in `argv` where the CLI session name is a directory, and requires the one - * result to be the failed write: the login the run could not save stopped it before it published - * connection state or reported success. - */ -async function expectOneFailureWhenTheLoginCannotBeSaved( - argv: string[], - prepare?: (project: string) => void, -): Promise { - stubApprovedDeviceLogin(); - const workspace = makeTempWorkspace(); - const { root, home, project } = workspace; - const stateDir = path.join(root, 'state'); - fs.mkdirSync(resolveCliSessionPath(stateDir), { recursive: true }); - prepare?.(project); - try { - const result = await runCliCapture([...argv, '--state-dir', stateDir, '--json'], { - cwd: project, - env: { - HOME: home, - AGENT_DEVICE_CLOUD_BASE_URL: CLOUD, - // A remote shell prints the verification URL and opens no browser. - SSH_TTY: '/dev/ttys001', - CI: '', - GITHUB_ACTIONS: '', - BUILDKITE: '', - }, - }); - - assert.equal(result.code, 1, result.stdout + result.stderr); - const outputs = parseJsonOutputs(result.stdout); - assert.equal(outputs.length, 1, result.stdout); - const output = outputs[0] as { success?: unknown; error?: { message?: string } }; - assert.equal(output.success, false, result.stdout); - assert.match(String(output.error?.message), /cli-session\.json/); - assert.equal(fs.existsSync(path.join(stateDir, 'remote-connections')), false); - } finally { - fs.rmSync(root, { recursive: true, force: true }); - } -} - -// Cloud discovery names the provider only after the login, so the login is saved where that provider -// is checked: before the profile is generated. -test.each([ - { route: 'connect cloud', argv: ['connect', 'cloud'] }, - { route: 'plain connect', argv: ['connect'] }, - { - route: 'connect --daemon-base-url, which discovers its profile too', - argv: ['connect', '--daemon-base-url', CLOUD_DAEMON, '--tenant', 'acme'], - }, -])( - '$route stops before it generates a profile when its login cannot be saved', - async ({ argv }) => { - await expectOneFailureWhenTheLoginCannotBeSaved([...argv, '--session', 'ci']); - }, -); - -// These routes already know their provider where they authenticate, so the auth step saves the login -// it approves: before the profile and connection record of the command that follows. -test.each([ - { - route: 'connect --remote-config', - argv: ['connect', '--remote-config', 'remote.json'], - prepare: (project: string) => { - fs.writeFileSync( - path.join(project, 'remote.json'), - JSON.stringify({ - daemonBaseUrl: CLOUD_DAEMON, - tenant: 'acme', - runId: 'run-1', - }), - ); - }, - }, - { - route: 'connect proxy', - argv: ['connect', 'proxy', '--daemon-base-url', 'https://bridge.agent-device.dev/agent-device'], - }, - { - route: 'connect through the proxy endpoint shortcut', - argv: ['connect', '--daemon-base-url', 'https://bridge.agent-device.dev/agent-device'], - }, - { - route: 'connect limrun', - argv: ['connect', 'limrun', '--daemon-base-url', CLOUD_DAEMON, '--provider-app', 'app.apk'], - }, -])( - '$route stops before it saves a connection record when its login cannot be saved', - async ({ argv, prepare }) => { - await expectOneFailureWhenTheLoginCannotBeSaved([...argv, '--session', 'ci'], prepare); - }, -); - -test('auth login answers one error when the approved login cannot be saved', async () => { - // Explicit `auth login` is outside any deferral: it saves before it reports success. - await expectOneFailureWhenTheLoginCannotBeSaved(['auth', 'login']); -}); diff --git a/src/cli/__tests__/auth-session.test.ts b/src/cli/__tests__/auth-session.test.ts index 42599c628e..1b4d87193c 100644 --- a/src/cli/__tests__/auth-session.test.ts +++ b/src/cli/__tests__/auth-session.test.ts @@ -598,12 +598,7 @@ test('a rewritten CLI session replaces the file, so a reader never sees a partia } assert.equal(readCliSession({ stateDir: tempRoot })?.id, 'session-second'); if (process.platform !== 'win32') assert.equal(fs.statSync(sessionPath).mode & 0o077, 0); - // The auth guard's own revision record stands beside the session it governs, so that directory - // holds exactly those two names and nothing else. - assert.deepEqual(fs.readdirSync(path.dirname(sessionPath)).sort(), [ - 'cli-session.json', - 'cli-session.revision.json', - ]); + assert.deepEqual(fs.readdirSync(path.dirname(sessionPath)), [path.basename(sessionPath)]); } finally { fs.rmSync(tempRoot, { recursive: true, force: true }); } diff --git a/src/cli/auth-session.ts b/src/cli/auth-session.ts index 11fb4d9e7b..3ba76c43d0 100644 --- a/src/cli/auth-session.ts +++ b/src/cli/auth-session.ts @@ -1,8 +1,6 @@ -import { AsyncLocalStorage } from 'node:async_hooks'; import fs from 'node:fs'; import path from 'node:path'; import { publishFileSync } from '@agent-device/host-kit/file'; -import { emitDiagnostic } from '@agent-device/host-kit/diagnostics'; import { AppError } from '@agent-device/kernel/errors'; import type { CliFlags } from '@agent-device/contracts/command'; import { type EnvMap } from '@agent-device/kernel/source-value'; @@ -78,96 +76,6 @@ type AuthIo = { openBrowser?: (url: string) => Promise; }; -/** - * The one guard over one state directory's auth state, shared by every write of it: an explicit - * `auth login`, an `auth logout`, and the deferred save of a `connect` login this run holds while the - * cloud names its provider. The guard is a revision record beside the session it governs, republished by - * every write of that session. An explicit auth command writes what it approves and republishes the - * revision. A held login reads the revision before its device authorization and saves only while that - * revision still stands, so the newest auth command wins: an explicit login or logout that completed - * while a connect held its login approved is never overwritten by that connect's later save. A counter is - * used rather than the stored session itself, because a logout leaves the state directory holding no - * session, which is what a first login finds too, and the two cannot tell a newer write from no write. - * - * The compare and the publish of a held login are separate filesystem calls, so an auth write landing - * between them is still overwritten. What this guard rules out is the reported shape: a write that - * finished before a held login read the revision is always seen by that read. - */ -const AUTH_REVISION_FILE_NAME = 'cli-session.revision.json'; -/** The shape of a revision record. A record of another version is unreadable, not absent. */ -const AUTH_REVISION_RECORD_VERSION = 1; - -type AuthRevisionRecord = Readonly<{ version: 1; generation: number }>; - -/** - * The auth revision of one state directory, as the guard answers it: no auth write recorded yet, a - * recorded generation, or a record the reader cannot parse. An unreadable record is unknown evidence, - * so a held login is not saved on it rather than concluding nothing changed. - */ -type AuthRevision = - | Readonly<{ state: 'absent' }> - | Readonly<{ state: 'recorded'; generation: number }> - | Readonly<{ state: 'unreadable' }>; - -/** - * A login of one `connect` run, held between its approval and the admission of the provider that run - * discovers. `revision` is the auth revision this state directory carried when the cloud approved the - * login, and the held session is saved only while that revision still stands. - */ -type PendingLogin = { - stateDir: string; - session: CliSessionRecord; - revision: AuthRevision; -}; - -const pendingLoginScope = new AsyncLocalStorage<{ pending?: PendingLogin }>(); - -/** - * Runs one command, holding a login it approves until that run's provider is admitted. Only - * `defersLogin` defers, and the CLI sets it for the one `connect` that learns its provider from the - * cloud control plane, which is the only route that can approve a login before it knows the provider. - * That route saves the pending login with {@link savePendingLoginAtAdmission} once the provider is - * admitted, or drops it with {@link discardPendingLoginAtRefusal} when the provider's plugin is - * refused. A run that ends with its login still pending, because discovery failed before any provider - * was named, saves it, so a failure unrelated to a provider does not cost the login. Every other - * route, including explicit `auth login`, saves a login as soon as it is approved. A held login is - * published only while the auth revision it captured still stands, so it never overwrites auth state - * an explicit `auth login` or `auth logout` wrote meanwhile: see {@link publishHeldLogin}. - */ -export async function withDeferredLogin( - options: { defersLogin: boolean }, - run: () => Promise, -): Promise { - if (!options.defersLogin) return await run(); - const scope: { pending?: PendingLogin } = {}; - try { - return await pendingLoginScope.run(scope, run); - } finally { - // Only a run that ended before it names a provider gets here with a pending login. - if (scope.pending) publishHeldLogin(scope.pending); - } -} - -/** - * Saves the login this run holds because its provider was just admitted. A route saves before it - * generates or publishes connection state, so a login it cannot save stops the command there. A login - * an explicit `auth login` or `auth logout` superseded while it was held is not saved and is not an - * error: the state directory already holds the auth state its caller asked for last. - */ -export function savePendingLoginAtAdmission(): void { - const scope = pendingLoginScope.getStore(); - const pending = scope?.pending; - if (scope === undefined) return; - scope.pending = undefined; - if (pending) publishHeldLogin(pending); -} - -/** Drops the login this run holds: its provider plugin was refused, so the route keeps no auth state. */ -export function discardPendingLoginAtRefusal(): void { - const scope = pendingLoginScope.getStore(); - if (scope) scope.pending = undefined; -} - export async function resolveRemoteAuthForCli(options: { command: string; flags: CliFlags; @@ -303,9 +211,6 @@ export async function loginWithDeviceAuth(options: { if (authMode === 'non-interactive') { throw buildNonInteractiveLoginError(options.commandLabel ?? 'agent-device connect', env); } - // The revision is read before the control plane is asked, so it is the answer this state directory - // gave when this login started, which is what a held login is compared with when it is saved. - const revisionAtStart = readAuthRevision(options.stateDir); const cloudBaseUrl = resolveCloudBaseUrl(env); const start = await postJson({ baseUrl: cloudBaseUrl, @@ -360,9 +265,7 @@ export async function loginWithDeviceAuth(options: { createdAt: nowIso, expiresAt: approved.cliSession?.expiresAt, }; - const scope = pendingLoginScope.getStore(); - if (scope) scope.pending = { stateDir: options.stateDir, session, revision: revisionAtStart }; - else writeCliSession({ stateDir: options.stateDir, session }); + writeCliSession({ stateDir: options.stateDir, session }); return { accessToken: approved.accessToken, expiresAt: approved.expiresAt, @@ -390,55 +293,7 @@ export function readCliSession(options: { stateDir: string }): CliSessionRecord } } -/** - * Saves the session an explicit auth command approved. The write is unconditional: an explicit login is - * the newest answer for this state directory, and recording its revision is what makes a login another - * run still holds stand down. - */ export function writeCliSession(options: { stateDir: string; session: CliSessionRecord }): void { - writeCliSessionRecord(options); - recordAuthRevision(options.stateDir); -} - -/** - * Removes the stored session on an explicit `auth logout`, and records that revision so a login another - * run holds stands down instead of signing this state directory back in. Nothing is removed and nothing - * is recorded when no session was stored, since that command changed nothing here. - */ -export function removeCliSession(options: { stateDir: string }): boolean { - const filePath = resolveCliSessionPath(options.stateDir); - if (!fs.existsSync(filePath)) return false; - fs.rmSync(filePath, { force: true }); - recordAuthRevision(options.stateDir); - return true; -} - -/** - * Saves a login this run held, only while the auth revision it read before its device authorization - * still stands. A login that no longer stands is not saved, and is not a failure of this command: the - * state directory holds the auth state its caller asked for last, which is why the stand-down is logged - * rather than thrown. The revision is recorded after the session is written, so a reader that finds the - * newer session always finds its revision too. - */ -function publishHeldLogin(pending: PendingLogin): void { - const current = readAuthRevision(pending.stateDir); - if (!sameAuthRevision(pending.revision, current)) { - emitDiagnostic({ - level: 'info', - phase: 'cli_deferred_login_superseded', - data: { - reason: current.state === 'unreadable' ? 'auth-revision-unreadable' : 'newer-auth-revision', - held: pending.revision, - current, - }, - }); - return; - } - writeCliSessionRecord({ stateDir: pending.stateDir, session: pending.session }); - recordAuthRevision(pending.stateDir); -} - -function writeCliSessionRecord(options: { stateDir: string; session: CliSessionRecord }): void { const filePath = resolveCliSessionPath(options.stateDir); fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 }); publishFileSync({ @@ -449,67 +304,11 @@ function writeCliSessionRecord(options: { stateDir: string; session: CliSessionR }); } -/** - * The auth revision this state directory's guard holds: the number of auth writes it has recorded. A - * record that cannot be read is its own answer, so a caller never mistakes unknown for unchanged. - */ -function readAuthRevision(stateDir: string): AuthRevision { - let contents: string; - try { - contents = fs.readFileSync(resolveAuthRevisionPath(stateDir), 'utf8'); - } catch (error) { - const code = (error as NodeJS.ErrnoException | null)?.code; - return code === 'ENOENT' || code === 'ENOTDIR' ? { state: 'absent' } : { state: 'unreadable' }; - } - const generation = parseAuthRevisionGeneration(contents); - return generation === undefined ? { state: 'unreadable' } : { state: 'recorded', generation }; -} - -/** Publishes the revision that follows the one held, so the newest auth write of this directory owns it. */ -function recordAuthRevision(stateDir: string): void { - const current = readAuthRevision(stateDir); - const marker: AuthRevisionRecord = { - version: AUTH_REVISION_RECORD_VERSION, - generation: current.state === 'recorded' ? current.generation + 1 : 1, - }; - publishFileSync({ - destination: resolveAuthRevisionPath(stateDir), - contents: `${JSON.stringify(marker, null, 2)}\n`, - mode: 0o600, - exactMode: true, - }); -} - -/** - * Whether a held login's reading is still the reading the guard holds. An unreadable reading on either - * side answers no: a record that cannot be read says nothing about what was written since, which is not - * proof that nothing was, so a held login is not saved on it. - */ -function sameAuthRevision(left: AuthRevision, right: AuthRevision): boolean { - if (left.state === 'absent') return right.state === 'absent'; - return ( - left.state === 'recorded' && right.state === 'recorded' && right.generation === left.generation - ); -} - -function parseAuthRevisionGeneration(contents: string): number | undefined { - let parsed: unknown; - try { - parsed = JSON.parse(contents); - } catch { - return undefined; - } - const marker = parsed as Record | null; - if (marker === null || typeof marker !== 'object') return undefined; - if (marker.version !== AUTH_REVISION_RECORD_VERSION) return undefined; - const generation = marker.generation; - return typeof generation === 'number' && Number.isSafeInteger(generation) && generation > 0 - ? generation - : undefined; -} - -function resolveAuthRevisionPath(stateDir: string): string { - return path.join(stateDir, 'auth', AUTH_REVISION_FILE_NAME); +export function removeCliSession(options: { stateDir: string }): boolean { + const filePath = resolveCliSessionPath(options.stateDir); + if (!fs.existsSync(filePath)) return false; + fs.rmSync(filePath, { force: true }); + return true; } export function resolveCliSessionPath(stateDir: string): string { diff --git a/src/cli/connect-preflight.ts b/src/cli/connect-preflight.ts index 0cc4e0c6f0..6e8fdaac68 100644 --- a/src/cli/connect-preflight.ts +++ b/src/cli/connect-preflight.ts @@ -1,37 +1,14 @@ -import type { CliFlags } from '@agent-device/contracts/command'; import type { HostEnvironment } from '@agent-device/kernel/source-value'; import { exitBeforeCommand } from './pre-command-failure.ts'; -type LoginTimingContext = { - command: string; - positionals: readonly string[]; - /** The run's flags, after every source that can carry one was resolved. */ - flags: CliFlags; -}; - -/** - * What the CLI answers about a `connect` before it runs that command: whether the command holds its - * login, and whether the provider it names is already refused. Both are answered from the plugin - * admission owner, which loads only when a `connect` needs it. - */ -const connectAdmission = () => import('./connection/provider-admission.ts'); - -/** Whether this run holds its login until the provider it discovers is admitted. */ -export async function defersLoginUntilProviderAdmission( - context: LoginTimingContext, -): Promise { - if (context.command !== 'connect') return false; - const { defersConnectLogin } = await connectAdmission(); - return defersConnectLogin(context); -} - /** Refuses a provider `connect` names before this run reads a credential, or goes on to its parse. */ export async function admitConnectProviderOrExit( argv: readonly string[], host: HostEnvironment, options: { jsonRequested: boolean; debugEnabled: boolean }, ): Promise { - const { admitConnectProviderNamedInArguments } = await connectAdmission(); + const { admitConnectProviderNamedInArguments } = + await import('./connection/provider-admission.ts'); try { await admitConnectProviderNamedInArguments(argv, host); } catch (error) { diff --git a/src/cli/connection/cloud-profile-store-refusal.test.ts b/src/cli/connection/cloud-profile-store-refusal.test.ts deleted file mode 100644 index 68408c6305..0000000000 --- a/src/cli/connection/cloud-profile-store-refusal.test.ts +++ /dev/null @@ -1,194 +0,0 @@ -import { afterEach, beforeEach, test, vi } from 'vitest'; -import assert from 'node:assert/strict'; -import fs from 'node:fs'; -import path from 'node:path'; -import { makeTempWorkspace } from '@agent-device/test-kit'; -import { runCliCapture } from '../../__tests__/cli-capture.ts'; -import { parseJsonOutputs } from '../../__tests__/test-utils/cli-json-outputs.ts'; -import { resolveCliSessionPath } from '../auth-session.ts'; - -// Limrun answers no case here as an installed plugin. Each case makes the plugin store refuse the -// provider, or select a Limrun package that cannot load, so the control plane's -// `leaseProvider: "limrun"` is refused when the cloud route admits it — after the login was approved. -const CLOUD = 'https://cloud.example'; -const LIMRUN_PACKAGE = '@agent-device/limrun'; -const terminals = [process.stdin, process.stdout] as const; -const originalTty = terminals.map((stream) => Object.getOwnPropertyDescriptor(stream, 'isTTY')); - -beforeEach(() => { - for (const stream of terminals) { - Object.defineProperty(stream, 'isTTY', { value: true, configurable: true }); - } -}); - -afterEach(() => { - terminals.forEach((stream, index) => { - const descriptor = originalTty[index]; - if (descriptor) Object.defineProperty(stream, 'isTTY', descriptor); - else delete (stream as { isTTY?: boolean }).isTTY; - }); - vi.unstubAllGlobals(); -}); - -/** The control plane: an approved device login, then a connection profile naming Limrun. */ -function stubControlPlaneNamingLimrun(): void { - const json = (body: unknown) => - new Response(JSON.stringify(body), { - status: 200, - headers: { 'content-type': 'application/json' }, - }); - vi.stubGlobal( - 'fetch', - vi.fn(async (input: RequestInfo | URL) => { - const { pathname } = new URL(String(input)); - if (pathname === '/api/control-plane/device-auth/start') { - return json({ deviceCode: 'device', userCode: 'USER', verificationUri: `${CLOUD}/verify` }); - } - if (pathname === '/api/control-plane/device-auth/poll') { - return json({ - status: 'approved', - accessToken: 'adc_agent_login', - cliSession: { id: 'cli-1', refreshCredential: 'refresh-1' }, - }); - } - if (pathname === '/api/control-plane/connection-profile') { - return json({ - ok: true, - connection: { - remoteConfigProfile: { - daemonBaseUrl: 'https://bridge.example.com/agent-device', - tenant: 'acme', - runId: 'run-1', - leaseProvider: 'limrun', - }, - }, - }); - } - throw new Error(`unexpected request: ${pathname}`); - }), - ); -} - -/** The user config the plugin store cannot read, which the CLI flag reader ignores. */ -function writeUnreadablePluginStore(pluginHome: string): void { - fs.writeFileSync(path.join(pluginHome, 'config.json'), JSON.stringify({ plugins: [] })); -} - -/** A Limrun selection whose entry throws as the store loads it. */ -function selectUnusableLimrunPackage(pluginHome: string): void { - const installation = '11111111-1111-4111-8111-111111111111'; - const directory = path.join(pluginHome, 'plugins', installation, 'node_modules', LIMRUN_PACKAGE); - fs.mkdirSync(directory, { recursive: true }); - fs.writeFileSync( - path.join(directory, 'package.json'), - JSON.stringify({ - name: LIMRUN_PACKAGE, - version: '2.0.0', - type: 'module', - engines: { node: '>=22.12' }, - 'agent-device': { apiVersion: 3, provider: 'limrun' }, - exports: { './agent-device': { import: './plugin.mjs' } }, - }), - ); - fs.writeFileSync(path.join(directory, 'plugin.mjs'), 'throw new Error("Limrun is not ready.");'); - fs.writeFileSync( - path.join(pluginHome, 'config.json'), - JSON.stringify({ plugins: { [LIMRUN_PACKAGE]: { installation } } }), - ); -} - -const CLOUD_ROUTES = [ - { route: 'connect cloud', argv: ['cloud'] }, - { route: 'plain connect', argv: [] }, - { - route: 'connect --daemon-base-url, where the generic auth step logs in', - argv: ['--daemon-base-url', 'https://bridge.agent-device.dev/api', '--tenant', 'acme'], - }, -]; - -async function connectOnCloudRoute(argv: string[], preparePluginHome: (home: string) => void) { - const { root, home, project } = makeTempWorkspace(); - const pluginHome = path.join(root, 'plugin-home'); - fs.mkdirSync(pluginHome, { recursive: true }); - preparePluginHome(pluginHome); - const stateDir = path.join(root, 'state'); - const result = await runCliCapture( - ['connect', ...argv, '--session', 'ci', '--state-dir', stateDir, '--json'], - { - cwd: project, - env: { - HOME: home, - AGENT_DEVICE_HOME: pluginHome, - AGENT_DEVICE_CLOUD_BASE_URL: CLOUD, - // A remote shell prints the verification URL and opens no browser. - SSH_TTY: '/dev/ttys001', - CI: '', - GITHUB_ACTIONS: '', - BUILDKITE: '', - }, - }, - ); - return { root, stateDir, result }; -} - -/** The one JSON result the run printed, as a provider-plugin refusal. */ -function refusalDetails( - stdout: string, - reason: string, -): { - package?: string; - failedPlugins: Array<{ error?: { message?: string } }>; -} { - const outputs = parseJsonOutputs(stdout); - assert.equal(outputs.length, 1, stdout); - const { error } = outputs[0] as { - error: { code: string; details: Record }; - }; - assert.equal(error.code, 'UNSUPPORTED_OPERATION'); - assert.equal(error.details.reason, reason); - return error.details as unknown as { - package?: string; - failedPlugins: Array<{ error?: { message?: string } }>; - }; -} - -/** The refused route wrote nothing: no CLI session, no `auth` directory, no connection state. */ -function assertKeptNoConnectionOrAuthState(stateDir: string): void { - assert.equal(fs.existsSync(resolveCliSessionPath(stateDir)), false, 'auth/cli-session.json'); - assert.equal(fs.existsSync(path.join(stateDir, 'auth')), false, 'auth directory'); - assert.equal( - fs.existsSync(path.join(stateDir, 'remote-connections')), - false, - 'remote-connections directory', - ); -} - -test.each(CLOUD_ROUTES)( - '$route with an unreadable plugin store discards the login Limrun discovery refused', - async ({ argv }) => { - stubControlPlaneNamingLimrun(); - const { root, stateDir, result } = await connectOnCloudRoute(argv, writeUnreadablePluginStore); - - assert.equal(result.code, 1, result.stdout + result.stderr); - const details = refusalDetails(result.stdout, 'plugin-unavailable'); - // The store's own repair instruction, kept over the generic install guidance. - assert.ok(details.failedPlugins.length > 0, result.stdout); - assert.match(String(details.failedPlugins[0]?.error?.message), /Plugin config/); - assertKeptNoConnectionOrAuthState(stateDir); - fs.rmSync(root, { recursive: true, force: true }); - }, -); - -test.each(CLOUD_ROUTES)( - '$route with a Limrun package that fails to load discards the refused login', - async ({ argv }) => { - stubControlPlaneNamingLimrun(); - const { root, stateDir, result } = await connectOnCloudRoute(argv, selectUnusableLimrunPackage); - - assert.equal(result.code, 1, result.stdout + result.stderr); - const details = refusalDetails(result.stdout, 'plugin-unavailable'); - assert.equal(details.package, LIMRUN_PACKAGE); - assertKeptNoConnectionOrAuthState(stateDir); - fs.rmSync(root, { recursive: true, force: true }); - }, -); diff --git a/src/cli/connection/cloud-profile.ts b/src/cli/connection/cloud-profile.ts index e6afff2265..d134b5302b 100644 --- a/src/cli/connection/cloud-profile.ts +++ b/src/cli/connection/cloud-profile.ts @@ -2,13 +2,8 @@ import type { RemoteConfigProfile } from '@agent-device/remote/remote-config-sch import { AppError } from '@agent-device/kernel/errors'; import type { CliFlags } from '@agent-device/contracts/command'; import { CLOUD_LEASE_PROVIDER } from '@agent-device/contracts/lease-scope'; -import { isProviderPluginRefusal } from '@agent-device/contracts/plugin-installation'; import { type EnvMap } from '@agent-device/kernel/source-value'; -import { - discardPendingLoginAtRefusal, - resolveCloudAccessForConnect, - savePendingLoginAtAdmission, -} from '../auth-session.ts'; +import { resolveCloudAccessForConnect } from '../auth-session.ts'; import { readCloudJsonResponse } from '../cloud-response.ts'; import { persistAndResolveGeneratedProfile } from './generated-config.ts'; import { buildConnectClientId } from './client-id.ts'; @@ -47,8 +42,8 @@ export async function resolveCloudConnectProfile(options: { fetchImpl: options.fetchImpl, }); // The control plane chose the provider. It is admitted here, before this route generates or writes - // any profile or connection record, so a provider whose plugin is missing or broken leaves nothing - // behind, and so does a login this run approved but cannot save. + // any profile or connection record, so a provider whose plugin is missing or broken leaves no + // connection state behind. await admitDiscoveredProvider(profile.leaseProvider, options.env); const clientId = buildConnectClientId( options.stateDir, @@ -78,22 +73,13 @@ export async function resolveCloudConnectProfile(options: { * Checks the provider the connection profile names, right after the control plane answers with it. * Limrun is checked here: the core ships no Limrun runtime, so only its plugin can supply it, and a * route that has no working plugin for it writes nothing. Any other provider name keeps the base - * behavior of this route, which saves the profile and verifies it as the cloud service does. A run - * that approved a login saves it at this point, before any profile or connection record is generated, - * so a login it cannot save stops the command there; a run whose Limrun plugin is refused keeps no - * auth state. + * behavior of this route, which saves the profile and verifies it as the cloud service does. */ async function admitDiscoveredProvider( provider: string | undefined, env: NodeJS.ProcessEnv, ): Promise { - try { - if (requiresOwnProviderAdmission(provider)) await primeProviderConnection(provider, env); - } catch (error) { - if (isProviderPluginRefusal(error)) discardPendingLoginAtRefusal(); - throw error; - } - savePendingLoginAtAdmission(); + if (requiresOwnProviderAdmission(provider)) await primeProviderConnection(provider, env); } async function fetchConnectionProfile(options: { diff --git a/src/cli/connection/connect-provider-adapters.ts b/src/cli/connection/connect-provider-adapters.ts index 60fc8b5cc1..a2ddec61f2 100644 --- a/src/cli/connection/connect-provider-adapters.ts +++ b/src/cli/connection/connect-provider-adapters.ts @@ -11,7 +11,6 @@ import { profileToCliFlags } from '../remote-config-flags.ts'; import { isConnectProviderName, primeProviderConnection, - usesProxyConnectShortcut, type ConnectProvider, } from './provider-policy.ts'; import { withPluginConnection } from '@agent-device/plugins/load'; @@ -113,7 +112,7 @@ export async function resolveConnectProviderProfile(options: { }; } const provider = - options.provider ?? (usesProxyConnectShortcut(options.flags) ? 'proxy' : 'cloud'); + options.provider ?? (shouldUseProxyConnectShortcut(options.flags) ? 'proxy' : 'cloud'); const context = { flags: options.flags, stateDir: options.stateDir, @@ -194,3 +193,15 @@ export async function verifyResolvedConnectProvider( const connection = await providerConnection(resolved.provider, host); return await connection.verify(context); } + +function shouldUseProxyConnectShortcut(flags: CliFlags): boolean { + if (!flags.daemonBaseUrl || flags.tenant || flags.runId || flags.leaseId || flags.leaseBackend) { + return false; + } + try { + const url = new URL(flags.daemonBaseUrl); + return url.pathname.replace(/\/+$/, '').endsWith('/agent-device'); + } catch { + return false; + } +} diff --git a/src/cli/connection/provider-admission.ts b/src/cli/connection/provider-admission.ts index d307a6e4be..6252aebb89 100644 --- a/src/cli/connection/provider-admission.ts +++ b/src/cli/connection/provider-admission.ts @@ -1,14 +1,12 @@ import type { CliFlags } from '@agent-device/contracts/command'; import type { RemoteConnectionRequestMetadata } from '@agent-device/remote/remote-connection-state'; import type { HostEnvironment } from '@agent-device/kernel/source-value'; -import { CLOUD_LEASE_PROVIDER } from '@agent-device/contracts/lease-scope'; import { readRemoteConfigFile } from '@agent-device/remote/remote-config-core'; import { parseRawArgs } from '../parser/args.ts'; import { connectionLeaseProvider, primeProviderConnection, requiresOwnProviderAdmission, - usesProxyConnectShortcut, } from './provider-policy.ts'; type AdmissionContext = Readonly<{ @@ -55,27 +53,6 @@ export async function admitConnectProviderNamedInArguments( await primeProviderConnection(provider, host.env); } -/** - * Whether `connect` holds a login it approves until the provider it discovers is admitted. - * - * Only the route that reads its profile from the cloud control plane learns its provider after it - * authenticates, and so is the one that can approve a login that provider then refuses. A `connect` - * that names a provider, or passes an explicit profile, admits that provider before it authenticates, - * so neither can hold a refused login. - */ -export function defersConnectLogin(context: { - command: string; - flags: CliFlags; - positionals: readonly string[]; -}): boolean { - if (context.command !== 'connect') return false; - const namedProvider = context.positionals[0]; - if (namedProvider !== undefined) return namedProvider === CLOUD_LEASE_PROVIDER; - if (context.flags.remoteConfig !== undefined) return false; - // A daemon whose URL is its own proxy endpoint is connected directly, without a profile. - return !usesProxyConnectShortcut(context.flags); -} - function connectProviderNamedInArguments( argv: readonly string[], host: HostEnvironment, diff --git a/src/cli/connection/provider-policy.ts b/src/cli/connection/provider-policy.ts index 78019c21bf..6d69578f25 100644 --- a/src/cli/connection/provider-policy.ts +++ b/src/cli/connection/provider-policy.ts @@ -1,5 +1,4 @@ import type { ConnectionProviderCapabilities } from '@agent-device/contracts/remote'; -import type { CliFlags } from '@agent-device/contracts/command'; import { pluginConnectionInventory, pluginConnectionCapabilities, @@ -85,22 +84,6 @@ export function connectProviderNamesForError(env: NodeJS.ProcessEnv = process.en : `${names}. Plugins that failed to load: ${failures.join('; ')}`; } -/** - * The `connect` shortcut that connects straight to a named proxy daemon through its own proxy - * endpoint, instead of reading a connection profile from the cloud control plane. - */ -export function usesProxyConnectShortcut(flags: CliFlags): boolean { - if (!flags.daemonBaseUrl || flags.tenant || flags.runId || flags.leaseId || flags.leaseBackend) { - return false; - } - try { - const url = new URL(flags.daemonBaseUrl); - return url.pathname.replace(/\/+$/, '').endsWith('/agent-device'); - } catch { - return false; - } -} - /** * Whether a route admits `provider` itself before it authenticates or writes anything. The core ships * no Limrun runtime, so only the plugin supplies that provider, and a route that selects it refuses From 5911afd405564cdd72ac83d8d376aea3b2535954 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sun, 22 Nov 2026 09:12:00 +0100 Subject: [PATCH 18/26] docs(website): list Limrun with the plugin providers on the Run anywhere card --- website/src/site/content.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/src/site/content.ts b/website/src/site/content.ts index 603e019f35..5fb2113d2a 100644 --- a/website/src/site/content.ts +++ b/website/src/site/content.ts @@ -474,8 +474,8 @@ export const cloud = { icon: 'cube', label: 'Device clouds', title: 'On hosted devices', - body: 'The same commands drive Limrun devices with built-in support, AWS Device Farm, BrowserStack, and TestMu AI through their provider plugins, and Expo Simulators on EAS.', - cmd: 'agent-device connect limrun --platform ios', + body: 'The same commands drive Limrun, AWS Device Farm, BrowserStack, and TestMu AI devices through their provider plugins, and Expo Simulators on EAS. Install `@agent-device/limrun`, then run `agent-device connect limrun --platform ios`.', + cmd: 'agent-device plugins add @agent-device/limrun', href: docs.clouds, }, ] as { icon: IconName; label: string; title: string; body: string; cmd: string; href: string }[], From 1db7701ca7fcf0096b07ef51e24b631212416ddf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sun, 22 Nov 2026 11:38:06 +0100 Subject: [PATCH 19/26] fix(website): install the Limrun plugin the 0.22 nightly reader needs The Run anywhere card printed the bare package name, which the plugin store resolves to latest: the runtime-free placeholder. Use the nightly selector the docs and the CLI hints use, and point readers at the printed command. --- website/src/site/content.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/src/site/content.ts b/website/src/site/content.ts index 5fb2113d2a..cbc10dd81b 100644 --- a/website/src/site/content.ts +++ b/website/src/site/content.ts @@ -474,8 +474,8 @@ export const cloud = { icon: 'cube', label: 'Device clouds', title: 'On hosted devices', - body: 'The same commands drive Limrun, AWS Device Farm, BrowserStack, and TestMu AI devices through their provider plugins, and Expo Simulators on EAS. Install `@agent-device/limrun`, then run `agent-device connect limrun --platform ios`.', - cmd: 'agent-device plugins add @agent-device/limrun', + body: 'The same commands drive Limrun, AWS Device Farm, BrowserStack, and TestMu AI devices through their provider plugins, and Expo Simulators on EAS. Install the Limrun plugin for your release, then run `agent-device connect limrun --platform ios`. A missing plugin answers with the install command for your release; use it.', + cmd: 'agent-device plugins add @agent-device/limrun@nightly-0.22', href: docs.clouds, }, ] as { icon: IconName; label: string; title: string; body: string; cmd: string; href: string }[], From 0d5dc6e16f62d9753536e31e8b04938e25ee01ac Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sun, 22 Nov 2026 11:38:09 +0100 Subject: [PATCH 20/26] fix(cli): let a remote daemon answer for a provider this host lacks A saved or explicit Limrun connection whose daemon is configured elsewhere was refused with plugin-not-installed before it authenticated or dispatched, which no base release did. The plugin is needed where the device is driven: keep the refusal for a direct connect and for a connection with no configured daemon, and let the daemon's own provider registration decide runtime admission otherwise. The connection's metadata is still read and saved either way. --- src/cli.ts | 4 +- src/cli/commands/connection-runtime.ts | 15 ++- src/cli/commands/connection.ts | 10 +- src/cli/connection/provider-admission.test.ts | 120 +++++++++++++++++- src/cli/connection/provider-admission.ts | 12 +- src/cli/connection/provider-policy.ts | 32 ++++- src/commands/schema/cli-help.ts | 2 +- website/docs/docs/plugins.md | 4 + 8 files changed, 187 insertions(+), 12 deletions(-) diff --git a/src/cli.ts b/src/cli.ts index 8fe31712d3..60f01c5569 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -454,12 +454,14 @@ async function resolveRemoteContext( ctx.parsedBatchSteps = readBatchSteps(ctx.flags); } - // A missing provider plugin answers with its install command before any login or auth state. + // A missing provider plugin answers with its install command before any login or auth state, unless + // this command dispatches to a configured remote daemon, whose own registration supplies it. if (ctx.command === 'connect' || ctx.effectiveFlags.remoteConfig) { const { admitConnectionProvider } = await import('./cli/connection/provider-admission.ts'); await admitConnectionProvider({ ...ctx, materializes: shouldMaterializeRemoteConnection(ctx.command), + daemonBaseUrl: ctx.effectiveFlags.daemonBaseUrl, }); } diff --git a/src/cli/commands/connection-runtime.ts b/src/cli/commands/connection-runtime.ts index b6e51cb3cb..3ea2767ae2 100644 --- a/src/cli/commands/connection-runtime.ts +++ b/src/cli/commands/connection-runtime.ts @@ -18,8 +18,10 @@ import type { CliFlags } from '@agent-device/contracts/command'; import type { AgentDeviceClient } from '@agent-device/command-surface'; import { connectionLeaseProvider, + connectionNeedsLocalProviderRuntime, connectionProviderCapabilities, primeProviderConnection, + primeProviderConnectionWithoutRefusal, } from '../connection/provider-policy.ts'; import { profileToCliFlags } from '../remote-config-flags.ts'; import { @@ -86,10 +88,15 @@ export async function materializeRemoteConnectionForCommand(options: { ); } - await primeProviderConnection( - connectionLeaseProvider(existingState, remoteConfig.profile.leaseProvider), - host.env, - ); + // A connection driven by a configured remote daemon needs no plugin here: that daemon's own + // provider registration supplies the runtime, and this command only leases and dispatches. Its + // connection metadata still has to be read and saved, so the profile is loaded either way. + const provider = connectionLeaseProvider(existingState, remoteConfig.profile.leaseProvider); + if (connectionNeedsLocalProviderRuntime(mergedFlags.daemonBaseUrl, host.env)) { + await primeProviderConnection(provider, host.env); + } else { + await primeProviderConnectionWithoutRefusal(provider, host.env); + } const state = existingState ?? createRemoteConnectionStateFromFlags( diff --git a/src/cli/commands/connection.ts b/src/cli/commands/connection.ts index a17cc42c66..5023186f72 100644 --- a/src/cli/commands/connection.ts +++ b/src/cli/commands/connection.ts @@ -21,9 +21,11 @@ import { AppError, errorMessage } from '@agent-device/kernel/errors'; import { isInactiveLeaseError } from '@agent-device/contracts/lease-scope'; import { connectProviderNamesForError, + connectionNeedsLocalProviderRuntime, connectionProviderCapabilities, isConnectProviderName, primeProviderConnection, + primeProviderConnectionWithoutRefusal, unavailableConnectPluginError, type ConnectProvider, } from '../connection/provider-policy.ts'; @@ -409,7 +411,13 @@ export const connectionCommand: ClientCommandHandler = async ({ positionals, fla await writeNoRemoteConnectionOutput(flags, session); return true; } - await primeProviderConnection(state.leaseProvider, host.env); + // A connection whose daemon is remote is answered there, so its provider's plugin is not needed to + // read this record; the plugin's own declaration is used when this host has it. + if (connectionNeedsLocalProviderRuntime(state.daemon?.baseUrl, host.env)) { + await primeProviderConnection(state.leaseProvider, host.env); + } else { + await primeProviderConnectionWithoutRefusal(state.leaseProvider, host.env); + } const leasePreparation = buildLeasePreparationNotice(state, undefined, host.env); const runtimePreparation = buildRuntimePreparationNoticeFromState(state, host); await writeCommandOutput( diff --git a/src/cli/connection/provider-admission.test.ts b/src/cli/connection/provider-admission.test.ts index 3992ac8af1..9c4d4f8577 100644 --- a/src/cli/connection/provider-admission.test.ts +++ b/src/cli/connection/provider-admission.test.ts @@ -116,16 +116,130 @@ function storedLimrunConnection() { return { root, home, project, stateDir }; } -test('a device command on a stored Limrun connection refuses the missing plugin before authentication', async () => { +// The rule: this host needs the plugin only for a connection it drives itself. A connection whose +// daemon is configured elsewhere is answered by that daemon's own provider registration, so the +// command authenticates and dispatches. +test('a device command on a stored Limrun connection with a remote daemon dispatches without the plugin', async () => { const { root, home, project, stateDir } = storedLimrunConnection(); + const token = 'adc_live_remote_daemon_token_1348'; + + const result = await runCliCapture( + ['snapshot', '--session', 'limrun-a', '--state-dir', stateDir, '--json'], + { + cwd: project, + env: { HOME: home, AGENT_DEVICE_DAEMON_AUTH_TOKEN: token }, + sendToDaemon: async (req) => + req.command === 'lease_heartbeat' || req.command === 'lease_allocate' + ? { + ok: true, + data: { + lease: { + leaseId: 'lease-limrun-a', + tenantId: 'team-a', + runId: 'run-a', + backend: 'android-instance', + leaseProvider: 'limrun', + }, + }, + } + : req.command === 'snapshot' + ? { ok: true, data: { nodes: [], truncated: false } } + : { ok: true, data: {} }, + }, + ); + + assert.equal(result.code, null, result.stdout + result.stderr); + assert.ok(vi.mocked(resolveRemoteAuthForCli).mock.calls.length > 0, 'auth must proceed'); + assert.deepEqual( + result.calls.map((call) => call.command), + ['lease_allocate', 'snapshot'], + ); + const snapshot = JSON.parse(result.stdout); + assert.equal(snapshot.success, true, result.stdout); + fs.rmSync(root, { recursive: true, force: true }); +}); + +test('an explicit Limrun remote config with a remote daemon dispatches without the plugin', async () => { + const { root, home, project } = makeTempWorkspace(); + const stateDir = path.join(root, 'state'); + const remoteConfig = limrunProfile(project); + const token = 'adc_live_remote_daemon_token_1348'; + + const result = await runCliCapture( + [ + 'snapshot', + '--session', + 'ci', + '--remote-config', + remoteConfig, + '--state-dir', + stateDir, + '--json', + ], + { + cwd: project, + env: { HOME: home, AGENT_DEVICE_DAEMON_AUTH_TOKEN: token }, + sendToDaemon: async (req) => + req.command === 'lease_allocate' || req.command === 'lease_heartbeat' + ? { + ok: true, + data: { + lease: { + leaseId: 'lease-ci', + tenantId: 'team-a', + runId: 'run-a', + backend: 'android-instance', + leaseProvider: 'limrun', + }, + }, + } + : { ok: true, data: {} }, + }, + ); + + assert.equal(result.code, null, result.stdout + result.stderr); + assert.ok(vi.mocked(resolveRemoteAuthForCli).mock.calls.length > 0, 'auth must proceed'); + assert.deepEqual( + result.calls.map((call) => call.command), + ['lease_allocate', 'snapshot'], + ); + fs.rmSync(root, { recursive: true, force: true }); +}); + +// A connection with no daemon configured elsewhere is driven from this process, and only the plugin +// can drive it: that route still refuses before it authenticates or dispatches. +test('a stored Limrun connection with no configured daemon refuses the missing plugin before authentication', async () => { + const { root, home, project } = makeTempWorkspace(); + const stateDir = path.join(root, 'state'); + const remoteConfig = limrunProfile(project); + const profile = JSON.parse(fs.readFileSync(remoteConfig, 'utf8')) as Record; + delete profile.daemonBaseUrl; + fs.writeFileSync(remoteConfig, JSON.stringify(profile)); + const now = new Date().toISOString(); + writeRemoteConnectionState({ + stateDir, + state: { + version: 1, + session: 'limrun-local', + remoteConfigPath: remoteConfig, + remoteConfigHash: hashRemoteConfigFile(remoteConfig), + tenant: 'team-a', + runId: 'run-a', + leaseBackend: 'android-instance', + leaseProvider: 'limrun', + platform: 'android', + connectedAt: now, + updatedAt: now, + }, + }); const before = snapshotTree(stateDir); const result = await runCliCapture( - ['apps', '--session', 'limrun-a', '--state-dir', stateDir, '--json'], + ['snapshot', '--session', 'limrun-local', '--state-dir', stateDir, '--json'], { cwd: project, env: { HOME: home } }, ); - assert.equal(result.code, 1); + assert.equal(result.code, 1, result.stdout + result.stderr); assertLimrunPluginMissing(result.stdout); assert.equal(vi.mocked(resolveRemoteAuthForCli).mock.calls.length, 0); assert.equal(result.calls.length, 0); diff --git a/src/cli/connection/provider-admission.ts b/src/cli/connection/provider-admission.ts index 6252aebb89..c01c60e45c 100644 --- a/src/cli/connection/provider-admission.ts +++ b/src/cli/connection/provider-admission.ts @@ -5,7 +5,9 @@ import { readRemoteConfigFile } from '@agent-device/remote/remote-config-core'; import { parseRawArgs } from '../parser/args.ts'; import { connectionLeaseProvider, + connectionNeedsLocalProviderRuntime, primeProviderConnection, + primeProviderConnectionWithoutRefusal, requiresOwnProviderAdmission, } from './provider-policy.ts'; @@ -18,6 +20,8 @@ type AdmissionContext = Readonly<{ connectionDefaults: { connection?: RemoteConnectionRequestMetadata } | null; /** Whether the command materializes its remote connection. Cleanup commands do not. */ materializes: boolean; + /** The daemon this command dispatches to, once the stored connection and profile are merged. */ + daemonBaseUrl: string | undefined; }>; /** @@ -25,6 +29,9 @@ type AdmissionContext = Readonly<{ * authenticates: a provider whose plugin cannot supply it refuses with its install or repair * guidance, so no login starts and no auth state is written. Cleanup commands admit no provider, so * they work after a plugin is removed. `connect` admits its own provider earlier, where it names it. + * A command that dispatches to a configured remote daemon is not driven by this host's plugin: the + * daemon's own provider registration answers for the provider there, so this host loads its plugin + * when it has one and proceeds when it does not. */ export async function admitConnectionProvider(context: AdmissionContext): Promise { if (!context.materializes) return; @@ -32,9 +39,12 @@ export async function admitConnectionProvider(context: AdmissionContext): Promis context.connectionDefaults?.connection, context.remoteConfigLeaseProvider, ); - if (requiresOwnProviderAdmission(provider)) { + if (!requiresOwnProviderAdmission(provider)) return; + if (connectionNeedsLocalProviderRuntime(context.daemonBaseUrl, context.host.env)) { await primeProviderConnection(provider, context.host.env); + return; } + await primeProviderConnectionWithoutRefusal(provider, context.host.env); } /** diff --git a/src/cli/connection/provider-policy.ts b/src/cli/connection/provider-policy.ts index 6d69578f25..670539c3e8 100644 --- a/src/cli/connection/provider-policy.ts +++ b/src/cli/connection/provider-policy.ts @@ -62,6 +62,21 @@ export async function primeProviderConnection( if (unavailable) throw unavailable; } +/** + * Loads the plugin store and reads a provider's declared capabilities, without refusing a provider + * this host has no working plugin for. A command that dispatches to a configured remote daemon uses + * it where the daemon's own provider registration answers for the provider, so a plugin this host + * lacks is not that command's answer; the plugin is still read when the host has it, so a connection + * keeps the capabilities its provider declares. + */ +export async function primeProviderConnectionWithoutRefusal( + provider: string | undefined, + env: NodeJS.ProcessEnv = process.env, +): Promise { + if (provider === undefined || ROUTING_PROVIDER_IDENTITIES.includes(provider)) return; + await primePluginConnections(env); +} + export function isConnectProviderName( value: string | undefined, env: NodeJS.ProcessEnv = process.env, @@ -86,7 +101,7 @@ export function connectProviderNamesForError(env: NodeJS.ProcessEnv = process.en /** * Whether a route admits `provider` itself before it authenticates or writes anything. The core ships - * no Limrun runtime, so only the plugin supplies that provider, and a route that selects it refuses + * no Limrun runtime, so only the plugin supplies that provider, and a route that needs it here refuses * it early. Every other provider name keeps this release's starting behavior: the connect handler * admits a named provider, and the adapter that reads a profile verifies the provider it names. */ @@ -94,6 +109,21 @@ export function requiresOwnProviderAdmission(provider: string | undefined): bool return provider === LIMRUN.provider; } +/** + * Whether a command on a remote connection needs the provider's plugin in this process. A configured + * remote daemon owns its own provider registration and answers for the provider, so a command that + * dispatches there needs no local plugin: it authenticates and sends its request. A connection with + * no configured daemon is driven from here, where the plugin is the only thing that can drive it. + * The daemon client treats any configured base URL as a remote daemon, so the test is its own: a + * base URL is set. + */ +export function connectionNeedsLocalProviderRuntime( + daemonBaseUrl: string | undefined, + env: NodeJS.ProcessEnv, +): boolean { + return (daemonBaseUrl ?? env.AGENT_DEVICE_DAEMON_BASE_URL) === undefined; +} + export function unavailableConnectPluginError( provider: string, env: NodeJS.ProcessEnv, diff --git a/src/commands/schema/cli-help.ts b/src/commands/schema/cli-help.ts index dfb6b1e2a4..4286b8e673 100644 --- a/src/commands/schema/cli-help.ts +++ b/src/commands/schema/cli-help.ts @@ -488,7 +488,7 @@ Providers: Limrun (plugin, install separately): agent-device connect limrun verifies access to the selected iOS or Android instance service, then stores a local provider profile. It does not create an instance. Revyl (plugin, install separately): agent-device connect revyl verifies credentials against the Revyl backend, then stores a local provider profile with the platform, optional --device model and --provider-os-version, and a required --provider-app https URL: Revyl downloads and installs that build when it starts the device. It does not rent a device. -Plugin installation: the lines below name the plugin each provider needs, and plugin help is available before installation. plugins list --json reports your installed plugins. A missing plugin returns reason plugin-not-installed with its installation command; a selected plugin that cannot supply the provider returns plugin-unavailable instead. After changing plugins, close sessions and stop an existing local daemon with the same --state-dir before the next device command. +Plugin installation: the lines below name the plugin each provider needs, and plugin help is available before installation. plugins list --json reports your installed plugins. A missing plugin returns reason plugin-not-installed with its installation command; a selected plugin that cannot supply the provider returns plugin-unavailable instead. A plugin is needed where the device is driven: a command that dispatches to a configured remote daemon is answered by that daemon's own plugins. After changing plugins, close sessions and stop an existing local daemon with the same --state-dir before the next device command. ${providerPluginHelp(coreVersion)} After direct-provider connect: diff --git a/website/docs/docs/plugins.md b/website/docs/docs/plugins.md index 163496a7fe..5f3174eac4 100644 --- a/website/docs/docs/plugins.md +++ b/website/docs/docs/plugins.md @@ -21,6 +21,10 @@ command and tells you to retry your original command. With `--json`, the error h If the plugin is selected but unavailable, the reason is `plugin-unavailable`; run `agent-device plugins list --json` to inspect it, then fix its configuration or update the package. +A plugin is needed on the host that runs the device. A device command that sends its request to a +configured remote daemon, such as a saved cloud or proxy connection, is answered by that daemon and +its own plugins, so the host you type on needs no plugin. + Use a full npm package name, optionally with `@version` or `@tag`. `update` keeps valid version constraints and options, including when it repairs a damaged selection. To change a constraint, run `add @`; to remove it, run `add ` without a suffix. Each installation lives in an npm project with a lockfile under `AGENT_DEVICE_HOME` (default `~/.agent-device`), and that directory's `config.json` records the selection. Plugin commands leave other settings in `config.json` unchanged. Project config and `--config` cannot select plugins. This home is independent of `--state-dir` and `AGENT_DEVICE_STATE_DIR`. From 010c6d4a409d5083c0536df890b376666b953978 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sun, 22 Nov 2026 11:38:13 +0100 Subject: [PATCH 21/26] fix(provider-limrun): keep a verification failure's cause in the plugin The Limrun SDK echoes a request body in its error message, so an endpoint that answers a verification with an unlabeled body naming the API key put that key in the cause the CLI prints, which pattern redaction cannot see. Answer with the typed verification error, its status and hint, and carry no cause. --- .../src/connection-verification.test.ts | 42 ++++++++++++++++++- .../src/connection-verification.ts | 27 +++++------- 2 files changed, 51 insertions(+), 18 deletions(-) diff --git a/packages/provider-limrun/src/connection-verification.test.ts b/packages/provider-limrun/src/connection-verification.test.ts index c8bce6b516..ec6f1dccbf 100644 --- a/packages/provider-limrun/src/connection-verification.test.ts +++ b/packages/provider-limrun/src/connection-verification.test.ts @@ -84,6 +84,44 @@ test('Limrun verification classifies authentication failures', async () => { ); }); +// The CLI prints an error's `cause`, and core redacts only by pattern: a body that echoes a +// credential without a recognizable key name survives it. These wrappers answer with their own typed +// summary, status and hint, so nothing the endpoint said leaves them. +test('Limrun verification answers a service failure without the SDK error it wraps', async () => { + mockState.androidList.mockRejectedValueOnce( + Object.assign( + new Error( + 'Unexpected server response: 500 {"detail":"key lim_verification_secret_9 denied"}', + ), + { status: 500 }, + ), + ); + + await assert.rejects( + verifyLimrunConnection({ + apiKey: 'lim_verification_secret_9', + clientVersion: '1.2.3', + platform: 'android', + }), + (error: unknown) => { + const appError = error as { + code?: string; + message?: string; + details?: unknown; + cause?: unknown; + }; + assert.equal(appError.code, 'COMMAND_FAILED'); + assert.equal(appError.message, 'Limrun connection verification failed.'); + assert.deepEqual(appError.details, { + status: 500, + hint: 'Check Limrun service access, LIMRUN_REGION, and network connectivity, then retry.', + }); + assert.equal(appError.cause, undefined); + return true; + }, + ); +}); + test('Limrun verification connects to an attached instance instead of the control plane', async () => { const android = { apiUrl: 'https://attached.example/api', token: 'tok', adbUrl: 'wss://adb' }; const result = await verifyLimrunConnection({ @@ -124,9 +162,11 @@ test('Limrun verification names the variables to check when an instance rejects await assert.rejects( verifyLimrunConnection({ clientVersion: '1.2.3', instances, platform }), (error: unknown) => { - assert.equal((error as { code?: string }).code, 'COMMAND_FAILED'); + const appError = error as { code?: string; cause?: unknown }; + assert.equal(appError.code, 'COMMAND_FAILED'); assert.match(JSON.stringify(error), variables); assert.doesNotMatch(JSON.stringify(error), /lim_st_secret/); + assert.equal(appError.cause, undefined); return true; }, ); diff --git a/packages/provider-limrun/src/connection-verification.ts b/packages/provider-limrun/src/connection-verification.ts index 905d322cf6..1960ddec4c 100644 --- a/packages/provider-limrun/src/connection-verification.ts +++ b/packages/provider-limrun/src/connection-verification.ts @@ -59,12 +59,10 @@ export async function verifyLimrunConnection( hint: 'Check LIMRUN_API_KEY and its organization access.', }); } - throw new AppError( - 'COMMAND_FAILED', - 'Limrun connection verification failed.', - { hint: 'Check Limrun service access, LIMRUN_REGION, and network connectivity, then retry.' }, - error, - ); + throw new AppError('COMMAND_FAILED', 'Limrun connection verification failed.', { + hint: 'Check Limrun service access, LIMRUN_REGION, and network connectivity, then retry.', + ...(status === undefined ? {} : { status }), + }); } const platformName = options.platform === 'android' ? 'Android' : 'iOS'; const deviceKind = options.platform === 'android' ? 'emulator' : 'simulator'; @@ -120,17 +118,12 @@ async function verifyAttachedInstance( const platformName = android ? 'Android' : 'iOS'; try { (await connecting).disconnect(); - } catch (error) { - throw new AppError( - 'COMMAND_FAILED', - `Limrun ${platformName} instance access failed.`, - { - hint: android - ? 'Check LIM_ANDROID_INSTANCE_URL, LIM_ANDROID_INSTANCE_TOKEN, and LIM_ANDROID_INSTANCE_ADB_URL, and that the instance is still running.' - : 'Check LIM_IOS_INSTANCE_URL and LIM_IOS_INSTANCE_TOKEN, and that the instance is still running.', - }, - error, - ); + } catch { + throw new AppError('COMMAND_FAILED', `Limrun ${platformName} instance access failed.`, { + hint: android + ? 'Check LIM_ANDROID_INSTANCE_URL, LIM_ANDROID_INSTANCE_TOKEN, and LIM_ANDROID_INSTANCE_ADB_URL, and that the instance is still running.' + : 'Check LIM_IOS_INSTANCE_URL and LIM_IOS_INSTANCE_TOKEN, and that the instance is still running.', + }); } return { provider: 'limrun', From bdaa850e69da38b41e60ec211b5067c1126e12c7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sun, 22 Nov 2026 11:38:17 +0100 Subject: [PATCH 22/26] fix(provider-limrun): strip the instance token from error details An instance that answers an authenticated download or an XCTest start with an unlabeled body naming the bearer token it was given put that token in the error details the daemon publishes. Remove each value sent to the endpoint from the response text before publishing it; the status and typed reason answer for the failure. --- .../provider-limrun/src/download-file.test.ts | 28 ++++++++++++++ packages/provider-limrun/src/download-file.ts | 3 +- .../provider-limrun/src/error-text.test.ts | 32 ++++++++++++++++ packages/provider-limrun/src/error-text.ts | 38 +++++++++++++++++++ packages/provider-limrun/src/ios-runner.ts | 10 ++++- 5 files changed, 109 insertions(+), 2 deletions(-) create mode 100644 packages/provider-limrun/src/error-text.test.ts create mode 100644 packages/provider-limrun/src/error-text.ts diff --git a/packages/provider-limrun/src/download-file.test.ts b/packages/provider-limrun/src/download-file.test.ts index 5cadd5bcca..f94fe2699b 100644 --- a/packages/provider-limrun/src/download-file.test.ts +++ b/packages/provider-limrun/src/download-file.test.ts @@ -101,6 +101,34 @@ test('a non-2xx answer whose body stalls ends at the deadline as the typed timeo }); }); +// The instance authenticates with a bearer token and its own error body can echo it unlabeled, so +// core's pattern redaction cannot see it. The typed status and reason still answer for the failure. +test('an error body that echoes the instance token publishes it redacted', async () => { + const token = 'liminst_5f4dcc3b5aa765d61d8327deb882cf99'; + const url = await serve((_request, response) => { + response.writeHead(500); + response.end(`upstream rejected ${token} for this transfer`); + }); + const destinationPath = path.join(await mkdtempForTest('limrun-download-'), 'clip.mp4'); + + let failure: unknown; + await downloadLimrunFile({ + url, + headers: { Authorization: `Bearer ${token}` }, + destinationPath, + timeoutMs: 5_000, + }).catch((error: AppError) => { + failure = error; + }); + + expect(failure).toBeInstanceOf(AppError); + expect((failure as AppError).details).toMatchObject({ + statusCode: 500, + reason: 'limrun_download_http_error', + }); + expect(JSON.stringify((failure as AppError).details)).not.toMatch(token); +}); + test('a failed retry removes the file an earlier attempt left at the destination', async () => { const url = await serve((_request, response) => { response.writeHead(500); diff --git a/packages/provider-limrun/src/download-file.ts b/packages/provider-limrun/src/download-file.ts index d9cf6ee7d1..4d434a1e7f 100644 --- a/packages/provider-limrun/src/download-file.ts +++ b/packages/provider-limrun/src/download-file.ts @@ -4,6 +4,7 @@ import { Readable } from 'node:stream'; import { pipeline } from 'node:stream/promises'; import type { ReadableStream as WebReadableStream } from 'node:stream/web'; import { AppError, createRequestCanceledError } from '@agent-device/kernel/errors'; +import { safeInstanceErrorText } from './error-text.ts'; import type { LimrunFileDownload } from './runtime-dependencies.ts'; const RESPONSE_BODY_PREVIEW_BYTES = 500; @@ -45,7 +46,7 @@ async function httpFailure(response: Response, options: LimrunFileDownload): Pro url: options.url, statusCode: response.status, reason: 'limrun_download_http_error', - body: await readBodyPreview(response), + body: safeInstanceErrorText(await readBodyPreview(response), Object.values(options.headers)), }); } diff --git a/packages/provider-limrun/src/error-text.test.ts b/packages/provider-limrun/src/error-text.test.ts new file mode 100644 index 0000000000..9552363d4f --- /dev/null +++ b/packages/provider-limrun/src/error-text.test.ts @@ -0,0 +1,32 @@ +import { describe, expect, test } from 'vitest'; +import { safeInstanceErrorText } from './error-text.ts'; + +const TOKEN = 'liminst_5f4dcc3b5aa765d61d8327deb882cf99'; + +describe('safeInstanceErrorText', () => { + test('removes a bare token an instance echoed unlabeled, alone and inside other text', () => { + expect(safeInstanceErrorText(TOKEN, [`Bearer ${TOKEN}`])).toBe('[REDACTED]'); + expect(safeInstanceErrorText(`upstream rejected ${TOKEN} at boot`, [`Bearer ${TOKEN}`])).toBe( + 'upstream rejected [REDACTED] at boot', + ); + }); + + test('removes a sent header whole, and the bare token when only it was echoed', () => { + const value = `Bearer ${TOKEN}`; + expect(safeInstanceErrorText(`got ${value} twice: ${TOKEN}`, [value])).toBe( + 'got [REDACTED] twice: [REDACTED]', + ); + }); + + test('keeps diagnostic text that carries no sent value', () => { + expect(safeInstanceErrorText('xctestrun is missing Runner section', [`Bearer ${TOKEN}`])).toBe( + 'xctestrun is missing Runner section', + ); + }); + + test('ignores a short header word, which is a scheme name rather than a secret', () => { + expect(safeInstanceErrorText('Bearer is not enough', ['Bearer ab'])).toBe( + 'Bearer is not enough', + ); + }); +}); diff --git a/packages/provider-limrun/src/error-text.ts b/packages/provider-limrun/src/error-text.ts new file mode 100644 index 0000000000..577f1d6ad4 --- /dev/null +++ b/packages/provider-limrun/src/error-text.ts @@ -0,0 +1,38 @@ +/** Below this length a word of a credential header is a scheme name or a common word, not a secret. */ +const MIN_SECRET_LENGTH = 8; + +/** + * Reads an instance's own error text into a diagnostic this process may publish. + * + * The caller authenticates to the instance with a token that the instance's error body can echo, and + * core redacts only what it recognizes by pattern: an unlabeled body that repeats the bare token + * survives. So every value the caller sent to this endpoint is removed first. Core still bounds and + * pattern-redacts what this returns, as it does for every error detail. The status and typed reason + * are published as details next to this text, so the text carries no other duty. + */ +export function safeInstanceErrorText( + text: string, + sentValues: Iterable, +): string { + let output = text; + for (const value of sentValues) { + if (!value) continue; + for (const secret of secretParts(value)) { + output = output.split(secret).join('[REDACTED]'); + } + } + return output; +} + +/** The secret values one header value carries: itself, and each of its long whitespace parts. */ +function secretParts(value: string): string[] { + const parts = new Set([value.trim()].filter(isSecretLength)); + for (const part of value.split(/\s+/)) { + if (isSecretLength(part)) parts.add(part); + } + return [...parts]; +} + +function isSecretLength(value: string): boolean { + return value.length >= MIN_SECRET_LENGTH; +} diff --git a/packages/provider-limrun/src/ios-runner.ts b/packages/provider-limrun/src/ios-runner.ts index 5c60da61f6..de468793b0 100644 --- a/packages/provider-limrun/src/ios-runner.ts +++ b/packages/provider-limrun/src/ios-runner.ts @@ -1,4 +1,5 @@ import { limrunRunnerError, withLimrunRunnerErrors } from './ios-runner-errors.ts'; +import { safeInstanceErrorText } from './error-text.ts'; import { awaitWithSignal } from '@agent-device/kernel/await-with-signal'; import type { DeadlineClock } from '@agent-device/host-kit/retry'; import { createLimrunAppleToolProvider } from './ios-tools.ts'; @@ -164,12 +165,19 @@ export async function createLimrunIosRunner( launchSignal, ); if (!result.ok) { + const responseText = await awaitWithSignal(result.text(), launchSignal).catch( + () => undefined, + ); const failure = limrunRunnerError( result.status === 409 ? 'limrun_xctest_slot_occupied' : 'limrun_runner_launch_failed', `Limrun XCTest launch failed (${result.status})`, { status: result.status, - response: await awaitWithSignal(result.text(), launchSignal).catch(() => undefined), + ...(responseText === undefined + ? {} + : { + response: safeInstanceErrorText(responseText, Object.values(headers)), + }), }, ); if (result.status === 409) lastConflict = failure; From 8ece3dccedb38dc45cbdbf4188e307d2806e6200 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sun, 22 Nov 2026 13:23:22 +0100 Subject: [PATCH 23/26] fix(cli): keep a provider's lease policy on every route A remote Limrun connection whose host has no plugin was answered from generic remote capabilities, so `apps` allocated a lease, `lease_allocate` sent the daemon's default TTL, and `open ` dropped the initial app. The plugin catalog now carries the provider's whole declared `ConnectionProviderCapabilities` and its admission policy, and `declaredConnectionCapabilities` falls back to that copy before the daemon's own routing, so a connection's lease policy is its provider's whether or not this host loads the plugin. The predicate, its without-refusal variant and the three duplicated if/else sites collapse into `admitProviderForRoute(provider, route, env)`, which primes the store, refuses only where this host must supply the provider, and answers capabilities from the plugin when loaded, else from the catalog. `providerRouteForConnection` reads the same two settings the daemon client reads. --- src/cli/commands/connection-runtime.ts | 18 ++-- src/cli/commands/connection.ts | 14 +-- src/cli/connection/provider-admission.test.ts | 99 +++++++++++++++++++ src/cli/connection/provider-admission.ts | 14 +-- src/cli/connection/provider-policy.test.ts | 68 ++++++++++--- src/cli/connection/provider-policy.ts | 99 ++++++++++++------- src/commands/provider-plugin-catalog.test.ts | 12 +++ src/commands/provider-plugin-catalog.ts | 53 +++++++++- 8 files changed, 300 insertions(+), 77 deletions(-) diff --git a/src/cli/commands/connection-runtime.ts b/src/cli/commands/connection-runtime.ts index 3ea2767ae2..3c2d111828 100644 --- a/src/cli/commands/connection-runtime.ts +++ b/src/cli/commands/connection-runtime.ts @@ -17,11 +17,10 @@ import type { SessionRuntimeHints } from '@agent-device/kernel/contracts'; import type { CliFlags } from '@agent-device/contracts/command'; import type { AgentDeviceClient } from '@agent-device/command-surface'; import { + admitProviderForRoute, connectionLeaseProvider, - connectionNeedsLocalProviderRuntime, connectionProviderCapabilities, - primeProviderConnection, - primeProviderConnectionWithoutRefusal, + providerRouteForConnection, } from '../connection/provider-policy.ts'; import { profileToCliFlags } from '../remote-config-flags.ts'; import { @@ -92,11 +91,14 @@ export async function materializeRemoteConnectionForCommand(options: { // provider registration supplies the runtime, and this command only leases and dispatches. Its // connection metadata still has to be read and saved, so the profile is loaded either way. const provider = connectionLeaseProvider(existingState, remoteConfig.profile.leaseProvider); - if (connectionNeedsLocalProviderRuntime(mergedFlags.daemonBaseUrl, host.env)) { - await primeProviderConnection(provider, host.env); - } else { - await primeProviderConnectionWithoutRefusal(provider, host.env); - } + await admitProviderForRoute( + provider, + providerRouteForConnection({ + daemonBaseUrl: mergedFlags.daemonBaseUrl, + env: host.env, + }), + host.env, + ); const state = existingState ?? createRemoteConnectionStateFromFlags( diff --git a/src/cli/commands/connection.ts b/src/cli/commands/connection.ts index 5023186f72..7920257d1c 100644 --- a/src/cli/commands/connection.ts +++ b/src/cli/commands/connection.ts @@ -20,12 +20,11 @@ import { import { AppError, errorMessage } from '@agent-device/kernel/errors'; import { isInactiveLeaseError } from '@agent-device/contracts/lease-scope'; import { + admitProviderForRoute, connectProviderNamesForError, - connectionNeedsLocalProviderRuntime, connectionProviderCapabilities, isConnectProviderName, primeProviderConnection, - primeProviderConnectionWithoutRefusal, unavailableConnectPluginError, type ConnectProvider, } from '../connection/provider-policy.ts'; @@ -411,13 +410,10 @@ export const connectionCommand: ClientCommandHandler = async ({ positionals, fla await writeNoRemoteConnectionOutput(flags, session); return true; } - // A connection whose daemon is remote is answered there, so its provider's plugin is not needed to - // read this record; the plugin's own declaration is used when this host has it. - if (connectionNeedsLocalProviderRuntime(state.daemon?.baseUrl, host.env)) { - await primeProviderConnection(state.leaseProvider, host.env); - } else { - await primeProviderConnectionWithoutRefusal(state.leaseProvider, host.env); - } + // Reading a stored record dispatches nothing, so a plugin this host lacks is not this command's + // answer; the provider's declared capabilities come from the plugin when it is loaded, and from the + // plugin catalog's copy of the declaration when it is not. + await admitProviderForRoute(state.leaseProvider, 'reads-connection-record', host.env); const leasePreparation = buildLeasePreparationNotice(state, undefined, host.env); const runtimePreparation = buildRuntimePreparationNoticeFromState(state, host); await writeCommandOutput( diff --git a/src/cli/connection/provider-admission.test.ts b/src/cli/connection/provider-admission.test.ts index 9c4d4f8577..8034deb3ca 100644 --- a/src/cli/connection/provider-admission.test.ts +++ b/src/cli/connection/provider-admission.test.ts @@ -2,6 +2,7 @@ import { afterEach, test, vi } from 'vitest'; import assert from 'node:assert/strict'; import fs from 'node:fs'; import path from 'node:path'; +import { REMOTE_LEASE_IDLE_TTL_MS } from '@agent-device/contracts/lease-scope'; import { hashRemoteConfigFile, readActiveConnectionState, @@ -206,6 +207,104 @@ test('an explicit Limrun remote config with a remote daemon dispatches without t fs.rmSync(root, { recursive: true, force: true }); }); +// Limrun owns its lease policy on this route too: the plugin catalog declares its capabilities, so a +// host without the plugin still defers app selection, bounds the lease with Limrun's idle TTL, and +// names the app `open` should preinstall. Without the declaration these commands would allocate on +// `apps`, send the daemon's default TTL, and drop the app. +test('a fresh apps command on a remote Limrun connection defers allocation without the plugin', async () => { + const { root, home, project } = makeTempWorkspace(); + const stateDir = path.join(root, 'state'); + const remoteConfig = limrunProfile(project); + + const result = await runCliCapture( + ['apps', '--session', 'ci', '--remote-config', remoteConfig, '--state-dir', stateDir, '--json'], + { + cwd: project, + env: { HOME: home, AGENT_DEVICE_DAEMON_AUTH_TOKEN: 'adc_live_remote_daemon_token_1348' }, + defaultResponse: { ok: true, data: { apps: [] } }, + }, + ); + + assert.equal(result.code, null, result.stdout + result.stderr); + assert.deepEqual( + result.calls.map((call) => call.command), + ['apps'], + ); + fs.rmSync(root, { recursive: true, force: true }); +}); + +test('an open command on a remote Limrun connection allocates with the idle TTL and initial app without the plugin', async () => { + const { root, home, project } = makeTempWorkspace(); + const stateDir = path.join(root, 'state'); + const remoteConfig = limrunProfile(project); + + const result = await runCliCapture( + [ + 'open', + 'com.example.app', + '--session', + 'ci', + '--remote-config', + remoteConfig, + '--state-dir', + stateDir, + '--json', + ], + { + cwd: project, + env: { HOME: home, AGENT_DEVICE_DAEMON_AUTH_TOKEN: 'adc_live_remote_daemon_token_1348' }, + defaultResponse: { + ok: true, + data: { + lease: { + leaseId: 'lease-ci', + tenantId: 'team-a', + runId: 'run-a', + backend: 'android-instance', + leaseProvider: 'limrun', + }, + }, + }, + }, + ); + + assert.equal(result.code, null, result.stdout + result.stderr); + const allocation = result.calls.find((call) => call.command === 'lease_allocate'); + assert.ok(allocation, `expected a lease_allocate in ${JSON.stringify(result.calls)}`); + assert.equal(allocation.meta?.leaseTtlMs, REMOTE_LEASE_IDLE_TTL_MS); + assert.equal(allocation.flags?.providerApp, 'com.example.app'); + fs.rmSync(root, { recursive: true, force: true }); +}); + +// `connection status` reads the record in this process and dispatches nothing, so a plugin this host +// lacks is not its answer either. The record still keeps Limrun's preparation, which is what the +// connect help promises: run `apps` to list uploaded assets, then `open` one by name. +test('connection status answers for a stored Limrun connection without the plugin and keeps its preparation', async () => { + const { root, home, project, stateDir } = storedLimrunConnection(); + const before = snapshotTree(stateDir); + + const result = await runCliCapture( + ['connection', 'status', '--session', 'limrun-a', '--state-dir', stateDir, '--json'], + { cwd: project, env: { HOME: home } }, + ); + + assert.equal(result.code, null, result.stdout + result.stderr); + assert.equal(result.calls.length, 0, 'status dispatches nothing'); + const { data: status } = JSON.parse(result.stdout) as { + data: { + leaseProvider?: string; + leasePreparation?: { status?: string; message?: string }; + }; + }; + assert.equal(status.leaseProvider, 'limrun'); + // App selection stays deferred to `apps`, which is what Limrun declares. Answered from generic + // capabilities, the same record promises an allocation on the next device command instead. + assert.equal(status.leasePreparation?.status, 'deferred'); + assert.match(status.leasePreparation?.message ?? '', /Run apps to inspect uploaded assets/); + assert.deepEqual(snapshotTree(stateDir), before); + fs.rmSync(root, { recursive: true, force: true }); +}); + // A connection with no daemon configured elsewhere is driven from this process, and only the plugin // can drive it: that route still refuses before it authenticates or dispatches. test('a stored Limrun connection with no configured daemon refuses the missing plugin before authentication', async () => { diff --git a/src/cli/connection/provider-admission.ts b/src/cli/connection/provider-admission.ts index c01c60e45c..eda82881ce 100644 --- a/src/cli/connection/provider-admission.ts +++ b/src/cli/connection/provider-admission.ts @@ -4,10 +4,10 @@ import type { HostEnvironment } from '@agent-device/kernel/source-value'; import { readRemoteConfigFile } from '@agent-device/remote/remote-config-core'; import { parseRawArgs } from '../parser/args.ts'; import { + admitProviderForRoute, connectionLeaseProvider, - connectionNeedsLocalProviderRuntime, primeProviderConnection, - primeProviderConnectionWithoutRefusal, + providerRouteForConnection, requiresOwnProviderAdmission, } from './provider-policy.ts'; @@ -40,11 +40,11 @@ export async function admitConnectionProvider(context: AdmissionContext): Promis context.remoteConfigLeaseProvider, ); if (!requiresOwnProviderAdmission(provider)) return; - if (connectionNeedsLocalProviderRuntime(context.daemonBaseUrl, context.host.env)) { - await primeProviderConnection(provider, context.host.env); - return; - } - await primeProviderConnectionWithoutRefusal(provider, context.host.env); + await admitProviderForRoute( + provider, + providerRouteForConnection({ daemonBaseUrl: context.daemonBaseUrl, env: context.host.env }), + context.host.env, + ); } /** diff --git a/src/cli/connection/provider-policy.test.ts b/src/cli/connection/provider-policy.test.ts index 02357a0992..9c4963b6ab 100644 --- a/src/cli/connection/provider-policy.test.ts +++ b/src/cli/connection/provider-policy.test.ts @@ -10,12 +10,13 @@ import { connectProviderNamesForError, isConnectProviderName, primeProviderConnection, + providerRouteForConnection, } from './provider-policy.ts'; import { pluginHome, selectPlugin, pluginSource } from '@agent-device/test-kit'; import limrun from '@agent-device/limrun'; import awsDeviceFarm from '@agent-device/aws-device-farm'; import browserstack from '@agent-device/browserstack'; -import { getProviderPluginDeclaration } from '../../commands/provider-plugin-catalog.ts'; +import { providerPluginConnectionCapabilities } from '../../commands/provider-plugin-catalog.ts'; import { declaredConnectionCapabilities } from '../../__tests__/test-utils/plugin-declaration.fixtures.ts'; test('provider policy projects provider identity into semantic capabilities', async () => { @@ -27,8 +28,9 @@ test('provider policy projects provider identity into semantic capabilities', as extra: `connection: { capabilities: ${JSON.stringify(declaredConnectionCapabilities(limrun()))}, resolve() {}, verify() {} },`, }), ); - // Without the plugin nothing declares Limrun's capabilities; the installed one answers once primed. - assert.equal(connectionProviderCapabilities('limrun', {}).leaseKind, 'remote-provider'); + // Limrun's lease policy is its own on every route: the catalog answers it before any plugin store is + // loaded, so a host without the plugin still defers app selection and bounds the lease. + assert.equal(connectionProviderCapabilities('limrun', {}).leaseKind, 'direct-device-provider'); await primeProviderConnection('limrun', limrunStore.env); assert.deepEqual(connectionProviderCapabilities('limrun', limrunStore.env), { leaseKind: 'direct-device-provider', @@ -41,7 +43,8 @@ test('provider policy projects provider identity into semantic capabilities', as holdsCloudDevice: true, forgetsEndedConnectionLease: true, }); - // BrowserStack is a plugin: without an installed one nothing declares its capabilities. + // BrowserStack and AWS Device Farm declare no catalog capabilities: without an installed plugin + // nothing declares theirs, and they keep the daemon's own routing. assert.equal( connectionProviderCapabilities('browserstack', pluginHome().env).leaseKind, 'remote-provider', @@ -138,18 +141,59 @@ test('a plugin that fails to load supplies no connection name even after priming ]); }); -test('the plugin catalog copies the ended-lease declaration of each plugin', () => { - // The catalog answers for a connection that records no policy when no plugin is loaded, so its - // copy must equal what the plugin declares. +test('the plugin catalog copies the connection capabilities each plugin declares', () => { + // The catalog answers a connection's lease policy on a route that loads no plugin, so every copy it + // carries must equal what the plugin itself declares. for (const [provider, plugin] of [ ['limrun', limrun()], ['aws-device-farm', awsDeviceFarm()], ['browserstack', browserstack()], ] as const) { - assert.equal( - getProviderPluginDeclaration(provider)?.forgetsEndedConnectionLease === true, - declaredConnectionCapabilities(plugin)?.forgetsEndedConnectionLease === true, - provider, - ); + const declared = providerPluginConnectionCapabilities(provider); + if (declared === undefined) continue; + assert.deepEqual(declared, declaredConnectionCapabilities(plugin), provider); } + // Limrun is the row a remote connection is answered from without the plugin, so its copy is required. + assert.deepEqual( + providerPluginConnectionCapabilities('limrun'), + declaredConnectionCapabilities(limrun()), + ); +}); + +test('a route is answered by the daemon only when a base URL is actually set', () => { + // The daemon client reads the same two settings with `??` and treats an empty one as no daemon, so an + // empty flag or an empty environment setting drives the connection from this host — the one route + // that refuses a provider it has no plugin for. + assert.equal( + providerRouteForConnection({ daemonBaseUrl: undefined, env: {} }), + 'drives-connection', + ); + assert.equal( + providerRouteForConnection({ + daemonBaseUrl: undefined, + env: { AGENT_DEVICE_DAEMON_BASE_URL: '' }, + }), + 'drives-connection', + ); + assert.equal( + providerRouteForConnection({ + daemonBaseUrl: '', + env: { AGENT_DEVICE_DAEMON_BASE_URL: 'http://127.0.0.1:50000' }, + }), + 'drives-connection', + ); + assert.equal( + providerRouteForConnection({ + daemonBaseUrl: undefined, + env: { AGENT_DEVICE_DAEMON_BASE_URL: 'http://127.0.0.1:50000' }, + }), + 'dispatches-to-remote-daemon', + ); + assert.equal( + providerRouteForConnection({ + daemonBaseUrl: 'http://127.0.0.1:50000', + env: {}, + }), + 'dispatches-to-remote-daemon', + ); }); diff --git a/src/cli/connection/provider-policy.ts b/src/cli/connection/provider-policy.ts index 670539c3e8..cb27a32312 100644 --- a/src/cli/connection/provider-policy.ts +++ b/src/cli/connection/provider-policy.ts @@ -14,13 +14,27 @@ import { readVersion } from '@agent-device/host-kit/version'; import { AppError } from '@agent-device/kernel/errors'; import { getProviderPluginDeclaration, + providerPluginAdmission, + providerPluginConnectionCapabilities, providerPluginRepairCommand, - LIMRUN, } from '../../commands/provider-plugin-catalog.ts'; import { ROUTING_PROVIDER_IDENTITIES } from '@agent-device/plugins/contract'; export type ConnectProvider = string; +/** + * What a route on a remote connection needs from the provider's plugin. + * + * `drives-connection`: this process drives the connection, so only a working local plugin can serve + * it. `dispatches-to-remote-daemon`: the command sends its request to a configured remote daemon, + * whose own provider registration answers for the provider here. `reads-connection-record`: the + * route reads stored connection state and does neither. + */ +export type ProviderRoute = + | 'drives-connection' + | 'dispatches-to-remote-daemon' + | 'reads-connection-record'; + function remoteDaemonConnection( leaseKind: 'proxy' | 'remote-provider', ): ConnectionProviderCapabilities { @@ -49,7 +63,9 @@ export function connectionLeaseProvider( /** * Loads the plugin store before the first synchronous capability lookup for a provider, because a - * plugin declares its capabilities in code, not in its manifest. + * plugin declares its capabilities in code, not in its manifest. A provider this host has no working + * plugin for refuses here: only the loaded plugin can drive a connection, and the catalog's copy of + * its declaration is not a runtime. */ export async function primeProviderConnection( provider: string | undefined, @@ -62,21 +78,6 @@ export async function primeProviderConnection( if (unavailable) throw unavailable; } -/** - * Loads the plugin store and reads a provider's declared capabilities, without refusing a provider - * this host has no working plugin for. A command that dispatches to a configured remote daemon uses - * it where the daemon's own provider registration answers for the provider, so a plugin this host - * lacks is not that command's answer; the plugin is still read when the host has it, so a connection - * keeps the capabilities its provider declares. - */ -export async function primeProviderConnectionWithoutRefusal( - provider: string | undefined, - env: NodeJS.ProcessEnv = process.env, -): Promise { - if (provider === undefined || ROUTING_PROVIDER_IDENTITIES.includes(provider)) return; - await primePluginConnections(env); -} - export function isConnectProviderName( value: string | undefined, env: NodeJS.ProcessEnv = process.env, @@ -100,28 +101,52 @@ export function connectProviderNamesForError(env: NodeJS.ProcessEnv = process.en } /** - * Whether a route admits `provider` itself before it authenticates or writes anything. The core ships - * no Limrun runtime, so only the plugin supplies that provider, and a route that needs it here refuses - * it early. Every other provider name keeps this release's starting behavior: the connect handler - * admits a named provider, and the adapter that reads a profile verifies the provider it names. + * Whether a route admits `provider` itself before it authenticates or writes anything. The catalog + * declares this per provider: `'provider'` means the core ships no runtime for it, so only its plugin + * can supply it and a route that needs it here refuses it early. `'route'`, the default, keeps this + * release's starting behavior: the connect handler admits a named provider, and the adapter that reads + * a profile verifies the provider it names. */ export function requiresOwnProviderAdmission(provider: string | undefined): boolean { - return provider === LIMRUN.provider; + return providerPluginAdmission(provider) === 'provider'; } /** - * Whether a command on a remote connection needs the provider's plugin in this process. A configured - * remote daemon owns its own provider registration and answers for the provider, so a command that - * dispatches there needs no local plugin: it authenticates and sends its request. A connection with - * no configured daemon is driven from here, where the plugin is the only thing that can drive it. - * The daemon client treats any configured base URL as a remote daemon, so the test is its own: a - * base URL is set. + * Loads the plugin store for a route on a remote connection, and refuses only where this host has to + * supply the provider and cannot. A command that dispatches to a configured remote daemon is answered + * by the daemon's own provider registration, so a plugin this host lacks is not that command's answer. + * `connection status` reads a stored record and dispatches nothing: it needs no runtime here, only the + * provider's declared capabilities, which its loaded plugin answers, or the plugin catalog's copy of + * that declaration when the plugin is absent. Every other route is driven by this host, where only a + * working plugin can serve it. All routes load the store when they can, so a connection keeps the + * capabilities its provider declares. */ -export function connectionNeedsLocalProviderRuntime( - daemonBaseUrl: string | undefined, - env: NodeJS.ProcessEnv, -): boolean { - return (daemonBaseUrl ?? env.AGENT_DEVICE_DAEMON_BASE_URL) === undefined; +export async function admitProviderForRoute( + provider: string | undefined, + route: ProviderRoute, + env: NodeJS.ProcessEnv = process.env, +): Promise { + if (provider === undefined || ROUTING_PROVIDER_IDENTITIES.includes(provider)) return; + await primePluginConnections(env); + if (route === 'dispatches-to-remote-daemon') return; + if (route === 'reads-connection-record' && declaredConnectionCapabilities(provider, env)) return; + if (pluginConnectionCapabilities(provider, env) !== undefined) return; + const unavailable = unavailableConnectPluginError(provider, env); + if (unavailable) throw unavailable; +} + +/** + * The route a command on a remote connection takes: a configured daemon base URL answers there, and no + * base URL means this process drives the connection. The daemon client reads the same two settings and + * treats an empty base URL as none, so this does too, and the daemon URL of a stored record counts. + */ +export function providerRouteForConnection(options: { + daemonBaseUrl: string | undefined; + env: NodeJS.ProcessEnv; +}): ProviderRoute { + return (options.daemonBaseUrl ?? options.env.AGENT_DEVICE_DAEMON_BASE_URL) + ? 'dispatches-to-remote-daemon' + : 'drives-connection'; } export function unavailableConnectPluginError( @@ -169,7 +194,9 @@ function declaredConnectionCapabilities( if (provider === 'proxy') return remoteDaemonConnection('proxy'); if (provider === undefined || provider === 'cloud') return remoteDaemonConnection('remote-provider'); - return pluginConnectionCapabilities(provider, env); + return ( + pluginConnectionCapabilities(provider, env) ?? providerPluginConnectionCapabilities(provider) + ); } /** @@ -182,9 +209,7 @@ export function providerForgetsEndedConnectionLease( env: NodeJS.ProcessEnv, ): boolean { const declared = declaredConnectionCapabilities(provider, env); - if (declared) return declared.forgetsEndedConnectionLease === true; - if (provider === undefined) return false; - return getProviderPluginDeclaration(provider)?.forgetsEndedConnectionLease === true; + return declared?.forgetsEndedConnectionLease === true; } /** Installed providers declare their capabilities; the rest is the daemon's own routing. */ diff --git a/src/commands/provider-plugin-catalog.test.ts b/src/commands/provider-plugin-catalog.test.ts index 28612bd3be..b6a79d3b53 100644 --- a/src/commands/provider-plugin-catalog.test.ts +++ b/src/commands/provider-plugin-catalog.test.ts @@ -2,6 +2,7 @@ import assert from 'node:assert/strict'; import { test } from 'vitest'; import { getProviderPluginDeclaration, + providerPluginAdmission, providerPluginDeclarations, providerPluginHelp, providerPluginInstallCommand, @@ -70,6 +71,17 @@ test('the catalog exposes every row, so the release check sees every install hin } }); +test('the catalog names which plugin providers a route must admit itself', () => { + // Limrun is the one provider the core ships no runtime for, so a route driving its connection + // refuses it without the plugin. Every other row keeps the route's own admission. + assert.equal(providerPluginAdmission('limrun'), 'provider'); + for (const provider of ['aws-device-farm', 'browserstack', 'revyl', 'testmu', 'webos', 'tizen']) { + assert.equal(providerPluginAdmission(provider), 'route', provider); + } + assert.equal(providerPluginAdmission(undefined), 'route'); + assert.equal(providerPluginAdmission('unknown-provider'), 'route'); +}); + test('help gives nightly and stable users the same plugin selectors as recovery', () => { const nightly = providerPluginHelp(NIGHTLY_0_22); const stable = providerPluginHelp('0.22.0'); diff --git a/src/commands/provider-plugin-catalog.ts b/src/commands/provider-plugin-catalog.ts index f43b9c7b06..181448cccd 100644 --- a/src/commands/provider-plugin-catalog.ts +++ b/src/commands/provider-plugin-catalog.ts @@ -1,3 +1,4 @@ +import type { ConnectionProviderCapabilities } from '@agent-device/contracts/remote'; import { readVersion } from '@agent-device/host-kit/version'; import { type PluginReleaseDeclaration, @@ -6,15 +7,28 @@ import { pluginRepairCommand, } from '@agent-device/contracts/plugin-installation'; +/** What a route must do about a provider whose plugin this host cannot supply. */ +export type ProviderAdmissionPolicy = 'provider' | 'route'; + type ProviderPluginDeclaration = PluginReleaseDeclaration & Readonly<{ provider: string; label: string; /** - * The plugin's own `forgetsEndedConnectionLease` declaration, readable without loading the - * plugin. A command that loads no plugin store reads it for a connection that records no policy. + * The plugin's own `connection.capabilities` declaration, readable without loading the plugin. A + * connection's lease policy comes from its provider on every route, including one whose plugin + * this host does not load, so the same command behaves the same with or without it installed. + * `provider-policy.test.ts` keeps this copy equal to the plugin's own declaration. + */ + connectionCapabilities?: ConnectionProviderCapabilities; + /** + * Whether a route that needs this provider admits it itself before it authenticates or writes + * anything. `'provider'` means only the plugin can supply the provider, because the core ships no + * runtime for it, so a route driving a connection here refuses a provider it has no plugin for. + * `'route'`, the default, keeps this release's starting behavior: the `connect` handler admits a + * named provider, and the adapter that reads a profile verifies the provider it names. */ - forgetsEndedConnectionLease?: boolean; + admission?: ProviderAdmissionPolicy; }>; export const AWS_DEVICE_FARM: ProviderPluginDeclaration = { @@ -36,7 +50,18 @@ export const LIMRUN: ProviderPluginDeclaration = { package: '@agent-device/limrun', label: 'Limrun', nightlyTag: 'nightly-0.22', - forgetsEndedConnectionLease: true, + admission: 'provider', + connectionCapabilities: { + leaseKind: 'direct-device-provider', + requiresAppAttachment: false, + requiresRemoteDaemon: false, + supportsArtifacts: false, + supportsDeferredAppSelection: true, + supportsDirectPortReverse: true, + usesCloudWebDriverLease: false, + holdsCloudDevice: true, + forgetsEndedConnectionLease: true, + }, }; const PROVIDER_PLUGIN_CATALOG: readonly ProviderPluginDeclaration[] = [ @@ -60,6 +85,26 @@ export function getProviderPluginDeclaration( return PROVIDER_PLUGIN_CATALOG.find((plugin) => plugin.provider === provider); } +/** + * The capabilities a plugin provider declares, read from the catalog without loading the plugin or + * its store. Undefined for a provider the catalog does not list. + */ +export function providerPluginConnectionCapabilities( + provider: string | undefined, +): ConnectionProviderCapabilities | undefined { + return provider === undefined + ? undefined + : getProviderPluginDeclaration(provider)?.connectionCapabilities; +} + +/** How a route treats a provider it must admit itself; see `ProviderAdmissionPolicy`. */ +export function providerPluginAdmission(provider: string | undefined): ProviderAdmissionPolicy { + return ( + (provider === undefined ? undefined : getProviderPluginDeclaration(provider)?.admission) ?? + 'route' + ); +} + export function providerPluginInstallCommand( declaration: ProviderPluginDeclaration, coreVersion: string = readVersion(), From 99e1e8206ed836b4faaa347045a1a8e1981c6f49 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sun, 22 Nov 2026 13:23:43 +0100 Subject: [PATCH 24/26] fix(provider-limrun): keep credentials out of published errors MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The SDK, an attached instance and a forwarding service in front of one all answer with their own text, and this plugin authenticates each of them with an account key or an instance token. An unlabelled echo of a bare credential survives core's pattern redaction, so each path that published peer text is closed at its owner: - Every client this plugin builds logs nothing: `off` on the organization client and `none` on an instance client, which outranks `LIMRUN_LOG`, so the SDK cannot write a failed response body that carries an account key or an instance token. - The scrubber drops a credential however brief — the reader of an attached instance accepts any nonempty token — and takes the credential out of both a header value and its bare credential. - A download publishes its typed reason, its status and a transport code: no URL, no peer body, and no fetch message, since an attached instance answers with its token as the download URL. - An account-API failure is re-raised as an `AppError` carrying status and reason before a create, an asset list, a recovery list, a reconnect lookup or a delete records or returns it, keeping the 404 answer a caller acts on. A termination reason is bounded to one line and scrubbed. - The runner's forwarded credential reaches its response, its cause and its log redaction boundary, including a credential split across stream chunks, and a `/sync` field this upload did not name stays out of the upload failure. - An instance client's own failures are answered through one wrapper, so `listApps`, `pressKey` and a remote install cannot return the peer's frame with the session token in it. Only a failure that names a sent value is re-raised, so a clean SDK failure keeps the reason and cause the command that caught it publishes. --- packages/provider-limrun/src/android.ts | 19 +- packages/provider-limrun/src/app-catalog.ts | 10 +- .../src/app-log-reconnect.test.ts | 2 +- .../provider-limrun/src/app-log-reconnect.ts | 49 +++-- .../src/client-options.test.ts | 64 ++++++- .../provider-limrun/src/client-options.ts | 103 ++++++++++- .../src/connection-verification.ts | 9 +- .../provider-limrun/src/connection.test.ts | 1 + .../provider-limrun/src/download-file.test.ts | 63 ++++--- packages/provider-limrun/src/download-file.ts | 101 ++++++----- .../provider-limrun/src/error-text.test.ts | 132 +++++++++++++- packages/provider-limrun/src/error-text.ts | 137 +++++++++++--- .../src/instance-error-scrubbing.test.ts | 169 ++++++++++++++++++ .../src/instance-error-scrubbing.ts | 134 ++++++++++++++ .../src/ios-runner-errors.test.ts | 22 +++ .../provider-limrun/src/ios-runner-errors.ts | 103 +++++++---- .../src/ios-runner-products.test.ts | 38 ++++ .../src/ios-runner-products.ts | 11 +- packages/provider-limrun/src/ios-runner.ts | 17 +- packages/provider-limrun/src/ios.ts | 17 +- packages/provider-limrun/src/lease-release.ts | 9 +- packages/provider-limrun/src/plugin.test.ts | 1 + packages/provider-limrun/src/runtime.ts | 20 ++- src/__tests__/limrun-runtime.test.ts | 4 +- website/docs/docs/error-reasons.md | 15 ++ 25 files changed, 1063 insertions(+), 187 deletions(-) create mode 100644 packages/provider-limrun/src/instance-error-scrubbing.test.ts create mode 100644 packages/provider-limrun/src/instance-error-scrubbing.ts diff --git a/packages/provider-limrun/src/android.ts b/packages/provider-limrun/src/android.ts index f97d81f53a..2565c52e79 100644 --- a/packages/provider-limrun/src/android.ts +++ b/packages/provider-limrun/src/android.ts @@ -1,4 +1,5 @@ import type { LimrunSyncCache } from './sync-cache.ts'; +import { LIMRUN_INSTANCE_CLIENT_LOGGING } from './client-options.ts'; import { AsyncLocalStorage } from 'node:async_hooks'; import { createInstanceClient as createAndroidInstanceClient, @@ -75,12 +76,18 @@ export async function createLimrunAndroidSession( }, dependencies: Pick, ): Promise { - const client = await createAndroidInstanceClient({ - apiUrl: options.apiUrl, - adbUrl: options.adbUrl, - token: options.token, - logLevel: 'warn', - }); + // The wrapper is loaded here, not imported: the runtime façade keeps its merge-base eager closure + // (ADR-0027), and this is one of the two routes that builds an instance client. + const { withInstanceCredentialScrubbing } = await import('./instance-error-scrubbing.ts'); + const client = withInstanceCredentialScrubbing( + await createAndroidInstanceClient({ + apiUrl: options.apiUrl, + adbUrl: options.adbUrl, + token: options.token, + ...LIMRUN_INSTANCE_CLIENT_LOGGING, + }), + [`Bearer ${options.token}`], + ); const session: LimrunAndroidAdbSession = { platform: 'android', lease: options.lease, diff --git a/packages/provider-limrun/src/app-catalog.ts b/packages/provider-limrun/src/app-catalog.ts index 4ed738bc07..6e55826bb4 100644 --- a/packages/provider-limrun/src/app-catalog.ts +++ b/packages/provider-limrun/src/app-catalog.ts @@ -1,6 +1,7 @@ import type Limrun from '@limrun/api'; import type { Asset } from '@limrun/api/resources/assets'; import { AppError } from '@agent-device/kernel/errors'; +import { fromLimrunOrgApi } from './client-options.ts'; const APP_CATALOG_LIMIT = 1_000; @@ -25,7 +26,9 @@ export async function listLimrunAppAssets( signal?: AbortSignal, ): Promise { signal?.throwIfAborted(); - const assets = await limrun.assets.list({ limit: APP_CATALOG_LIMIT }, { signal }); + const assets = await fromLimrunOrgApi( + limrun.assets.list({ limit: APP_CATALOG_LIMIT }, { signal }), + ); signal?.throwIfAborted(); const apps: LimrunAppAsset[] = []; for (const asset of assets) { @@ -42,9 +45,8 @@ export async function resolveLimrunAppAsset( signal?: AbortSignal, ): Promise { signal?.throwIfAborted(); - const assets = await limrun.assets.list( - { limit: APP_CATALOG_LIMIT, nameFilter: name }, - { signal }, + const assets = await fromLimrunOrgApi( + limrun.assets.list({ limit: APP_CATALOG_LIMIT, nameFilter: name }, { signal }), ); signal?.throwIfAborted(); const matches = assets diff --git a/packages/provider-limrun/src/app-log-reconnect.test.ts b/packages/provider-limrun/src/app-log-reconnect.test.ts index df08262aa8..a4701c25d5 100644 --- a/packages/provider-limrun/src/app-log-reconnect.test.ts +++ b/packages/provider-limrun/src/app-log-reconnect.test.ts @@ -280,7 +280,7 @@ test('reattaches app logs to the attached instance the descriptor names', async }); expect(vi.mocked(createIosInstanceClient)).toHaveBeenLastCalledWith({ ...ATTACHED_ACCESS, - logLevel: 'warn', + logLevel: 'none', }); expect(outcome.status).toBe('opened'); diff --git a/packages/provider-limrun/src/app-log-reconnect.ts b/packages/provider-limrun/src/app-log-reconnect.ts index 2d78488f56..4e41bc7699 100644 --- a/packages/provider-limrun/src/app-log-reconnect.ts +++ b/packages/provider-limrun/src/app-log-reconnect.ts @@ -1,11 +1,16 @@ import type Limrun from '@limrun/api'; -import { NotFoundError } from '@limrun/api'; import { createInstanceClient as createAndroidInstanceClient } from '@limrun/api/instance-client'; import { createInstanceClient as createIosInstanceClient } from '@limrun/api/ios-client'; import { AsyncCleanupStack } from '@agent-device/contracts/async-lifecycle'; import type { LimrunAppLogDescriptor } from './app-log-descriptor.ts'; import type { LimrunAppLogReader, LimrunAppLogReconnectOutcome } from './app-log-runtime.ts'; -import { requireLimrunOrgClient } from './client-options.ts'; +import { + fromLimrunOrgApi, + isLimrunApiNotFound, + LIMRUN_INSTANCE_CLIENT_LOGGING, + requireLimrunOrgClient, +} from './client-options.ts'; +import { withInstanceCredentialScrubbing } from './instance-error-scrubbing.ts'; import { attachedLimrunInstanceId } from './device.ts'; import type { LimrunAndroidInstanceAccess, @@ -31,11 +36,15 @@ export async function reconnectLimrunAppLogReader(options: { } const limrun = requireLimrunOrgClient(options.limrun, 'Reconnecting app logs'); try { - return options.descriptor.platform === 'ios' - ? await reconnectIos({ ...options, limrun }) - : await reconnectAndroid({ ...options, limrun }); + // The lookup is asked with the account key and its failure text is the response body, so it is + // answered with a typed status before anything here records or returns it. + return await fromLimrunOrgApi( + options.descriptor.platform === 'ios' + ? reconnectIos({ ...options, limrun }) + : reconnectAndroid({ ...options, limrun }), + ); } catch (error) { - if (error instanceof NotFoundError) return { status: 'missing' }; + if (isLimrunApiNotFound(error)) return { status: 'missing' }; throw error; } } @@ -90,11 +99,14 @@ async function openIosReader( descriptor: LimrunAppLogDescriptor, dependencies: LimrunRuntimeDependencies, ): Promise { - const client = await createIosInstanceClient({ - apiUrl: access.apiUrl, - token: access.token, - logLevel: 'warn', - }); + const client = withInstanceCredentialScrubbing( + await createIosInstanceClient({ + apiUrl: access.apiUrl, + token: access.token, + ...LIMRUN_INSTANCE_CLIENT_LOGGING, + }), + [`Bearer ${access.token}`], + ); const logs = dependencies.ios.createAppLogReader({ ...access, client }); const reader: LimrunAppLogReader = { platform: 'ios', @@ -147,12 +159,15 @@ async function openAndroidReader( descriptor: LimrunAppLogDescriptor, dependencies: LimrunRuntimeDependencies, ): Promise { - const client = await createAndroidInstanceClient({ - apiUrl: access.apiUrl, - adbUrl: access.adbUrl, - token: access.token, - logLevel: 'warn', - }); + const client = withInstanceCredentialScrubbing( + await createAndroidInstanceClient({ + apiUrl: access.apiUrl, + adbUrl: access.adbUrl, + token: access.token, + ...LIMRUN_INSTANCE_CLIENT_LOGGING, + }), + [`Bearer ${access.token}`], + ); const rollback = new AsyncCleanupStack(); let adopted = false; rollback.defer(async () => { diff --git a/packages/provider-limrun/src/client-options.test.ts b/packages/provider-limrun/src/client-options.test.ts index d1e7149ce9..ba4334f8e0 100644 --- a/packages/provider-limrun/src/client-options.test.ts +++ b/packages/provider-limrun/src/client-options.test.ts @@ -1,6 +1,6 @@ import Limrun from '@limrun/api'; import { expect, test } from 'vitest'; -import { limrunUserAgent } from './client-options.ts'; +import { fromLimrunOrgApi, limrunUserAgent, LIMRUN_ORG_CLIENT_LOGGING } from './client-options.ts'; test('the Limrun SDK sends the agent-device prefix ahead of its own User-Agent', async () => { const userAgents: Array = []; @@ -25,3 +25,65 @@ test('the Limrun SDK sends the agent-device prefix ahead of its own User-Agent', expect(userAgent).toMatch(/^agent-device-cli\/1\.2\.3 Limrun\/JS /); } }); + +// The SDK builds an error's message from the response body and logs the failed request around it. Both +// are Limrun's own text, and this client authenticates with the account key, so neither may leave here. +test.each([401, 403, 404, 429, 500])( + 'an account-API refusal answers with its status alone (HTTP %i)', + async (status) => { + const apiKey = 'lim_test_key_0123456789abcdef'; + const limrun = new Limrun({ + apiKey, + baseURL: 'https://limrun.example', + maxRetries: 0, + ...LIMRUN_ORG_CLIENT_LOGGING, + fetch: async () => + new Response(JSON.stringify({ message: `key ${apiKey} rejected for account ${apiKey}` }), { + status, + headers: { 'content-type': 'application/json' }, + }), + }); + + let failure: unknown; + await fromLimrunOrgApi(limrun.iosInstances.list({ limit: 1 })).catch((error: unknown) => { + failure = error; + }); + + expect(failure).toBeInstanceOf(Error); + const error = failure as { code?: string; message?: string; details?: Record }; + expect(error.details).toEqual({ + status, + reason: + status === 401 || status === 403 + ? 'limrun_api_unauthorized' + : status === 404 + ? 'limrun_api_not_found' + : status === 429 + ? 'limrun_api_rate_limited' + : 'limrun_api_failed', + }); + expect(JSON.stringify({ message: error.message, details: error.details })).not.toContain( + apiKey, + ); + }, +); + +// `off` is the SDK's own value for logging nothing, and the option outranks LIMRUN_LOG. Without it the +// SDK defaults to `warn` and follows that variable, and each failed request's details are written. +test('the organization client this plugin builds logs nothing, whatever LIMRUN_LOG names', () => { + const previous = process.env.LIMRUN_LOG; + process.env.LIMRUN_LOG = 'debug'; + try { + const withoutTheOption = new Limrun({ apiKey: 'lim_test_key' }); + const builtByThisPlugin = new Limrun({ + apiKey: 'lim_test_key', + ...LIMRUN_ORG_CLIENT_LOGGING, + }); + + expect(withoutTheOption.logLevel).toBe('debug'); + expect(builtByThisPlugin.logLevel).toBe('off'); + } finally { + if (previous === undefined) delete process.env.LIMRUN_LOG; + else process.env.LIMRUN_LOG = previous; + } +}); diff --git a/packages/provider-limrun/src/client-options.ts b/packages/provider-limrun/src/client-options.ts index 7f0997f335..49dbd141db 100644 --- a/packages/provider-limrun/src/client-options.ts +++ b/packages/provider-limrun/src/client-options.ts @@ -1,5 +1,5 @@ import type Limrun from '@limrun/api'; -import { AppError, errorMessage } from '@agent-device/kernel/errors'; +import { AppError, errorMessage, type ReasonTable } from '@agent-device/kernel/errors'; import type { LimrunDeleteResult } from './lease-ownership.ts'; export const LIMRUN_CLIENT_ID = 'agent-device-cli'; @@ -20,6 +20,30 @@ export function limrunUserAgent(clientVersion: string): string { */ export const LIMRUN_SINGLE_ATTEMPT = Object.freeze({ maxRetries: 0 }); +/** + * Silences the SDK's own logging on every client this plugin builds. + * + * The SDK writes a failed request's response body, and the request details around it, to the console + * before it throws — at `warn` by default, and at whatever `LIMRUN_LOG` names. Those bodies are the + * peer's text and this plugin authenticates with an account key or an instance token, so a plain-text + * error body can carry one of them unlabelled and no error handling downstream can take it back out. + * `off` for the organization client and `none` for an instance client are the two SDKs' own values for + * "log nothing"; the request's typed status and this plugin's own diagnostics still answer for a + * failure. + */ +export const LIMRUN_ORG_CLIENT_LOGGING = Object.freeze({ logLevel: 'off' }); + +/** See {@link LIMRUN_ORG_CLIENT_LOGGING}. An instance client spells the same setting `none`. */ +export const LIMRUN_INSTANCE_CLIENT_LOGGING = Object.freeze({ logLevel: 'none' }) as Readonly<{ + logLevel: 'none'; +}>; + +/** Verifies an attached instance without letting it reconnect, and logs nothing. */ +export const LIMRUN_INSTANCE_PROBE_OPTIONS = Object.freeze({ + ...LIMRUN_INSTANCE_CLIENT_LOGGING, + maxReconnectAttempts: 0, +}); + /** * Ends one instance, answering with no failure once Limrun has it gone and with a failure string and its error * otherwise. Like the create, the delete is asked for in one attempt: a lost answer is ambiguous, and this @@ -39,12 +63,25 @@ export async function deleteLimrunInstance( } return { failure: undefined, cause: undefined }; } catch (error) { - // A 404 names the outcome this request was after, however it came about. + // A 404 is Limrun answering that the instance is already gone, however it came about. if (readHttpStatus(error) === 404) return { failure: undefined, cause: undefined }; - return { failure: errorMessage(error), cause: error }; + // The failure string is written to the release record a caller reads back, and the SDK's own text is + // the response body, which can carry the account key. The status answers for it instead. + const normalized = limrunOrgApiError(error); + return { failure: errorMessage(normalized), cause: normalized }; } } +/** + * Whether a failure answers that the account API has nothing for what was asked — an instance that is + * already gone. Callers that act on that outcome read this instead of the SDK's own error class, since + * every account-API failure this plugin raises is normalized to a typed `AppError`. + */ +export function isLimrunApiNotFound(error: unknown): boolean { + if (error instanceof AppError && error.details?.reason === 'limrun_api_not_found') return true; + return readHttpStatus(error) === 404; +} + /** The HTTP status of an SDK failure, for a route that can answer for one particular refusal. */ function readHttpStatus(error: unknown): number | undefined { if (!error || typeof error !== 'object') return undefined; @@ -61,3 +98,63 @@ export function requireLimrunOrgClient( if (limrun) return limrun; throw new AppError('UNSUPPORTED_OPERATION', `${operation} requires a Limrun API key.`, { hint }); } + +/** + * Answers for one organization-API failure with this runtime's own words. + * + * The SDK builds an error's message from the response body — the body's `message` field, or the whole + * body serialized — and that text is what a lease create, an asset list, or a delete returns to the + * daemon, which records it and answers the caller with it. A body is Limrun's own text: it can name a + * value this process authenticates with, and nothing downstream can pick a secret back out of a message + * once it has been logged. So the account API's failures are re-raised as an `AppError` that keeps the + * two things a caller acts on, the status and what kind of refusal it was, and adds nothing else. + */ +export async function fromLimrunOrgApi(request: Promise): Promise { + try { + return await request; + } catch (error) { + throw limrunOrgApiError(error); + } +} + +/** + * Every `details.reason` a failure of the organization API publishes. The account API's own text is not + * published with it: the SDK builds its message from the response body, which can name the account key. + */ +const LIMRUN_ORG_API_REASONS = { + // The account key was refused or lacks access to what was asked for. + unauthorized: { reason: 'limrun_api_unauthorized' }, + // The account API has nothing under the identifier the request named. + notFound: { reason: 'limrun_api_not_found' }, + // The account API is taking this key's requests too fast to answer them. + rateLimited: { reason: 'limrun_api_rate_limited' }, + // The account API refused the request for a reason with no separate recovery. + rejected: { reason: 'limrun_api_failed' }, +} as const satisfies ReasonTable<'limrun'>; + +/** + * Re-raises one organization-API failure as this runtime's own error. See {@link fromLimrunOrgApi}. + * A 404 keeps its own reason: a caller that acts on a gone instance reads it. + */ +function limrunOrgApiError(error: unknown): unknown { + const status = readHttpStatus(error); + if (status === undefined) return error; + const code = + status === 401 || status === 403 + ? 'UNAUTHORIZED' + : status === 404 + ? 'DEVICE_NOT_FOUND' + : 'COMMAND_FAILED'; + const reason = + status === 401 || status === 403 + ? LIMRUN_ORG_API_REASONS.unauthorized.reason + : status === 404 + ? LIMRUN_ORG_API_REASONS.notFound.reason + : status === 429 + ? LIMRUN_ORG_API_REASONS.rateLimited.reason + : LIMRUN_ORG_API_REASONS.rejected.reason; + return new AppError(code, `Limrun rejected the request (${status}).`, { + status, + reason, + }); +} diff --git a/packages/provider-limrun/src/connection-verification.ts b/packages/provider-limrun/src/connection-verification.ts index 1960ddec4c..97f56d0e11 100644 --- a/packages/provider-limrun/src/connection-verification.ts +++ b/packages/provider-limrun/src/connection-verification.ts @@ -2,7 +2,11 @@ import Limrun from '@limrun/api'; import { AppError } from '@agent-device/kernel/errors'; import type { ProviderConnectionVerification } from '@agent-device/contracts/remote'; import type { LimrunInstanceAccess } from './instance-access.ts'; -import { limrunUserAgent } from './client-options.ts'; +import { + LIMRUN_INSTANCE_PROBE_OPTIONS, + LIMRUN_ORG_CLIENT_LOGGING, + limrunUserAgent, +} from './client-options.ts'; export type LimrunConnectionVerification = ProviderConnectionVerification & { provider: 'limrun'; @@ -43,6 +47,7 @@ export async function verifyLimrunConnection( userAgent: limrunUserAgent(options.clientVersion), timeout: 15_000, maxRetries: 0, + ...LIMRUN_ORG_CLIENT_LOGGING, }); const query = { limit: 1, ...(options.region ? { region: options.region } : {}) }; try { @@ -91,7 +96,7 @@ function readStatus(error: unknown): number | undefined { function connectAttachedInstance( options: LimrunConnectionVerificationOptions, ): Promise<{ disconnect(): void }> | undefined { - const clientOptions = { logLevel: 'none', maxReconnectAttempts: 0 } as const; + const clientOptions = LIMRUN_INSTANCE_PROBE_OPTIONS; const { ios, android } = options.instances ?? {}; if (options.platform === 'android') { return ( diff --git a/packages/provider-limrun/src/connection.test.ts b/packages/provider-limrun/src/connection.test.ts index 82835f7140..66a55f9294 100644 --- a/packages/provider-limrun/src/connection.test.ts +++ b/packages/provider-limrun/src/connection.test.ts @@ -230,6 +230,7 @@ test('verify asks the selected platform of the account the scoped credentials re userAgent: 'agent-device-cli/1.2.3', timeout: 15_000, maxRetries: 0, + logLevel: 'off', }, ]); assert.deepEqual(limrunSdk.iosList.mock.calls, [[{ limit: 1 }]]); diff --git a/packages/provider-limrun/src/download-file.test.ts b/packages/provider-limrun/src/download-file.test.ts index f94fe2699b..a4c7b7d503 100644 --- a/packages/provider-limrun/src/download-file.test.ts +++ b/packages/provider-limrun/src/download-file.test.ts @@ -60,7 +60,7 @@ test('a non-2xx answer is a typed failure carrying the status and no file is lef downloadLimrunFile({ url, headers: {}, destinationPath, timeoutMs: 5_000 }), ).rejects.toMatchObject({ code: 'COMMAND_FAILED', - details: { statusCode: 404, body: 'no active recording' }, + details: { statusCode: 404, reason: 'limrun_download_http_error' }, }); expect(fs.existsSync(destinationPath)).toBe(false); }); @@ -84,27 +84,27 @@ test('a stalled transfer ends at the deadline as a typed timeout and removes the expect(fs.existsSync(destinationPath)).toBe(false); }); -test('a non-2xx answer whose body stalls ends at the deadline as the typed timeout', async () => { +test('a non-2xx answer whose body stalls is answered by its status without waiting for the body', async () => { const url = await serve((_request, response) => { response.writeHead(503); response.write('upstr'); - // Never end: the error body stalls like a transfer can. + // Never end: nothing here reads the body, so the status answers at once. }); const destinationPath = path.join(await mkdtempForTest('limrun-download-'), 'clip.mp4'); await expect( - downloadLimrunFile({ url, headers: {}, destinationPath, timeoutMs: 150 }), + downloadLimrunFile({ url, headers: {}, destinationPath, timeoutMs: 5_000 }), ).rejects.toMatchObject({ code: 'COMMAND_FAILED', - message: 'Limrun download timed out', - details: { timeoutMs: 150 }, + details: { statusCode: 503, reason: 'limrun_download_http_error' }, }); }); -// The instance authenticates with a bearer token and its own error body can echo it unlabeled, so -// core's pattern redaction cannot see it. The typed status and reason still answer for the failure. -test('an error body that echoes the instance token publishes it redacted', async () => { - const token = 'liminst_5f4dcc3b5aa765d61d8327deb882cf99'; +// The download route is authenticated with the instance token, and an error body is the peer's own text, +// which can echo that token as a bare value. So no body text is published at all: the typed status and +// reason answer for the failure, and the token cannot survive a clipping or a short length. +test('an HTTP failure publishes its status and reason, and no peer body text at all', async () => { + const token = 'abc123'; const url = await serve((_request, response) => { response.writeHead(500); response.end(`upstream rejected ${token} for this transfer`); @@ -122,13 +122,36 @@ test('an error body that echoes the instance token publishes it redacted', async }); expect(failure).toBeInstanceOf(AppError); - expect((failure as AppError).details).toMatchObject({ + expect((failure as AppError).details).toEqual({ statusCode: 500, reason: 'limrun_download_http_error', }); expect(JSON.stringify((failure as AppError).details)).not.toMatch(token); }); +// A malformed URL is the failure an attached instance can cause: it answers with its bare bearer token +// as the download URL. Neither the URL nor fetch's message about it may be published. +test('a malformed download URL publishes neither the URL nor the transport message', async () => { + const token = 'liminst_9b74c9897bac770ffc029102a200c5de'; + const destinationPath = path.join(await mkdtempForTest('limrun-download-'), 'clip.mp4'); + + let failure: unknown; + await downloadLimrunFile({ + url: token, + headers: { Authorization: `Bearer ${token}` }, + destinationPath, + timeoutMs: 5_000, + }).catch((error: AppError) => { + failure = error; + }); + + expect(failure).toBeInstanceOf(AppError); + const details = (failure as AppError).details ?? {}; + expect(details).toEqual({ reason: 'limrun_download_failed', transport: 'invalid-request' }); + expect(JSON.stringify(details)).not.toMatch(token); + expect(JSON.stringify((failure as AppError).cause ?? '')).not.toMatch(token); +}); + test('a failed retry removes the file an earlier attempt left at the destination', async () => { const url = await serve((_request, response) => { response.writeHead(500); @@ -160,27 +183,11 @@ test('a destination directory that cannot be created ends typed without fetching await expect(failure).rejects.toMatchObject({ code: 'COMMAND_FAILED', message: 'Limrun download failed', - details: { url }, + details: { reason: 'limrun_download_failed', transport: 'EEXIST' }, }); expect(requests).toEqual([]); }); -test('an error body is read only up to the preview, without waiting for the rest', async () => { - const url = await serve((_request, response) => { - response.writeHead(502); - response.write('x'.repeat(2_048)); - // Never end: the preview must not wait for the whole body. - }); - const destinationPath = path.join(await mkdtempForTest('limrun-download-'), 'clip.mp4'); - - await expect( - downloadLimrunFile({ url, headers: {}, destinationPath, timeoutMs: 5_000 }), - ).rejects.toMatchObject({ - code: 'COMMAND_FAILED', - details: { statusCode: 502, body: 'x'.repeat(500) }, - }); -}); - test.each(['default', 'typed', 'deadline'] as const)( 'a %s abort keeps its failure classification and removes partial downloads', async (kind) => { diff --git a/packages/provider-limrun/src/download-file.ts b/packages/provider-limrun/src/download-file.ts index 4d434a1e7f..4fb0e63da5 100644 --- a/packages/provider-limrun/src/download-file.ts +++ b/packages/provider-limrun/src/download-file.ts @@ -3,16 +3,33 @@ import path from 'node:path'; import { Readable } from 'node:stream'; import { pipeline } from 'node:stream/promises'; import type { ReadableStream as WebReadableStream } from 'node:stream/web'; -import { AppError, createRequestCanceledError } from '@agent-device/kernel/errors'; -import { safeInstanceErrorText } from './error-text.ts'; +import { + AppError, + createRequestCanceledError, + type ReasonTable, +} from '@agent-device/kernel/errors'; import type { LimrunFileDownload } from './runtime-dependencies.ts'; -const RESPONSE_BODY_PREVIEW_BYTES = 500; +/** Every `details.reason` a Limrun file download publishes. */ +const LIMRUN_DOWNLOAD_REASONS = { + // The instance answered the download with no body at all, so nothing could reach disk. + emptyBody: { reason: 'limrun_download_empty_body' }, + // The instance refused the download; its HTTP status answers for the refusal. + httpError: { reason: 'limrun_download_http_error' }, + // The transfer's own deadline passed before the file reached disk. + timeout: { reason: 'limrun_download_timeout' }, + // The transfer failed before it could ask the instance for the file. + failed: { reason: 'limrun_download_failed' }, +} as const satisfies ReasonTable<'limrun'>; /** * Streams one authenticated Limrun download to disk. The transfer is bounded by `timeoutMs`; a * failed or timed-out attempt leaves no file at the destination, so the caller can retry from the * same URL and never mistakes an earlier attempt's file for this one's. + * + * A destination is a file this process chose, so a caller reads back what it asked for. The URL is not + * published: an attached instance answers with a download URL that carries its bearer token as the + * whole value, so the URL is a credential, not a location. */ export async function downloadLimrunFile(options: LimrunFileDownload): Promise { const timeout = AbortSignal.timeout(options.timeoutMs); @@ -24,10 +41,11 @@ export async function downloadLimrunFile(options: LimrunFileDownload): Promise { +/** + * Refuses a download by its HTTP status. The peer's body is deliberately unread: it is the peer's own + * text and this request is authenticated with a token the peer can echo, so a published preview could + * carry that token out with or without its label. `statusCode` is what a caller acts on — a missing + * recording and a missing file are both a 404 answer, not a failure of the transfer. + */ +function httpFailure(response: Response): AppError { + void response.body?.cancel().catch(() => {}); return new AppError('COMMAND_FAILED', `Limrun download failed with HTTP ${response.status}`, { - url: options.url, statusCode: response.status, - reason: 'limrun_download_http_error', - body: safeInstanceErrorText(await readBodyPreview(response), Object.values(options.headers)), + reason: LIMRUN_DOWNLOAD_REASONS.httpError.reason, }); } -/** Reads at most the preview's bytes of an error body; a body that stalls fails like the transfer. */ -async function readBodyPreview(response: Response): Promise { - if (!response.body) return ''; - const reader = response.body.getReader(); - const chunks: Uint8Array[] = []; - let bytes = 0; - try { - while (bytes < RESPONSE_BODY_PREVIEW_BYTES) { - const { done, value } = await reader.read(); - if (done) break; - const room = RESPONSE_BODY_PREVIEW_BYTES - bytes; - chunks.push(value.subarray(0, room)); - bytes += value.byteLength; - } - } finally { - void reader.cancel().catch(() => {}); - } - return Buffer.concat(chunks).toString('utf8'); -} - +/** + * Names why a download did not reach disk. A fetch failure's own text is not published: it can quote + * the request URL, and this request's URL can be the caller's instance token. The failure is answered + * by its typed reason and by the transport class: a rejected URL, a refused connection, or an + * interrupted transfer. + */ function downloadFailure( error: unknown, options: LimrunFileDownload, @@ -83,27 +92,31 @@ function downloadFailure( if (!(reason instanceof Error && reason.name === 'TimeoutError')) { return createRequestCanceledError(undefined, reason); } - return new AppError( - 'COMMAND_FAILED', - 'Limrun download deadline expired', - { - url: options.url, - reason: 'limrun_download_timeout', - timeoutMs: options.timeoutMs, - }, - reason, - ); + return new AppError('COMMAND_FAILED', 'Limrun download deadline expired', { + reason: LIMRUN_DOWNLOAD_REASONS.timeout.reason, + timeoutMs: options.timeoutMs, + transport: transportSummary(error), + }); } if (timeout.aborted) { return new AppError('COMMAND_FAILED', 'Limrun download timed out', { - url: options.url, + reason: LIMRUN_DOWNLOAD_REASONS.timeout.reason, timeoutMs: options.timeoutMs, - reason: 'limrun_download_timeout', }); } return new AppError('COMMAND_FAILED', 'Limrun download failed', { - url: options.url, - reason: 'limrun_download_failed', - cause: error instanceof Error ? error.message : String(error), + reason: LIMRUN_DOWNLOAD_REASONS.failed.reason, + transport: transportSummary(error), }); } + +/** + * The transport's own code for a failure, without its message. `fetch` names a malformed request URL + * with a `TypeError` and reports a socket failure with a Node code like `ECONNREFUSED`; both answer for + * what went wrong without quoting the request it happened on. + */ +function transportSummary(error: unknown): string { + if (error instanceof TypeError) return 'invalid-request'; + const code = (error as { code?: unknown } | null)?.code; + return typeof code === 'string' && code.length > 0 ? code : 'unknown'; +} diff --git a/packages/provider-limrun/src/error-text.test.ts b/packages/provider-limrun/src/error-text.test.ts index 9552363d4f..3589b4dfcf 100644 --- a/packages/provider-limrun/src/error-text.test.ts +++ b/packages/provider-limrun/src/error-text.test.ts @@ -1,5 +1,9 @@ import { describe, expect, test } from 'vitest'; -import { safeInstanceErrorText } from './error-text.ts'; +import { + createInstanceStreamScrubber, + safeInstanceErrorText, + safeTerminationReason, +} from './error-text.ts'; const TOKEN = 'liminst_5f4dcc3b5aa765d61d8327deb882cf99'; @@ -24,9 +28,131 @@ describe('safeInstanceErrorText', () => { ); }); - test('ignores a short header word, which is a scheme name rather than a secret', () => { - expect(safeInstanceErrorText('Bearer is not enough', ['Bearer ab'])).toBe( + // The credential reader of an attached instance accepts any nonempty token, so a short one is still a + // secret. The scheme name is not: it is the same word every request sends. + test.each(['abc123', 'x', 'a b'])('removes a short credential however brief: %s', (token) => { + expect(safeInstanceErrorText(`echo ${token} here`, [`Bearer ${token}`])).toBe( + 'echo [REDACTED] here', + ); + expect(safeInstanceErrorText('Bearer is not enough', [`Bearer ${token}`])).toBe( 'Bearer is not enough', ); }); }); + +describe('createInstanceStreamScrubber', () => { + const headers = [`Bearer ${TOKEN}`]; + + test('removes a credential split across two chunks', () => { + const scrubber = createInstanceStreamScrubber(headers); + const half = Math.floor(TOKEN.length / 2); + const published = + scrubber.push(`stream said ${TOKEN.slice(0, half)}`) + + scrubber.push(`${TOKEN.slice(half)} then stopped`) + + scrubber.flush(); + + expect(published).not.toContain(TOKEN); + expect(published).toContain('stream said'); + expect(published).toContain('then stopped'); + }); + + test.each([1, 2, 3, 7, 13, TOKEN.length, TOKEN.length + 5])( + 'removes a credential published in chunks of %i characters', + (size) => { + const scrubber = createInstanceStreamScrubber(headers); + const line = `runner failed on ${TOKEN} during boot`; + let published = ''; + for (let offset = 0; offset < line.length; offset += size) { + published += scrubber.push(line.slice(offset, offset + size)); + } + published += scrubber.flush(); + + expect(published).not.toContain(TOKEN); + expect(published).toContain('runner failed on'); + expect(published).toContain('during boot'); + }, + ); + + test('answers with the whole text when nothing can still be a credential', () => { + const scrubber = createInstanceStreamScrubber(headers); + expect(scrubber.push('simulator booted but the runner exited early') + scrubber.flush()).toBe( + 'simulator booted but the runner exited early', + ); + }); + + // The stream is a live log: a reader waits on each push, so only a tail that could still be the start of + // a credential may be held back. `'l'` is this token's first character, so it is the one held. + test.each([ + ['simulator booted', 'simulator booted'], + ['simulator booted l', 'simulator booted '], + ] as const)('releases %j on the push that carries it', (chunk, expected) => { + const scrubber = createInstanceStreamScrubber(headers); + expect(scrubber.push(chunk)).toBe(expected); + }); + + test('a held character that turns out to be ordinary reaches the reader with its chunk', () => { + const scrubber = createInstanceStreamScrubber(headers); + expect(scrubber.push('booted l')).toBe('booted '); + expect(scrubber.push('aunch succeeded')).toBe('launch succeeded'); + expect(scrubber.flush()).toBe(''); + }); +}); + +describe('safeTerminationReason', () => { + // The reason ends a lease through an error's message, and a message is not bound the way a detail is. + test.each([ + [' InactivityTimeout ', 'InactivityTimeout'], + [ + 'inactivity timeout reached\nLIMRUN_API_KEY=leaked\nsecond line', + 'inactivity timeout reached LIMRUN_API_KEY=leaked second line', + ], + ] as const)('reads %j into one published line', (input, expected) => { + expect(safeTerminationReason(input, [])).toBe(expected); + }); + + test('answers Unknown for a terminated instance that gave no reason', () => { + for (const reason of [undefined, '', ' ']) { + expect(safeTerminationReason(reason, [])).toBe('Unknown'); + } + }); + + test('publishes a reason that names the account key scrubbed, on one bounded line', () => { + const apiKey = 'lim_test_key_0123456789abcdef'; + const reason = `terminated after ${'drain '.repeat(60)}while ${apiKey} was in use`; + + const published = safeTerminationReason(reason, [apiKey]); + + expect(published).not.toContain(apiKey); + expect(published).not.toContain('\n'); + expect(published.length).toBeLessThanOrEqual(201); + }); + + // The bound falls inside the credential: the lead-in puts the token across the 200-character cut, so + // shortening the text before it is read would publish the token's own first characters, which are no + // longer a whole secret and so cannot be recognised or removed. The cut may also fall inside the marker + // that stands for a credential, which must not be published half. + test.each([180, 191, 200, 214, 229, 230, 231])( + 'bounds a reason whose credential starts at character %i without publishing a fragment', + (leadIn) => { + const reason = `${'x'.repeat(leadIn)} ${TOKEN} during drain`; + + const published = safeTerminationReason(reason, [`Bearer ${TOKEN}`]); + + for (let length = 6; length <= TOKEN.length; length++) { + expect(published).not.toContain(TOKEN.slice(0, length)); + } + const bounded = published.endsWith('…') ? published.slice(0, -1) : published; + for (const partial of MARKER_PARTIALS) { + expect(bounded.endsWith(partial)).toBe(false); + } + expect(published).not.toContain('\n'); + expect(published.length).toBeLessThanOrEqual(201); + }, + ); +}); + +/** Every proper prefix of the marker `safeInstanceErrorText` answers with. */ +const MARKER = '[REDACTED]'; +const MARKER_PARTIALS = Array.from({ length: MARKER.length - 1 }, (_, length) => + MARKER.slice(0, length + 1), +); diff --git a/packages/provider-limrun/src/error-text.ts b/packages/provider-limrun/src/error-text.ts index 577f1d6ad4..c1aee5b63b 100644 --- a/packages/provider-limrun/src/error-text.ts +++ b/packages/provider-limrun/src/error-text.ts @@ -1,38 +1,133 @@ -/** Below this length a word of a credential header is a scheme name or a common word, not a secret. */ -const MIN_SECRET_LENGTH = 8; - /** - * Reads an instance's own error text into a diagnostic this process may publish. + * Reads an instance's own text into something this process may publish. * - * The caller authenticates to the instance with a token that the instance's error body can echo, and - * core redacts only what it recognizes by pattern: an unlabeled body that repeats the bare token - * survives. So every value the caller sent to this endpoint is removed first. Core still bounds and - * pattern-redacts what this returns, as it does for every error detail. The status and typed reason - * are published as details next to this text, so the text carries no other duty. + * The caller authenticates to the instance with a token that the instance's text can echo, and core + * redacts only what it recognizes by pattern: an unlabeled echo of the bare token survives. So every + * value the caller sent to this endpoint is removed first. Core still bounds and pattern-redacts what + * this returns, as it does for every error detail. The status and typed reason are published as details + * next to this text, so the text carries no other duty. */ export function safeInstanceErrorText( text: string, sentValues: Iterable, ): string { let output = text; + for (const secret of instanceSecrets(sentValues)) { + output = output.split(secret).join(REPLACEMENT); + } + return output; +} + +const REPLACEMENT = '[REDACTED]'; + +/** One whitespace-separated header value's parts: a scheme name carries no secret on its own. */ +const CREDENTIAL_SCHEMES = new Set(['bearer', 'basic', 'token', 'digest']); + +/** + * Every secret value the caller sent: each header value whole, and its credential on its own, which is + * the form an instance echoes. A short credential is still a credential — the reader of an attached + * instance's token accepts any nonempty value — so no candidate is skipped for being brief. + */ +function instanceSecrets(sentValues: Iterable): string[] { + const secrets = new Set(); for (const value of sentValues) { - if (!value) continue; - for (const secret of secretParts(value)) { - output = output.split(secret).join('[REDACTED]'); + const trimmed = value?.trim(); + if (!trimmed) continue; + secrets.add(trimmed); + const [scheme = '', ...rest] = trimmed.split(/\s+/); + const credential = rest.join(' ').trim(); + if (credential.length > 0 && CREDENTIAL_SCHEMES.has(scheme.toLowerCase())) { + secrets.add(credential); } } - return output; + // The longest first, so a header value is replaced before its own shorter credential is. + return [...secrets].sort((left, right) => right.length - left.length); +} + +/** + * A scrubber for one authenticated stream, safe across chunk boundaries. + * + * The credential is not atomic in the stream: a chunk can end in the first half of a token and the next + * can carry the rest, and no chunk on its own then holds anything to match. So each push scrubs what it + * holds and releases all of it except the tail that could still be the beginning of a credential — the + * longest ending of it that is a proper prefix of one. `flush()` releases what a finished stream holds + * back. The replacement marker itself may straddle two answers; concatenated, they read as one marker. + */ +export function createInstanceStreamScrubber(sentValues: Iterable): { + /** Scrubs what the stream holds plus `chunk`, and answers with the text now safe to publish. */ + push(chunk: string): string; + /** Scrubs and answers with whatever the stream still holds back at its end. */ + flush(): string; +} { + const secrets = instanceSecrets(sentValues); + let pending = ''; + return { + push(chunk) { + pending = safeInstanceErrorText(pending + chunk, secrets); + const releaseEnd = pending.length - longestCredentialPrefixAtTheEnd(pending, secrets); + const released = pending.slice(0, releaseEnd); + pending = pending.slice(releaseEnd); + return released; + }, + flush() { + const released = safeInstanceErrorText(pending, secrets); + pending = ''; + return released; + }, + }; } -/** The secret values one header value carries: itself, and each of its long whitespace parts. */ -function secretParts(value: string): string[] { - const parts = new Set([value.trim()].filter(isSecretLength)); - for (const part of value.split(/\s+/)) { - if (isSecretLength(part)) parts.add(part); +/** + * How much of `text`'s end could still be the beginning of a credential: the longest ending of it that is + * a proper prefix of one. Only that much has to wait for the next chunk, since a credential reaching + * across the released boundary would have to start inside what is held back. + */ +function longestCredentialPrefixAtTheEnd(text: string, secrets: readonly string[]): number { + const longest = longestSecretLength(secrets); + for (let length = Math.min(text.length, longest - 1); length > 0; length--) { + const ending = text.slice(-length); + if (secrets.some((secret) => secret.length > length && secret.startsWith(ending))) + return length; } - return [...parts]; + return 0; +} + +function longestSecretLength(secrets: readonly string[]): number { + return secrets.reduce((longest, secret) => Math.max(longest, secret.length), 0); +} + +/** How much of the peer's own classification this process publishes. */ +const MAX_PUBLISHED_REASON_LENGTH = 200; + +/** + * Reads the account API's reason for ending an instance into text this process may publish. + * + * The field is Limrun's own classification and its length is not bounded here. It is published in the + * message and the details of the error that ends a lease, and a message is not bound the way a detail + * is, so a reason carrying a newline would put a second line into a log and one carrying the account + * key would hand it to every reader of the lease. So it is shortened to one line and scrubbed like any + * other peer text; an empty answer is still answered with `Unknown`. + * + * The text is scrubbed before it is shortened. A credential the peer echoed can sit across the cut, and + * shortening first would publish the characters it holds up to the cut: no longer the whole credential, + * so nothing recognizes or removes them. The cut can also fall inside the marker that stands for a + * credential, and a published line never ends with half of one. + */ +export function safeTerminationReason( + reason: string | undefined, + sentValues: Iterable, +): string { + const trimmed = reason?.trim(); + if (!trimmed) return 'Unknown'; + const oneLine = safeInstanceErrorText(trimmed.replaceAll(/\s+/g, ' '), sentValues); + if (oneLine.length <= MAX_PUBLISHED_REASON_LENGTH) return oneLine; + return `${withoutTrailingPartialMarker(oneLine.slice(0, MAX_PUBLISHED_REASON_LENGTH))}…`; } -function isSecretLength(value: string): boolean { - return value.length >= MIN_SECRET_LENGTH; +/** Drops the tail of `text` that is the beginning of a replacement marker but not a whole one. */ +function withoutTrailingPartialMarker(text: string): string { + for (let length = REPLACEMENT.length - 1; length > 0; length--) { + if (text.endsWith(REPLACEMENT.slice(0, length))) return text.slice(0, -length); + } + return text; } diff --git a/packages/provider-limrun/src/instance-error-scrubbing.test.ts b/packages/provider-limrun/src/instance-error-scrubbing.test.ts new file mode 100644 index 0000000000..b82c3519a4 --- /dev/null +++ b/packages/provider-limrun/src/instance-error-scrubbing.test.ts @@ -0,0 +1,169 @@ +import { describe, expect, test } from 'vitest'; +import { AppError } from '@agent-device/kernel/errors'; +import { + scrubPublishedError, + withInstanceCredentialScrubbing, +} from './instance-error-scrubbing.ts'; + +const TOKEN = 'liminst_c0ffee'; +const SENT = [`Bearer ${TOKEN}`]; + +type FakeClient = { + fails: () => Promise; + answers: () => Promise; + throwsNow: () => never; + state: { disconnect(): void }; + count: number; +}; + +function fakeClient(options: { rejectWith: unknown }): FakeClient { + return { + fails: async () => { + throw options.rejectWith; + }, + answers: async () => 'two apps installed', + throwsNow: () => { + throw new Error(`synchronous ${TOKEN}`); + }, + state: { disconnect: () => {} }, + count: 1, + }; +} + +// The instance client's failures are the peer's own text — a rejected frame, or a reply body — and this +// session authenticated the channel with the instance token, which an instance echoes as a bare value. +test.each([ + ['a raw Error naming the token', new Error(`frame rejected: ${TOKEN}`)], + [ + 'an AppError whose details name the token', + new AppError('COMMAND_FAILED', `install refused for ${TOKEN}`, { + reply: `token ${TOKEN} is not valid here`, + attempt: 2, + nested: { text: `${TOKEN}` }, + }), + ], +])('an instance command failure is published without the credential: %s', async (_name, error) => { + const client = withInstanceCredentialScrubbing(fakeClient({ rejectWith: error }), SENT); + + let failure: unknown; + await client.fails().catch((error: unknown) => { + failure = error; + }); + + expect(failure).toBeInstanceOf(Error); + const published = failure as { message: string; details?: unknown }; + expect(published.message).toMatch(/rejected|refused/); + expect(JSON.stringify({ message: published.message, details: published.details })).not.toContain( + TOKEN, + ); +}); + +test('a method that answers normally is passed through untouched', async () => { + const client = withInstanceCredentialScrubbing(fakeClient({ rejectWith: new Error('x') }), SENT); + + await expect(client.answers()).resolves.toBe('two apps installed'); +}); + +// A failure that names nothing this session sent is the command's own to answer for: the caller that +// caught it publishes its own reason and its own cause, so the wrapper must not answer first. +test('a rejection that names no sent value keeps its own failure', async () => { + const cause = new Error('SDK sync refused'); + const client = withInstanceCredentialScrubbing(fakeClient({ rejectWith: cause }), SENT); + + await expect(client.fails()).rejects.toBe(cause); +}); + +test('an AppError that names no sent value keeps its own code, details and cause', async () => { + const cause = new Error('device busy'); + const failure = new AppError( + 'COMMAND_FAILED', + 'the instance is busy', + { + reason: 'limrun_app_sync_failed', + platform: 'ios', + }, + cause, + ); + const client = withInstanceCredentialScrubbing(fakeClient({ rejectWith: failure }), SENT); + + await expect(client.fails()).rejects.toBe(failure); +}); + +test('a non-function member is read through unchanged', () => { + const client = withInstanceCredentialScrubbing(fakeClient({ rejectWith: new Error('x') }), SENT); + + expect(client.count).toBe(1); + expect(typeof client.state).toBe('object'); +}); + +// A synchronous throw happens before any request was made, so the call keeps the SDK's own error and the +// caller's own control flow. +test('a method that throws before a request was made keeps its own failure', () => { + const client = withInstanceCredentialScrubbing(fakeClient({ rejectWith: new Error('x') }), SENT); + + expect(() => client.throwsNow()).toThrow(TOKEN); +}); + +describe('scrubPublishedError', () => { + test('removes a credential from a published message and every detail string', () => { + const failure = new AppError('COMMAND_FAILED', `the runner failed for ${TOKEN}`, { + text: `401 Unauthorized: ${TOKEN}`, + statusCode: 401, + paths: ['Runner.xctestrun', TOKEN], + }); + + const scrubbed = scrubPublishedError(failure, SENT) as AppError; + + expect(scrubbed).toBeInstanceOf(AppError); + expect(scrubbed.code).toBe('COMMAND_FAILED'); + expect(scrubbed.details?.statusCode).toBe(401); + expect(scrubbed.details?.paths).toEqual(['Runner.xctestrun', '[REDACTED]']); + expect(JSON.stringify({ message: scrubbed.message, details: scrubbed.details })).not.toContain( + TOKEN, + ); + }); + + test('answers with the same error when nothing it publishes names a sent value', () => { + const failure = new AppError('COMMAND_FAILED', 'the runner exited early', { statusCode: 500 }); + + expect(scrubPublishedError(failure, SENT)).toBe(failure); + }); + + test('passes a failure this plugin did not build through unchanged', () => { + const failure = new TypeError(`bad url ${TOKEN}`); + + expect(scrubPublishedError(failure, SENT)).toBe(failure); + }); + + test('is a no-op when no credential was sent', () => { + const failure = new AppError('COMMAND_FAILED', `mentions ${TOKEN}`, { text: TOKEN }); + + expect(scrubPublishedError(failure, [])).toBe(failure); + }); + + // A cause is published as text too: the CLI prints `Cause: `. An AppError cause's own + // details are not published, so the rebuild keeps its code and its scrubbed message. + test('removes a credential from a cause the failure carries', () => { + const failure = new AppError( + 'COMMAND_FAILED', + 'the runner refused the command', + { reason: 'limrun_runner_upload_failed' }, + new AppError('COMMAND_FAILED', `refused: ${TOKEN}`, { response: `401 ${TOKEN}` }), + ); + + const scrubbed = scrubPublishedError(failure, SENT) as AppError; + + expect(scrubbed.cause).toBeInstanceOf(AppError); + const cause = scrubbed.cause as AppError; + expect(cause.code).toBe('COMMAND_FAILED'); + expect(cause.message).toBe('refused: [REDACTED]'); + expect(cause.details).toBeUndefined(); + }); + + test('a cause that names no sent value is the same object', () => { + const cause = new AppError('COMMAND_FAILED', 'the instance exited early'); + const failure = new AppError('COMMAND_FAILED', `refused: ${TOKEN}`, {}, cause); + + expect((scrubPublishedError(failure, SENT) as AppError).cause).toBe(cause); + }); +}); diff --git a/packages/provider-limrun/src/instance-error-scrubbing.ts b/packages/provider-limrun/src/instance-error-scrubbing.ts new file mode 100644 index 0000000000..cb99b6465c --- /dev/null +++ b/packages/provider-limrun/src/instance-error-scrubbing.ts @@ -0,0 +1,134 @@ +import { AppError, type ReasonTable } from '@agent-device/kernel/errors'; +import { safeInstanceErrorText } from './error-text.ts'; + +/** Every `details.reason` a command sent to an attached or created instance publishes. */ +const LIMRUN_INSTANCE_REASONS = { + // The instance refused or could not answer the command; its text, with this session's credential + // removed, is the message. + commandFailed: { reason: 'limrun_instance_command_failed' }, +} as const satisfies ReasonTable<'limrun'>; + +/** + * Wraps one connected instance client so a failure it answers with cannot carry this session's credential. + * + * The instance client speaks to its instance over a WebSocket and reports a rejected frame, an unreadable + * frame, or a refused command by throwing an `Error` whose message is the peer's own text — the frame + * itself, or the body of the reply. This plugin authenticated that channel with the instance token, and + * an instance that echoes it does so as a bare value core's pattern redaction cannot recognise. So every + * method of the client is answered through this wrapper: a failure that names a value this session sent + * is re-raised with that value removed, and keeps the original as its cause. + * + * A failure that names nothing this session sent is passed through untouched, so the command that caught + * it still answers with its own reason. A method's own answer, and a method that throws synchronously + * before a request was made, pass through untouched too. + */ +export function withInstanceCredentialScrubbing( + client: Client, + sentValues: Iterable, +): Client { + const secrets = [...sentValues].filter((value): value is string => typeof value === 'string'); + const scrub = (error: unknown): never => { + throw instanceCommandFailure(error, secrets); + }; + return new Proxy(client, { + get(target, property, receiver) { + const value = Reflect.get(target, property, receiver); + if (typeof value !== 'function') return value; + const method = value as (...args: unknown[]) => unknown; + return (...args: unknown[]) => { + const answer = method.apply(target, args); + return answer instanceof Promise ? answer.then(undefined, scrub) : answer; + }; + }, + }); +} + +/** + * Names a failed instance command with its own text, minus what this session sent. The peer's text stays + * the message: it is the only diagnosis of a rejected command an instance gives. A failure that names + * none of it is this plugin's caller's own error to answer for, and is returned as it came. + */ +function instanceCommandFailure(error: unknown, secrets: readonly string[]): unknown { + if (!(error instanceof Error)) return error; + if (error instanceof AppError) { + const text = safeInstanceErrorText(error.message, secrets); + const details = scrubPublishedDetails(error.details, secrets); + const cause = scrubPublishedCause(error.cause, secrets); + return text === error.message && details === error.details && cause === error.cause + ? error + : new AppError(error.code, text, details, cause); + } + const text = safeInstanceErrorText(error.message, secrets); + if (text === error.message) return error; + return new AppError('COMMAND_FAILED', text, { + reason: LIMRUN_INSTANCE_REASONS.commandFailed.reason, + }); +} + +/** + * Removes this session's credentials from an error this process is about to publish. + * + * The message, every string of the details, and a cause's message go: a failure that reached a caller's + * `--json` output, a daemon record, or a log line cannot be taken back, and core's redaction only answers + * for the values it recognises by pattern. An attached instance or a forwarding service in front of one is + * given this session's token to authenticate with and answers with its own text, so a bare echo of that + * token is the case no pattern can see. + */ +export function scrubPublishedError( + error: unknown, + sentValues: Iterable, +): unknown { + if (!(error instanceof AppError)) return error; + const secrets = [...sentValues].filter((value): value is string => typeof value === 'string'); + if (secrets.length === 0) return error; + const message = safeInstanceErrorText(error.message, secrets); + const details = scrubPublishedDetails(error.details, secrets); + const cause = scrubPublishedCause(error.cause, secrets); + if (message === error.message && details === error.details && cause === error.cause) return error; + return new AppError(error.code, message, details, cause); +} + +/** + * Removes this session's credentials from a cause this process publishes alongside a failure. Core reads a + * cause for its code and its message only, so those are the two parts a peer's text reaches, and a cause + * that named a sent value is rebuilt with just them. + */ +function scrubPublishedCause(cause: unknown, secrets: readonly string[]): unknown { + if (!(cause instanceof Error)) return cause; + const message = safeInstanceErrorText(cause.message, secrets); + if (message === cause.message) return cause; + return cause instanceof AppError ? new AppError(cause.code, message) : new Error(message); +} + +function scrubPublishedDetails( + details: Record | undefined, + sentValues: Iterable, +): Record | undefined { + if (details === undefined) return undefined; + const secrets = [...sentValues].filter((value): value is string => typeof value === 'string'); + if (secrets.length === 0) return details; + const scrubbed = scrubValue(details, secrets); + return scrubbed === details ? details : (scrubbed as Record); +} + +/** Rebuilds only the strings of a diagnostic value that name a sent credential; a type is preserved. */ +function scrubValue(value: unknown, secrets: readonly string[]): unknown { + if (typeof value === 'string') { + const scrubbed = safeInstanceErrorText(value, secrets); + return scrubbed === value ? value : scrubbed; + } + if (Array.isArray(value)) { + const entries = value.map((entry) => scrubValue(entry, secrets)); + return entries.every((entry, index) => entry === value[index]) ? value : entries; + } + if (value === null || typeof value !== 'object') return value; + const entries = Object.entries(value as Record).map( + ([key, entry]) => [key, scrubValue(entry, secrets)] as const, + ); + return entries.every( + ([key, entry], index) => + key === Object.keys(value)[index] && entry === (value as Record)[key], + ) + ? value + : Object.fromEntries(entries); +} diff --git a/packages/provider-limrun/src/ios-runner-errors.test.ts b/packages/provider-limrun/src/ios-runner-errors.test.ts index aa518bd128..12e672831d 100644 --- a/packages/provider-limrun/src/ios-runner-errors.test.ts +++ b/packages/provider-limrun/src/ios-runner-errors.test.ts @@ -56,6 +56,28 @@ test('shared startup failures retain their reason with a remote toolchain recove }); }); +test('a runner failure that echoes the forwarded credential publishes it scrubbed', async () => { + const token = 'abc123'; + const error = new AppError('COMMAND_FAILED', `the command route refused ${token}`, { + reason: 'IOS_RUNNER_CONNECT_TIMEOUT', + response: `401 Unauthorized: ${token}`, + }); + + let failure: unknown; + await withLimrunRunnerErrors(async () => { + throw error; + }, [`Bearer ${token}`]).catch((error: unknown) => { + failure = error; + }); + + const published = failure as AppError; + expect(published.code).toBe('COMMAND_FAILED'); + expect(published.details?.reason).toBe('IOS_RUNNER_CONNECT_TIMEOUT'); + expect(JSON.stringify({ message: published.message, details: published.details })).not.toContain( + token, + ); +}); + test('retains product-specific recovery instructions over the default hint', () => { expect( limrunRunnerError('limrun_runner_products_invalid', 'Invalid runner', { diff --git a/packages/provider-limrun/src/ios-runner-errors.ts b/packages/provider-limrun/src/ios-runner-errors.ts index 11b1b0272d..cf8f964ae8 100644 --- a/packages/provider-limrun/src/ios-runner-errors.ts +++ b/packages/provider-limrun/src/ios-runner-errors.ts @@ -1,4 +1,21 @@ -import { AppError, type AppErrorCode, type AppErrorDetails } from '@agent-device/kernel/errors'; +import { + AppError, + type AppErrorCode, + type AppErrorDetails, + type ReasonTable, +} from '@agent-device/kernel/errors'; +import { scrubPublishedError } from './instance-error-scrubbing.ts'; + +/** + * Every `details.reason` this module publishes on a runner failure it classifies itself. The capture + * failure below is the one it answers with in place of the runner's own: the recovery is the session's, + * not the simulator's, so the caller is told to reopen rather than to inspect the device. + */ +const LIMRUN_RUNNER_REASONS = { + // The runner's own capture failure is answered over: the recovery is to reopen this session, not to + // inspect the simulator. + snapshotUnavailable: { reason: 'limrun_runner_snapshot_unavailable' }, +} as const satisfies ReasonTable<'limrun'>; const hints = { limrun_xctest_slot_occupied: @@ -22,44 +39,58 @@ export function limrunRunnerError( return new AppError(code, message, { ...details, reason, hint: details.hint ?? hints[reason] }); } -/** Preserve the shared capture failure while naming the remote recovery action. */ -export async function withLimrunRunnerErrors(task: () => Promise): Promise { +/** + * Preserves the shared capture failure while naming the remote recovery action. + * + * Every failure a runner operation answers with is published to a caller, and the routes it went through + * are given this session's credentials: the command route forwards the instance's `Authorization` header, + * and a forwarding service in front of it answers a refusal with the value it was refused. So what leaves + * here has that value taken out of both its message and its details. + */ +export async function withLimrunRunnerErrors( + task: () => Promise, + sentValues: Iterable = [], +): Promise { try { return await task(); } catch (error) { if (!(error instanceof AppError)) throw error; - if (error.details?.runnerConnectFailureReason) { - throw new AppError( - error.code, - error.message, - { - ...error.details, - hint: hints.limrun_runner_launch_failed, - }, - error, - ); - } - const quality = error.details?.snapshotQuality as - | { state?: string; reasonCode?: string } - | undefined; - if ( - (error.details?.reason === 'invalid-viewport' || - error.details?.reason === 'missing-viewport' || - error.details?.reason === 'empty-snapshot') && - quality?.state === 'sparse' && - (quality.reasonCode === 'capture-failed' || quality.reasonCode === 'budget') - ) { - throw new AppError( - error.code, - 'The Limrun XCTest runner could not capture the simulator screen', - { - ...error.details, - reason: 'limrun_runner_snapshot_unavailable', - hint: 'Close and reopen the agent-device session to restart its XCTest runner. If snapshots still fail on this reused simulator, recreate the Limrun instance. Use a screenshot and coordinate actions to inspect its current screen; do not reuse snapshot refs.', - }, - error, - ); - } - throw error; + throw scrubPublishedError(withRunnerHint(error), sentValues); + } +} + +function withRunnerHint(error: AppError): AppError { + if (error.details?.runnerConnectFailureReason) { + return new AppError( + error.code, + error.message, + { + ...error.details, + hint: hints.limrun_runner_launch_failed, + }, + error, + ); + } + const quality = error.details?.snapshotQuality as + | { state?: string; reasonCode?: string } + | undefined; + if ( + (error.details?.reason === 'invalid-viewport' || + error.details?.reason === 'missing-viewport' || + error.details?.reason === 'empty-snapshot') && + quality?.state === 'sparse' && + (quality.reasonCode === 'capture-failed' || quality.reasonCode === 'budget') + ) { + return new AppError( + error.code, + 'The Limrun XCTest runner could not capture the simulator screen', + { + ...error.details, + reason: LIMRUN_RUNNER_REASONS.snapshotUnavailable.reason, + hint: 'Close and reopen the agent-device session to restart its XCTest runner. If snapshots still fail on this reused simulator, recreate the Limrun instance. Use a screenshot and coordinate actions to inspect its current screen; do not reuse snapshot refs.', + }, + error, + ); } + return error; } diff --git a/packages/provider-limrun/src/ios-runner-products.test.ts b/packages/provider-limrun/src/ios-runner-products.test.ts index 7218f2d430..37ef9ad525 100644 --- a/packages/provider-limrun/src/ios-runner-products.test.ts +++ b/packages/provider-limrun/src/ios-runner-products.test.ts @@ -208,3 +208,41 @@ for (const recover of [true, false]) { } }); } + +// A `/sync` reply is the instance's own JSON, and this request is authenticated with the instance +// token. Only a path this upload named is an answer about the sync; any other entry is peer text and +// stays out of the published details. +test('a sync answer naming an entry this upload did not send keeps it out of the failure', async () => { + const { createServer } = await import('node:http'); + const token = 'liminst_deadbeefcafe'; + const directory = await mkdtempForTest('runner-products-'); + await fs.writeFile(path.join(directory, 'Runner.xctestrun'), ''); + await fs.mkdir(path.join(directory, 'Runner.app')); + await fs.writeFile(path.join(directory, 'Runner.app/Runner'), 'runner executable'); + const server = createServer((_request, response) => { + response.setHeader('Content-Type', 'application/json'); + response.end(JSON.stringify({ ok: false, needFull: ['Runner.app/Runner', token] })); + }); + await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve)); + const address = server.address(); + if (!address || typeof address === 'string') throw new Error('Missing server address'); + try { + let failure: unknown; + await uploadLimrunRunnerProducts( + directory, + `http://127.0.0.1:${address.port}`, + token, + new AbortController().signal, + ['Runner.xctestrun'], + ).catch((error: unknown) => { + failure = error; + }); + + const details = (failure as { details?: { needFull?: string[] } }).details; + expect(details?.needFull).toEqual(['Runner.app/Runner']); + expect(JSON.stringify(details)).not.toContain(token); + } finally { + server.closeAllConnections(); + await new Promise((resolve) => server.close(() => resolve())); + } +}); diff --git a/packages/provider-limrun/src/ios-runner-products.ts b/packages/provider-limrun/src/ios-runner-products.ts index 660921daf1..08375fc386 100644 --- a/packages/provider-limrun/src/ios-runner-products.ts +++ b/packages/provider-limrun/src/ios-runner-products.ts @@ -205,16 +205,21 @@ export async function uploadLimrunRunnerProducts( }; await visit(''); const selected = payloadPaths ? files.filter((file) => payloadPaths.includes(file.path)) : files; + // Only a path this upload named is a sync answer: an entry the instance returns is its own text and + // can echo the token this request is authenticated with. So a failure names back only what it was + // asked to sync, and drops anything else it put in that field. + const knownProductPaths = new Set(files.map((file) => file.path)); for (let attempt = 0; attempt < 2; attempt++) { signal.throwIfAborted(); const result = await upload(attempt === 0 ? selected : files); - if (result.ok === true && !result.needFull?.length) return; - if (!result.needFull?.length || attempt === 1) { + const needFull = (result.needFull ?? []).filter((name) => knownProductPaths.has(name)); + if (result.ok === true && needFull.length === 0) return; + if (needFull.length === 0 || attempt === 1) { throw limrunRunnerError( 'limrun_runner_upload_failed', 'Limrun runner products could not be synchronized', { - needFull: result.needFull, + needFull, }, ); } diff --git a/packages/provider-limrun/src/ios-runner.ts b/packages/provider-limrun/src/ios-runner.ts index de468793b0..b41fbf06de 100644 --- a/packages/provider-limrun/src/ios-runner.ts +++ b/packages/provider-limrun/src/ios-runner.ts @@ -1,5 +1,5 @@ import { limrunRunnerError, withLimrunRunnerErrors } from './ios-runner-errors.ts'; -import { safeInstanceErrorText } from './error-text.ts'; +import { createInstanceStreamScrubber, safeInstanceErrorText } from './error-text.ts'; import { awaitWithSignal } from '@agent-device/kernel/await-with-signal'; import type { DeadlineClock } from '@agent-device/host-kit/retry'; import { createLimrunAppleToolProvider } from './ios-tools.ts'; @@ -32,7 +32,9 @@ export async function createLimrunIosRunner( const withTools = (task: () => Promise, signal?: AbortSignal) => apple.tools.withProvider( createLimrunAppleToolProvider(session, host, lifetime.signal, signal), - () => withLimrunRunnerErrors(task), + // The runner's command route is given this session's credential, so whatever a runner operation + // answers with has it taken out before a caller sees it. + () => withLimrunRunnerErrors(task, Object.values(headers)), ); const hostTools = withMethodScope({ ...apple.applicationTools }, (task) => apple.tools.hasScopedProvider() ? task() : withTools(task), @@ -224,15 +226,22 @@ export async function createLimrunIosRunner( const exited = new Promise((resolve) => { settle = resolve; }); + // The XCTest stream is the instance's own text, and this request carries the instance token to the + // forwarding service in front of it. What is published here is written to runner.log and to a startup + // failure, so every chunk goes through the scrubber, whose held tail carries a credential that a chunk + // boundary cut in half. async function* output() { const decoder = new TextDecoder(); + const scrubber = createInstanceStreamScrubber(Object.values(headers)); try { while (true) { const { done, value } = await reader.read(); if (done) break; - yield decoder.decode(value, { stream: true }); + const text = scrubber.push(decoder.decode(value, { stream: true })); + if (text.length > 0) yield text; } - yield decoder.decode(); + const tail = scrubber.push(decoder.decode()) + scrubber.flush(); + if (tail.length > 0) yield tail; } catch (error) { canceledRunMayHoldSlot = true; if (!signal.aborted) throw error; diff --git a/packages/provider-limrun/src/ios.ts b/packages/provider-limrun/src/ios.ts index ffbc838bfe..7c01aecb84 100644 --- a/packages/provider-limrun/src/ios.ts +++ b/packages/provider-limrun/src/ios.ts @@ -1,4 +1,5 @@ import type { LimrunSyncCache } from './sync-cache.ts'; +import { LIMRUN_INSTANCE_CLIENT_LOGGING } from './client-options.ts'; import type { SettingOptions } from '@agent-device/contracts/settings'; import type { DeviceLease, @@ -62,11 +63,17 @@ export async function createLimrunIosSession( }, dependencies: Pick, ): Promise { - const client = await createIosInstanceClient({ - apiUrl: options.apiUrl, - token: options.token, - logLevel: 'warn', - }); + // The wrapper is loaded here, not imported: the runtime façade keeps its merge-base eager closure + // (ADR-0027). + const { withInstanceCredentialScrubbing } = await import('./instance-error-scrubbing.ts'); + const client = withInstanceCredentialScrubbing( + await createIosInstanceClient({ + apiUrl: options.apiUrl, + token: options.token, + ...LIMRUN_INSTANCE_CLIENT_LOGGING, + }), + [`Bearer ${options.token}`], + ); try { const runner = await dependencies.ios.createRunner({ ...options, client }); return { ...options, platform: 'ios', client, runner, dependencies }; diff --git a/packages/provider-limrun/src/lease-release.ts b/packages/provider-limrun/src/lease-release.ts index 0f8652fade..b74d884625 100644 --- a/packages/provider-limrun/src/lease-release.ts +++ b/packages/provider-limrun/src/lease-release.ts @@ -3,7 +3,7 @@ import type { DeviceLease } from '@agent-device/contracts/device'; import { AppError, errorMessage } from '@agent-device/kernel/errors'; import { cleanupLimrunAndroidAdbTunnel } from './android.ts'; import { CAPTURE_OPEN_BUDGET_MS } from './capture-lifecycle.ts'; -import { deleteLimrunInstance } from './client-options.ts'; +import { deleteLimrunInstance, fromLimrunOrgApi } from './client-options.ts'; import type { LimrunBudgetOutcome } from './lifecycle-budget.ts'; import { LIMRUN_PROVIDER, platformForLimrunLeaseBackend, type LimrunPlatform } from './device.ts'; import type { @@ -406,10 +406,11 @@ async function releaseLabeledInstances( const platform = platformForLimrunLeaseBackend(lease.backend); if (!platform || !limrun) return undefined; const labelSelector = `provider=${LIMRUN_PROVIDER},leaseId=${lease.leaseId}`; - const instances = + const instances = await fromLimrunOrgApi( platform === 'ios' - ? await limrun.iosInstances.list({ labelSelector }) - : await limrun.androidInstances.list({ labelSelector }); + ? limrun.iosInstances.list({ labelSelector }) + : limrun.androidInstances.list({ labelSelector }), + ); const instanceIds = instances.getPaginatedItems().map((instance) => instance.metadata.id); const { awaitLimrunWithinBudget, workOutstandingFailure } = await import('./lifecycle-budget.ts'); const confirmed: string[] = []; diff --git a/packages/provider-limrun/src/plugin.test.ts b/packages/provider-limrun/src/plugin.test.ts index 7c80f4be8f..b15aaa8bb7 100644 --- a/packages/provider-limrun/src/plugin.test.ts +++ b/packages/provider-limrun/src/plugin.test.ts @@ -153,6 +153,7 @@ test('verify runs its own SDK check over scoped credentials, version and platfor userAgent: 'agent-device-cli/1.2.3', timeout: 15_000, maxRetries: 0, + logLevel: 'off', }, ]); // Only the platform this call selected is asked, and the region narrows its query. `keepAlive` diff --git a/packages/provider-limrun/src/runtime.ts b/packages/provider-limrun/src/runtime.ts index 7cfcb11aa3..4baaef7215 100644 --- a/packages/provider-limrun/src/runtime.ts +++ b/packages/provider-limrun/src/runtime.ts @@ -44,6 +44,8 @@ import type { LimrunAppLogReader } from './app-log-runtime.ts'; import { deleteLimrunInstance, LIMRUN_CLIENT_ID, + LIMRUN_ORG_CLIENT_LOGGING, + fromLimrunOrgApi, limrunUserAgent, requireLimrunOrgClient, } from './client-options.ts'; @@ -188,6 +190,7 @@ class LimrunRuntimeImplementation implements ProviderDeviceRuntime { ? new Limrun({ apiKey: options.apiKey, userAgent: limrunUserAgent(dependencies.clientVersion), + ...LIMRUN_ORG_CLIENT_LOGGING, }) : undefined; } @@ -552,10 +555,12 @@ class LimrunRuntimeImplementation implements ProviderDeviceRuntime { // The session is recorded in the step that answers for it, so every later step of this allocation // fails with its handles still owned: the instance client and the host ADB endpoint are released by // whoever ends this lease, whether or not the allocation ever answered. + // The create's failure is the one answer this lease has for its caller and is recorded by the daemon, + // so it is normalized here: the SDK's own text for an account-API refusal is the response body. const session = platform === 'ios' - ? await allocateLimrunIosSession(params, rent) - : await allocateLimrunAndroidSession(params, rent); + ? await fromLimrunOrgApi(allocateLimrunIosSession(params, rent)) + : await fromLimrunOrgApi(allocateLimrunAndroidSession(params, rent)); owner.session = session; const appAlias: LimrunAppAlias | undefined = requestedAsset && { assetName: requestedAsset.name, @@ -778,6 +783,8 @@ class LimrunRuntimeImplementation implements ProviderDeviceRuntime { } if (terminationReason === undefined) return undefined; const { PROVIDER_INSTANCE_ENDED } = await import('@agent-device/contracts/lease-scope'); + // `terminationReason` is bounded and scrubbed by its reader; `readLimrunTerminationReason` is the only + // route that can name it here, so the published line is one line. throw new AppError('COMMAND_FAILED', `The Limrun instance ended (${terminationReason}).`, { reason: PROVIDER_INSTANCE_ENDED, terminationReason, @@ -969,7 +976,14 @@ async function readLimrunTerminationReason( return undefined; } if (answer.value.status.state !== 'terminated') return undefined; - return answer.value.status.terminationReason ?? 'Unknown'; + // The termination reason is the account API's own text, and this request carries the account key in + // its header, so it goes through the same reader as an instance's error body before it is published. + // It is read here rather than imported at the top: the runtime façade keeps its merge-base closure + // (ADR-0027), and this is the only route that publishes the account API's text. + const { safeTerminationReason } = await import('./error-text.ts'); + return safeTerminationReason(answer.value.status.terminationReason, [ + limrun.apiKey ?? undefined, + ]); } catch { return undefined; } diff --git a/src/__tests__/limrun-runtime.test.ts b/src/__tests__/limrun-runtime.test.ts index 34a0bcaf5c..f98e0fcfe6 100644 --- a/src/__tests__/limrun-runtime.test.ts +++ b/src/__tests__/limrun-runtime.test.ts @@ -741,10 +741,10 @@ test('Limrun drives existing instances without an API key and never deletes them assert.match(String(ios?.limrunInstanceId), /^attached-[a-f0-9]{12}$/); assert.deepEqual(vi.mocked(createIosInstanceClient).mock.calls, [ - [{ ...ATTACHED_IOS, logLevel: 'warn' }], + [{ ...ATTACHED_IOS, logLevel: 'none' }], ]); assert.deepEqual(vi.mocked(createAndroidInstanceClient).mock.calls, [ - [{ ...ATTACHED_ANDROID, logLevel: 'warn' }], + [{ ...ATTACHED_ANDROID, logLevel: 'none' }], ]); await releaseLease(iosLease('lease-attached-ios')); diff --git a/website/docs/docs/error-reasons.md b/website/docs/docs/error-reasons.md index 48eed42345..69154925cc 100644 --- a/website/docs/docs/error-reasons.md +++ b/website/docs/docs/error-reasons.md @@ -203,6 +203,21 @@ These reasons can come from more than one command. | `LEASE_CAPACITY_EXCEEDED` | Every iOS simulator lease slot is taken; retry after another lease is released. | | `LEASE_LEDGER_OVERWRITE` | The CLI already tracks an allocated lease and must release or transfer it before it allocates another. | +### Limrun + +| Reason | Meaning | +| --- | --- | +| `limrun_api_unauthorized` | The account key was refused or lacks access to what was asked for. | +| `limrun_api_not_found` | The account API has nothing under the identifier the request named. | +| `limrun_api_rate_limited` | The account API is taking this key's requests too fast to answer them. | +| `limrun_api_failed` | The account API refused the request for a reason with no separate recovery. | +| `limrun_download_empty_body` | The instance answered the download with no body at all, so nothing could reach disk. | +| `limrun_download_http_error` | The instance refused the download; its HTTP status answers for the refusal. | +| `limrun_download_timeout` | The transfer's own deadline passed before the file reached disk. | +| `limrun_download_failed` | The transfer failed before it could ask the instance for the file. | +| `limrun_instance_command_failed` | The instance refused or could not answer the command; its text, with this session's credential removed, is the message. | +| `limrun_runner_snapshot_unavailable` | The runner's own capture failure is answered over: the recovery is to reopen this session, not to inspect the simulator. | + ### Macos helper | Reason | Meaning | From 972b0360b18d384ddceff83ea18532a3231793dd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sun, 22 Nov 2026 16:26:02 +0100 Subject: [PATCH 25/26] fix(limrun): scrub authenticated peer failures at provider boundaries --- packages/apple-runner/src/runner-contract.ts | 9 +- packages/apple-runner/src/runner-transport.ts | 2 +- packages/provider-limrun/src/android.ts | 17 ++-- .../src/app-log-reconnect.test.ts | 33 +++++++ .../provider-limrun/src/app-log-reconnect.ts | 51 +++------- .../src/client-options.test.ts | 29 ++++++ .../provider-limrun/src/client-options.ts | 60 +++++++----- .../provider-limrun/src/error-text.test.ts | 7 ++ packages/provider-limrun/src/error-text.ts | 7 +- .../src/instance-error-scrubbing.test.ts | 10 ++ .../src/instance-error-scrubbing.ts | 38 +++++--- .../provider-limrun/src/ios-app-logs.test.ts | 40 ++++++++ packages/provider-limrun/src/ios-app-logs.ts | 7 +- .../provider-limrun/src/ios-files.test.ts | 43 +++++++++ packages/provider-limrun/src/ios-files.ts | 30 +++++- .../src/ios-runner-products.test.ts | 37 +++++++ .../src/ios-runner-products.ts | 15 ++- .../provider-limrun/src/ios-runner.test.ts | 50 ++++++++++ packages/provider-limrun/src/ios-runner.ts | 46 ++++++++- packages/provider-limrun/src/ios.ts | 15 +-- .../provider-limrun/src/lease-release.test.ts | 6 +- .../src/runtime-dependencies.test.ts | 12 ++- packages/provider-limrun/src/runtime.ts | 10 +- .../src/session-allocation.test.ts | 6 +- .../provider-limrun/src/session-allocation.ts | 96 ++++++++++--------- src/__tests__/limrun-runtime.test.ts | 5 +- website/docs/docs/error-reasons.md | 1 + 27 files changed, 513 insertions(+), 169 deletions(-) create mode 100644 packages/provider-limrun/src/ios-app-logs.test.ts create mode 100644 packages/provider-limrun/src/ios-files.test.ts create mode 100644 packages/provider-limrun/src/ios-runner.test.ts diff --git a/packages/apple-runner/src/runner-contract.ts b/packages/apple-runner/src/runner-contract.ts index 5da9cfbe22..108e9ddede 100644 --- a/packages/apple-runner/src/runner-contract.ts +++ b/packages/apple-runner/src/runner-contract.ts @@ -693,7 +693,6 @@ export function assertRunnerRequestActive(requestId: string | undefined): void { throw createRequestCanceledError(); } -// ── Listener endpoint and token ───────────────────────────────────────────────────────────────── const RUNNER_TOKEN_HEADER = 'X-Agent-Device-Runner-Token'; const RUNNER_TOKEN_ENFORCED_HEADER = 'X-Agent-Device-Runner-Auth'; const RUNNER_TOKEN_BYTES = 24; @@ -704,7 +703,11 @@ export type RunnerEndpoint = Readonly<{ port: number; token: string; /** A provider's authenticated forwarding route; omitted for local and USB runners. */ - http?: Readonly<{ url: string; headers?: Readonly> }>; + http?: Readonly<{ + url: string; + headers?: Readonly>; + transformResponse?(response: Response): Response; + }>; }>; export function mintRunnerToken(): string { @@ -739,8 +742,6 @@ export function requireTokenEnforcingRunner(response: Response): Response { }); } -// --- Sequence commands --- - export const SEQUENCEABLE_RUNNER_STEP_KINDS = ['tap', 'doubleTap', 'longPress'] as const; export type SequenceableRunnerStepKind = (typeof SEQUENCEABLE_RUNNER_STEP_KINDS)[number]; diff --git a/packages/apple-runner/src/runner-transport.ts b/packages/apple-runner/src/runner-transport.ts index 2657af38ed..18fdc4d888 100644 --- a/packages/apple-runner/src/runner-transport.ts +++ b/packages/apple-runner/src/runner-transport.ts @@ -119,7 +119,7 @@ export async function postRunnerCommandOverRoute( status: response.status, }); } - return response; + return endpoint.http?.transformResponse?.(response) ?? response; } /** A cancellation that lands before the POST is issued proves the runner received nothing. */ diff --git a/packages/provider-limrun/src/android.ts b/packages/provider-limrun/src/android.ts index 2565c52e79..b8985aacf8 100644 --- a/packages/provider-limrun/src/android.ts +++ b/packages/provider-limrun/src/android.ts @@ -1,5 +1,4 @@ import type { LimrunSyncCache } from './sync-cache.ts'; -import { LIMRUN_INSTANCE_CLIENT_LOGGING } from './client-options.ts'; import { AsyncLocalStorage } from 'node:async_hooks'; import { createInstanceClient as createAndroidInstanceClient, @@ -78,16 +77,12 @@ export async function createLimrunAndroidSession( ): Promise { // The wrapper is loaded here, not imported: the runtime façade keeps its merge-base eager closure // (ADR-0027), and this is one of the two routes that builds an instance client. - const { withInstanceCredentialScrubbing } = await import('./instance-error-scrubbing.ts'); - const client = withInstanceCredentialScrubbing( - await createAndroidInstanceClient({ - apiUrl: options.apiUrl, - adbUrl: options.adbUrl, - token: options.token, - ...LIMRUN_INSTANCE_CLIENT_LOGGING, - }), - [`Bearer ${options.token}`], - ); + const { connectLimrunInstanceClient } = await import('./instance-error-scrubbing.ts'); + const client = await connectLimrunInstanceClient(createAndroidInstanceClient, { + apiUrl: options.apiUrl, + adbUrl: options.adbUrl, + token: options.token, + }); const session: LimrunAndroidAdbSession = { platform: 'android', lease: options.lease, diff --git a/packages/provider-limrun/src/app-log-reconnect.test.ts b/packages/provider-limrun/src/app-log-reconnect.test.ts index a4701c25d5..0ea3ecda6f 100644 --- a/packages/provider-limrun/src/app-log-reconnect.test.ts +++ b/packages/provider-limrun/src/app-log-reconnect.test.ts @@ -321,3 +321,36 @@ test('does not connect once the reconnect request is aborted', async () => { ).rejects.toThrow(); expect(vi.mocked(createIosInstanceClient)).not.toHaveBeenCalled(); }); + +test('scrubs an iOS device-info failure while reconnecting the app log', async () => { + const token = 'syntheticInstanceCredential'; + vi.mocked(createIosInstanceClient).mockRejectedValueOnce( + new Error('deviceInfo refused ' + token), + ); + await expect( + reconnectLimrunAppLogReader({ + limrun: { + iosInstances: { + get: async () => ({ + metadata: { labels: { provider: 'limrun', leaseId: 'lease-a' } }, + status: { state: 'ready', apiUrl: 'https://instance', token }, + }), + }, + } as never, + descriptor: { + transport: 'limrun-log-poller', + platform: 'ios', + leaseId: 'lease-a', + instanceId: 'instance-a', + ownership: 'created', + appBundleId: 'com.example.app', + outputPath: '/sessions/one/app.log', + }, + dependencies: iosDependencies, + }), + ).rejects.toMatchObject({ + code: 'COMMAND_FAILED', + message: 'deviceInfo refused [REDACTED]', + details: { reason: 'limrun_instance_command_failed' }, + }); +}); diff --git a/packages/provider-limrun/src/app-log-reconnect.ts b/packages/provider-limrun/src/app-log-reconnect.ts index 4e41bc7699..b98740bea1 100644 --- a/packages/provider-limrun/src/app-log-reconnect.ts +++ b/packages/provider-limrun/src/app-log-reconnect.ts @@ -4,13 +4,8 @@ import { createInstanceClient as createIosInstanceClient } from '@limrun/api/ios import { AsyncCleanupStack } from '@agent-device/contracts/async-lifecycle'; import type { LimrunAppLogDescriptor } from './app-log-descriptor.ts'; import type { LimrunAppLogReader, LimrunAppLogReconnectOutcome } from './app-log-runtime.ts'; -import { - fromLimrunOrgApi, - isLimrunApiNotFound, - LIMRUN_INSTANCE_CLIENT_LOGGING, - requireLimrunOrgClient, -} from './client-options.ts'; -import { withInstanceCredentialScrubbing } from './instance-error-scrubbing.ts'; +import { fromLimrunOrgApi, isLimrunApiNotFound, requireLimrunOrgClient } from './client-options.ts'; +import { connectLimrunInstanceClient } from './instance-error-scrubbing.ts'; import { attachedLimrunInstanceId } from './device.ts'; import type { LimrunAndroidInstanceAccess, @@ -35,18 +30,9 @@ export async function reconnectLimrunAppLogReader(options: { ); } const limrun = requireLimrunOrgClient(options.limrun, 'Reconnecting app logs'); - try { - // The lookup is asked with the account key and its failure text is the response body, so it is - // answered with a typed status before anything here records or returns it. - return await fromLimrunOrgApi( - options.descriptor.platform === 'ios' - ? reconnectIos({ ...options, limrun }) - : reconnectAndroid({ ...options, limrun }), - ); - } catch (error) { - if (isLimrunApiNotFound(error)) return { status: 'missing' }; - throw error; - } + return options.descriptor.platform === 'ios' + ? await reconnectIos({ ...options, limrun }) + : await reconnectAndroid({ ...options, limrun }); } async function reconnectAttached( @@ -99,14 +85,7 @@ async function openIosReader( descriptor: LimrunAppLogDescriptor, dependencies: LimrunRuntimeDependencies, ): Promise { - const client = withInstanceCredentialScrubbing( - await createIosInstanceClient({ - apiUrl: access.apiUrl, - token: access.token, - ...LIMRUN_INSTANCE_CLIENT_LOGGING, - }), - [`Bearer ${access.token}`], - ); + const client = await connectLimrunInstanceClient(createIosInstanceClient, access); const logs = dependencies.ios.createAppLogReader({ ...access, client }); const reader: LimrunAppLogReader = { platform: 'ios', @@ -159,15 +138,7 @@ async function openAndroidReader( descriptor: LimrunAppLogDescriptor, dependencies: LimrunRuntimeDependencies, ): Promise { - const client = withInstanceCredentialScrubbing( - await createAndroidInstanceClient({ - apiUrl: access.apiUrl, - adbUrl: access.adbUrl, - token: access.token, - ...LIMRUN_INSTANCE_CLIENT_LOGGING, - }), - [`Bearer ${access.token}`], - ); + const client = await connectLimrunInstanceClient(createAndroidInstanceClient, access); const rollback = new AsyncCleanupStack(); let adopted = false; rollback.defer(async () => { @@ -233,7 +204,13 @@ async function selectOwnedActiveInstance | Extract > { - const instance = await load(); + let instance: Instance; + try { + instance = await fromLimrunOrgApi(load()); + } catch (error) { + if (isLimrunApiNotFound(error)) return { status: 'missing' }; + throw error; + } if (!hasDescriptorOwnership(instance.metadata.labels, descriptor)) { return { status: 'ownership-lost' }; } diff --git a/packages/provider-limrun/src/client-options.test.ts b/packages/provider-limrun/src/client-options.test.ts index ba4334f8e0..9304886493 100644 --- a/packages/provider-limrun/src/client-options.test.ts +++ b/packages/provider-limrun/src/client-options.test.ts @@ -87,3 +87,32 @@ test('the organization client this plugin builds logs nothing, whatever LIMRUN_L else process.env.LIMRUN_LOG = previous; } }); + +test('a malformed organization JSON reply never publishes the decoder error', async () => { + const key = 'syntheticAccountCredential'; + const limrun = new Limrun({ + apiKey: key, + baseURL: 'https://limrun.example', + ...LIMRUN_ORG_CLIENT_LOGGING, + fetch: async () => new Response(key, { headers: { 'content-type': 'application/json' } }), + }); + await expect(fromLimrunOrgApi(limrun.iosInstances.list({}))).rejects.toMatchObject({ + code: 'COMMAND_FAILED', + message: 'Limrun organization request failed.', + details: { reason: 'limrun_api_failed' }, + cause: undefined, + }); +}); + +test('an aborted organization request preserves cancellation', async () => { + const controller = new AbortController(); + const limrun = new Limrun({ + apiKey: 'syntheticAccountCredential', + baseURL: 'https://limrun.example', + ...LIMRUN_ORG_CLIENT_LOGGING, + }); + controller.abort(); + await expect( + fromLimrunOrgApi(limrun.iosInstances.list({}, { signal: controller.signal })), + ).rejects.toBeInstanceOf(Limrun.APIUserAbortError); +}); diff --git a/packages/provider-limrun/src/client-options.ts b/packages/provider-limrun/src/client-options.ts index 49dbd141db..8a3aaf9a46 100644 --- a/packages/provider-limrun/src/client-options.ts +++ b/packages/provider-limrun/src/client-options.ts @@ -1,5 +1,11 @@ -import type Limrun from '@limrun/api'; -import { AppError, errorMessage, type ReasonTable } from '@agent-device/kernel/errors'; +import Limrun from '@limrun/api'; +import { + AppError, + errorMessage, + isRequestCanceledError, + type AppErrorCode, + type ReasonTable, +} from '@agent-device/kernel/errors'; import type { LimrunDeleteResult } from './lease-ownership.ts'; export const LIMRUN_CLIENT_ID = 'agent-device-cli'; @@ -132,29 +138,33 @@ const LIMRUN_ORG_API_REASONS = { rejected: { reason: 'limrun_api_failed' }, } as const satisfies ReasonTable<'limrun'>; -/** - * Re-raises one organization-API failure as this runtime's own error. See {@link fromLimrunOrgApi}. - * A 404 keeps its own reason: a caller that acts on a gone instance reads it. - */ +const LIMRUN_ORG_HTTP_ERRORS = new Map([ + [401, { code: 'UNAUTHORIZED', reason: LIMRUN_ORG_API_REASONS.unauthorized.reason }], + [403, { code: 'UNAUTHORIZED', reason: LIMRUN_ORG_API_REASONS.unauthorized.reason }], + [404, { code: 'DEVICE_NOT_FOUND', reason: LIMRUN_ORG_API_REASONS.notFound.reason }], + [429, { code: 'COMMAND_FAILED', reason: LIMRUN_ORG_API_REASONS.rateLimited.reason }], +]); + function limrunOrgApiError(error: unknown): unknown { const status = readHttpStatus(error); - if (status === undefined) return error; - const code = - status === 401 || status === 403 - ? 'UNAUTHORIZED' - : status === 404 - ? 'DEVICE_NOT_FOUND' - : 'COMMAND_FAILED'; - const reason = - status === 401 || status === 403 - ? LIMRUN_ORG_API_REASONS.unauthorized.reason - : status === 404 - ? LIMRUN_ORG_API_REASONS.notFound.reason - : status === 429 - ? LIMRUN_ORG_API_REASONS.rateLimited.reason - : LIMRUN_ORG_API_REASONS.rejected.reason; - return new AppError(code, `Limrun rejected the request (${status}).`, { - status, - reason, - }); + if (status === undefined) { + if ( + (Limrun.APIUserAbortError && error instanceof Limrun.APIUserAbortError) || + (error instanceof Error && error.name === 'AbortError') || + isRequestCanceledError(error) + ) + return error; + return new AppError('COMMAND_FAILED', 'Limrun organization request failed.', { + reason: LIMRUN_ORG_API_REASONS.rejected.reason, + }); + } + const classified = LIMRUN_ORG_HTTP_ERRORS.get(status); + return new AppError( + classified?.code ?? 'COMMAND_FAILED', + `Limrun rejected the request (${status}).`, + { + status, + reason: classified?.reason ?? LIMRUN_ORG_API_REASONS.rejected.reason, + }, + ); } diff --git a/packages/provider-limrun/src/error-text.test.ts b/packages/provider-limrun/src/error-text.test.ts index 3589b4dfcf..09be0eede5 100644 --- a/packages/provider-limrun/src/error-text.test.ts +++ b/packages/provider-limrun/src/error-text.test.ts @@ -156,3 +156,10 @@ const MARKER = '[REDACTED]'; const MARKER_PARTIALS = Array.from({ length: MARKER.length - 1 }, (_, length) => MARKER.slice(0, length + 1), ); + +test('matches the exact bare token before normalizing whitespace', () => { + const token = 'synthetic instance-token'; + const sent = ['Bearer ' + token]; + expect(safeInstanceErrorText('refused ' + token, sent)).toBe('refused [REDACTED]'); + expect(safeTerminationReason('ended\nusing ' + token, sent)).toBe('ended using [REDACTED]'); +}); diff --git a/packages/provider-limrun/src/error-text.ts b/packages/provider-limrun/src/error-text.ts index c1aee5b63b..2124a5ac2f 100644 --- a/packages/provider-limrun/src/error-text.ts +++ b/packages/provider-limrun/src/error-text.ts @@ -34,9 +34,8 @@ function instanceSecrets(sentValues: Iterable): string[] { const trimmed = value?.trim(); if (!trimmed) continue; secrets.add(trimmed); - const [scheme = '', ...rest] = trimmed.split(/\s+/); - const credential = rest.join(' ').trim(); - if (credential.length > 0 && CREDENTIAL_SCHEMES.has(scheme.toLowerCase())) { + const [, scheme, credential] = /^(\S+)\s+([\s\S]+)$/.exec(trimmed) ?? []; + if (scheme && credential && CREDENTIAL_SCHEMES.has(scheme.toLowerCase())) { secrets.add(credential); } } @@ -119,7 +118,7 @@ export function safeTerminationReason( ): string { const trimmed = reason?.trim(); if (!trimmed) return 'Unknown'; - const oneLine = safeInstanceErrorText(trimmed.replaceAll(/\s+/g, ' '), sentValues); + const oneLine = safeInstanceErrorText(trimmed, sentValues).replaceAll(/\s+/g, ' '); if (oneLine.length <= MAX_PUBLISHED_REASON_LENGTH) return oneLine; return `${withoutTrailingPartialMarker(oneLine.slice(0, MAX_PUBLISHED_REASON_LENGTH))}…`; } diff --git a/packages/provider-limrun/src/instance-error-scrubbing.test.ts b/packages/provider-limrun/src/instance-error-scrubbing.test.ts index b82c3519a4..3cd526aaea 100644 --- a/packages/provider-limrun/src/instance-error-scrubbing.test.ts +++ b/packages/provider-limrun/src/instance-error-scrubbing.test.ts @@ -167,3 +167,13 @@ describe('scrubPublishedError', () => { expect((scrubPublishedError(failure, SENT) as AppError).cause).toBe(cause); }); }); + +test('drops nested diagnostic properties whose names contain the instance token', () => { + const failure = new AppError('COMMAND_FAILED', 'runner refused', { + runner: { status: 401, ['echo-' + TOKEN]: 'unexpected' }, + }); + expect(scrubPublishedError(failure, SENT)).toMatchObject({ + details: { runner: { status: 401 } }, + }); + expect(JSON.stringify(scrubPublishedError(failure, SENT))).not.toContain(TOKEN); +}); diff --git a/packages/provider-limrun/src/instance-error-scrubbing.ts b/packages/provider-limrun/src/instance-error-scrubbing.ts index cb99b6465c..bb2c114dfc 100644 --- a/packages/provider-limrun/src/instance-error-scrubbing.ts +++ b/packages/provider-limrun/src/instance-error-scrubbing.ts @@ -1,5 +1,22 @@ import { AppError, type ReasonTable } from '@agent-device/kernel/errors'; import { safeInstanceErrorText } from './error-text.ts'; +import { LIMRUN_INSTANCE_CLIENT_LOGGING } from './client-options.ts'; + +export async function connectLimrunInstanceClient< + Options extends { token: string }, + Client extends object, +>( + connect: (options: Options & typeof LIMRUN_INSTANCE_CLIENT_LOGGING) => Promise, + access: Options, +): Promise { + const secrets = [`Bearer ${access.token}`]; + try { + const client = await connect({ ...access, ...LIMRUN_INSTANCE_CLIENT_LOGGING }); + return withInstanceCredentialScrubbing(client, secrets); + } catch (error) { + throw instanceCommandFailure(error, secrets); + } +} /** Every `details.reason` a command sent to an attached or created instance publishes. */ const LIMRUN_INSTANCE_REASONS = { @@ -16,7 +33,7 @@ const LIMRUN_INSTANCE_REASONS = { * itself, or the body of the reply. This plugin authenticated that channel with the instance token, and * an instance that echoes it does so as a bare value core's pattern redaction cannot recognise. So every * method of the client is answered through this wrapper: a failure that names a value this session sent - * is re-raised with that value removed, and keeps the original as its cause. + * is re-raised with that value removed, before reaching its caller. * * A failure that names nothing this session sent is passed through untouched, so the command that caught * it still answers with its own reason. A method's own answer, and a method that throws synchronously @@ -107,28 +124,27 @@ function scrubPublishedDetails( if (details === undefined) return undefined; const secrets = [...sentValues].filter((value): value is string => typeof value === 'string'); if (secrets.length === 0) return details; - const scrubbed = scrubValue(details, secrets); + const scrubbed = scrubInstanceDiagnostic(details, secrets); return scrubbed === details ? details : (scrubbed as Record); } /** Rebuilds only the strings of a diagnostic value that name a sent credential; a type is preserved. */ -function scrubValue(value: unknown, secrets: readonly string[]): unknown { +export function scrubInstanceDiagnostic(value: unknown, secrets: readonly string[]): unknown { if (typeof value === 'string') { const scrubbed = safeInstanceErrorText(value, secrets); return scrubbed === value ? value : scrubbed; } if (Array.isArray(value)) { - const entries = value.map((entry) => scrubValue(entry, secrets)); + const entries = value.map((entry) => scrubInstanceDiagnostic(entry, secrets)); return entries.every((entry, index) => entry === value[index]) ? value : entries; } if (value === null || typeof value !== 'object') return value; - const entries = Object.entries(value as Record).map( - ([key, entry]) => [key, scrubValue(entry, secrets)] as const, - ); - return entries.every( - ([key, entry], index) => - key === Object.keys(value)[index] && entry === (value as Record)[key], - ) + const original = Object.entries(value); + const entries = original + .filter(([key]) => safeInstanceErrorText(key, secrets) === key) + .map(([key, entry]) => [key, scrubInstanceDiagnostic(entry, secrets)] as const); + return entries.length === original.length && + entries.every(([, entry], index) => entry === original[index]?.[1]) ? value : Object.fromEntries(entries); } diff --git a/packages/provider-limrun/src/ios-app-logs.test.ts b/packages/provider-limrun/src/ios-app-logs.test.ts new file mode 100644 index 0000000000..f2481904a0 --- /dev/null +++ b/packages/provider-limrun/src/ios-app-logs.test.ts @@ -0,0 +1,40 @@ +import { EventEmitter } from 'node:events'; +import { afterEach, expect, test, vi } from 'vitest'; +import { createLimrunIosAppLogReader } from './ios-app-logs.ts'; + +afterEach(() => vi.unstubAllGlobals()); + +test('scrubs retained, live console, and buffered unified app logs', async () => { + const token = 'syntheticInstanceCredential'; + const consoleStream = Object.assign(new EventEmitter(), { stop() {} }); + const systemStream = Object.assign(new EventEmitter(), { stop() {} }); + vi.stubGlobal('fetch', async () => new Response(null, { status: 404 })); + const reader = createLimrunIosAppLogReader( + { + apiUrl: 'https://instance.invalid/api', + token, + client: { + appLogTail: async () => 'retained ' + token, + streamAppLog: () => consoleStream, + streamSyslog: () => systemStream, + }, + } as unknown as Parameters[0], + async () => async () => ({}), + ); + const signal = new AbortController().signal; + const app = 'com.example.app'; + const unified = '2026-11-22 12:00:00.000 Info process[123] (' + app + ') '; + try { + const retained = await reader.readLogs(app, 20, signal); + consoleStream.emit('line', 'console ' + token); + systemStream.emit('line', unified + token); + await vi.waitFor(async () => { + expect(await reader.readLogs(app, 20, signal)).toBe( + ['retained [REDACTED]', 'console [REDACTED]', unified + '[REDACTED]'].join('\n'), + ); + }); + expect(retained).toBe('retained [REDACTED]'); + } finally { + await reader[Symbol.asyncDispose](); + } +}); diff --git a/packages/provider-limrun/src/ios-app-logs.ts b/packages/provider-limrun/src/ios-app-logs.ts index 9dc257ef62..c306a67ae3 100644 --- a/packages/provider-limrun/src/ios-app-logs.ts +++ b/packages/provider-limrun/src/ios-app-logs.ts @@ -3,6 +3,7 @@ import type { LimrunRuntimeDependencies } from './runtime-dependencies.ts'; import type { ProviderAppLogReader } from '@agent-device/capture-kit/provider-app-log'; import type { LogStream } from '@limrun/api/ios-client'; import type { LimrunIosHost } from './ios-host.ts'; +import { safeInstanceErrorText } from './error-text.ts'; const MAX_LOG_BYTES = 1024 * 1024; @@ -18,9 +19,11 @@ export function createLimrunIosAppLogReader( let failure: Error | undefined; const lines: string[] = []; let bytes = 0; + const credentials = [`Bearer ${input.token}`]; const append = (line: string) => { - lines.push(line); - bytes += Buffer.byteLength(line) + 1; + const scrubbed = safeInstanceErrorText(line, credentials); + lines.push(scrubbed); + bytes += Buffer.byteLength(scrubbed) + 1; while (bytes > MAX_LOG_BYTES && lines.length) bytes -= Buffer.byteLength(lines.shift()!) + 1; }; const stop = () => { diff --git a/packages/provider-limrun/src/ios-files.test.ts b/packages/provider-limrun/src/ios-files.test.ts new file mode 100644 index 0000000000..803862fba2 --- /dev/null +++ b/packages/provider-limrun/src/ios-files.test.ts @@ -0,0 +1,43 @@ +import { mkdtempForTest } from '@agent-device/test-kit'; +import { writeFile } from 'node:fs/promises'; +import path from 'node:path'; +import { afterEach, expect, test, vi } from 'vitest'; +import { createLimrunSimulatorFiles } from './ios-files.ts'; +import { limrunIosSimulator } from './app-log-runtime.fixtures.ts'; + +afterEach(() => vi.unstubAllGlobals()); + +test('invalid file list and staging JSON preserve status without a decoder cause', async () => { + const token = 'syntheticInstanceCredential'; + vi.stubGlobal('fetch', async (_url: URL, init: RequestInit) => + init.method === 'DELETE' + ? new Response(null, { status: 204 }) + : new Response(token, { status: 202 }), + ); + const { simulatorFiles } = createLimrunSimulatorFiles( + { apiUrl: 'https://instance.invalid/api', token } as Parameters< + typeof createLimrunSimulatorFiles + >[0], + async () => ({}), + new AbortController().signal, + ); + const file = path.join(await mkdtempForTest('limrun-files-'), 'data.txt'); + await writeFile(file, 'data'); + for (const request of [ + () => + simulatorFiles.openContainer({ + device: limrunIosSimulator, + bundleId: 'com.example.app', + containerType: 'data', + timeoutMs: 15_000, + }), + () => simulatorFiles.stageFile(file), + ]) { + await expect(request()).rejects.toMatchObject({ + code: 'COMMAND_FAILED', + message: 'Limrun file operation returned invalid JSON', + details: { status: 202, reason: 'limrun_file_response_invalid' }, + cause: undefined, + }); + } +}); diff --git a/packages/provider-limrun/src/ios-files.ts b/packages/provider-limrun/src/ios-files.ts index 307cf34c45..6601f06ff8 100644 --- a/packages/provider-limrun/src/ios-files.ts +++ b/packages/provider-limrun/src/ios-files.ts @@ -7,7 +7,11 @@ import type { AppleToolExecOptions, } from '@agent-device/platform-apple/tool-provider'; import type { LimrunRuntimeDependencies } from './runtime-dependencies.ts'; -import { AppError, createRequestCanceledError } from '@agent-device/kernel/errors'; +import { + AppError, + createRequestCanceledError, + type ReasonTable, +} from '@agent-device/kernel/errors'; import { downloadLimrunFile } from './download-file.ts'; import type { LimrunIosHost } from './ios-host.ts'; @@ -16,6 +20,23 @@ type Files = AppleToolProvider['simulatorFiles']; type ParsePlist = LimrunIosHost['apple']['tools']['parsePlist']; type Container = Parameters[0]; +const LIMRUN_FILE_REASONS = { + // The instance returned an unreadable JSON reply for a simulator file operation. + invalidResponse: { reason: 'limrun_file_response_invalid' }, +} as const satisfies ReasonTable<'limrun'>; + +async function readFileReply(response: Response, signal: AbortSignal): Promise { + try { + return (await response.json()) as T; + } catch { + signal.throwIfAborted(); + throw new AppError('COMMAND_FAILED', 'Limrun file operation returned invalid JSON', { + reason: LIMRUN_FILE_REASONS.invalidResponse.reason, + status: response.status, + }); + } +} + export function createLimrunSimulatorFiles( session: Session, parsePlist: ParsePlist, @@ -98,7 +119,10 @@ export function createLimrunSimulatorFiles( const list = () => operation(container, async (signal) => { const response = await request('GET', urlFor('files/list', '', container), signal); - const result = (await response.json()) as { entries: Array<{ name: string }> }; + const result = await readFileReply<{ entries: Array<{ name: string }> }>( + response, + signal, + ); return result.entries.map((entry) => entry.name); }); try { @@ -144,7 +168,7 @@ export function createLimrunSimulatorFiles( signal, await fs.readFile(localPath, { signal }), ); - return (await response.json()) as { path: string }; + return await readFileReply<{ path: string }>(response, signal); }).catch(async (error: unknown) => { await remove().catch(() => {}); throw error; diff --git a/packages/provider-limrun/src/ios-runner-products.test.ts b/packages/provider-limrun/src/ios-runner-products.test.ts index 37ef9ad525..116b9e5e58 100644 --- a/packages/provider-limrun/src/ios-runner-products.test.ts +++ b/packages/provider-limrun/src/ios-runner-products.test.ts @@ -246,3 +246,40 @@ test('a sync answer naming an entry this upload did not send keeps it out of the await new Promise((resolve) => server.close(() => resolve())); } }); + +test('a stale needFull name still triggers the full sync retry', async () => { + const directory = await mkdtempForTest('runner-products-'); + await fs.writeFile(path.join(directory, 'Runner.xctestrun'), ''); + const fetch = vi + .fn() + .mockImplementationOnce(async () => Response.json({ ok: true, needFull: ['stale'] })) + .mockImplementationOnce(async () => Response.json({ ok: true })); + vi.stubGlobal('fetch', fetch); + await uploadLimrunRunnerProducts( + directory, + 'https://instance.invalid', + 'token', + new AbortController().signal, + ); + expect(fetch).toHaveBeenCalledTimes(2); +}); + +test('invalid sync JSON returns a static failure and status', async () => { + const directory = await mkdtempForTest('runner-products-'); + await fs.writeFile(path.join(directory, 'Runner.xctestrun'), ''); + const token = 'syntheticInstanceCredential'; + vi.stubGlobal('fetch', async () => new Response(token)); + await expect( + uploadLimrunRunnerProducts( + directory, + 'https://instance.invalid', + token, + new AbortController().signal, + ), + ).rejects.toMatchObject({ + code: 'COMMAND_FAILED', + message: 'Limrun runner upload returned invalid JSON', + details: { status: 200, reason: 'limrun_runner_upload_failed' }, + cause: undefined, + }); +}); diff --git a/packages/provider-limrun/src/ios-runner-products.ts b/packages/provider-limrun/src/ios-runner-products.ts index 08375fc386..2ba129dc56 100644 --- a/packages/provider-limrun/src/ios-runner-products.ts +++ b/packages/provider-limrun/src/ios-runner-products.ts @@ -212,14 +212,14 @@ export async function uploadLimrunRunnerProducts( for (let attempt = 0; attempt < 2; attempt++) { signal.throwIfAborted(); const result = await upload(attempt === 0 ? selected : files); - const needFull = (result.needFull ?? []).filter((name) => knownProductPaths.has(name)); + const needFull = result.needFull ?? []; if (result.ok === true && needFull.length === 0) return; if (needFull.length === 0 || attempt === 1) { throw limrunRunnerError( 'limrun_runner_upload_failed', 'Limrun runner products could not be synchronized', { - needFull, + needFull: needFull.filter((name) => knownProductPaths.has(name)), }, ); } @@ -273,7 +273,16 @@ export async function uploadLimrunRunnerProducts( }, ); } - return (await response.json()) as { ok?: boolean; needFull?: string[] }; + try { + return (await response.json()) as { ok?: boolean; needFull?: string[] }; + } catch { + signal.throwIfAborted(); + throw limrunRunnerError( + 'limrun_runner_upload_failed', + 'Limrun runner upload returned invalid JSON', + { status: response.status }, + ); + } } finally { stream.destroy(); await compression; diff --git a/packages/provider-limrun/src/ios-runner.test.ts b/packages/provider-limrun/src/ios-runner.test.ts new file mode 100644 index 0000000000..730db50c75 --- /dev/null +++ b/packages/provider-limrun/src/ios-runner.test.ts @@ -0,0 +1,50 @@ +import { expect, test, vi } from 'vitest'; +import type { LimrunIosHost } from './ios-host.ts'; +import { createLimrunIosRunner } from './ios-runner.ts'; + +test('the forwarded runner endpoint scrubs replies before the host consumes them', async () => { + const token = 'synthetic instance-token'; + type RunnerHost = LimrunIosHost['apple']['runner']; + const createLaunchedProvider = vi.fn( + async () => ({}) as Awaited>, + ); + const host = { + apple: { + applicationTools: {}, + runner: { + mintToken: () => 'runner-token', + createLaunchedProvider, + createRuntime: async () => ({}), + }, + }, + kit: {}, + } as unknown as LimrunIosHost; + await createLimrunIosRunner( + { apiUrl: 'https://instance.invalid/api', token } as Parameters< + typeof createLimrunIosRunner + >[0], + host, + ); + const http = createLaunchedProvider.mock.calls[0]?.[1].endpoint.http; + const rejected = Response.json( + { ok: false, error: { code: 'APP_NOT_RUNNING', message: 'refused ' + token, [token]: 'echo' } }, + { status: 409, headers: { 'x-agent-device-runner-auth': 'required' } }, + ); + const failure = http?.transformResponse?.(rejected) ?? rejected; + expect(failure.status).toBe(409); + expect(failure.headers.get('x-agent-device-runner-auth')).toBe('required'); + expect(await failure.json()).toEqual({ + ok: false, + error: { code: 'APP_NOT_RUNNING', message: 'refused [REDACTED]' }, + }); + + const accepted = Response.json({ + ok: true, + data: { gestureFallback: 'coordinate', gestureFallbackMessage: 'used ' + token }, + }); + const success = http?.transformResponse?.(accepted) ?? accepted; + expect(await success.json()).toEqual({ + ok: true, + data: { gestureFallback: 'coordinate', gestureFallbackMessage: 'used [REDACTED]' }, + }); +}); diff --git a/packages/provider-limrun/src/ios-runner.ts b/packages/provider-limrun/src/ios-runner.ts index b41fbf06de..632e2e8f25 100644 --- a/packages/provider-limrun/src/ios-runner.ts +++ b/packages/provider-limrun/src/ios-runner.ts @@ -1,5 +1,6 @@ import { limrunRunnerError, withLimrunRunnerErrors } from './ios-runner-errors.ts'; import { createInstanceStreamScrubber, safeInstanceErrorText } from './error-text.ts'; +import { scrubInstanceDiagnostic } from './instance-error-scrubbing.ts'; import { awaitWithSignal } from '@agent-device/kernel/await-with-signal'; import type { DeadlineClock } from '@agent-device/host-kit/retry'; import { createLimrunAppleToolProvider } from './ios-tools.ts'; @@ -49,7 +50,17 @@ export async function createLimrunIosRunner( let preparationWaiters = 0; let prepared = false; let canceledRunMayHoldSlot = false; - const endpoint = { port, token: apple.runner.mintToken(), http: { url: commandUrl, headers } }; + const token = apple.runner.mintToken(); + const endpoint = { + port, + token, + http: { + url: commandUrl, + headers, + transformResponse: (response: Response) => + scrubRunnerResponse(response, [headers.Authorization, token]), + }, + }; const provider = await apple.runner.createLaunchedProvider(session.device, { endpoint, launch }); const { stop, release, prepare, isStarted, releaseSpeculative } = provider; const isReady = provider.hasLiveSession; @@ -342,3 +353,36 @@ export async function createLimrunIosRunner( }, }; } + +function scrubRunnerResponse(response: Response, credentials: readonly string[]): Response { + if (!response.body) return response; + const chunks: string[] = []; + const body = response.body.pipeThrough(new TextDecoderStream()).pipeThrough( + new TransformStream({ + transform: (chunk) => { + chunks.push(chunk); + }, + flush: (controller) => { + controller.enqueue( + new TextEncoder().encode(scrubRunnerResponseText(chunks.join(''), credentials)), + ); + }, + }), + ); + return new Response(body, { + status: response.status, + statusText: safeInstanceErrorText(response.statusText, credentials), + headers: response.headers, + }); +} + +function scrubRunnerResponseText(text: string, credentials: readonly string[]): string { + let payload: unknown; + try { + payload = JSON.parse(text); + } catch { + return safeInstanceErrorText(text, credentials); + } + const scrubbed = scrubInstanceDiagnostic(payload, credentials); + return scrubbed === payload ? text : JSON.stringify(scrubbed); +} diff --git a/packages/provider-limrun/src/ios.ts b/packages/provider-limrun/src/ios.ts index 7c01aecb84..7b693b944e 100644 --- a/packages/provider-limrun/src/ios.ts +++ b/packages/provider-limrun/src/ios.ts @@ -1,5 +1,4 @@ import type { LimrunSyncCache } from './sync-cache.ts'; -import { LIMRUN_INSTANCE_CLIENT_LOGGING } from './client-options.ts'; import type { SettingOptions } from '@agent-device/contracts/settings'; import type { DeviceLease, @@ -65,15 +64,11 @@ export async function createLimrunIosSession( ): Promise { // The wrapper is loaded here, not imported: the runtime façade keeps its merge-base eager closure // (ADR-0027). - const { withInstanceCredentialScrubbing } = await import('./instance-error-scrubbing.ts'); - const client = withInstanceCredentialScrubbing( - await createIosInstanceClient({ - apiUrl: options.apiUrl, - token: options.token, - ...LIMRUN_INSTANCE_CLIENT_LOGGING, - }), - [`Bearer ${options.token}`], - ); + const { connectLimrunInstanceClient } = await import('./instance-error-scrubbing.ts'); + const client = await connectLimrunInstanceClient(createIosInstanceClient, { + apiUrl: options.apiUrl, + token: options.token, + }); try { const runner = await dependencies.ios.createRunner({ ...options, client }); return { ...options, platform: 'ios', client, runner, dependencies }; diff --git a/packages/provider-limrun/src/lease-release.test.ts b/packages/provider-limrun/src/lease-release.test.ts index 00f2a90058..f09244614e 100644 --- a/packages/provider-limrun/src/lease-release.test.ts +++ b/packages/provider-limrun/src/lease-release.test.ts @@ -223,7 +223,11 @@ test('recovery by labels refuses with every id when a delete is not confirmed', 'Ask Limrun to delete: android-instance-b, android-instance-c.', ); expect(String(thrown.details?.hint)).toContain('android-instance-a was confirmed deleted'); - expect(String(thrown.cause)).toContain('refused'); + expect(thrown.cause).toMatchObject({ + code: 'COMMAND_FAILED', + details: { reason: 'limrun_api_failed' }, + cause: undefined, + }); }); /** diff --git a/packages/provider-limrun/src/runtime-dependencies.test.ts b/packages/provider-limrun/src/runtime-dependencies.test.ts index 9814d2ac8e..ee4e0aaca6 100644 --- a/packages/provider-limrun/src/runtime-dependencies.test.ts +++ b/packages/provider-limrun/src/runtime-dependencies.test.ts @@ -69,6 +69,8 @@ vi.mock('@limrun/api', () => ({ list: state.assetList, }; + readonly apiKey = 'lim_test_key'; + constructor(options: { defaultHeaders?: Record }) { state.constructorOptions.push(options); } @@ -109,12 +111,20 @@ test('heartbeat reports a terminated instance with its typed cause', async () => assert.equal(await timedOut, undefined); assert.equal(probeSignal?.aborted, true); vi.useRealTimers(); + state.instanceGet.mockResolvedValueOnce({ + status: { + state: 'terminated', + terminationReason: 'InactivityTimeout instance-token lim_test_key', + }, + }); await assert.rejects( runtime.leaseLifecycle.heartbeat!(lease), (error: unknown) => error instanceof AppError && error.details?.reason === 'provider-instance-ended' && - error.details.terminationReason === 'InactivityTimeout', + error.details.terminationReason === 'InactivityTimeout [REDACTED] [REDACTED]' && + !error.message.includes('instance-token') && + !error.message.includes('lim_test_key'), ); } finally { vi.useRealTimers(); diff --git a/packages/provider-limrun/src/runtime.ts b/packages/provider-limrun/src/runtime.ts index 4baaef7215..a923066020 100644 --- a/packages/provider-limrun/src/runtime.ts +++ b/packages/provider-limrun/src/runtime.ts @@ -45,7 +45,6 @@ import { deleteLimrunInstance, LIMRUN_CLIENT_ID, LIMRUN_ORG_CLIENT_LOGGING, - fromLimrunOrgApi, limrunUserAgent, requireLimrunOrgClient, } from './client-options.ts'; @@ -555,12 +554,10 @@ class LimrunRuntimeImplementation implements ProviderDeviceRuntime { // The session is recorded in the step that answers for it, so every later step of this allocation // fails with its handles still owned: the instance client and the host ADB endpoint are released by // whoever ends this lease, whether or not the allocation ever answered. - // The create's failure is the one answer this lease has for its caller and is recorded by the daemon, - // so it is normalized here: the SDK's own text for an account-API refusal is the response body. const session = platform === 'ios' - ? await fromLimrunOrgApi(allocateLimrunIosSession(params, rent)) - : await fromLimrunOrgApi(allocateLimrunAndroidSession(params, rent)); + ? await allocateLimrunIosSession(params, rent) + : await allocateLimrunAndroidSession(params, rent); owner.session = session; const appAlias: LimrunAppAlias | undefined = requestedAsset && { assetName: requestedAsset.name, @@ -959,7 +956,7 @@ function allocationRefusedAfterShutdown(lease: DeviceLease): never { */ async function readLimrunTerminationReason( limrun: Limrun, - session: Pick, + session: Pick, requestSignal: AbortSignal | undefined, ): Promise { const expiry = new AbortController(); @@ -983,6 +980,7 @@ async function readLimrunTerminationReason( const { safeTerminationReason } = await import('./error-text.ts'); return safeTerminationReason(answer.value.status.terminationReason, [ limrun.apiKey ?? undefined, + session.token, ]); } catch { return undefined; diff --git a/packages/provider-limrun/src/session-allocation.test.ts b/packages/provider-limrun/src/session-allocation.test.ts index a8b68cfb12..24e0ac1794 100644 --- a/packages/provider-limrun/src/session-allocation.test.ts +++ b/packages/provider-limrun/src/session-allocation.test.ts @@ -131,8 +131,10 @@ test('the instance delete asks the SDK for one attempt, so a lost answer is not try { const deleted = await deleteLimrunInstance(clientFor(server), 'android', 'android-instance-1'); assert.deepEqual(routes, ['DELETE /v1/android_instances/android-instance-1']); - assert.match(String(deleted.failure), /connection|socket|abort|fetch|closed/i); - assert.ok(deleted.cause !== undefined, 'the refusal is reported, not swallowed'); + assert.equal(deleted.failure, 'Limrun organization request failed.'); + assert.ok(deleted.cause instanceof AppError); + assert.equal(deleted.cause.details?.reason, 'limrun_api_failed'); + assert.equal(deleted.cause.cause, undefined); } finally { await server.close(); } diff --git a/packages/provider-limrun/src/session-allocation.ts b/packages/provider-limrun/src/session-allocation.ts index a0eb860386..ef6f56dba0 100644 --- a/packages/provider-limrun/src/session-allocation.ts +++ b/packages/provider-limrun/src/session-allocation.ts @@ -4,7 +4,7 @@ import { REMOTE_LEASE_IDLE_TTL_MS } from '@agent-device/contracts/lease-scope'; import { AppError } from '@agent-device/kernel/errors'; import { rejectRefusedProviderProfileFields } from '@agent-device/contracts/provider-profile-fields'; import { createLimrunAndroidSession, type LimrunAndroidSession } from './android.ts'; -import { LIMRUN_SINGLE_ATTEMPT } from './client-options.ts'; +import { fromLimrunOrgApi, LIMRUN_SINGLE_ATTEMPT } from './client-options.ts'; import { buildLimrunDevice, LIMRUN_PROFILE_FIELDS } from './device.ts'; import { createLimrunIosSession, type LimrunIosSession } from './ios.ts'; import { @@ -74,30 +74,32 @@ export async function allocateLimrunIosSession( params: SessionAllocationParams, onRent: (instanceId: string) => void, ): Promise { - const instance = (await params.limrun.iosInstances.create( - { - wait: true, - metadata: params.metadata, - spec: { - inactivityTimeout: LIMRUN_INACTIVITY_TIMEOUT, - ...(params.region ? { region: params.region } : {}), - ...(params.app - ? { - initialAssets: [ - { - kind: 'App' as const, - source: 'AssetID' as const, - assetId: params.app.id, - launchMode: 'RelaunchIfRunning' as const, - }, - ], - } - : {}), + const instance = (await fromLimrunOrgApi( + params.limrun.iosInstances.create( + { + wait: true, + metadata: params.metadata, + spec: { + inactivityTimeout: LIMRUN_INACTIVITY_TIMEOUT, + ...(params.region ? { region: params.region } : {}), + ...(params.app + ? { + initialAssets: [ + { + kind: 'App' as const, + source: 'AssetID' as const, + assetId: params.app.id, + launchMode: 'RelaunchIfRunning' as const, + }, + ], + } + : {}), + }, }, - }, - // Limrun may have created this instance even though its answer was lost, so the SDK must not POST - // this call again: a second create would rent a second instance nobody is standing beside. - LIMRUN_SINGLE_ATTEMPT, + // Limrun may have created this instance even though its answer was lost, so the SDK must not POST + // this call again: a second create would rent a second instance nobody is standing beside. + LIMRUN_SINGLE_ATTEMPT, + ), )) as LimrunInstance; const instanceId = instance.metadata.id; // Rented from this step: the caller's owner records the instance here, before any session is built on it, @@ -123,29 +125,31 @@ export async function allocateLimrunAndroidSession( params: SessionAllocationParams, onRent: (instanceId: string) => void, ): Promise { - const instance = (await params.limrun.androidInstances.create( - { - wait: true, - metadata: params.metadata, - spec: { - inactivityTimeout: LIMRUN_INACTIVITY_TIMEOUT, - ...(params.region ? { region: params.region } : {}), - ...(params.app - ? { - initialAssets: [ - { - kind: 'App' as const, - source: 'AssetIDs' as const, - assetIds: [params.app.id], - }, - ], - } - : {}), + const instance = (await fromLimrunOrgApi( + params.limrun.androidInstances.create( + { + wait: true, + metadata: params.metadata, + spec: { + inactivityTimeout: LIMRUN_INACTIVITY_TIMEOUT, + ...(params.region ? { region: params.region } : {}), + ...(params.app + ? { + initialAssets: [ + { + kind: 'App' as const, + source: 'AssetIDs' as const, + assetIds: [params.app.id], + }, + ], + } + : {}), + }, }, - }, - // Limrun may have created this instance even though its answer was lost, so the SDK must not POST - // this call again: a second create would rent a second instance nobody is standing beside. - LIMRUN_SINGLE_ATTEMPT, + // Limrun may have created this instance even though its answer was lost, so the SDK must not POST + // this call again: a second create would rent a second instance nobody is standing beside. + LIMRUN_SINGLE_ATTEMPT, + ), )) as LimrunInstance; const instanceId = instance.metadata.id; // Rented from this step: the caller's owner records the instance here, before any session is built on it, diff --git a/src/__tests__/limrun-runtime.test.ts b/src/__tests__/limrun-runtime.test.ts index f98e0fcfe6..61110a984d 100644 --- a/src/__tests__/limrun-runtime.test.ts +++ b/src/__tests__/limrun-runtime.test.ts @@ -707,7 +707,10 @@ test('Limrun keeps session tracked when release fails so release can be retried' error instanceof AppError && details?.reason === 'limrun_instance_delete_unconfirmed' && details.limrunInstanceId === 'android-instance-1' && - details.cause === 'temporary delete failure' + details.cause === 'Limrun organization request failed.' && + error.cause instanceof AppError && + error.cause.details?.reason === 'limrun_api_failed' && + error.cause.cause === undefined ); }, ); diff --git a/website/docs/docs/error-reasons.md b/website/docs/docs/error-reasons.md index 69154925cc..e0aad7780f 100644 --- a/website/docs/docs/error-reasons.md +++ b/website/docs/docs/error-reasons.md @@ -216,6 +216,7 @@ These reasons can come from more than one command. | `limrun_download_timeout` | The transfer's own deadline passed before the file reached disk. | | `limrun_download_failed` | The transfer failed before it could ask the instance for the file. | | `limrun_instance_command_failed` | The instance refused or could not answer the command; its text, with this session's credential removed, is the message. | +| `limrun_file_response_invalid` | The instance returned an unreadable JSON reply for a simulator file operation. | | `limrun_runner_snapshot_unavailable` | The runner's own capture failure is answered over: the recovery is to reopen this session, not to inspect the simulator. | ### Macos helper From eb28689b6a8bfb6f1ad371b5f59358c7f5b25e59 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sun, 22 Nov 2026 18:23:53 +0100 Subject: [PATCH 26/26] fix(limrun): redact diagnostics without changing runner replies --- .../__tests__/runner-command-recovery.test.ts | 34 ++++++++-- .../src/runner-command-recovery.ts | 21 +++++-- packages/apple-runner/src/runner-contract.ts | 62 +++++++++---------- packages/apple-runner/src/runner-exchange.ts | 33 +++++++--- packages/apple-runner/src/runner-transport.ts | 2 +- packages/provider-limrun/src/android.test.ts | 50 +++++++++++++++ packages/provider-limrun/src/android.ts | 39 ++++++++++-- .../provider-limrun/src/app-catalog.test.ts | 18 ++++++ packages/provider-limrun/src/app-catalog.ts | 2 +- .../src/app-log-reconnect.test.ts | 6 +- .../provider-limrun/src/app-log-reconnect.ts | 7 ++- .../src/device-session.test.ts | 23 ++++++- .../provider-limrun/src/device-session.ts | 9 ++- .../src/instance-error-scrubbing.ts | 25 +++++--- .../provider-limrun/src/ios-runner.test.ts | 29 +++------ packages/provider-limrun/src/ios-runner.ts | 40 ++---------- packages/provider-limrun/src/ios.ts | 9 ++- .../provider-limrun/src/sync-cache.test.ts | 19 ++++++ packages/provider-limrun/src/sync-cache.ts | 2 +- ...ost-capabilities-limrun-ios-runner.test.ts | 25 ++++++++ ...n-host-capabilities-limrun-ios.fixtures.ts | 6 +- 21 files changed, 324 insertions(+), 137 deletions(-) diff --git a/packages/apple-runner/src/__tests__/runner-command-recovery.test.ts b/packages/apple-runner/src/__tests__/runner-command-recovery.test.ts index 7cd0bc85e8..3e7db640db 100644 --- a/packages/apple-runner/src/__tests__/runner-command-recovery.test.ts +++ b/packages/apple-runner/src/__tests__/runner-command-recovery.test.ts @@ -6,7 +6,7 @@ import { AppError } from '@agent-device/kernel/errors'; import { IOS_SIMULATOR } from './device-fixtures.ts'; import type { ExecResult } from '@agent-device/host-kit/command'; import { handleRunnerTransportErrorAfterCommandSend } from '../runner-command-recovery.ts'; -import type { RunnerCommand } from '../runner-contract.ts'; +import type { RunnerCommand, RunnerEndpoint } from '../runner-contract.ts'; import { RUNNER_REPLY_LOST_REASON } from '../runner-error-classification.ts'; import type { RunnerSession } from '../runner-session.ts'; import { @@ -27,12 +27,12 @@ afterEach(async () => { server = undefined; }); -function makeRunnerSession(port: number): RunnerSession { +function makeRunnerSession(port: number, http?: RunnerEndpoint['http']): RunnerSession { return makeLocalRunnerSession({ sessionId: `fake:${port}`, device: IOS_SIMULATOR, deviceId: IOS_SIMULATOR.id, - endpoint: { port, token: 'runner-token-fixture' }, + endpoint: { port, token: 'runner-token-fixture', http }, xctestrunPath: '/tmp/fake.xctestrun', jsonPath: '/tmp/fake.json', testPromise: new Promise(() => {}), @@ -50,6 +50,7 @@ async function runRecovery(params: { script: FakeRunnerResponse[]; command?: RunnerCommand; transportError?: AppError; + scrubText?: (text: string) => string; }): Promise<{ result: Promise>; session: RunnerSession; @@ -57,7 +58,15 @@ async function runRecovery(params: { transportError: AppError; }> { server = await startFakeRunnerServer(params.script); - const session = makeRunnerSession(server.port); + const session = makeRunnerSession( + server.port, + params.scrubText + ? { + url: `http://127.0.0.1:${server.port}/command`, + diagnostics: { scrubText: params.scrubText, scrubPayload: (payload) => payload }, + } + : undefined, + ); const invalidate = vi.fn(async () => {}); const transportError = params.transportError ?? new AppError('COMMAND_FAILED', 'socket hang up'); const result = handleRunnerTransportErrorAfterCommandSend({ @@ -124,6 +133,23 @@ test('an unknown lifecycle state invalidates the session and says so', async () assert.equal(invalidate.mock.calls[0]?.[1], 'transport_error_after_command_send'); }); +test('an unknown provider lifecycle state is scrubbed when published', async () => { + const token = 'synthetic-instance-token'; + const { result, invalidate } = await runRecovery({ + script: [{ kind: 'ok', data: { lifecycleState: token } }], + scrubText: (text) => text.replaceAll(token, '[REDACTED]'), + }); + await assert.rejects( + result, + (error: unknown) => + error instanceof AppError && + error.message.includes('invalidated the runner session') && + !error.message.includes(token) && + error.details?.lifecycleState === '[REDACTED]', + ); + assert.equal(invalidate.mock.calls.length, 1); +}); + test('notAccepted from a restarted runner fails the lost command as unknown, naming the lost reply', async () => { const { result, invalidate } = await runRecovery({ script: [{ kind: 'ok', data: { lifecycleState: 'notAccepted' } }], diff --git a/packages/apple-runner/src/runner-command-recovery.ts b/packages/apple-runner/src/runner-command-recovery.ts index a5070fb59f..40c9fc5b35 100644 --- a/packages/apple-runner/src/runner-command-recovery.ts +++ b/packages/apple-runner/src/runner-command-recovery.ts @@ -262,6 +262,7 @@ async function tryRecoverRunnerCommandAfterTransportError( }; } + const scrubText = session.endpoint.http?.diagnostics?.scrubText; const lifecycleState = typeof status.lifecycleState === 'string' ? status.lifecycleState : ''; // Terminal evidence says the runner finished *this* command, so that command's abandoned charge pays // off and no other's does. `accepted`, `started`, and a state this daemon cannot name all keep the @@ -273,7 +274,7 @@ async function tryRecoverRunnerCommandAfterTransportError( data: { command: command.command, commandId: command.commandId, - lifecycleState, + lifecycleState: scrubText?.(lifecycleState) ?? lifecycleState, ...readinessPreflight, // Whether this terminal evidence discharged a debt. Absent when the state is not terminal, so // nothing was attempted; `false` when the command held no abandoned charge to pay. @@ -286,6 +287,7 @@ async function tryRecoverRunnerCommandAfterTransportError( command, transportError, options, + scrubText, ); } @@ -295,6 +297,7 @@ function handleRunnerCommandStatusRecovery( command: RunnerCommand, transportError: AppError, options: AppleRunnerCommandOptions, + scrubText?: (text: string) => string, ): RunnerTransportRecovery { if (lifecycleState === 'completed') { return handleCompletedRunnerStatus(status, command, transportError); @@ -307,6 +310,7 @@ function handleRunnerCommandStatusRecovery( // surrenders its budget to a condition that clears on its own. const classification = classifyRunnerReportedError( typeof status.lifecycleErrorCode === 'string' ? status.lifecycleErrorCode : undefined, + scrubText, ); return { type: 'skipInvalidation', @@ -319,6 +323,7 @@ function handleRunnerCommandStatusRecovery( command, transportError, options, + scrubText, ), }; } @@ -341,14 +346,15 @@ function handleRunnerCommandStatusRecovery( }; } + const publishedState = scrubText?.(lifecycleState) ?? lifecycleState; return { type: 'retainInvalidation', reason: lifecycleState ? 'unknown_lifecycle_state' : 'missing_lifecycle_state', - lifecycleState, + lifecycleState: publishedState, lostReply: { recovery: 'lifecycle_state_not_recoverable', - lifecycleState, - cause: `lifecycle status was ${lifecycleState ? `"${lifecycleState}"` : 'missing'}`, + lifecycleState: publishedState, + cause: `lifecycle status was ${publishedState ? `"${publishedState}"` : 'missing'}`, hint: unknownLifecycleStateHint(command.command), }, }; @@ -392,13 +398,16 @@ function runnerStatusFailureError( command: RunnerCommand, transportError: AppError, options: AppleRunnerCommandOptions, + scrubText: (text: string) => string = (text) => text, ): AppError { const errorMessage = typeof status.lifecycleErrorMessage === 'string' - ? status.lifecycleErrorMessage + ? scrubText(status.lifecycleErrorMessage) : 'Runner command failed'; const hint = - typeof status.lifecycleErrorHint === 'string' ? status.lifecycleErrorHint : undefined; + typeof status.lifecycleErrorHint === 'string' + ? scrubText(status.lifecycleErrorHint) + : undefined; const readinessPreflight = readReadinessPreflightRecoveryDetails(transportError); return new AppError( classification.code, diff --git a/packages/apple-runner/src/runner-contract.ts b/packages/apple-runner/src/runner-contract.ts index 108e9ddede..70346515b3 100644 --- a/packages/apple-runner/src/runner-contract.ts +++ b/packages/apple-runner/src/runner-contract.ts @@ -524,14 +524,10 @@ export type RunnerReportedErrorClass = Readonly<{ }>; }>; -/** - * The one reading of a runner-reported error code (#2484 follow-up). A runner failure reaches the - * host by two routes — the command's own response, and the lifecycle journal a status probe reads - * back after the transport response was lost — and both must classify it identically, or the same - * runner condition surfaces under two codes with only one of them marked retriable. - */ +/** Classifies live and retained runner failures from the original protocol code. */ export function classifyRunnerReportedError( runnerErrorCode: string | undefined, + scrubText?: (text: string) => string, ): RunnerReportedErrorClass { const row = runnerErrorCodeRow(runnerErrorCode); // A code the table does not declare carries no dispatch evidence, so it publishes `unknown`. @@ -542,7 +538,10 @@ export function classifyRunnerReportedError( ? (row.diagnosticOnly.wireCode ?? 'COMMAND_FAILED') : toAppErrorCode(runnerErrorCode), details: Object.freeze({ - runnerErrorCode, + runnerErrorCode: + row || runnerErrorCode === undefined + ? runnerErrorCode + : (scrubText?.(runnerErrorCode) ?? runnerErrorCode), ...(row?.diagnosticOnly?.retriable === true ? { retriable: true as const } : {}), ...(row?.reason === undefined ? {} : { reason: row.reason }), dispatched, @@ -612,26 +611,21 @@ function backDismissHint(controls: readonly BackDismissControl[]): string | unde : 'Press one of details.dismissControls by its selector to dismiss this screen; back only pops the navigation stack.'; } -/** - * The one decoding of a runner response body (#2662). The envelope arrives at three readers — a - * command's own response, the lifecycle journal a status probe reads back after the transport - * response was lost, and the adoption `uptime` probe — and all three must agree on what is - * readable, or a body one of them refuses becomes an answer for another. - * - * Only a JSON object can be an envelope. A body that is not JSON at all, and a JSON scalar or array - * that carries no `ok`, are both transport-shaped: neither is something the runner's encoder emits, - * and reading either as an empty reply would let a proxy page or a half-written body answer for a - * command the runner may still be executing. - */ -export function decodeRunnerResponseBody(text: string): RunnerResponsePayload { +/** Decodes command, retained journal, and adoption replies with the same envelope rules. */ +export function decodeRunnerResponseBody( + text: string, + scrubText?: (text: string) => string, +): RunnerResponsePayload { let parsed: unknown; try { parsed = JSON.parse(text); } catch { - throw new AppError('COMMAND_FAILED', 'Invalid runner response', { text }); + parsed = undefined; } if (!isRunnerEnvelopeObject(parsed)) { - throw new AppError('COMMAND_FAILED', 'Invalid runner response', { text }); + throw new AppError('COMMAND_FAILED', 'Invalid runner response', { + text: scrubText?.(text) ?? text, + }); } return parsed; } @@ -653,15 +647,20 @@ export function readRunnerResponseData(payload: RunnerResponsePayload): Record['diagnostics'], ): AppError { - const runnerErrorCode = readRunnerErrorCode(payload.error?.code); + const rawCode = payload.error?.code; + const runnerErrorCode = typeof rawCode === 'string' ? rawCode.trim() || undefined : undefined; + const text = diagnostics?.scrubText ?? ((value) => value); const errorMessage = - typeof payload.error?.message === 'string' ? payload.error.message : undefined; - const hint = typeof payload.error?.hint === 'string' ? payload.error.hint : undefined; - const classification = classifyRunnerReportedError(runnerErrorCode); - const dismissControls = readBackDismissControls(runnerErrorCode, payload.error); + typeof payload.error?.message === 'string' ? text(payload.error.message) : undefined; + const hint = typeof payload.error?.hint === 'string' ? text(payload.error.hint) : undefined; + const classification = classifyRunnerReportedError(runnerErrorCode, text); + const dismissControls = readBackDismissControls(runnerErrorCode, payload.error).filter( + (control) => !diagnostics || diagnostics.scrubPayload(control) === control, + ); return new AppError(classification.code, errorMessage ?? 'Runner error', { - runner: payload, + runner: diagnostics ? diagnostics.scrubPayload(payload) : payload, ...classification.details, ...(dismissControls.length > 0 ? { dismissControls } : {}), xcodebuild: { @@ -674,10 +673,6 @@ export function buildRunnerResponseError( }); } -function readRunnerErrorCode(rawCode: unknown): string | undefined { - return typeof rawCode === 'string' && rawCode.trim().length > 0 ? rawCode.trim() : undefined; -} - export function withRunnerCommandId(command: RunnerCommand): RunnerCommand { if (command.command === 'status') return command; if (command.commandId?.trim()) return command; @@ -706,7 +701,10 @@ export type RunnerEndpoint = Readonly<{ http?: Readonly<{ url: string; headers?: Readonly>; - transformResponse?(response: Response): Response; + diagnostics?: Readonly<{ + scrubText(text: string): string; + scrubPayload(payload: unknown): unknown; + }>; }>; }>; diff --git a/packages/apple-runner/src/runner-exchange.ts b/packages/apple-runner/src/runner-exchange.ts index 2e66b82dda..8396d8ab4a 100644 --- a/packages/apple-runner/src/runner-exchange.ts +++ b/packages/apple-runner/src/runner-exchange.ts @@ -205,7 +205,8 @@ async function settleRunnerAnsweredExchange( const runnerFatalReason = resolveRunnerFatalReason(data); if (runnerFatalReason) { session.lastHealthyMutation = undefined; - await invalidateFatalSession(runnerFatalReason); + const scrubText = session.endpoint.http?.diagnostics?.scrubText; + await invalidateFatalSession(scrubText?.(runnerFatalReason) ?? runnerFatalReason); } else if (canSkipRunnerReadinessPreflightAfterHealthyMutation(runnerCommand)) { session.lastHealthyMutation = { atMs: Date.now(), @@ -411,7 +412,10 @@ async function drainCanceledRunnerCommand(params: { command: runnerCommand.command, commandId: runnerCommand.commandId, outcome, - lifecycleState, + lifecycleState: + lifecycleState === undefined + ? undefined + : (session.endpoint.http?.diagnostics?.scrubText(lifecycleState) ?? lifecycleState), polls, }, }); @@ -509,34 +513,43 @@ function emitRunnerReadinessPreflightSkipped( */ export async function parseRunnerResponse( response: Response, - session: Pick, + session: Pick & Partial>, /** The command's own log boundary. Absent means no log was configured, so nothing is read. */ logAttempt?: RunnerLogAttempt, ): Promise> { - const payload = decodeRunnerResponseBody(await response.text()); + const diagnostics = session.endpoint?.http?.diagnostics; + const payload = decodeRunnerResponseBody(await response.text(), diagnostics?.scrubText); if (!isRunnerResponseOk(payload)) { throw await enrichRunnerFailureFromLog({ - error: buildRunnerResponseError(payload, logAttempt?.logPath), + error: buildRunnerResponseError(payload, logAttempt?.logPath, diagnostics), logSince: logAttempt, }); } advanceRunnerSessionState(session, 'ready'); const data = readRunnerResponseData(payload); - emitRunnerResponseDiagnostics(data); + emitRunnerResponseDiagnostics(data, diagnostics?.scrubText); return data; } -function emitRunnerResponseDiagnostics(data: Record): void { +function emitRunnerResponseDiagnostics( + data: Record, + scrubText: (text: string) => string = (text) => text, +): void { const fallback = data.gestureFallback; if (typeof fallback !== 'string' || fallback.length === 0) return; emitDiagnostic({ level: 'debug', phase: 'ios_runner_gesture_fallback', data: { - fallback, + fallback: scrubText(fallback), message: - typeof data.gestureFallbackMessage === 'string' ? data.gestureFallbackMessage : undefined, - hint: typeof data.gestureFallbackHint === 'string' ? data.gestureFallbackHint : undefined, + typeof data.gestureFallbackMessage === 'string' + ? scrubText(data.gestureFallbackMessage) + : undefined, + hint: + typeof data.gestureFallbackHint === 'string' + ? scrubText(data.gestureFallbackHint) + : undefined, }, }); } diff --git a/packages/apple-runner/src/runner-transport.ts b/packages/apple-runner/src/runner-transport.ts index 18fdc4d888..2657af38ed 100644 --- a/packages/apple-runner/src/runner-transport.ts +++ b/packages/apple-runner/src/runner-transport.ts @@ -119,7 +119,7 @@ export async function postRunnerCommandOverRoute( status: response.status, }); } - return endpoint.http?.transformResponse?.(response) ?? response; + return response; } /** A cancellation that lands before the POST is issued proves the runner received nothing. */ diff --git a/packages/provider-limrun/src/android.test.ts b/packages/provider-limrun/src/android.test.ts index 85163a9971..9f252f5355 100644 --- a/packages/provider-limrun/src/android.test.ts +++ b/packages/provider-limrun/src/android.test.ts @@ -1,5 +1,6 @@ import { beforeEach, expect, test, vi } from 'vitest'; import type { DeviceLease } from '@agent-device/contracts/device'; +import { AppError } from '@agent-device/kernel/errors'; import type { DeviceInfo } from '@agent-device/kernel/device'; import { androidAdbHostTarget, @@ -296,3 +297,52 @@ function androidDependencies( } as unknown as LimrunRuntimeDependencies['host'], }; } + +test('redacts failed ADB result text and preserves the exit and binary output', async () => { + const dependencies = androidDependencies(); + const stdoutBuffer = Buffer.from([0, 255]); + dependencies.host.runAdb = async () => ({ + exitCode: 17, + stdout: 'stdout instance-token', + stderr: 'stderr instance-token', + stdoutBuffer, + }); + const session = await createLimrunAndroidSession(ANDROID_SESSION_OPTIONS, dependencies); + const result = await session.adbProvider.exec(['shell', 'pm', 'list', 'packages', '-3'], { + allowFailure: true, + binaryStdout: true, + }); + expect(result).toEqual({ + exitCode: 17, + stdout: 'stdout [REDACTED]', + stderr: 'stderr [REDACTED]', + stdoutBuffer, + }); + expect(result.stdoutBuffer).toBe(stdoutBuffer); +}); + +test('redacts thrown ADB errors while preserving typed failure details', async () => { + const dependencies = androidDependencies(); + dependencies.host.runAdb = async () => { + throw new AppError( + 'COMMAND_FAILED', + 'ADB failed status', + { + stderr: 'connection refused status', + exitCode: 17, + status: 502, + }, + new Error('transport status'), + ); + }; + const session = await createLimrunAndroidSession( + { ...ANDROID_SESSION_OPTIONS, token: 'status' }, + dependencies, + ); + await expect(session.adbProvider.exec(['shell', 'echo', 'ready'])).rejects.toMatchObject({ + code: 'COMMAND_FAILED', + message: 'ADB failed [REDACTED]', + details: { stderr: 'connection refused [REDACTED]', exitCode: 17, status: 502 }, + cause: { message: 'transport [REDACTED]' }, + }); +}); diff --git a/packages/provider-limrun/src/android.ts b/packages/provider-limrun/src/android.ts index b8985aacf8..0af2db998f 100644 --- a/packages/provider-limrun/src/android.ts +++ b/packages/provider-limrun/src/android.ts @@ -282,12 +282,9 @@ async function runLimrunAndroidAdbAtSerial( options?: LimrunAdbCommandOptions, ): Promise { const invocation = session.dependencies.android.deviceAdbInvocation(serial, args); - const result = await session.dependencies.host.runAdb(invocation, { - allowFailure: options?.allowFailure, - binaryStdout: options?.binaryStdout, - stdin: options?.stdin, + const result = await runLimrunAndroidAdbCommand(session.dependencies, session.token, invocation, { + ...options, timeoutMs: options?.timeoutMs ?? 30_000, - signal: options?.signal, }); return await requireSuccessfulLimrunAndroidAdb( invocation, @@ -297,6 +294,38 @@ async function runLimrunAndroidAdbAtSerial( ); } +export async function runLimrunAndroidAdbCommand( + dependencies: Pick, + token: string, + invocation: AndroidAdbInvocation, + options?: LimrunAdbCommandOptions, +): Promise { + let result: LimrunAdbCommandResult; + try { + result = await dependencies.host.runAdb(invocation, options); + } catch (error) { + const { scrubInstanceCommandFailure } = await import('./instance-error-scrubbing.ts'); + throw scrubInstanceCommandFailure(error, [token]); + } + if (result.exitCode === 0) return result; + const { safeInstanceErrorText } = await import('./error-text.ts'); + return { + ...result, + stdout: safeInstanceErrorText(result.stdout, [token]), + stderr: safeInstanceErrorText(result.stderr, [token]), + }; +} + +export async function readLimrunAndroidLogs( + dependencies: Pick, + token: string, + adb: LimrunAdbExecutor, + lineLimit: number, +): Promise { + const { safeInstanceErrorText } = await import('./error-text.ts'); + return safeInstanceErrorText(await dependencies.android.readLogs(adb, lineLimit), [token]); +} + async function requireSuccessfulLimrunAndroidAdb( invocation: AndroidAdbInvocation, result: LimrunAdbCommandResult, diff --git a/packages/provider-limrun/src/app-catalog.test.ts b/packages/provider-limrun/src/app-catalog.test.ts index 0fe2ddfb69..9c2dc3e718 100644 --- a/packages/provider-limrun/src/app-catalog.test.ts +++ b/packages/provider-limrun/src/app-catalog.test.ts @@ -78,3 +78,21 @@ describe('Limrun uploaded app catalog', () => { ).toBeUndefined(); }); }); + +test('reports only the match count for ambiguous uploaded assets', async () => { + const name = 'Example.apk'; + const apiKey = 'synthetic-account-key'; + const limrun = { + apiKey, + assets: { + list: async () => [ + { id: 'echo-' + apiKey, name, md5: 'a' }, + { id: 'other', name, md5: 'b' }, + ], + }, + } as never; + await expect(resolveLimrunAppAsset(limrun, 'android', name)).rejects.toMatchObject({ + code: 'COMMAND_FAILED', + details: { app: name, platform: 'android', matchCount: 2 }, + }); +}); diff --git a/packages/provider-limrun/src/app-catalog.ts b/packages/provider-limrun/src/app-catalog.ts index 6e55826bb4..89d1e699ec 100644 --- a/packages/provider-limrun/src/app-catalog.ts +++ b/packages/provider-limrun/src/app-catalog.ts @@ -57,7 +57,7 @@ export async function resolveLimrunAppAsset( throw new AppError('COMMAND_FAILED', `Limrun returned multiple uploaded apps named ${name}.`, { app: name, platform, - assetIds: matches.map((asset) => asset.id), + matchCount: matches.length, }); } diff --git a/packages/provider-limrun/src/app-log-reconnect.test.ts b/packages/provider-limrun/src/app-log-reconnect.test.ts index 0ea3ecda6f..ae44161669 100644 --- a/packages/provider-limrun/src/app-log-reconnect.test.ts +++ b/packages/provider-limrun/src/app-log-reconnect.test.ts @@ -224,7 +224,7 @@ test('addresses app-log adb traffic at the tunnel serial and hands cleanup a com androidAdbInvocation(androidAdbHostTarget(), command), readLogs: async (adb: LimrunAdbExecutor) => { await adb(['shell', 'logcat', '-d', '-T', '20']); - return 'line\n'; + return 'line secret\n'; }, }, } as unknown as LimrunRuntimeDependencies, @@ -232,7 +232,9 @@ test('addresses app-log adb traffic at the tunnel serial and hands cleanup a com expect(outcome.status).toBe('opened'); if (outcome.status !== 'opened') return; - await outcome.reader.readLogs('com.example.app', 20, new AbortController().signal); + await expect( + outcome.reader.readLogs('com.example.app', 20, new AbortController().signal), + ).resolves.toBe('line [REDACTED]\n'); // The tunnel serial is addressing, so the command the reader wrote travels unchanged: no `-s` // is stitched back into the payload the provider hands over. expect(calls[0]).toEqual({ diff --git a/packages/provider-limrun/src/app-log-reconnect.ts b/packages/provider-limrun/src/app-log-reconnect.ts index b98740bea1..0f52bddf54 100644 --- a/packages/provider-limrun/src/app-log-reconnect.ts +++ b/packages/provider-limrun/src/app-log-reconnect.ts @@ -6,6 +6,7 @@ import type { LimrunAppLogDescriptor } from './app-log-descriptor.ts'; import type { LimrunAppLogReader, LimrunAppLogReconnectOutcome } from './app-log-runtime.ts'; import { fromLimrunOrgApi, isLimrunApiNotFound, requireLimrunOrgClient } from './client-options.ts'; import { connectLimrunInstanceClient } from './instance-error-scrubbing.ts'; +import { readLimrunAndroidLogs, runLimrunAndroidAdbCommand } from './android.ts'; import { attachedLimrunInstanceId } from './device.ts'; import type { LimrunAndroidInstanceAccess, @@ -154,7 +155,9 @@ async function openAndroidReader( args: readonly string[], commandOptions?: Parameters[1], ) => - await dependencies.host.runAdb( + await runLimrunAndroidAdbCommand( + dependencies, + access.token, dependencies.android.deviceAdbInvocation(serial, args), commandOptions, ); @@ -164,7 +167,7 @@ async function openAndroidReader( instanceId: descriptor.instanceId, ownership: descriptor.ownership, readLogs: async (_appBundleId, lineLimit) => - await dependencies.android.readLogs(adb, lineLimit), + await readLimrunAndroidLogs(dependencies, access.token, adb, lineLimit), [Symbol.asyncDispose]: async () => { await dependencies.host .runAdb(dependencies.android.hostAdbInvocation(['disconnect', serial]), { diff --git a/packages/provider-limrun/src/device-session.test.ts b/packages/provider-limrun/src/device-session.test.ts index 5606d77bd5..ad837bd9bf 100644 --- a/packages/provider-limrun/src/device-session.test.ts +++ b/packages/provider-limrun/src/device-session.test.ts @@ -36,7 +36,7 @@ const TEST_DEPENDENCIES = { wasVisible: false, dismissed: false, }), - readLogs: async () => 'log line\n', + readLogs: async () => 'log line android-instance-token\n', }, host: { ...baseDependencies.host, runAdb: async () => adbResult(''), downloadFile }, } satisfies LimrunRuntimeDependencies; @@ -167,7 +167,7 @@ test('Android device session exposes semantic ADB capabilities without its raw c }); assert.equal((await session.getKeyboardState()).visible, false); assert.equal((await session.dismissKeyboard()).dismissed, false); - assert.equal(await session.readLogs(20), 'log line\n'); + assert.equal(await session.readLogs(20), 'log line [REDACTED]\n'); assert.equal(await session.installRemoteApp('https://assets.example/android.apk'), undefined); await session.pressKey('KEYCODE_ENTER', ['shift']); await session.startRecording({ recordingId: 'recording-id', quality: 7 }); @@ -268,3 +268,22 @@ function commandExecution( function adbResult(stdout: string) { return { stdout, stderr: '', exitCode: 0, stdoutBuffer: undefined }; } + +test('iOS install verification errors redact the SDK identifier and inventory', async () => { + const rawSession = iosSession({ + deviceInfo: { screenWidth: 402, screenHeight: 874 }, + listApps: async () => [ + { bundleId: 'com.example.echo.ios-instance-token', name: 'Existing', installType: 'User' }, + ], + installApp: async () => ({ bundleId: 'ios-instance-token' }), + }); + const session = createLimrunDeviceSession(rawSession); + if (session.platform !== 'ios') throw new Error('Expected iOS'); + await assert.rejects(session.installRemoteApp('https://assets.example/example.zip'), { + details: { + resultBundleId: '[REDACTED]', + requestedBundleId: undefined, + installedUserApps: ['com.example.echo.[REDACTED]'], + }, + }); +}); diff --git a/packages/provider-limrun/src/device-session.ts b/packages/provider-limrun/src/device-session.ts index 2a59addb15..3fd0406d1f 100644 --- a/packages/provider-limrun/src/device-session.ts +++ b/packages/provider-limrun/src/device-session.ts @@ -7,7 +7,11 @@ import type { LimrunAndroidKeyboardState, LimrunHostAdapter, } from './runtime-dependencies.ts'; -import { createLimrunAndroidInteractor, type LimrunAndroidSession } from './android.ts'; +import { + createLimrunAndroidInteractor, + readLimrunAndroidLogs, + type LimrunAndroidSession, +} from './android.ts'; import { createLimrunIosInteractor, installLimrunIosRemoteApp, @@ -130,7 +134,8 @@ function createAndroidDeviceSession(session: LimrunAndroidSession): LimrunAndroi }, getKeyboardState: async () => await session.dependencies.android.getKeyboardState(adb), dismissKeyboard: async () => await session.dependencies.android.dismissKeyboard(adb), - readLogs: async (lineLimit) => await session.dependencies.android.readLogs(adb, lineLimit), + readLogs: async (lineLimit) => + await readLimrunAndroidLogs(session.dependencies, session.token, adb, lineLimit), ...createRecordingOperations(session.client, session.token, session.dependencies.host), installRemoteApp: async (url) => { await session.client.sendAsset(url); diff --git a/packages/provider-limrun/src/instance-error-scrubbing.ts b/packages/provider-limrun/src/instance-error-scrubbing.ts index bb2c114dfc..bc9e99b1a3 100644 --- a/packages/provider-limrun/src/instance-error-scrubbing.ts +++ b/packages/provider-limrun/src/instance-error-scrubbing.ts @@ -14,7 +14,7 @@ export async function connectLimrunInstanceClient< const client = await connect({ ...access, ...LIMRUN_INSTANCE_CLIENT_LOGGING }); return withInstanceCredentialScrubbing(client, secrets); } catch (error) { - throw instanceCommandFailure(error, secrets); + throw scrubInstanceCommandFailure(error, secrets); } } @@ -44,9 +44,6 @@ export function withInstanceCredentialScrubbing( sentValues: Iterable, ): Client { const secrets = [...sentValues].filter((value): value is string => typeof value === 'string'); - const scrub = (error: unknown): never => { - throw instanceCommandFailure(error, secrets); - }; return new Proxy(client, { get(target, property, receiver) { const value = Reflect.get(target, property, receiver); @@ -54,7 +51,12 @@ export function withInstanceCredentialScrubbing( const method = value as (...args: unknown[]) => unknown; return (...args: unknown[]) => { const answer = method.apply(target, args); - return answer instanceof Promise ? answer.then(undefined, scrub) : answer; + if (!(answer instanceof Promise)) return answer; + return answer.catch((error: unknown) => { + // The SDK's sync response decoder can quote only a prefix of the token. + if (property === 'syncApp' && error instanceof SyntaxError) throw new SyntaxError(); + throw scrubInstanceCommandFailure(error, secrets); + }); }; }, }); @@ -65,7 +67,7 @@ export function withInstanceCredentialScrubbing( * the message: it is the only diagnosis of a rejected command an instance gives. A failure that names * none of it is this plugin's caller's own error to answer for, and is returned as it came. */ -function instanceCommandFailure(error: unknown, secrets: readonly string[]): unknown { +export function scrubInstanceCommandFailure(error: unknown, secrets: readonly string[]): unknown { if (!(error instanceof Error)) return error; if (error instanceof AppError) { const text = safeInstanceErrorText(error.message, secrets); @@ -124,8 +126,13 @@ function scrubPublishedDetails( if (details === undefined) return undefined; const secrets = [...sentValues].filter((value): value is string => typeof value === 'string'); if (secrets.length === 0) return details; - const scrubbed = scrubInstanceDiagnostic(details, secrets); - return scrubbed === details ? details : (scrubbed as Record); + const scrubbed = scrubInstanceDiagnostic(details, secrets) as Record; + if (scrubbed === details) return details; + for (const key of ['status', 'statusCode', 'exitCode']) { + const status = details[key]; + if (typeof status === 'number') scrubbed[key] = status; + } + return scrubbed; } /** Rebuilds only the strings of a diagnostic value that name a sent credential; a type is preserved. */ @@ -138,7 +145,7 @@ export function scrubInstanceDiagnostic(value: unknown, secrets: readonly string const entries = value.map((entry) => scrubInstanceDiagnostic(entry, secrets)); return entries.every((entry, index) => entry === value[index]) ? value : entries; } - if (value === null || typeof value !== 'object') return value; + if (value === null || typeof value !== 'object' || ArrayBuffer.isView(value)) return value; const original = Object.entries(value); const entries = original .filter(([key]) => safeInstanceErrorText(key, secrets) === key) diff --git a/packages/provider-limrun/src/ios-runner.test.ts b/packages/provider-limrun/src/ios-runner.test.ts index 730db50c75..f53b3f3137 100644 --- a/packages/provider-limrun/src/ios-runner.test.ts +++ b/packages/provider-limrun/src/ios-runner.test.ts @@ -2,7 +2,7 @@ import { expect, test, vi } from 'vitest'; import type { LimrunIosHost } from './ios-host.ts'; import { createLimrunIosRunner } from './ios-runner.ts'; -test('the forwarded runner endpoint scrubs replies before the host consumes them', async () => { +test('the forwarded runner endpoint scrubs text and structured diagnostics', async () => { const token = 'synthetic instance-token'; type RunnerHost = LimrunIosHost['apple']['runner']; const createLaunchedProvider = vi.fn( @@ -25,26 +25,15 @@ test('the forwarded runner endpoint scrubs replies before the host consumes them >[0], host, ); - const http = createLaunchedProvider.mock.calls[0]?.[1].endpoint.http; - const rejected = Response.json( - { ok: false, error: { code: 'APP_NOT_RUNNING', message: 'refused ' + token, [token]: 'echo' } }, - { status: 409, headers: { 'x-agent-device-runner-auth': 'required' } }, - ); - const failure = http?.transformResponse?.(rejected) ?? rejected; - expect(failure.status).toBe(409); - expect(failure.headers.get('x-agent-device-runner-auth')).toBe('required'); - expect(await failure.json()).toEqual({ + const diagnostics = createLaunchedProvider.mock.calls[0]?.[1].endpoint.http?.diagnostics; + expect(diagnostics?.scrubText('refused ' + token)).toBe('refused [REDACTED]'); + expect( + diagnostics?.scrubPayload({ + ok: false, + error: { code: 'APP_NOT_RUNNING', message: 'refused ' + token, [token]: 'echo' }, + }), + ).toEqual({ ok: false, error: { code: 'APP_NOT_RUNNING', message: 'refused [REDACTED]' }, }); - - const accepted = Response.json({ - ok: true, - data: { gestureFallback: 'coordinate', gestureFallbackMessage: 'used ' + token }, - }); - const success = http?.transformResponse?.(accepted) ?? accepted; - expect(await success.json()).toEqual({ - ok: true, - data: { gestureFallback: 'coordinate', gestureFallbackMessage: 'used [REDACTED]' }, - }); }); diff --git a/packages/provider-limrun/src/ios-runner.ts b/packages/provider-limrun/src/ios-runner.ts index 632e2e8f25..f4597f489a 100644 --- a/packages/provider-limrun/src/ios-runner.ts +++ b/packages/provider-limrun/src/ios-runner.ts @@ -51,14 +51,17 @@ export async function createLimrunIosRunner( let prepared = false; let canceledRunMayHoldSlot = false; const token = apple.runner.mintToken(); + const credentials = [headers.Authorization, token]; const endpoint = { port, token, http: { url: commandUrl, headers, - transformResponse: (response: Response) => - scrubRunnerResponse(response, [headers.Authorization, token]), + diagnostics: { + scrubText: (text: string) => safeInstanceErrorText(text, credentials), + scrubPayload: (payload: unknown) => scrubInstanceDiagnostic(payload, credentials), + }, }, }; const provider = await apple.runner.createLaunchedProvider(session.device, { endpoint, launch }); @@ -353,36 +356,3 @@ export async function createLimrunIosRunner( }, }; } - -function scrubRunnerResponse(response: Response, credentials: readonly string[]): Response { - if (!response.body) return response; - const chunks: string[] = []; - const body = response.body.pipeThrough(new TextDecoderStream()).pipeThrough( - new TransformStream({ - transform: (chunk) => { - chunks.push(chunk); - }, - flush: (controller) => { - controller.enqueue( - new TextEncoder().encode(scrubRunnerResponseText(chunks.join(''), credentials)), - ); - }, - }), - ); - return new Response(body, { - status: response.status, - statusText: safeInstanceErrorText(response.statusText, credentials), - headers: response.headers, - }); -} - -function scrubRunnerResponseText(text: string, credentials: readonly string[]): string { - let payload: unknown; - try { - payload = JSON.parse(text); - } catch { - return safeInstanceErrorText(text, credentials); - } - const scrubbed = scrubInstanceDiagnostic(payload, credentials); - return scrubbed === payload ? text : JSON.stringify(scrubbed); -} diff --git a/packages/provider-limrun/src/ios.ts b/packages/provider-limrun/src/ios.ts index 7b693b944e..20b5bca590 100644 --- a/packages/provider-limrun/src/ios.ts +++ b/packages/provider-limrun/src/ios.ts @@ -187,12 +187,15 @@ async function verifyLimrunIosInstall( }); if (verifiedBundleId) return { appId: verifiedBundleId }; } + const { safeInstanceErrorText } = await import('./error-text.ts'); + const scrubId = (value?: string) => + value === undefined ? undefined : safeInstanceErrorText(value, [session.token]); throw new AppError('COMMAND_FAILED', 'Limrun iOS app installation could not be verified.', { - resultBundleId, - requestedBundleId, + resultBundleId: scrubId(resultBundleId), + requestedBundleId: scrubId(requestedBundleId), installedUserApps: afterInstallApps .filter(isUserInstalledIosApp) - .map((app) => app.bundleId) + .map((app) => safeInstanceErrorText(app.bundleId, [session.token])) .sort(), }); } diff --git a/packages/provider-limrun/src/sync-cache.test.ts b/packages/provider-limrun/src/sync-cache.test.ts index 8e16ed5fe0..de9cf1d740 100644 --- a/packages/provider-limrun/src/sync-cache.test.ts +++ b/packages/provider-limrun/src/sync-cache.test.ts @@ -3,6 +3,7 @@ import path from 'node:path'; import { expect, test } from 'vitest'; import { mkdtempForTest } from '@agent-device/test-kit'; import { AppError } from '@agent-device/kernel/errors'; +import { withInstanceCredentialScrubbing } from './instance-error-scrubbing.ts'; import { LimrunSyncCache } from './sync-cache.ts'; test('materializations reuse one basis, prune removed resources, and release it with the lease', async () => { @@ -117,3 +118,21 @@ test('a canceled queued install never reaches the SDK after the previous install expect(secondRan).toBe(false); await cache.dispose(); }); + +test.each([ + ['ios', 'syntheticLongInstanceTokenForSync'], + ['android', 'short'], +] as const)('discards the %s SDK sync JSON decoder cause', async (platform, token) => { + const client = withInstanceCredentialScrubbing({ syncApp: async () => JSON.parse(token) }, [ + token, + ]); + const cache = new LimrunSyncCache(); + await expect(cache.run('/synthetic-app', platform, () => client.syncApp())).rejects.toMatchObject( + { + code: 'COMMAND_FAILED', + details: { reason: 'limrun_app_sync_failed', platform, installablePath: '/synthetic-app' }, + cause: undefined, + }, + ); + await cache.dispose(); +}); diff --git a/packages/provider-limrun/src/sync-cache.ts b/packages/provider-limrun/src/sync-cache.ts index bf1981660e..af9ceb2215 100644 --- a/packages/provider-limrun/src/sync-cache.ts +++ b/packages/provider-limrun/src/sync-cache.ts @@ -47,7 +47,7 @@ export class LimrunSyncCache { platform, installablePath, }, - error, + error instanceof SyntaxError ? undefined : error, ); } }); diff --git a/src/provider-plugin-host-capabilities-limrun-ios-runner.test.ts b/src/provider-plugin-host-capabilities-limrun-ios-runner.test.ts index 09231807f9..0540b1d917 100644 --- a/src/provider-plugin-host-capabilities-limrun-ios-runner.test.ts +++ b/src/provider-plugin-host-capabilities-limrun-ios-runner.test.ts @@ -818,3 +818,28 @@ test('an interrupted upload does not prevent the fixture from serving a later re await f.runner.applicationTools.prewarmRunnerCache(f.device, {}, new AbortController().signal); expect(f.uploads).toHaveLength(1); }); + +test('a short instance token matching the success field leaves the runner reply intact', async () => { + const f = await fixture({ + instanceToken: 'ok', + snapshot: { + nodes: [ + { + index: 0, + type: 'Application', + label: 'Book', + rect: { x: 0, y: 0, width: 390, height: 844 }, + }, + ], + truncated: false, + }, + }); + try { + const snapshot = await f.runner + .createInteractor() + .snapshot({ appBundleId: 'com.apple.Preferences' }); + expect(snapshot).toMatchObject({ nodes: [expect.objectContaining({ label: 'Book' })] }); + } finally { + await f.runner.dispose(); + } +}); diff --git a/src/provider-plugin-host-capabilities-limrun-ios.fixtures.ts b/src/provider-plugin-host-capabilities-limrun-ios.fixtures.ts index 7105f3659f..8ae3d2ca18 100644 --- a/src/provider-plugin-host-capabilities-limrun-ios.fixtures.ts +++ b/src/provider-plugin-host-capabilities-limrun-ios.fixtures.ts @@ -59,6 +59,7 @@ async function requestBody(request: IncomingMessage): Promise; } & FileStoreOptions = {}, ): Promise { + const instanceToken = options.instanceToken ?? 'instance-token'; const directory = await mkdtempForTest('limrun-runner-'); const app = path.join(directory, 'AgentDeviceRunnerUITests-Runner.app'); await fs.mkdir(path.join(app, 'PlugIns', 'AgentDeviceRunnerUITests.xctest'), { recursive: true }); @@ -208,7 +210,7 @@ export async function fixture( const storage = fileStore(options); const server = createServer(async (request, response) => { requests.push(request.url!); - if (request.headers.authorization !== 'Bearer instance-token') { + if (request.headers.authorization !== `Bearer ${instanceToken}`) { response.writeHead(401).end(); return; } @@ -256,7 +258,7 @@ export async function fixture( const stopReadiness: Mock<() => void> = vi.fn(); const session = { apiUrl: `http://127.0.0.1:${address.port}/v1/ios_test/api`, - token: 'instance-token', + token: instanceToken, device: { id: 'limrun:ios:test', platform: 'apple',