callstack / callstack/agent-device
Add Apple frame-health sampling to perf
- Lingua principale
- TypeScript
- Stelle
- 4.6k
- Fork
- 299
- Merge medio
- 10h 17m
- PR unite (30g)
- 544
Descrizione
## Context
PR #474 adds Android frame-health sampling to `agent-device perf` using `adb shell dumpsys gfxinfo framestats`. Apple platforms currently still expose startup, CPU, and memory metrics, but no native frame/drop health metric.
The Android work settled on an agent-oriented contract: dropped-frame percentage is more useful than FPS for judging transition, animation, and gesture health. The default CLI output stays token-efficient, and richer timing/attribution data remains available in JSON.
## Desired Apple behavior
Add Apple frame-health sampling to `perf` where it can be collected reliably. Keep the same agent-facing shape as Android when possible:
- `droppedFramePercent` as the primary health signal
- `droppedFrameCount` and `totalFrameCount`
- explicit `sampleWindowMs`, `windowStartedAt`, and `windowEndedAt`
- worst dropped-frame windows with relative timestamps, e.g. `+1m20s-+1m22s: 8 missed-deadline frames`
- recent related session actions for correlation with logs and agent interactions
- clear `available: false` reasons when Apple tooling cannot provide trustworthy data
The default non-JSON CLI output on Apple should remain a compact CPU/memory summary until frame health exists, rather than printing FPS-only or misleading placeholder data.
## Implementation insights from Android
- Prefer dropped-frame percentage over FPS; FPS alone hides short jank clusters.
- Raw frame timestamps are important even when an aggregate summary exists. Do not discard attribution data if the source provides both.
- Avoid hard-coded 60Hz deadlines. Infer the display/frame deadline from source data or omit deadline-dependent fields when it cannot be inferred.
- Sampling windows need explicit start/end timestamps. Android resets gfxinfo after `open` and after each successful `perf`; Apple should either reset its source or report a precise collection window.
- Worst windows make the metric actionable for agents because they can correlate `perf --json` output with logs and interaction timelines.
- If attribution is approximate, document the limitation in code and expose enough source metadata to make the confidence clear.
## Investigation candidates
- iOS simulator: evaluate whether `xctrace`/Instruments Core Animation, simulator diagnostics, or another Apple-supported source can provide frame timing or hitch data quickly enough for interactive agent use.
- Physical iOS: current CPU/memory sampling already uses Apple tooling; investigate whether `xctrace` can collect Core Animation/hitch data with acceptable overhead and parseable output.
- macOS app sessions: decide whether this issue includes macOS frame health or whether macOS should be tracked separately.
- React Native render profiling via React DevTools is complementary, not a replacement for native frame health, because it does not directly measure compositor/display missed deadlines.
## Acceptance criteria
- `agent-device perf --json` includes Apple frame-health data only when the source is reliable enough to avoid misleading agents.
- The non-JSON `perf` output stays compact and platform-independent.
- The implementation reports sample start/end and worst jank windows where frame timestamps are available.
- Unavailable cases include clear reasons and do not invent FPS or dropped-frame values.
- Tests cover parser/window behavior and CLI output, and docs explain the Apple support level.
- Validate against the test app on at least one Apple target that supports the chosen source.
Guida per i contributori
Apri la guida per i contributori
Direzione di ricerca
Inizia dall’agent-device perf entry point e dall’implementazione Android di PR #474, quindi valuta xctrace, Instruments Core Animation, la diagnostica del simulatore o un’altra sorgente supportata da Apple su un target iOS. Il lavoro è completato quando sono disponibili dati JSON frame-health affidabili con finestre esplicite e motivi di indisponibilità, un output compatto non JSON, test di parser/window e CLI, la documentazione del supporto e la validazione su un target di test Apple.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Valutazione
- Stack tecnologico
- ios, macos, typescript
- Ambito
- cli, devtools, mobile-dev, performance
- Tipo di issue
- Funzionalità
- Difficoltà
- 5/5
- Tempo stimato
- Più di una settimana
- Stato di attività
- Tranquilla
- Chiarezza
- Abbastanza chiara
- Idoneità per principianti
- 38/100