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>

src/actions.ts

@@ -65,6 +65,8 @@ import type {
   StylesCommand,
   TraceStartCommand,
   TraceStopCommand,
+  ProfilerStartCommand,
+  ProfilerStopCommand,
   HarStopCommand,
   StorageStateSaveCommand,
   StateListCommand,
@@ -355,6 +357,10 @@ export async function executeCommand(command: Command, browser: BrowserManager):
         return await handleTraceStart(command, browser);
       case 'trace_stop':
         return await handleTraceStop(command, browser);
+      case 'profiler_start':
+        return await handleProfilerStart(command, browser);
+      case 'profiler_stop':
+        return await handleProfilerStop(command, browser);
       case 'har_start':
         return await handleHarStart(command, browser);
       case 'har_stop':
@@ -1448,6 +1454,31 @@ async function handleTraceStop(
   );
 }
 
+async function handleProfilerStart(
+  command: ProfilerStartCommand,
+  browser: BrowserManager
+): Promise<Response> {
+  await browser.startProfiling({ categories: command.categories });
+  return successResponse(command.id, { started: true });
+}
+
+async function handleProfilerStop(
+  command: ProfilerStopCommand,
+  browser: BrowserManager
+): Promise<Response> {
+  let outputPath = command.path;
+  if (!outputPath) {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const random = Math.random().toString(36).substring(2, 8);
+    const filename = `profile-${timestamp}-${random}.json`;
+    const profileDir = path.join(getAppDir(), 'tmp', 'profiles');
+    mkdirSync(profileDir, { recursive: true });
+    outputPath = path.join(profileDir, filename);
+  }
+  const result = await browser.stopProfiling(outputPath);
+  return successResponse(command.id, result);
+}
+
 async function handleHarStart(
   command: Command & { action: 'har_start' },
   browser: BrowserManager

src/browser.test.ts

@@ -866,6 +866,83 @@ describe('BrowserManager', () => {
     });
   });
 
