feat: Enable capture of profiling data (#290)

* feat: Enable capture of profiling data

Adding a new set of commands:
```
agent-browser profiler start

agent-browser profiler stop trace.json
```

With this, agents can start a profiling trace, perform a set of actions, and then extract the profiling data for analysis.

**Note:** I was originally going to call it `agent-browser profile` but I realized that might cause confusion with the `--profile` flag

CDP supports a couple commands for starting/stopping a trace.
When a trace is running, it emits events that need to be picked up.
We store these locally in the daemon until the trace is completed.
When the final event is received, we dump all of them into an output file.

That file can be loaded directly into chrome devtools or another analysis tool to visualize what happened during the agentic run.

Added some basic rust tests for parsing the commands (since they have some optional / required args)

TS daemon adds ~6 tests to make sure the profiling lifecycle (including saving the output file) works as intended

* add docs

* fixes

* fixes

---------

Co-authored-by: Chris Tate <chris@ctate.dev>

cli/src/output.rs

@@ -275,10 +275,21 @@ pub fn print_response(resp: &Response, json_mode: bool, action: Option<&str>) {
         // Recording start (has "started" field)
         if let Some(started) = data.get("started").and_then(|v| v.as_bool()) {
             if started {
-                if let Some(path) = data.get("path").and_then(|v| v.as_str()) {
-                    println!("{} Recording started: {}", color::success_indicator(), path);
-                } else {
-                    println!("{} Recording started", color::success_indicator());
+                match action {
+                    Some("profiler_start") => {
+                        println!("{} Profiling started", color::success_indicator());
+                    }
+                    _ => {
+                        if let Some(path) = data.get("path").and_then(|v| v.as_str()) {
+                            println!(
+                                "{} Recording started: {}",
+                                color::success_indicator(),
+                                path
+                            );
+                        } else {
+                            println!("{} Recording started", color::success_indicator());
+                        }
+                    }
                 }
                 return;
             }
@@ -367,6 +378,12 @@ pub fn print_response(resp: &Response, json_mode: bool, action: Option<&str>) {
                     color::success_indicator(),
                     color::green(path)
                 ),
+                "profiler_stop" => println!(
+                    "{} Profile saved to {} ({} events)",
+                    color::success_indicator(),
+                    color::green(path),
+                    data.get("eventCount").and_then(|c| c.as_u64()).unwrap_or(0)
+                ),
                 "har_stop" => println!(
                     "{} HAR saved to {}",
                     color::success_indicator(),
@@ -1471,6 +1488,46 @@ Examples:
 "##
         }
 
+        // === Profile (CDP Tracing) ===
+        "profiler" => {
+            r##"
+agent-browser profiler - Record Chrome DevTools performance profile
+
+Usage: agent-browser profiler <operation> [options]
+
+Record a performance profile using Chrome DevTools Protocol (CDP) Tracing.
+The output JSON file can be loaded into Chrome DevTools Performance panel,
+Perfetto UI (https://ui.perfetto.dev/), or other trace analysis tools.
+
+Operations:
+  start                Start profiling
+  stop [path]          Stop profiling and save to file
+
+Start Options:
+  --categories <list>  Comma-separated trace categories (default includes
+                       devtools.timeline, v8.execute, blink, and others)
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  # Basic profiling
+  agent-browser profiler start
+  agent-browser navigate https://example.com
+  agent-browser click "#button"
+  agent-browser profiler stop ./trace.json
+
+  # With custom categories
+  agent-browser profiler start --categories "devtools.timeline,v8.execute,blink.user_timing"
+  agent-browser profiler stop ./custom-trace.json
+
+The output file can be viewed in:
+  - Chrome DevTools: Performance panel > Load profile
+  - Perfetto: https://ui.perfetto.dev/
+"##
+        }
+
         // === Record (video) ===
         "record" => {
             r##"
@@ -1833,7 +1890,8 @@ Tabs:
   tab [new|list|close|<n>]   Manage tabs
 
 Debug:
-  trace start|stop [path]    Record trace
+  trace start|stop [path]    Record Playwright trace
+  profiler start|stop [path] Record Chrome DevTools profile
   record start <path> [url]  Start video recording (WebM)
   record stop                Stop and save video
   console [--clear]          View console logs