refactor: generalize deferred provider app selection

Author: thymikee

packages/contracts/src/application-lifecycle-interaction.test.ts

@@ -91,7 +91,7 @@ test('direct lifecycle owners preserve the daemon runtime launch URL follow-up',
   expect(calls[1]?.options).toHaveProperty('launchArgs', undefined);
 });
 
-test('direct lifecycle owners resolve app aliases once before target dispatch', async () => {
+test('direct lifecycle owners resolve provider app references before target dispatch', async () => {
   const open = vi.fn(async () => undefined);
   const binding = bindLocalApplicationLifecycleInteractor({
     device: WEB_DEVICE,
@@ -102,7 +102,7 @@ test('direct lifecycle owners resolve app aliases once before target dispatch',
     binding,
     owner: 'Provider',
     openTargetIdentity: 'bundle-id',
-    resolveAppAlias: (app) => (app === 'Example.app.zip' ? 'com.example.app' : app),
+    resolveAppReference: (app) => (app === 'Example.app.zip' ? 'com.example.app' : app),
   });
 
   await expect(

packages/contracts/src/application-lifecycle-interaction.ts

@@ -262,7 +262,7 @@ export type DirectApplicationLifecycleParams = Readonly<{
   openTargetIdentity: DirectOpenTargetIdentity;
   /** Owners whose native open does not replace a running application close it first. */
   closeBeforeRelaunch?: boolean;
-  resolveAppAlias?(app: string): string;
+  resolveAppReference?(app: string): string;
   /** Port reverse is the one non-direct operation a provider owner may still implement. */
   configureProviderPortReverse?: ApplicationLifecycleRuntimeOperations['configureProviderPortReverse'];
 }>;
@@ -284,7 +284,7 @@ export function bindDirectApplicationLifecycle(
   };
   return Object.freeze({
     resolveOpenTarget: async (input) =>
-      resolveDirectOpenTarget(params.openTargetIdentity, resolveOpenTargetAlias(params, input)),
+      resolveDirectOpenTarget(params.openTargetIdentity, resolveOpenTargetReference(params, input)),
     prepareApplicationOpen: async () => undefined,
     openApplication: async (input) => await openDirectApplication(params, input),
     applyRuntimeHints: unavailable,
@@ -306,7 +306,7 @@ async function openDirectApplication(
   params: DirectApplicationLifecycleParams,
   input: OpenApplicationInput,
 ): Promise<OpenApplicationOutcome> {
-  const resolvedInput = resolveOpenApplicationAliases(params, input);
+  const resolvedInput = resolveOpenApplicationReferences(params, input);
   const { binding } = params;
   const interactor = await binding.resolveInteractor(
     resolvedInput.execution,
@@ -344,19 +344,19 @@ async function openDirectApplication(
   return { appBundleId: resolvedInput.appBundleId, timing: {} };
 }
 
-function resolveOpenTargetAlias(
+function resolveOpenTargetReference(
   params: DirectApplicationLifecycleParams,
   input: OpenTargetResolutionInput,
 ): OpenTargetResolutionInput {
-  if (!input.target || !params.resolveAppAlias) return input;
-  return { ...input, target: params.resolveAppAlias(input.target) };
+  if (!input.target || !params.resolveAppReference) return input;
+  return { ...input, target: params.resolveAppReference(input.target) };
 }
 
-function resolveOpenApplicationAliases(
+function resolveOpenApplicationReferences(
   params: DirectApplicationLifecycleParams,
   input: OpenApplicationInput,
 ): OpenApplicationInput {
-  const resolve = params.resolveAppAlias;
+  const resolve = params.resolveAppReference;
   if (!resolve) return input;
   return {
     ...input,

packages/provider-limrun/src/app-log-runtime.ts

@@ -59,7 +59,7 @@ export type LimrunPlatformRuntimeOwnerOptions = Omit<
     runtimeInstance: string;
     ownsDevice(device: DeviceInfo): boolean;
     getInteractor(device: DeviceInfo, runner?: RunnerContext): Interactor | undefined;
-    resolveAppAlias?(device: DeviceInfo, app: string): string;
+    resolveAppReference?(device: DeviceInfo, app: string): string;
     openCurrent(device: DeviceInfo): Promise<LimrunAppLogReader | undefined>;
     hasLiveSession(device: DeviceInfo): boolean;
     reconnect(
@@ -281,7 +281,7 @@ function bindLimrunAppLogs(
         device,
         signal,
         getInteractor: options.getInteractor,
-        resolveAppAlias: (app) => options.resolveAppAlias?.(device, app) ?? app,
+        resolveAppReference: (app) => options.resolveAppReference?.(device, app) ?? app,
         configurePortReverse: options.configurePortReverse,
       }),
       runtimeFacts.operations,

packages/provider-limrun/src/lifecycle.ts

@@ -14,7 +14,7 @@ type LimrunLifecycleParams = Readonly<{
   configurePortReverse(
     options: ProviderPortReverseOptions,
   ): Promise<Record<string, unknown> | undefined>;
-  resolveAppAlias?(app: string): string;
+  resolveAppReference?(app: string): string;
 }>;
 
 /** Limrun owns its live-session lifecycle, relaunch, and exact port-reverse mechanics. */
@@ -25,7 +25,7 @@ export function bindLimrunApplicationLifecycle(
     owner: 'Limrun',
     openTargetIdentity: 'bundle-id',
     closeBeforeRelaunch: true,
-    resolveAppAlias: params.resolveAppAlias,
+    resolveAppReference: params.resolveAppReference,
     configureProviderPortReverse: async (input) => await params.configurePortReverse(input),
     binding: bindProviderApplicationLifecycleInteractor({
       device: params.device,

packages/provider-limrun/src/runtime.ts

@@ -331,7 +331,7 @@ class LimrunRuntimeImplementation implements ProviderDeviceRuntime {
     return session?.platform === parsed.platform ? session : undefined;
   }
 
-  resolveAppAlias(device: DeviceInfo, app: string): string {
+  resolveAppReference(device: DeviceInfo, app: string): string {
     const parsed = parseLimrunDeviceId(device.id);
     if (!parsed) return app;
     const alias = this.appAliases.get(parsed.leaseId);
@@ -386,7 +386,7 @@ async function loadLimrunPlatformRuntime(
     ownsDevice: (device) => runtime.ownsDevice(device),
     hasLiveSession: (device) => runtime.hasLiveSession(device),
     getInteractor: (device, runner) => runtime.getInteractor(device, runner),
-    resolveAppAlias: (device, app) => runtime.resolveAppAlias(device, app),
+    resolveAppReference: (device, app) => runtime.resolveAppReference(device, app),
     openCurrent: async (device) => runtime.currentAppLogReader(device),
     reconnect: async (descriptor, signal) =>
       await runtime.reconnectAppLogReader(descriptor, signal),

src/cli/commands/connection-runtime.ts

@@ -33,7 +33,10 @@ import type { AgentDeviceClient, Lease } from '../../agent-device-client.ts';
 import type { CloudProviderSessionResult } from '@agent-device/contracts/observability';
 import { INTERNAL_COMMANDS, PUBLIC_COMMANDS } from '../../command-catalog.ts';
 import { readMetroPrepareKind } from '../../commands/metro/prepare-kind.ts';
-import { connectionProviderRequiresRemoteDaemon } from '../connection/provider-policy.ts';
+import {
+  connectionProviderRequiresRemoteDaemon,
+  connectionProviderSupportsDeferredAppSelection,
+} from '../connection/provider-policy.ts';
 import { readCloudDeviceFeatureProfileFields } from '../connection/profile-fields.ts';
 import { isCloudWebDriverProviderName } from '@agent-device/provider-webdriver';
 import type { PreviousLeaseReleaseNotice } from './connection-presentation.ts';
@@ -112,7 +115,7 @@ export async function materializeRemoteConnectionForCommand(options: {
     );
   const nextFlags = { ...mergedFlags, session: state.session };
   if (
-    state.leaseProvider === 'limrun' &&
+    connectionProviderSupportsDeferredAppSelection(state.leaseProvider) &&
     command === PUBLIC_COMMANDS.open &&
     typeof options.positionals?.[0] === 'string'
   ) {
@@ -385,14 +388,16 @@ type ConnectionLeasePolicy = {
 
 function connectionLeasePolicyForState(state: RemoteConnectionState): ConnectionLeasePolicy {
   if (state.leaseProvider === 'proxy') return PROXY_CONNECTION_LEASE_POLICY;
-  if (state.leaseProvider === 'limrun') return LIMRUN_CONNECTION_LEASE_POLICY;
+  if (connectionProviderSupportsDeferredAppSelection(state.leaseProvider)) {
+    return DEFERRED_APP_SELECTION_CONNECTION_LEASE_POLICY;
+  }
   if (isCloudWebDriverProviderName(state.leaseProvider)) {
     return CLOUD_WEBDRIVER_CONNECTION_LEASE_POLICY;
   }
   return DEFAULT_CONNECTION_LEASE_POLICY;
 }
 
-const LIMRUN_CONNECTION_LEASE_POLICY: ConnectionLeasePolicy = {
+const DEFERRED_APP_SELECTION_CONNECTION_LEASE_POLICY: ConnectionLeasePolicy = {
   shouldAllocate: (command) =>
     command !== PUBLIC_COMMANDS.apps && !leaseDeferredCommands.has(command),
   ttlMs: () => undefined,

src/cli/connection/provider-policy.test.ts

@@ -0,0 +1,11 @@
+import assert from 'node:assert/strict';
+import { test } from 'vitest';
+import { connectionProviderSupportsDeferredAppSelection } from './provider-policy.ts';
+
+test('only providers declaring deferred app selection use app catalog before allocation', () => {
+  assert.equal(connectionProviderSupportsDeferredAppSelection('limrun'), true);
+  assert.equal(connectionProviderSupportsDeferredAppSelection('browserstack'), false);
+  assert.equal(connectionProviderSupportsDeferredAppSelection('aws-device-farm'), false);
+  assert.equal(connectionProviderSupportsDeferredAppSelection('proxy'), false);
+  assert.equal(connectionProviderSupportsDeferredAppSelection(undefined), false);
+});

src/cli/connection/provider-policy.ts

@@ -7,6 +7,8 @@ import {
 export type DirectDeviceConnectProvider = CloudWebDriverKnownProviderName | 'limrun';
 export type ConnectProvider = 'cloud' | 'proxy' | DirectDeviceConnectProvider;
 
+const DEFERRED_APP_SELECTION_PROVIDERS = new Set<DirectDeviceConnectProvider>(['limrun']);
+
 export function isConnectProviderName(value: string | undefined): value is ConnectProvider {
   return value === 'cloud' || value === 'proxy' || isDirectDeviceConnectProvider(value);
 }
@@ -31,6 +33,12 @@ export function connectionProviderRequiresRemoteDaemon(provider: string | undefi
   return !isDirectDeviceConnectProvider(provider);
 }
 
+export function connectionProviderSupportsDeferredAppSelection(
+  provider: string | undefined,
+): boolean {
+  return isDirectDeviceConnectProvider(provider) && DEFERRED_APP_SELECTION_PROVIDERS.has(provider);
+}
+
 export function connectionProviderLeaseKind(
   provider: string | undefined,
 ): 'proxy' | 'direct-device-provider' | 'remote-provider' {