feat(limrun): capture session traffic into a live HAR and report tunnel failures

packages/command-registry/src/flag-definitions-connection.ts

@@ -303,6 +303,26 @@ export const CONNECTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     projectConfig: false,
     recorded: false,
   },
+  {
+    key: 'providerNetworkLogs',
+    names: ['--provider-network-logs'],
+    type: 'boolean',
+    usageLabel: '--provider-network-logs',
+    usageDescription:
+      'Limrun: capture session network traffic into a live HAR file on the daemon host; artifacts and close print its path and any tunnel failures. Pass --provider-network-hosts with your app API hosts. Captured traffic exits through the daemon host, the HAR holds raw headers and bodies, certificate-pinned hosts fail, and DNS-over-HTTPS bypasses the capture',
+    projectConfig: false,
+    recorded: false,
+  },
+  {
+    key: 'providerNetworkHosts',
+    names: ['--provider-network-hosts'],
+    type: 'string',
+    usageLabel: '--provider-network-hosts <list>',
+    usageDescription:
+      'With --provider-network-logs: comma-separated hosts to capture, such as your app API hosts (exact hosts, wildcards like *.example.com, or localhost:<port> routes). Replaces the noisy default of common public domains plus localhost:8081',
+    projectConfig: false,
+    recorded: false,
+  },
   {
     key: 'awsProjectArn',
     names: ['--aws-project-arn'],

packages/command-registry/src/flag-groups.ts

@@ -98,6 +98,8 @@ export const COMMON_COMMAND_SUPPORTED_FLAG_KEYS = flagKeys(
   'providerNetworkProfile',
   'providerCustomNetwork',
   'providerNoResignApp',
+  'providerNetworkLogs',
+  'providerNetworkHosts',
   'awsProjectArn',
   'awsDeviceArn',
   'awsAppArn',

packages/contracts/src/client-connection.ts

@@ -167,6 +167,8 @@ export type AgentDeviceRequestOverrides = Pick<
   | 'providerNetworkProfile'
   | 'providerCustomNetwork'
   | 'providerNoResignApp'
+  | 'providerNetworkLogs'
+  | 'providerNetworkHosts'
   | 'awsProjectArn'
   | 'awsDeviceArn'
   | 'awsAppArn'

packages/contracts/src/cloud-artifacts.ts

@@ -6,6 +6,7 @@ const CLOUD_ARTIFACT_KINDS = [
   'appium-log',
   'device-log',
   'automation-log',
+  'network',
   'provider-session',
   'raw',
 ] as const;

packages/contracts/src/lease-scope.ts

@@ -255,6 +255,8 @@ const LEASE_ALLOCATE_PROVIDER_FLAG_KEYS = [
   'providerNetworkProfile',
   'providerCustomNetwork',
   'providerNoResignApp',
+  'providerNetworkLogs',
+  'providerNetworkHosts',
   'awsProjectArn',
   'awsDeviceArn',
   'awsAppArn',

packages/contracts/src/provider-profile-fields.test.ts

@@ -27,6 +27,8 @@ const DECLARATION: ProviderProfileFieldDeclaration = {
     providerNetworkProfile: 'consumed',
     providerCustomNetwork: 'consumed',
     providerNoResignApp: 'refused',
+    providerNetworkLogs: 'consumed',
+    providerNetworkHosts: 'consumed',
     awsProjectArn: 'consumed',
     awsDeviceArn: 'consumed',
     awsAppArn: 'consumed',

packages/contracts/src/remote-config-fields.ts

@@ -41,6 +41,13 @@ export type CloudProviderProfileFields = {
   providerNetworkProfile?: string;
   providerCustomNetwork?: string;
   providerNoResignApp?: boolean;
+  /**
+   * Asks a provider that supports it to capture session network traffic and deliver it as a HAR
+   * artifact. On Limrun the HAR is a live file the session writes while it runs.
+   */
+  providerNetworkLogs?: boolean;
+  /** With `providerNetworkLogs`: comma-separated tunnel selectors replacing the default capture list. */
+  providerNetworkHosts?: string;
   awsProjectArn?: string;
   awsDeviceArn?: string;
   awsAppArn?: string;
@@ -67,6 +74,8 @@ export const PROVIDER_PROFILE_FIELD_FLAGS: Readonly<
   providerNetworkProfile: '--provider-network-profile',
   providerCustomNetwork: '--provider-custom-network',
   providerNoResignApp: '--provider-no-resign-app',
+  providerNetworkLogs: '--provider-network-logs',
+  providerNetworkHosts: '--provider-network-hosts',
   awsProjectArn: '--aws-project-arn',
   awsDeviceArn: '--aws-device-arn',
   awsAppArn: '--aws-app-arn',

packages/daemon/src/sessions/handlers/session-doctor-options.test.ts

@@ -0,0 +1,29 @@
+import assert from 'node:assert/strict';
+import { test } from 'vitest';
+import type { DaemonRequest } from '../../core/daemon-request.ts';
+import { remoteConnectionChecks } from './session-doctor-options.ts';
+
+function doctorRequest(flags: Record<string, unknown>): DaemonRequest {
+  return {
+    token: 't',
+    session: 'default',
+    command: 'doctor',
+    positionals: [],
+    flags,
+  } as DaemonRequest;
+}
+
+test('an enabled opt-in provider flag counts as configured provider scope', () => {
+  const [check] = remoteConnectionChecks(doctorRequest({ providerNetworkLogs: true }), {
+    required: true,
+  });
+  assert.equal(check?.status, 'pass');
+  assert.deepEqual(check?.evidence, { providerNetworkLogs: '<configured>' });
+});
+
+test('a disabled opt-in provider flag is not provider scope', () => {
+  const [check] = remoteConnectionChecks(doctorRequest({ providerNetworkLogs: false }), {
+    required: true,
+  });
+  assert.equal(check?.status, 'fail');
+});

packages/daemon/src/sessions/handlers/session-doctor-options.ts

@@ -33,6 +33,8 @@ const REMOTE_PROVIDER_FLAG_KEYS = [
   'providerNetworkProfile',
   'providerCustomNetwork',
   'providerNoResignApp',
+  'providerNetworkLogs',
+  'providerNetworkHosts',
   'awsProjectArn',
   'awsDeviceArn',
   'awsAppArn',
@@ -153,8 +155,11 @@ function shouldProbeMetro(req: DaemonRequest, kind: DoctorKind): boolean {
 
 function remoteConnectionEvidence(req: DaemonRequest): Record<string, unknown> | undefined {
   const configured = Object.fromEntries(
+    // An opt-in boolean counts only when it is on.
     [...REMOTE_CONNECTION_FLAG_KEYS, ...REMOTE_PROVIDER_FLAG_KEYS].flatMap((key) =>
-      typeof req.flags?.[key] === 'string' ? [[key, '<configured>']] : [],
+      typeof req.flags?.[key] === 'string' || req.flags?.[key] === true
+        ? [[key, '<configured>']]
+        : [],
     ),
   );
   const evidence = {

packages/provider-limrun/src/device.ts

@@ -7,7 +7,10 @@ export type LimrunPlatform = 'ios' | 'android';
 
 export const LIMRUN_PROVIDER = 'limrun';
 
-/** Limrun reads only the app to preinstall; it picks the instance itself. */
+/**
+ * Limrun reads the app to preinstall and the network capture settings; it picks the instance
+ * itself.
+ */
 export const LIMRUN_PROFILE_FIELDS: ProviderProfileFieldDeclaration = {
   provider: LIMRUN_PROVIDER,
   label: 'Limrun',
@@ -27,6 +30,8 @@ export const LIMRUN_PROFILE_FIELDS: ProviderProfileFieldDeclaration = {
     providerNetworkProfile: 'refused',
     providerCustomNetwork: 'refused',
     providerNoResignApp: 'refused',
+    providerNetworkLogs: 'consumed',
+    providerNetworkHosts: 'consumed',
     awsProjectArn: 'refused',
     awsDeviceArn: 'refused',
     awsAppArn: 'refused',