+  describe('profiling (CDP tracing)', () => {
+    const fs = require('node:fs/promises');
+    const path = require('node:path');
+    const testOutputDir = '/tmp/agent-browser-test';
+
+    beforeAll(async () => {
+      // Ensure test output directory exists
+      await fs.mkdir(testOutputDir, { recursive: true }).catch(() => {});
+    });
+
+    afterEach(async () => {
+      // Stop profiling if still active
+      if (browser.isProfilingActive()) {
+        const tempPath = path.join(testOutputDir, 'cleanup.json');
+        await browser.stopProfiling(tempPath).catch(() => {});
+      }
+    });
+
+    it('should report profiling state correctly', () => {
+      expect(browser.isProfilingActive()).toBe(false);
+    });
+
+    it('should start profiling', async () => {
+      await browser.startProfiling();
+      expect(browser.isProfilingActive()).toBe(true);
+    });
+
+    it('should throw when starting profiling twice', async () => {
+      await browser.startProfiling();
+      await expect(browser.startProfiling()).rejects.toThrow('Profiling already active');
+    });
+
+    it('should stop profiling and write file', async () => {
+      await browser.startProfiling();
+
+      const outputPath = path.join(testOutputDir, 'test-profile.json');
+      const result = await browser.stopProfiling(outputPath);
+
+      expect(result.path).toBe(outputPath);
+      expect(typeof result.eventCount).toBe('number');
+      expect(browser.isProfilingActive()).toBe(false);
+
+      // Verify file was written
+      const fileExists = await fs
+        .access(outputPath)
+        .then(() => true)
+        .catch(() => false);
+      expect(fileExists).toBe(true);
+
+      // Verify file content is valid JSON with traceEvents
+      const content = await fs.readFile(outputPath, 'utf-8');
+      const data = JSON.parse(content);
+      expect(data).toHaveProperty('traceEvents');
+      expect(Array.isArray(data.traceEvents)).toBe(true);
+
+      // Cleanup
+      await fs.unlink(outputPath).catch(() => {});
+    });
+
+    it('should throw when stopping without start', async () => {
+      expect(browser.isProfilingActive()).toBe(false);
+      await expect(browser.stopProfiling('/tmp/should-not-exist.json')).rejects.toThrow(
+        'No profiling session active'
+      );
+    });
+
+    it('should start profiling with custom categories', async () => {
+      await browser.startProfiling({ categories: ['devtools.timeline', 'v8.execute'] });
+      expect(browser.isProfilingActive()).toBe(true);
+
+      // Stop and cleanup
+      const outputPath = path.join(testOutputDir, 'custom-categories.json');
+      await browser.stopProfiling(outputPath);
+      await fs.unlink(outputPath).catch(() => {});
+    });
+  });
+
   describe('input injection', () => {
     it('should inject mouse move event', async () => {
       await expect(

src/browser.ts

@@ -17,7 +17,8 @@ import {
 import path from 'node:path';
 import os from 'node:os';
 import { existsSync, mkdirSync, rmSync, readFileSync } from 'node:fs';
-import type { LaunchCommand } from './types.js';
+import { writeFile, mkdir } from 'node:fs/promises';
+import type { LaunchCommand, TraceEvent } from './types.js';
 import { type RefMap, type EnhancedSnapshot, getEnhancedSnapshot, parseRef } from './snapshot.js';
 import { safeHeaderMerge } from './state-utils.js';
 import {
@@ -120,6 +121,15 @@ export class BrowserManager {
     return warnings;
   }
 
+  // CDP profiling state
+  private static readonly MAX_PROFILE_EVENTS = 5_000_000;
+  private profilingActive: boolean = false;
+  private profileChunks: TraceEvent[] = [];
+  private profileEventsDropped: boolean = false;
+  private profileCompleteResolver: (() => void) | null = null;
+  private profileDataHandler: ((params: { value?: TraceEvent[] }) => void) | null = null;
+  private profileCompleteHandler: (() => void) | null = null;
+
   /**
    * Check if browser is launched
    */
@@ -1818,6 +1828,156 @@ export class BrowserManager {
     this.screencastFrameHandler = null;
   }
 
+  /**
+   * Check if profiling is currently active
+   */
+  isProfilingActive(): boolean {
+    return this.profilingActive;
+  }
+
+  /**
+   * Start CDP profiling (Tracing)
+   */
+  async startProfiling(options?: { categories?: string[] }): Promise<void> {
+    if (this.profilingActive) {
+      throw new Error('Profiling already active');
+    }
+
+    const cdp = await this.getCDPSession();
+
+    const dataHandler = (params: { value?: TraceEvent[] }) => {
+      if (params.value) {
+        for (const evt of params.value) {
+          if (this.profileChunks.length >= BrowserManager.MAX_PROFILE_EVENTS) {
+            if (!this.profileEventsDropped) {
+              this.profileEventsDropped = true;
+              console.warn(
+                `Profiling: exceeded ${BrowserManager.MAX_PROFILE_EVENTS} events, dropping further data`
+              );
+            }
+            return;
+          }
+          this.profileChunks.push(evt);
+        }
+      }
+    };
+
+    const completeHandler = () => {
+      if (this.profileCompleteResolver) {
+        this.profileCompleteResolver();
+      }
+    };
+
+    cdp.on('Tracing.dataCollected', dataHandler);
+    cdp.on('Tracing.tracingComplete', completeHandler);
+
+    const categories = options?.categories ?? [
+      'devtools.timeline',
+      'disabled-by-default-devtools.timeline',
+      'disabled-by-default-devtools.timeline.frame',
+      'disabled-by-default-devtools.timeline.stack',
+      'v8.execute',
+      'disabled-by-default-v8.cpu_profiler',
+      'disabled-by-default-v8.cpu_profiler.hires',
+      'v8',
+      'disabled-by-default-v8.runtime_stats',
+      'blink',
+      'blink.user_timing',
+      'latencyInfo',
+      'renderer.scheduler',
+      'sequence_manager',
+      'toplevel',
+    ];
+
+    try {
+      await cdp.send('Tracing.start', {
+        traceConfig: {
+          includedCategories: categories,
+          enableSampling: true,
+        },
+        transferMode: 'ReportEvents',
+      });
+    } catch (error) {
+      cdp.off('Tracing.dataCollected', dataHandler);
+      cdp.off('Tracing.tracingComplete', completeHandler);
+      throw error;
+    }
+
+    // Only commit state after the CDP call succeeds
+    this.profilingActive = true;
+    this.profileChunks = [];
+    this.profileEventsDropped = false;
+    this.profileDataHandler = dataHandler;
+    this.profileCompleteHandler = completeHandler;
+  }
+
+  /**
+   * Stop CDP profiling and save to file
+   */
+  async stopProfiling(outputPath: string): Promise<{ path: string; eventCount: number }> {
+    if (!this.profilingActive) {
+      throw new Error('No profiling session active');
+    }
+
+    const cdp = await this.getCDPSession();
+
+    const TRACE_TIMEOUT_MS = 30_000;
+    const completePromise = new Promise<void>((resolve, reject) => {
+      const timer = setTimeout(
+        () => reject(new Error('Profiling data collection timed out')),
+        TRACE_TIMEOUT_MS
+      );
+      this.profileCompleteResolver = () => {
+        clearTimeout(timer);
+        resolve();
+      };
+    });
+
+    await cdp.send('Tracing.end');
+
+    let chunks: TraceEvent[];
+    try {
+      await completePromise;
+      chunks = this.profileChunks;
+    } finally {
+      if (this.profileDataHandler) {
+        cdp.off('Tracing.dataCollected', this.profileDataHandler);
+      }
+      if (this.profileCompleteHandler) {
+        cdp.off('Tracing.tracingComplete', this.profileCompleteHandler);
+      }
+      this.profilingActive = false;
+      this.profileChunks = [];
+      this.profileEventsDropped = false;
+      this.profileCompleteResolver = null;
+      this.profileDataHandler = null;
+      this.profileCompleteHandler = null;
+    }
+
+    const clockDomain =
+      process.platform === 'linux'
+        ? 'LINUX_CLOCK_MONOTONIC'
+        : process.platform === 'darwin'
+          ? 'MAC_MACH_ABSOLUTE_TIME'
+          : undefined;
+
+    const traceData: Record<string, unknown> = {
+      traceEvents: chunks,
+    };
+    if (clockDomain) {
+      traceData.metadata = { 'clock-domain': clockDomain };
+    }
+
+    const dir = path.dirname(outputPath);
+    await mkdir(dir, { recursive: true });
+
+    await writeFile(outputPath, JSON.stringify(traceData));
+
+    const eventCount = chunks.length;
+
+    return { path: outputPath, eventCount };
+  }
+
   /**
    * Inject a mouse event via CDP
    */
@@ -2131,6 +2291,26 @@ export class BrowserManager {
       await this.stopScreencast();
     }
 
+    // Clean up profiling state if active (without saving)
+    if (this.profilingActive) {
+      const cdp = this.cdpSession;
+      if (cdp) {
+        if (this.profileDataHandler) {
+          cdp.off('Tracing.dataCollected', this.profileDataHandler);
+        }
+        if (this.profileCompleteHandler) {
+          cdp.off('Tracing.tracingComplete', this.profileCompleteHandler);
+        }
+        await cdp.send('Tracing.end').catch(() => {});
+      }
+      this.profilingActive = false;
+      this.profileChunks = [];
+      this.profileEventsDropped = false;
+      this.profileCompleteResolver = null;
+      this.profileDataHandler = null;
+      this.profileCompleteHandler = null;
+    }
+
     // Clean up CDP session
     if (this.cdpSession) {
       await this.cdpSession.detach().catch(() => {});

src/protocol.ts

@@ -374,6 +374,16 @@ const traceStopSchema = baseCommandSchema.extend({
   path: z.string().min(1).optional(),
 });
 
+const profilerStartSchema = baseCommandSchema.extend({
+  action: z.literal('profiler_start'),
+  categories: z.array(z.string()).optional(),
+});
+
+const profilerStopSchema = baseCommandSchema.extend({
+  action: z.literal('profiler_stop'),
+  path: z.string().min(1).optional(),
+});
+
 const harStartSchema = baseCommandSchema.extend({
   action: z.literal('har_start'),
 });
@@ -898,6 +908,8 @@ const commandSchema = z.discriminatedUnion('action', [
   recordingRestartSchema,
   traceStartSchema,
   traceStopSchema,
+  profilerStartSchema,
+  profilerStopSchema,
   harStartSchema,
   harStopSchema,
   stateSaveSchema,

src/types.ts

@@ -579,6 +579,33 @@ export interface TraceStopCommand extends BaseCommand {
   path?: string;
 }
 
+/**
+ * Chrome Trace Event format. All fields are optional because CDP trace event
+ * shapes vary across categories and event phases -- this type is intentionally
+ * loose to accept any valid trace event without data loss.
+ */
+export interface TraceEvent {
+  cat?: string;
+  name?: string;
+  ph?: string;
+  pid?: number;
+  tid?: number;
+  ts?: number;
+  dur?: number;
+  args?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface ProfilerStartCommand extends BaseCommand {
+  action: 'profiler_start';
+  categories?: string[]; // Optional trace categories (e.g., "devtools.timeline")
+}
+
+export interface ProfilerStopCommand extends BaseCommand {
+  action: 'profiler_stop';
+  path?: string;
+}
+
 // HAR recording
 export interface HarStartCommand extends BaseCommand {
   action: 'har_start';
@@ -924,6 +951,8 @@ export type Command =
   | RecordingRestartCommand
   | TraceStartCommand
   | TraceStopCommand
+  | ProfilerStartCommand
+  | ProfilerStopCommand
   | HarStartCommand
   | HarStopCommand
   | StorageStateSaveCommand