feat: generalize perf sampling for Apple app sessions (#351)

* feat: generalize perf sampling for Apple app sessions

* fix: report physical ios perf as unsupported

* refactor: simplify Apple perf sampling flow

* docs: refresh debugging skill guidance

Author: thymikee

README.md

@@ -65,7 +65,8 @@ In non-JSON mode, core mutating commands print a short success acknowledgment so
 
 - Startup timing is available on iOS and Android from `open` command round-trip sampling.
 - Android app sessions also sample CPU (`adb shell dumpsys cpuinfo`) and memory (`adb shell dumpsys meminfo <package>`) when the session has an active app package context.
-- Android CPU data is a recent process snapshot and may read as `0` for idle apps; Android memory values are reported in kilobytes from `dumpsys meminfo`.
+- Apple app sessions on macOS and iOS simulators also sample CPU and memory from process snapshots resolved from the active app bundle ID.
+- Physical iOS devices still report CPU and memory as unavailable in this release.
 
 ## Where To Go Next
 

skills/agent-device/references/debugging.md

@@ -36,6 +36,7 @@ Logging is off by default. Enable it only when you need a debugging window.
 - Default app logs live under `~/.agent-device/sessions/<session>/app.log`.
 - `logs clear --restart` is the fastest clean repro loop.
 - `network dump [limit] [summary|headers|body|all]` parses recent HTTP(s) entries from the same session app log.
+- On macOS, `network dump` is app-scoped and only sees Unified Logging associated with the active session app.
 - On iOS simulators, `network dump` can recover recent app log history with `simctl log show` when the live session stream is sparse, so check the returned notes before assuming the repro window was empty.
 - On iOS, `network dump` is still limited to what Unified Logging exposes for the app process. If the app does not emit request metadata there, `network dump` can legitimately return no HTTP entries even during a real repro.
 - Summary output already shows timestamp, status, and duration when the log backend exposes them.
@@ -44,6 +45,7 @@ Logging is off by default. Enable it only when you need a debugging window.
 - `logs doctor` checks backend and runtime readiness for the current session and device.
 - `logs mark "before tap"` inserts a timestamped marker into the app log.
 - Android `network dump` surfaces timestamps from logcat-style prefixes and can backfill status and request/response duration from adjacent GIBSDK packet lines, so check it before dumping raw log windows.
+- Android app-log streaming rebinds to the current app PID after relaunches, so rerun the repro window before assuming the last log slice is stale.
 - Marker lines are emitted with the `[agent-device][mark][...]` prefix. When you grep later, prefer a narrow pattern such as `grep -n -E "agent-device.*mark|before tap" <path>`.
 - Session app logs can contain runtime data, headers, or payload fragments. Review them before sharing.
 - `logs start` requires an active app session and appends to `app.log`.
@@ -78,16 +80,16 @@ If the app showed a visible warning or error overlay during the flow:
 
 ## Alerts and permissions
 
-Use `alert` for iOS simulator permission dialogs instead of tapping coordinates.
+Use `alert` for iOS simulator permission dialogs and macOS desktop alerts instead of tapping coordinates.
 
 ```bash
 agent-device alert wait 5000
 agent-device alert accept
 ```
 
-- `alert` is only supported on iOS simulators.
+- `alert` is supported on iOS simulators and macOS desktop targets.
 - `alert accept` and `alert dismiss` retry internally for a short window, so you usually do not need manual sleeps.
-- If a permission sheet is visible in `snapshot` or `screenshot` but `alert accept` says no alert was found, treat it as normal tappable UI for that run: take a scoped `snapshot -i -s "<visible label>"` and `press @ref` instead of looping on `alert`.
+- If a permission sheet or modal is visible in `snapshot` or `screenshot` but `alert accept` says no alert was found, treat it as normal tappable UI for that run: take a scoped `snapshot -i -s "<visible label>"` and `press @ref` instead of looping on `alert`.
 - iOS 16+ "Allow Paste" prompts are suppressed under XCUITest. Use `xcrun simctl pbcopy booted` when you need to seed simulator clipboard content directly.
 
 ## Setup problems worth recognizing early

skills/agent-device/references/verification.md

@@ -107,4 +107,5 @@ agent-device perf --json
 - `startup` is command round-trip timing around `open`.
 - It is not true first-frame or first-interactive telemetry.
 - Android app sessions also expose `memory` (`dumpsys meminfo`) and `cpu` (`dumpsys cpuinfo`) snapshots when the session has an app package context.
-- iOS still reports `fps`, `memory`, and `cpu` as unavailable placeholders.
+- Apple app sessions on macOS and iOS simulators also expose `memory` and `cpu` process snapshots when the session has an app bundle ID.
+- `fps` is still unavailable, and physical iOS devices still leave `memory` and `cpu` unavailable in this release.

src/daemon/handlers/__tests__/session.test.ts

@@ -2020,6 +2020,198 @@ test('perf preserves successful metrics and normalizes per-metric Android sampli
   }
 });
 
