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/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/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/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/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 5da9cfbe22..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; @@ -693,7 +688,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 +698,14 @@ 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>; + diagnostics?: Readonly<{ + scrubText(text: string): string; + scrubPayload(payload: unknown): unknown; + }>; + }>; }>; export function mintRunnerToken(): string { @@ -739,8 +740,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-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/contracts/src/plugin-installation.ts b/packages/contracts/src/plugin-installation.ts index 1705409d26..d4b563a858 100644 --- a/packages/contracts/src/plugin-installation.ts +++ b/packages/contracts/src/plugin-installation.ts @@ -137,6 +137,8 @@ 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; /** 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..fe14708ee5 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" }, @@ -8,29 +8,68 @@ "apiVersion": 3, "provider": "limrun" }, - "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/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 f97d81f53a..0af2db998f 100644 --- a/packages/provider-limrun/src/android.ts +++ b/packages/provider-limrun/src/android.ts @@ -75,11 +75,13 @@ export async function createLimrunAndroidSession( }, dependencies: Pick, ): Promise { - const client = await createAndroidInstanceClient({ + // 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 { connectLimrunInstanceClient } = await import('./instance-error-scrubbing.ts'); + const client = await connectLimrunInstanceClient(createAndroidInstanceClient, { apiUrl: options.apiUrl, adbUrl: options.adbUrl, token: options.token, - logLevel: 'warn', }); const session: LimrunAndroidAdbSession = { platform: 'android', @@ -280,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, @@ -295,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 4ed738bc07..89d1e699ec 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 @@ -55,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 df08262aa8..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({ @@ -280,7 +282,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'); @@ -321,3 +323,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 2d78488f56..0f52bddf54 100644 --- a/packages/provider-limrun/src/app-log-reconnect.ts +++ b/packages/provider-limrun/src/app-log-reconnect.ts @@ -1,11 +1,12 @@ 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, 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, @@ -30,14 +31,9 @@ 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 }); - } catch (error) { - if (error instanceof NotFoundError) return { status: 'missing' }; - throw error; - } + return options.descriptor.platform === 'ios' + ? await reconnectIos({ ...options, limrun }) + : await reconnectAndroid({ ...options, limrun }); } async function reconnectAttached( @@ -90,11 +86,7 @@ async function openIosReader( descriptor: LimrunAppLogDescriptor, dependencies: LimrunRuntimeDependencies, ): Promise { - const client = await createIosInstanceClient({ - apiUrl: access.apiUrl, - token: access.token, - logLevel: 'warn', - }); + const client = await connectLimrunInstanceClient(createIosInstanceClient, access); const logs = dependencies.ios.createAppLogReader({ ...access, client }); const reader: LimrunAppLogReader = { platform: 'ios', @@ -147,12 +139,7 @@ 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 = await connectLimrunInstanceClient(createAndroidInstanceClient, access); const rollback = new AsyncCleanupStack(); let adopted = false; rollback.defer(async () => { @@ -168,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, ); @@ -178,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]), { @@ -218,7 +207,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 d1e7149ce9..9304886493 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,94 @@ 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; + } +}); + +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 7f0997f335..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 } 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'; @@ -20,6 +26,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 +69,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 +104,67 @@ 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'>; + +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) { + 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/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..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 { @@ -59,12 +64,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'; @@ -93,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 ( @@ -120,17 +123,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', diff --git a/packages/provider-limrun/src/connection.test.ts b/packages/provider-limrun/src/connection.test.ts index d64ced10cf..66a55f9294 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'; @@ -231,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/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/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/src/core/limrun-download-file.test.ts b/packages/provider-limrun/src/download-file.test.ts similarity index 73% rename from src/core/limrun-download-file.test.ts rename to packages/provider-limrun/src/download-file.test.ts index 324128028c..a4c7b7d503 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[] = []; @@ -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,23 +84,74 @@ 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 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`); + }); + 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).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); @@ -132,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 new file mode 100644 index 0000000000..4fb0e63da5 --- /dev/null +++ b/packages/provider-limrun/src/download-file.ts @@ -0,0 +1,122 @@ +import fs from 'node:fs'; +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, + type ReasonTable, +} from '@agent-device/kernel/errors'; +import type { LimrunFileDownload } from './runtime-dependencies.ts'; + +/** 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); + const signal = options.signal ? AbortSignal.any([timeout, options.signal]) : timeout; + try { + await fs.promises.mkdir(path.dirname(options.destinationPath), { recursive: true }); + const response = await fetch(options.url, { + method: 'GET', + headers: options.headers, + signal, + }); + if (!response.ok) throw httpFailure(response); + if (!response.body) { + throw new AppError('COMMAND_FAILED', 'Limrun download returned no body', { + reason: LIMRUN_DOWNLOAD_REASONS.emptyBody.reason, + destination: path.basename(options.destinationPath), + }); + } + await pipeline( + Readable.fromWeb(response.body as WebReadableStream), + fs.createWriteStream(options.destinationPath), + { signal }, + ); + } catch (error) { + await fs.promises.rm(options.destinationPath, { force: true }).catch(() => {}); + throw downloadFailure(error, options, timeout, signal); + } +} + +/** + * 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}`, { + statusCode: response.status, + reason: LIMRUN_DOWNLOAD_REASONS.httpError.reason, + }); +} + +/** + * 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, + timeout: AbortSignal, + signal: AbortSignal, +): unknown { + if (error instanceof AppError) return error; + if (options.signal?.aborted && signal.reason === options.signal.reason) { + const reason: unknown = options.signal.reason; + if (reason instanceof AppError) return reason; + if (!(reason instanceof Error && reason.name === 'TimeoutError')) { + return createRequestCanceledError(undefined, 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', { + reason: LIMRUN_DOWNLOAD_REASONS.timeout.reason, + timeoutMs: options.timeoutMs, + }); + } + return new AppError('COMMAND_FAILED', 'Limrun download failed', { + 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 new file mode 100644 index 0000000000..09be0eede5 --- /dev/null +++ b/packages/provider-limrun/src/error-text.test.ts @@ -0,0 +1,165 @@ +import { describe, expect, test } from 'vitest'; +import { + createInstanceStreamScrubber, + safeInstanceErrorText, + safeTerminationReason, +} 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', + ); + }); + + // 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), +); + +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 new file mode 100644 index 0000000000..2124a5ac2f --- /dev/null +++ b/packages/provider-limrun/src/error-text.ts @@ -0,0 +1,132 @@ +/** + * 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 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) { + const trimmed = value?.trim(); + if (!trimmed) continue; + secrets.add(trimmed); + const [, scheme, credential] = /^(\S+)\s+([\s\S]+)$/.exec(trimmed) ?? []; + if (scheme && credential && CREDENTIAL_SCHEMES.has(scheme.toLowerCase())) { + secrets.add(credential); + } + } + // 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; + }, + }; +} + +/** + * 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 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, sentValues).replaceAll(/\s+/g, ' '); + if (oneLine.length <= MAX_PUBLISHED_REASON_LENGTH) return oneLine; + return `${withoutTrailingPartialMarker(oneLine.slice(0, MAX_PUBLISHED_REASON_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/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/instance-error-scrubbing.test.ts b/packages/provider-limrun/src/instance-error-scrubbing.test.ts new file mode 100644 index 0000000000..3cd526aaea --- /dev/null +++ b/packages/provider-limrun/src/instance-error-scrubbing.test.ts @@ -0,0 +1,179 @@ +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); + }); +}); + +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 new file mode 100644 index 0000000000..bc9e99b1a3 --- /dev/null +++ b/packages/provider-limrun/src/instance-error-scrubbing.ts @@ -0,0 +1,157 @@ +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 scrubInstanceCommandFailure(error, secrets); + } +} + +/** 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, 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 + * 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'); + 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); + 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); + }); + }; + }, + }); +} + +/** + * 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. + */ +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); + 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 = 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. */ +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) => scrubInstanceDiagnostic(entry, secrets)); + return entries.every((entry, index) => entry === value[index]) ? value : entries; + } + 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) + .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/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/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/src/core/interactors/limrun-ios-app-logs.ts b/packages/provider-limrun/src/ios-app-logs.ts similarity index 88% rename from src/core/interactors/limrun-ios-app-logs.ts rename to packages/provider-limrun/src/ios-app-logs.ts index b12c98ff29..c306a67ae3 100644 --- a/src/core/interactors/limrun-ios-app-logs.ts +++ b/packages/provider-limrun/src/ios-app-logs.ts @@ -1,13 +1,16 @@ 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'; +import { safeInstanceErrorText } from './error-text.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; @@ -16,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 = () => { @@ -65,8 +70,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/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/src/core/interactors/limrun-ios-files.ts b/packages/provider-limrun/src/ios-files.ts similarity index 83% rename from src/core/interactors/limrun-ios-files.ts rename to packages/provider-limrun/src/ios-files.ts index 9ad197b71d..6601f06ff8 100644 --- a/src/core/interactors/limrun-ios-files.ts +++ b/packages/provider-limrun/src/ios-files.ts @@ -2,20 +2,44 @@ 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 { AppError, createRequestCanceledError } from '@agent-device/kernel/errors'; -import { downloadLimrunFile } from '../limrun-download-file.ts'; +import type { LimrunRuntimeDependencies } from './runtime-dependencies.ts'; +import { + AppError, + createRequestCanceledError, + type ReasonTable, +} from '@agent-device/kernel/errors'; +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]; +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, lifetime: AbortSignal, requestSignal?: AbortSignal, ): { simulatorFiles: Files; readInfoPlist: AppleToolProvider['simulatorApps']['readInfoPlist'] } { @@ -95,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 { @@ -141,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; @@ -161,6 +188,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 +201,7 @@ export function createLimrunSimulatorFiles( export async function readLimrunAppInfo( access: { apiUrl: string; token: string }, + parsePlist: ParsePlist, bundleId: string, signal: AbortSignal, timeoutMs = 15_000, @@ -193,8 +222,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 72% rename from src/core/interactors/limrun-ios-runner-errors.test.ts rename to packages/provider-limrun/src/ios-runner-errors.test.ts index 2abb40857f..12e672831d 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', @@ -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 new file mode 100644 index 0000000000..cf8f964ae8 --- /dev/null +++ b/packages/provider-limrun/src/ios-runner-errors.ts @@ -0,0 +1,96 @@ +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: + 'Another XCTest run owns this simulator. Stop its agent-device or Appium session, wait for its run stream to close, then retry. If the previous client died and the slot stays occupied, recreate the Limrun instance.', + limrun_runner_launch_failed: + 'Inspect runner.log and the Limrun XCTest stream. Use a simulator runner built for this instance’s Xcode and iOS runtime.', + limrun_runner_products_invalid: + 'Set AGENT_DEVICE_LIMRUN_IOS_RUNNER_APP to the simulator runner .app built for this instance’s Xcode and iOS runtime, or use a matching release runner.', + limrun_runner_upload_failed: + 'Check the Limrun instance connection and retry preparing the runner.', + limrun_runner_bind_address_missing: + 'The simulator must expose USE_IP for HTTP forwarding. Check the instance connection and simulator configuration.', +} as const; + +export function limrunRunnerError( + reason: keyof typeof hints, + message: string, + details: AppErrorDetails = {}, + code: AppErrorCode = 'COMMAND_FAILED', +): AppError { + return new AppError(code, message, { ...details, reason, hint: details.hint ?? hints[reason] }); +} + +/** + * 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; + 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/src/core/interactors/limrun-ios-runner-products.test.ts b/packages/provider-limrun/src/ios-runner-products.test.ts similarity index 64% rename from src/core/interactors/limrun-ios-runner-products.test.ts rename to packages/provider-limrun/src/ios-runner-products.test.ts index 2ea6fa925c..116b9e5e58 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', @@ -194,3 +208,78 @@ 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())); + } +}); + +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/src/core/interactors/limrun-ios-runner-products.ts b/packages/provider-limrun/src/ios-runner-products.ts similarity index 85% rename from src/core/interactors/limrun-ios-runner-products.ts rename to packages/provider-limrun/src/ios-runner-products.ts index e7394a8f21..2ba129dc56 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 @@ -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 ?? []; + 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: needFull.filter((name) => knownProductPaths.has(name)), }, ); } @@ -268,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..f53b3f3137 --- /dev/null +++ b/packages/provider-limrun/src/ios-runner.test.ts @@ -0,0 +1,39 @@ +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 text and structured diagnostics', 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 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]' }, + }); +}); diff --git a/src/core/interactors/limrun-ios-runner.ts b/packages/provider-limrun/src/ios-runner.ts similarity index 75% rename from src/core/interactors/limrun-ios-runner.ts rename to packages/provider-limrun/src/ios-runner.ts index e1778f3add..f4597f489a 100644 --- a/src/core/interactors/limrun-ios-runner.ts +++ b/packages/provider-limrun/src/ios-runner.ts @@ -1,24 +1,23 @@ -import { limrunRunnerError, withLimrunRunnerErrors } from './limrun-ios-runner-errors.ts'; +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 { 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 +25,20 @@ 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), + // 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({ ...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 +50,24 @@ 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 token = apple.runner.mintToken(); + const credentials = [headers.Authorization, token]; + const endpoint = { + port, + token, + http: { + url: commandUrl, + headers, + diagnostics: { + scrubText: (text: string) => safeInstanceErrorText(text, credentials), + scrubPayload: (payload: unknown) => scrubInstanceDiagnostic(payload, credentials), + }, + }, + }; + 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 +79,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 +152,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', ]); @@ -181,12 +181,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; @@ -233,15 +240,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; @@ -283,7 +297,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 +308,7 @@ export async function createLimrunIosRunner( releaseSpeculative, }, hostTools, + emitDiagnostic, ); return { applicationTools, @@ -312,14 +327,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/ios.ts b/packages/provider-limrun/src/ios.ts index ffbc838bfe..20b5bca590 100644 --- a/packages/provider-limrun/src/ios.ts +++ b/packages/provider-limrun/src/ios.ts @@ -62,10 +62,12 @@ export async function createLimrunIosSession( }, dependencies: Pick, ): Promise { - const client = await createIosInstanceClient({ + // The wrapper is loaded here, not imported: the runtime façade keeps its merge-base eager closure + // (ADR-0027). + const { connectLimrunInstanceClient } = await import('./instance-error-scrubbing.ts'); + const client = await connectLimrunInstanceClient(createIosInstanceClient, { apiUrl: options.apiUrl, token: options.token, - logLevel: 'warn', }); try { const runner = await dependencies.ios.createRunner({ ...options, client }); @@ -185,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/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/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 e7c5931318..b15aaa8bb7 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; @@ -151,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` @@ -161,12 +164,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 +191,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-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 63d2fe8db2..a923066020 100644 --- a/packages/provider-limrun/src/runtime.ts +++ b/packages/provider-limrun/src/runtime.ts @@ -44,6 +44,7 @@ import type { LimrunAppLogReader } from './app-log-runtime.ts'; import { deleteLimrunInstance, LIMRUN_CLIENT_ID, + LIMRUN_ORG_CLIENT_LOGGING, limrunUserAgent, requireLimrunOrgClient, } from './client-options.ts'; @@ -188,6 +189,7 @@ class LimrunRuntimeImplementation implements ProviderDeviceRuntime { ? new Limrun({ apiKey: options.apiKey, userAgent: limrunUserAgent(dependencies.clientVersion), + ...LIMRUN_ORG_CLIENT_LOGGING, }) : undefined; } @@ -778,6 +780,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, @@ -952,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(); @@ -969,8 +973,18 @@ 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, + session.token, + ]); } catch { return undefined; } } + +export type { LimrunRuntimeDependencies } from './runtime-dependencies.ts'; 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/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/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/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', 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..cf3e2ccf9d 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'); @@ -52,6 +58,71 @@ test('Limrun apps lists uploaded assets without allocating an instance', async ( 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 }); +}); + test('Limrun state keeps explicit connection identity and excludes profile secrets', 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..4f3f48ed12 100644 --- a/src/__tests__/cloud-connect-profile-fields.test.ts +++ b/src/__tests__/cloud-connect-profile-fields.test.ts @@ -1,7 +1,16 @@ -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'; +import { mkdtempForTestSync } from '@agent-device/test-kit'; 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 +69,33 @@ 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 stateDir = path.join( + mkdtempForTestSync('agent-device-connect-limrun-device-type-'), + 'state', + ); + const result = await runCliCapture( + [ + 'connect', + 'limrun', + '--session', + 'ci', + '--platform', + 'ios', + '--provider-device-type', + 'real', + '--state-dir', + stateDir, + '--json', + ], + { 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'); + 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..61110a984d 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(); @@ -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 ); }, ); @@ -728,7 +731,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; @@ -741,10 +744,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')); @@ -768,7 +771,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 +801,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 +841,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 +860,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 +870,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 +894,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/cli-json-outputs.ts b/src/__tests__/test-utils/cli-json-outputs.ts new file mode 100644 index 0000000000..e4cba7e89d --- /dev/null +++ b/src/__tests__/test-utils/cli-json-outputs.ts @@ -0,0 +1,17 @@ +/** + * 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; +} 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.ts b/src/cli.ts index c5e54c426f..60f01c5569 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -166,6 +166,10 @@ 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. + const { admitConnectProviderOrExit } = await import('./cli/connect-preflight.ts'); + await admitConnectProviderOrExit(argv, host, { jsonRequested, debugEnabled }); const { parsed, command, positionals } = await parseCliInputOrExit(argv, { host, version, @@ -312,23 +316,8 @@ 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); + const { exitBeforeCommand } = await import('./cli/pre-command-failure.ts'); + return await exitBeforeCommand(error, argv, options, 'cli_parse_failed'); } type CliRunContext = { @@ -344,6 +333,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 +408,7 @@ async function resolveRunContextOrExit( daemonPaths, sessionName, connectionDefaults, + remoteConfigLeaseProvider: parsed.remoteConfigLeaseProvider, explicitFlagKeys, effectiveFlags, resolvedRuntime: connectionDefaults?.runtime, @@ -462,6 +454,17 @@ async function resolveRemoteContext( ctx.parsedBatchSteps = readBatchSteps(ctx.flags); } + // 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, + }); + } + if (shouldResolveRemoteAuth(ctx.command)) { const authResolution = await resolveRemoteAuthForCli({ command: ctx.command, 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/connection-runtime.ts b/src/cli/commands/connection-runtime.ts index 4285f74e2c..3c2d111828 100644 --- a/src/cli/commands/connection-runtime.ts +++ b/src/cli/commands/connection-runtime.ts @@ -17,8 +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, connectionProviderCapabilities, - primeProviderConnection, + providerRouteForConnection, } from '../connection/provider-policy.ts'; import { profileToCliFlags } from '../remote-config-flags.ts'; import { @@ -85,7 +87,18 @@ export async function materializeRemoteConnectionForCommand(options: { ); } - await primeProviderConnection(providerOf(existingState, remoteConfig.profile), 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); + await admitProviderForRoute( + provider, + providerRouteForConnection({ + daemonBaseUrl: mergedFlags.daemonBaseUrl, + env: host.env, + }), + host.env, + ); const state = existingState ?? createRemoteConnectionStateFromFlags( @@ -183,14 +196,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/commands/connection.ts b/src/cli/commands/connection.ts index a17cc42c66..7920257d1c 100644 --- a/src/cli/commands/connection.ts +++ b/src/cli/commands/connection.ts @@ -20,6 +20,7 @@ import { import { AppError, errorMessage } from '@agent-device/kernel/errors'; import { isInactiveLeaseError } from '@agent-device/contracts/lease-scope'; import { + admitProviderForRoute, connectProviderNamesForError, connectionProviderCapabilities, isConnectProviderName, @@ -409,7 +410,10 @@ export const connectionCommand: ClientCommandHandler = async ({ positionals, fla await writeNoRemoteConnectionOutput(flags, session); return true; } - await primeProviderConnection(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/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/connect-preflight.ts b/src/cli/connect-preflight.ts new file mode 100644 index 0000000000..6e8fdaac68 --- /dev/null +++ b/src/cli/connect-preflight.ts @@ -0,0 +1,17 @@ +import type { HostEnvironment } from '@agent-device/kernel/source-value'; +import { exitBeforeCommand } from './pre-command-failure.ts'; + +/** 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 import('./connection/provider-admission.ts'); + try { + await admitConnectProviderNamedInArguments(argv, host); + } catch (error) { + await exitBeforeCommand(error, [...argv], options, 'cli_plugin_refused'); + } +} diff --git a/src/cli/connection/cloud-profile.ts b/src/cli/connection/cloud-profile.ts index fe58324e96..d134b5302b 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, requiresOwnProviderAdmission } from './provider-policy.ts'; const CONNECTION_PROFILE_PATH = '/api/control-plane/connection-profile'; const HTTP_TIMEOUT_MS = 15_000; @@ -40,6 +41,10 @@ export async function resolveCloudConnectProfile(options: { accessToken: auth.accessToken, 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 no + // connection state behind. + await admitDiscoveredProvider(profile.leaseProvider, options.env); const clientId = buildConnectClientId( options.stateDir, auth.cloudBaseUrl, @@ -64,6 +69,19 @@ 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. + */ +async function admitDiscoveredProvider( + provider: string | undefined, + env: NodeJS.ProcessEnv, +): Promise { + if (requiresOwnProviderAdmission(provider)) await primeProviderConnection(provider, env); +} + 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 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-unprimed-store.test.ts b/src/cli/connection/ended-lease-unprimed-store.test.ts new file mode 100644 index 0000000000..90e6caf73f --- /dev/null +++ b/src/cli/connection/ended-lease-unprimed-store.test.ts @@ -0,0 +1,103 @@ +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. +function storedConnection(leaseProvider = 'limrun') { + 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, + platform: 'android', + connectedAt: now, + updatedAt: now, + }, + }); + return { root, home, project, stateDir }; +} + +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'], + { + 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 }); +}); + +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 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); + 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 } = storedConnection(); + 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.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/ended-lease.ts b/src/cli/connection/ended-lease.ts index 87455b4f14..d3a3e3a58b 100644 --- a/src/cli/connection/ended-lease.ts +++ b/src/cli/connection/ended-lease.ts @@ -7,7 +7,7 @@ import { readRemoteConnectionState, writeRemoteConnectionState, } from '@agent-device/remote/remote-connection-state'; -import { connectionProviderCapabilities } from './provider-policy.ts'; +import { providerForgetsEndedConnectionLease } from './provider-policy.ts'; import { isHostAllocatedLease } from '../commands/connection-lease-transaction.ts'; /** @@ -29,8 +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; - if (!connectionProviderCapabilities(state.leaseProvider, host.env).forgetsEndedConnectionLease) - 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-admission-credential-order.test.ts b/src/cli/connection/provider-admission-credential-order.test.ts new file mode 100644 index 0000000000..caae6c1d32 --- /dev/null +++ b/src/cli/connection/provider-admission-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.test.ts b/src/cli/connection/provider-admission.test.ts new file mode 100644 index 0000000000..8034deb3ca --- /dev/null +++ b/src/cli/connection/provider-admission.test.ts @@ -0,0 +1,414 @@ +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, + 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 }; +} + +// 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 }); +}); + +// 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 () => { + 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( + ['snapshot', '--session', 'limrun-local', '--state-dir', stateDir, '--json'], + { cwd: project, env: { HOME: home } }, + ); + + 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); + 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..eda82881ce --- /dev/null +++ b/src/cli/connection/provider-admission.ts @@ -0,0 +1,95 @@ +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 { readRemoteConfigFile } from '@agent-device/remote/remote-config-core'; +import { parseRawArgs } from '../parser/args.ts'; +import { + admitProviderForRoute, + connectionLeaseProvider, + primeProviderConnection, + providerRouteForConnection, + requiresOwnProviderAdmission, +} from './provider-policy.ts'; + +type AdmissionContext = Readonly<{ + host: HostEnvironment; + command: 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; + /** The daemon this command dispatches to, once the stored connection and profile are merged. */ + daemonBaseUrl: string | undefined; +}>; + +/** + * 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. + * 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; + const provider = connectionLeaseProvider( + context.connectionDefaults?.connection, + context.remoteConfigLeaseProvider, + ); + if (!requiresOwnProviderAdmission(provider)) return; + await admitProviderForRoute( + provider, + providerRouteForConnection({ daemonBaseUrl: context.daemonBaseUrl, env: context.host.env }), + 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); +} + +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-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..9c4963b6ab 100644 --- a/src/cli/connection/provider-policy.test.ts +++ b/src/cli/connection/provider-policy.test.ts @@ -10,11 +10,29 @@ 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 { 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', () => { - 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() {} },`, + }), + ); + // 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', requiresAppAttachment: false, requiresRemoteDaemon: false, @@ -25,7 +43,8 @@ test('provider policy projects provider identity into semantic capabilities', () 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', @@ -121,3 +140,60 @@ test('a plugin that fails to load supplies no connection name even after priming ['dup', 'duplicate_provider'], ]); }); + +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) { + 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 9e2aeb4028..cb27a32312 100644 --- a/src/cli/connection/provider-policy.ts +++ b/src/cli/connection/provider-policy.ts @@ -6,21 +6,35 @@ 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, + providerPluginAdmission, + providerPluginConnectionCapabilities, 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; +/** + * 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 { @@ -37,15 +51,28 @@ 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. + * 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. 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, 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 +84,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}`, @@ -73,6 +100,55 @@ export function connectProviderNamesForError(env: NodeJS.ProcessEnv = process.en : `${names}. Plugins that failed to load: ${failures.join('; ')}`; } +/** + * 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 providerPluginAdmission(provider) === 'provider'; +} + +/** + * 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 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( provider: string, env: NodeJS.ProcessEnv, @@ -88,7 +164,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 } : {}), @@ -107,16 +183,39 @@ export function unavailableConnectPluginError( ); } -/** Bundled and installed providers declare their capabilities; the rest is the daemon's own routing. */ +/** + * 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. + */ +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) ?? providerPluginConnectionCapabilities(provider) + ); +} + +/** + * 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); + return declared?.forgetsEndedConnectionLease === true; +} + +/** 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' - ? undefined - : pluginConnectionCapabilities(provider, env)); - return declared ?? remoteDaemonConnection('remote-provider'); + return declaredConnectionCapabilities(provider, env) ?? remoteDaemonConnection('remote-provider'); } 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); +} 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 725ee80e12..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,10 +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 `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. + */ + admission?: ProviderAdmissionPolicy; }>; export const AWS_DEVICE_FARM: ProviderPluginDeclaration = { @@ -26,9 +45,29 @@ export const BROWSERSTACK: ProviderPluginDeclaration = { nightlyTag: 'nightly-0.22', }; +export const LIMRUN: ProviderPluginDeclaration = { + provider: 'limrun', + package: '@agent-device/limrun', + label: 'Limrun', + nightlyTag: 'nightly-0.22', + 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[] = [ 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' }, @@ -46,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(), 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..4286b8e673 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,10 +485,10 @@ 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. +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: @@ -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/core/interactors/limrun-ios-runner-errors.ts b/src/core/interactors/limrun-ios-runner-errors.ts deleted file mode 100644 index 11b1b0272d..0000000000 --- a/src/core/interactors/limrun-ios-runner-errors.ts +++ /dev/null @@ -1,65 +0,0 @@ -import { AppError, type AppErrorCode, type AppErrorDetails } from '@agent-device/kernel/errors'; - -const hints = { - limrun_xctest_slot_occupied: - 'Another XCTest run owns this simulator. Stop its agent-device or Appium session, wait for its run stream to close, then retry. If the previous client died and the slot stays occupied, recreate the Limrun instance.', - limrun_runner_launch_failed: - 'Inspect runner.log and the Limrun XCTest stream. Use a simulator runner built for this instance’s Xcode and iOS runtime.', - limrun_runner_products_invalid: - 'Set AGENT_DEVICE_LIMRUN_IOS_RUNNER_APP to the simulator runner .app built for this instance’s Xcode and iOS runtime, or use a matching release runner.', - limrun_runner_upload_failed: - 'Check the Limrun instance connection and retry preparing the runner.', - limrun_runner_bind_address_missing: - 'The simulator must expose USE_IP for HTTP forwarding. Check the instance connection and simulator configuration.', -} as const; - -export function limrunRunnerError( - reason: keyof typeof hints, - message: string, - details: AppErrorDetails = {}, - code: AppErrorCode = 'COMMAND_FAILED', -): AppError { - 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 { - 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; - } -} diff --git a/src/core/limrun-download-file.ts b/src/core/limrun-download-file.ts deleted file mode 100644 index 52f5e5b59f..0000000000 --- a/src/core/limrun-download-file.ts +++ /dev/null @@ -1,108 +0,0 @@ -import fs from 'node:fs'; -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 type { LimrunFileDownload } from '@agent-device/provider-limrun'; - -const RESPONSE_BODY_PREVIEW_BYTES = 500; - -/** - * 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. - */ -export async function downloadLimrunFile(options: LimrunFileDownload): Promise { - const timeout = AbortSignal.timeout(options.timeoutMs); - const signal = options.signal ? AbortSignal.any([timeout, options.signal]) : timeout; - try { - await fs.promises.mkdir(path.dirname(options.destinationPath), { recursive: true }); - const response = await fetch(options.url, { - method: 'GET', - headers: options.headers, - signal, - }); - if (!response.ok) throw await httpFailure(response, options); - if (!response.body) { - throw new AppError('COMMAND_FAILED', 'Limrun download returned no body', { - url: options.url, - }); - } - await pipeline( - Readable.fromWeb(response.body as WebReadableStream), - fs.createWriteStream(options.destinationPath), - { signal }, - ); - } catch (error) { - await fs.promises.rm(options.destinationPath, { force: true }).catch(() => {}); - throw downloadFailure(error, options, timeout, signal); - } -} - -async function httpFailure(response: Response, options: LimrunFileDownload): Promise { - return new AppError('COMMAND_FAILED', `Limrun download failed with HTTP ${response.status}`, { - url: options.url, - statusCode: response.status, - reason: 'limrun_download_http_error', - body: await readBodyPreview(response), - }); -} - -/** 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'); -} - -function downloadFailure( - error: unknown, - options: LimrunFileDownload, - timeout: AbortSignal, - signal: AbortSignal, -): unknown { - if (error instanceof AppError) return error; - if (options.signal?.aborted && signal.reason === options.signal.reason) { - const reason: unknown = options.signal.reason; - if (reason instanceof AppError) return reason; - 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, - ); - } - if (timeout.aborted) { - return new AppError('COMMAND_FAILED', 'Limrun download timed out', { - url: options.url, - 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), - }); -} 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 97% rename from src/core/interactors/limrun-ios-runner.test.ts rename to src/provider-plugin-host-capabilities-limrun-ios-runner.test.ts index da34e8238b..0540b1d917 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({ @@ -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/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 93% rename from src/core/interactors/limrun-ios-runner.fixtures.ts rename to src/provider-plugin-host-capabilities-limrun-ios.fixtures.ts index 0c235972e9..8ae3d2ca18 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; @@ -54,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 }); @@ -203,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; } @@ -251,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', @@ -306,11 +313,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/error-reasons.md b/website/docs/docs/error-reasons.md index 48eed42345..e0aad7780f 100644 --- a/website/docs/docs/error-reasons.md +++ b/website/docs/docs/error-reasons.md @@ -203,6 +203,22 @@ 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_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 | Reason | Meaning | 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..5f3174eac4 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,12 +15,16 @@ 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 `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`. @@ -47,7 +51,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 +140,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 diff --git a/website/src/site/content.ts b/website/src/site/content.ts index 603e019f35..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 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 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 }[],