Native diagnostics API rollout

[thymikee]

What to build

Track the native diagnostics API rollout for agent-device. The goal is a compact agent experience for native crash, issue, and performance evidence without creating a large command catalog or making every workflow look like a generic debug task.

Recommended taxonomy:

• Keep evidence primitives top-level: logs, network, record, screenshot, perf, and react-devtools.
• Extend perf into a native performance family: perf metrics, perf frames, perf cpu profile, perf memory snapshot, and perf trace.
• Preserve perf --json and metrics --json as aliases for perf metrics.
• Treat debug as optional workflow, bundle, and symbolication space only. Do not move low-level evidence collection under debug.

Prototype CLI shape:

agent-device perf metrics --json
agent-device perf frames --json
agent-device perf cpu sample --json
agent-device perf cpu profile start --out cpu.trace
agent-device perf cpu profile stop --out cpu.trace
agent-device perf memory sample --json
agent-device perf memory snapshot --out heap.artifact
agent-device perf trace start --kind perfetto --out app.perfetto-trace
agent-device perf trace start --kind xctrace --template "Time Profiler" --out app.trace
agent-device debug symbols --dsym MyApp.dSYM --artifact crash.log

Prototype structured input:

type PerfOptions = ClientCommandBaseOptions & {
  area?: "metrics" | "frames" | "cpu" | "memory" | "trace";
  action?: "sample" | "snapshot" | "profile-start" | "profile-stop" | "start" | "stop" | "report";
  kind?: "simpleperf" | "perfetto" | "xctrace" | "heapprofd" | "memgraph";
  template?: string;
  sampleMs?: number;
  durationMs?: number;
  out?: string;
  format?: "json" | "text";
  includeRawArtifact?: boolean;
};

Acceptance criteria

• Child issues cover the rollout in a small number of cohesive slices rather than one issue per native tool.
• The accepted API keeps evidence primitives top-level and avoids a catch-all debug command.
• Each child issue includes user-visible behavior, API shape, acceptance criteria, and validation expectations.
• Agent-facing guidance preserves the symptom routing: crash -> logs/symbols, HTTP -> network, native slowness -> perf, React render slowness -> react-devtools, visual proof -> record/screenshot.
• Large profiler artifacts are returned as paths plus compact summaries, not dumped into agent context.

Blocked by

None - tracking issue.

[thymikee]

Created grouped implementation issues:

• Add perf metrics and frames subcommands as native diagnostics foundation #695 - Perf API foundation: perf metrics, perf frames, compatibility aliases, structured Node/MCP input, and agent-facing routing.
• Add Android native CPU and Perfetto profiling under perf #696 - Android native profiling: Simpleperf CPU profiles and Perfetto trace artifacts under perf.
• Add Apple xctrace CPU profiling under perf #697 - Apple native profiling: xctrace CPU/profile artifacts and compact reports under perf.
• Add memory diagnostics artifacts under perf memory #698 - Memory diagnostics: perf memory sample, heap/memgraph artifacts, and optional heapprofd once Perfetto plumbing exists.
• Add narrow debug symbols workflow for crash symbolication #699 - Crash symbolication: narrow debug symbols workflow for dSYM/symbolicated crash artifacts.

Dependency shape:

• Add perf metrics and frames subcommands as native diagnostics foundation #695 should land first.
• Add Android native CPU and Perfetto profiling under perf #696 and Add Apple xctrace CPU profiling under perf #697 can proceed after Add perf metrics and frames subcommands as native diagnostics foundation #695.
• Add memory diagnostics artifacts under perf memory #698 can start after Add perf metrics and frames subcommands as native diagnostics foundation #695; heapprofd-specific work should wait for Add Android native CPU and Perfetto profiling under perf #696 if included.
• Add narrow debug symbols workflow for crash symbolication #699 is independent once the taxonomy in this umbrella is accepted.

The split intentionally keeps similar platform/tooling work close together without creating one issue per native tool.