+test('perf samples Apple cpu and memory metrics on macOS app sessions', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'perf-session-macos';
+  sessionStore.set(sessionName, {
+    ...makeSession(sessionName, {
+      platform: 'macos',
+      id: 'host-mac',
+      name: 'Host Mac',
+      kind: 'device',
+      target: 'desktop',
+      booted: true,
+    }),
+    appBundleId: 'com.example.mac',
+  });
+  mockRunCmd.mockImplementation(async (cmd, _args) => {
+    if (cmd === 'mdfind') {
+      return { stdout: '/Applications/Example.app\n', stderr: '', exitCode: 0 };
+    }
+    if (cmd === 'plutil') {
+      return { stdout: 'ExampleExec\n', stderr: '', exitCode: 0 };
+    }
+    if (cmd === 'ps') {
+      return {
+        stdout: [
+          '111 7.5 4096 /Applications/Example.app/Contents/MacOS/ExampleExec',
+          '222 0.5 1024 /Applications/Example.app/Contents/MacOS/ExampleExec --flag',
+          '333 5.0 2048 /Applications/Other.app/Contents/MacOS/OtherExec',
+        ].join('\n'),
+        stderr: '',
+        exitCode: 0,
+      };
+    }
+    return { stdout: '', stderr: '', exitCode: 0 };
+  });
+
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'perf',
+      positionals: [],
+      flags: {},
+    },
+    sessionName,
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+  });
+
+  expect(response?.ok).toBe(true);
+  if (!response?.ok) throw new Error('Expected perf response to succeed for macOS session');
+  const memory = (response.data?.metrics as any)?.memory;
+  const cpu = (response.data?.metrics as any)?.cpu;
+  expect(memory?.available).toBe(true);
+  expect(memory?.residentMemoryKb).toBe(5120);
+  expect(cpu?.available).toBe(true);
+  expect(cpu?.usagePercent).toBe(8);
+  expect(cpu?.matchedProcesses).toEqual(['ExampleExec']);
+});
+
+test('perf samples Apple cpu and memory metrics on iOS simulator app sessions', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'perf-session-ios-sim';
+  sessionStore.set(sessionName, {
+    ...makeSession(sessionName, {
+      platform: 'ios',
+      id: 'sim-1',
+      name: 'iPhone 17 Pro',
+      kind: 'simulator',
+      booted: true,
+    }),
+    appBundleId: 'com.example.sim',
+  });
+  mockRunCmd.mockImplementation(async (cmd, args) => {
+    if (cmd === 'xcrun' && args.includes('get_app_container')) {
+      return { stdout: '/tmp/Example.app\n', stderr: '', exitCode: 0 };
+    }
+    if (cmd === 'plutil') {
+      return { stdout: 'ExampleSimExec\n', stderr: '', exitCode: 0 };
+    }
+    if (cmd === 'xcrun' && args.includes('spawn') && args.includes('ps')) {
+      return {
+        stdout: ['111 11.0 6144 ExampleSimExec', '222 2.0 2048 SpringBoard'].join('\n'),
+        stderr: '',
+        exitCode: 0,
+      };
+    }
+    return { stdout: '', stderr: '', exitCode: 0 };
+  });
+
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'perf',
+      positionals: [],
+      flags: {},
+    },
+    sessionName,
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+  });
+
+  expect(response?.ok).toBe(true);
+  if (!response?.ok) throw new Error('Expected perf response to succeed for iOS simulator session');
+  const memory = (response.data?.metrics as any)?.memory;
+  const cpu = (response.data?.metrics as any)?.cpu;
+  expect(memory?.available).toBe(true);
+  expect(memory?.residentMemoryKb).toBe(6144);
+  expect(cpu?.available).toBe(true);
+  expect(cpu?.usagePercent).toBe(11);
+  expect(cpu?.matchedProcesses).toEqual(['ExampleSimExec']);
+});
+
+test('perf degrades Apple cpu and memory metrics on physical iOS devices', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'perf-session-ios-device';
+  sessionStore.set(sessionName, {
+    ...makeSession(sessionName, {
+      platform: 'ios',
+      id: 'ios-device-1',
+      name: 'iPhone Device',
+      kind: 'device',
+      booted: true,
+    }),
+    appBundleId: 'com.example.device',
+  });
+
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'perf',
+      positionals: [],
+      flags: {},
+    },
+    sessionName,
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+  });
+
+  expect(response?.ok).toBe(true);
+  if (!response?.ok) throw new Error('Expected perf response to succeed for physical iOS session');
+  const memory = (response.data?.metrics as any)?.memory;
+  const cpu = (response.data?.metrics as any)?.cpu;
+  expect(memory?.available).toBe(false);
+  expect(memory?.reason).toMatch(/not yet implemented for physical iOS devices/i);
+  expect(cpu?.available).toBe(false);
+  expect(cpu?.reason).toMatch(/not yet implemented for physical iOS devices/i);
+});
+
+test('perf reports physical iOS cpu and memory as unsupported even without an app bundle id', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'perf-session-ios-device-no-bundle';
+  sessionStore.set(sessionName, {
+    ...makeSession(sessionName, {
+      platform: 'ios',
+      id: 'ios-device-2',
+      name: 'iPhone Device',
+      kind: 'device',
+      booted: true,
+    }),
+  });
+
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'perf',
+      positionals: [],
+      flags: {},
+    },
+    sessionName,
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+  });
+
+  expect(response?.ok).toBe(true);
+  if (!response?.ok) {
+    throw new Error('Expected perf response to succeed for physical iOS session without bundle id');
+  }
+  const memory = (response.data?.metrics as any)?.memory;
+  const cpu = (response.data?.metrics as any)?.cpu;
+  expect(memory?.available).toBe(false);
+  expect(memory?.reason).toMatch(/not yet implemented for physical iOS devices/i);
+  expect(cpu?.available).toBe(false);
+  expect(cpu?.reason).toMatch(/not yet implemented for physical iOS devices/i);
+});
+
 test('open URL on existing iOS session clears stale app bundle id', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'ios-session';