refactor: migrate perf to device runtime (#2061)

Author: thymikee

.fallowrc.json

@@ -60,6 +60,11 @@
     "@arethetypeswrong/cli"
   ],
   "ignoreExports": [
+    {
+      "comment": "Android perf mechanics are selected through the lazy platform host so importing agent-device does not eagerly load adb mechanics. Fallow cannot follow the dynamic property read in src/platform-runtime-perf-host.ts.",
+      "file": "src/platforms/android/perf.ts",
+      "exports": ["sampleAndroidMemoryPerf"]
+    },
     {
       "comment": "Daemon route handlers are reached only through the dynamic `import()` table in request-handler-chain.ts, which --production analysis cannot follow to a consumer.",
       "file": "src/daemon/handlers/{lease,session,snapshot,react-native,record-trace,find,interaction}.ts",

packages/capture-kit/src/index.ts

@@ -12,6 +12,7 @@ export {
 export { createAppLogLiveHandle, createAppLogLiveHandleFromFinish } from './app-log-live-handle.ts';
 export { createHostAudioProbeCaptureOperations } from './audio-probe-runtime.ts';
 export { hostAudioProbeDescriptorCodec } from './audio-probe-descriptor.ts';
+export { decodeDurableDescriptor } from './durable-descriptor-codec.ts';
 export { createScreenRecordingLiveHandle } from './screen-recording-live-handle.ts';
 export { createScreenRecordingCompletion } from './screen-recording-completion.ts';
 export { assertScreenRecordingOptionsSupported } from './screen-recording-options.ts';

packages/contracts/package.json

@@ -291,6 +291,22 @@
       "types": "./src/platform-runtime-unavailable.ts",
       "default": "./src/platform-runtime-unavailable.ts"
     },
+    "./perf-runtime": {
+      "types": "./src/perf-runtime.ts",
+      "default": "./src/perf-runtime.ts"
+    },
+    "./perf-runtime-host": {
+      "types": "./src/perf-runtime-host.ts",
+      "default": "./src/perf-runtime-host.ts"
+    },
+    "./perf-runtime-operation-builder": {
+      "types": "./src/perf-runtime-operation-builder.ts",
+      "default": "./src/perf-runtime-operation-builder.ts"
+    },
+    "./perf-runtime-plan": {
+      "types": "./src/perf-runtime-plan.ts",
+      "default": "./src/perf-runtime-plan.ts"
+    },
     "./progress": {
       "types": "./src/facades/progress.ts",
       "default": "./src/facades/progress.ts"

packages/contracts/src/perf-runtime-host.ts

@@ -0,0 +1,56 @@
+import type { DeviceInfo } from '@agent-device/kernel/device';
+import type { RuntimeOwnerRef } from './platform-runtime.ts';
+import type {
+  PerfData,
+  PerfNativeCaptureRecoveryInput,
+  PerfNativeCaptureStartInput,
+  PerfNativeCaptureStartResult,
+  PerfProfileReportInput,
+  PerfRuntimeOperations,
+} from './perf-runtime.ts';
+
+type NativeCaptureHost = Readonly<{
+  start(
+    device: DeviceInfo,
+    owner: RuntimeOwnerRef,
+    input: PerfNativeCaptureStartInput,
+  ): Promise<PerfNativeCaptureStartResult>;
+  reattach(
+    device: DeviceInfo,
+    input: PerfNativeCaptureRecoveryInput,
+  ): ReturnType<PerfRuntimeOperations['perfNativeCaptureReattach']>;
+  cleanup(
+    device: DeviceInfo,
+    input: PerfNativeCaptureRecoveryInput,
+  ): ReturnType<PerfRuntimeOperations['perfNativeCaptureCleanup']>;
+}>;
+
+export type ApplePerfHost = NativeCaptureHost &
+  Readonly<{
+    sampleFrames(device: DeviceInfo, appId: string): Promise<object>;
+    frameSampling(device: DeviceInfo): Promise<PerfData>;
+    sampleMemory(device: DeviceInfo, appId: string): Promise<object>;
+    memorySampling(device: DeviceInfo): Promise<PerfData>;
+    memorySnapshotSupport(device: DeviceInfo): Promise<PerfData>;
+    captureMemorySnapshot(device: DeviceInfo, appId: string, outputPath: string): Promise<PerfData>;
+    writeProfileReport(input: PerfProfileReportInput): Promise<PerfData>;
+  }>;
+
+export type AndroidPerfHost = NativeCaptureHost &
+  Readonly<{
+    sampleFrames(device: DeviceInfo, appId: string): Promise<object>;
+    sampleMemory(device: DeviceInfo, appId: string): Promise<object>;
+    captureMemorySnapshot(device: DeviceInfo, appId: string, outputPath: string): Promise<PerfData>;
+    writeProfileReport(device: DeviceInfo, input: PerfProfileReportInput): Promise<PerfData>;
+  }>;
+
+export type HarmonyPerfHost = Readonly<{
+  sampleMemory(device: DeviceInfo, appId: string): Promise<object>;
+}>;
+
+/** Family-specific native mechanics; platform packages own policy and operation construction. */
+export type PerfRuntimeHost = Readonly<{
+  apple: ApplePerfHost;
+  android: AndroidPerfHost;
+  harmony: HarmonyPerfHost;
+}>;

packages/contracts/src/perf-runtime-operation-builder.test.ts

@@ -0,0 +1,55 @@
+import { expect, test, vi } from 'vitest';
+import type { PerfRuntimeOperations } from './perf-runtime.ts';
+import {
+  createPerfNativeOperations,
+  missingPerfAppMetric,
+  missingPerfSnapshotAppError,
+  settlePerfMetric,
+  unsupportedPerfMemoryArtifact,
+} from './perf-runtime-operation-builder.ts';
+
+test('builds compact unavailable observations and memory-artifact guidance', async () => {
+  await expect(settlePerfMetric(Promise.reject(new Error('sample failed')))).resolves.toMatchObject(
+    {
+      available: false,
+      reason: 'sample failed',
+    },
+  );
+  expect(missingPerfAppMetric('Apple', 'bundle ID')).toMatchObject({
+    available: false,
+    reason: expect.stringContaining('Run open <app> first'),
+  });
+  expect(unsupportedPerfMemoryArtifact('Apple', 'android-hprof', {}, 'Use memgraph')).toEqual({
+    artifact: {
+      available: false,
+      kind: 'android-hprof',
+      reason: 'Apple perf memory snapshot does not support android-hprof.',
+      hint: 'Use memgraph',
+      support: {},
+    },
+    support: {},
+  });
+  expect(missingPerfSnapshotAppError()).toMatchObject({ code: 'INVALID_ARGS' });
+});
+
+test('delegates a valid native profile report', async () => {
+  const writeProfileReport = vi.fn(async () => ({ report: true }));
+  const unused = vi.fn() as unknown as PerfRuntimeOperations['perfNativeCaptureStart'];
+  const operations = createPerfNativeOperations({
+    platform: 'Apple',
+    expectedProfileKind: 'xctrace',
+    start: unused,
+    reattach: vi.fn() as unknown as PerfRuntimeOperations['perfNativeCaptureReattach'],
+    cleanup: vi.fn() as unknown as PerfRuntimeOperations['perfNativeCaptureCleanup'],
+    writeProfileReport,
+  });
+
+  await expect(
+    operations.perfProfileReport({
+      kind: 'xctrace',
+      tracePath: '/tmp/profile.trace',
+      outPath: '/tmp/report.json',
+    }),
+  ).resolves.toEqual({ report: true });
+  expect(writeProfileReport).toHaveBeenCalledOnce();
+});

packages/contracts/src/perf-runtime-operation-builder.ts

@@ -0,0 +1,74 @@
+import type { PerfData, PerfRuntimeOperations } from './perf-runtime.ts';
+import { AppError, normalizeError } from '@agent-device/kernel/errors';
+
+export async function settlePerfMetric(promise: Promise<object>): Promise<PerfData> {
+  try {
+    return { available: true, ...(await promise) };
+  } catch (error) {
+    const normalized = normalizeError(error);
+    return { available: false, reason: normalized.message, error: normalized };
+  }
+}
+
+export function missingPerfAppMetric(platform: string, appIdentity: string): PerfData {
+  return {
+    available: false,
+    reason: `No ${platform} app ${appIdentity} is associated with this session. Run open <app> first.`,
+  };
+}
+
+export function unsupportedPerfMemoryArtifact(
+  platform: string,
+  kind: string,
+  support: PerfData,
+  hint: string,
+): PerfData {
+  return {
+    artifact: {
+      available: false,
+      kind,
+      reason: `${platform} perf memory snapshot does not support ${kind}.`,
+      hint,
+      support,
+    },
+    support,
+  };
+}
+
+export function missingPerfSnapshotAppError(): AppError {
+  return new AppError('INVALID_ARGS', 'perf memory snapshot requires an active app session', {
+    hint: 'Run open <app> first so perf memory snapshot can resolve the app process.',
+  });
+}
+
+export function createPerfNativeOperations(
+  params: Readonly<{
+    platform: string;
+    expectedProfileKind: 'xctrace' | 'simpleperf';
+    start: PerfRuntimeOperations['perfNativeCaptureStart'];
+    reattach: PerfRuntimeOperations['perfNativeCaptureReattach'];
+    cleanup: PerfRuntimeOperations['perfNativeCaptureCleanup'];
+    writeProfileReport: PerfRuntimeOperations['perfProfileReport'];
+  }>,
+): Pick<
+  PerfRuntimeOperations,
+  | 'perfNativeCaptureStart'
+  | 'perfNativeCaptureReattach'
+  | 'perfNativeCaptureCleanup'
+  | 'perfProfileReport'
+> {
+  return Object.freeze({
+    perfNativeCaptureStart: params.start,
+    perfNativeCaptureReattach: params.reattach,
+    perfNativeCaptureCleanup: params.cleanup,
+    perfProfileReport: async (input) => {
+      if (input.kind !== params.expectedProfileKind) {
+        throw new AppError(
+          'INVALID_ARGS',
+          `${params.platform} native perf requires --kind ${params.expectedProfileKind}, not ${input.kind}`,
+        );
+      }
+      return await params.writeProfileReport(input);
+    },
+  });
+}

packages/contracts/src/perf-runtime-plan.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, test } from 'vitest';
+import { parsePerfRuntimeRequest, resolvePerfRuntimePlan } from './perf-runtime-plan.ts';
+
+describe('perf runtime grammar', () => {
+  test('rejects flags and positionals that do not belong to frame sampling', () => {
+    expect(() => parsePerfRuntimeRequest({ positionals: ['frames'], kind: 'perfetto' })).toThrow(
+      'perf action must be frames',
+    );
+    expect(() => parsePerfRuntimeRequest({ positionals: ['frames', 'sample', 'extra'] })).toThrow(
+      'perf action must be frames',
+    );
+  });
+
+  test('keeps memory sample and snapshot grammars disjoint', () => {
+    expect(() =>
+      parsePerfRuntimeRequest({ positionals: ['memory', 'sample', 'memgraph'] }),
+    ).toThrow('does not accept additional positionals');
+    expect(() =>
+      parsePerfRuntimeRequest({ positionals: ['memory', 'sample'], kind: 'memgraph' }),
+    ).toThrow('--kind is only supported');
+    expect(
+      parsePerfRuntimeRequest({ positionals: ['memory', 'snapshot'], kind: 'memgraph' }),
+    ).toEqual({ area: 'memory', action: 'snapshot', kind: 'memgraph' });
+    expect(() =>
+      parsePerfRuntimeRequest({ positionals: ['memory', 'snapshot'], kind: 'perfetto' }),
+    ).toThrow('--kind must be android-hprof or memgraph');
+  });
+
+  test('maps every accepted request to its single runtime use', () => {
+    expect(resolvePerfRuntimePlan(parsePerfRuntimeRequest({ positionals: ['frames'] })).kind).toBe(
+      'frames',
+    );
+    expect(
+      resolvePerfRuntimePlan(parsePerfRuntimeRequest({ positionals: ['memory', 'snapshot'] })).kind,
+    ).toBe('memory-snapshot');
+    expect(
+      resolvePerfRuntimePlan(
+        parsePerfRuntimeRequest({ positionals: ['cpu', 'profile', 'report', 'xctrace'] }),
+      ).kind,
+    ).toBe('profile-report');
+  });
+});