Add in-memory trace analysis commands

packages/agent-cdp/README.md

@@ -92,7 +92,7 @@ agent-cdp target clear
 
 - **Console** — list and fetch log lines: `console list`, `console get <id>`
 - **Network** — bounded live capture plus persisted sessions: `network status`, `network start`, `network summary`, `network list`, `network request`, `network request-headers`, `network response-headers`, `network request-body`, `network response-body`
-- **Trace** — `trace start` / `trace stop [--file PATH]` for raw trace capture
+- **Trace** — explicit trace capture plus in-memory session analysis for `performance.measure`, `performance.mark`, `console.timeStamp`, and custom DevTools tracks: `trace start`, `trace stop`, `trace summary`, `trace tracks`, `trace entries`, `trace entry`
 - **Memory (raw)** — `memory capture --file PATH` for a heap snapshot file
 - **Heap snapshot tools** — `mem-snapshot` commands to capture, load, summarize, diff snapshots, inspect classes/instances/retainers, and triage leak-style comparisons
 - **JS heap monitor** — `js-memory` commands for sampling, summaries, diffs, trends, and leak-oriented signals
@@ -160,3 +160,56 @@ Current limitations:
 - WebSocket visibility is limited to handshake metadata in v1.
 - There is no throttling, blocking, mocking, replay, or HAR export in v1.
 - Timing, size, protocol, cache, and remote-endpoint metadata may be partial or absent depending on target behavior.
+
+## Trace inspection
+
+Use `trace` when you need to capture a bounded trace, then navigate the analyzed results in small, filterable chunks rather than dumping raw `traceEvents` into the terminal.
+
+Quick start:
+
+```sh
+agent-cdp trace start
+# reproduce the interaction you want to inspect
+agent-cdp trace stop
+agent-cdp trace summary
+agent-cdp trace tracks
+agent-cdp trace entries
+agent-cdp trace entry --id te_1
+```
+
+What the current trace tooling can inspect:
+
+- plain `performance.measure()` entries
+- plain `performance.mark()` entries
+- `console.timeStamp()` entries, including custom tracks and groups emitted through DevTools timeline events
+- custom track and group metadata attached through DevTools-style `detail.devtools` payloads on user timing entries
+- custom traces emitted by tools like React DevTools when they surface track-based timeline data through the trace stream
+
+Default behavior:
+
+- Tracing is explicit. The daemon does not start recording on startup; use `trace start` when you want a capture.
+- `trace stop` stores an analyzed trace session in daemon memory so agents can query it immediately.
+- `trace stop --file PATH` can still export the raw trace JSON when you need to inspect the underlying `traceEvents` directly.
+- When `--session` is omitted, trace queries read from the latest analyzed session.
+- `trace summary` gives a compact overview first.
+- `trace tracks` lists discovered built-in and custom tracks with pagination/filtering.
+- `trace entries` is the main drill-down command; it defaults to measures and supports `--track`, `--type`, `--text`, `--start-ms`, `--end-ms`, `--limit`, `--offset`, and `--sort`.
+- `trace entry` shows the full details for exactly one selected entry.
+
+Examples:
+
+```sh
+agent-cdp trace summary
+agent-cdp trace tracks --group "Scheduler ⚛"
+agent-cdp trace entries --track "Image Processing" --limit 10
+agent-cdp trace entries --type mark --text boot
+agent-cdp trace entries --start-ms 0 --end-ms 100 --sort duration
+agent-cdp trace entry --id te_16
+```
+
+Current limitations:
+
+- Trace analysis is optimized for compact CLI inspection, not full flamechart rendering.
+- Default track output reports active time on a track; use verbose output when you need the broader span between first and last entry.
+- The parser handles common user timing and DevTools custom-track shapes seen in Chrome, React DevTools, and similar tools, but uncommon trace producers may still emit unsupported event forms.
+- Trace sessions are stored in a bounded in-memory history rather than persisted automatically.

packages/agent-cdp/skills/core.md

@@ -91,13 +91,25 @@ That skill contains session behavior, common workflows, body inspection guidance
 
 ## Trace recording
 
+For trace workflows, run:
+
+```bash
+agent-cdp skills get trace
+```
+
+That skill contains trace session behavior, user-timing/custom-track inspection, token-efficient navigation guidance, and raw export guidance.
+
+Minimal commands:
+
 ```bash
 agent-cdp trace start                       # begin recording a performance trace
-agent-cdp trace stop [--file PATH]          # stop and save (or auto-name) the trace
+agent-cdp trace stop [--file PATH]          # stop, analyze in memory, and optionally export the raw trace
+agent-cdp trace summary
+agent-cdp trace tracks
+agent-cdp trace entries
 ```
 
-Produces a `.json` file loadable in Chrome DevTools Performance tab or
-`chrome://tracing`.
+Use `--file PATH` only when you need the raw trace JSON for direct inspection or external tools.
 
 ## Raw memory capture
 

packages/agent-cdp/skills/trace.md

@@ -0,0 +1,166 @@
+---
+name: trace
+description: Trace inspection workflows for agent-cdp. Use after reading the core skill and selecting a target. Covers explicit trace capture, in-memory trace sessions, user timing inspection, custom DevTools tracks, token-efficient navigation, and raw trace export when needed.
+allowed-tools: Bash(agent-cdp:*)
+---
+
+# agent-cdp trace
+
+Focused guide for trace capture and inspection after the daemon is running and a target has been selected.
+
+Prerequisite:
+
+```bash
+agent-cdp skills get core
+agent-cdp start
+agent-cdp target list --url URL
+agent-cdp target select <id> --url URL
+```
+
+## Mental model
+
+- Tracing is explicit. The daemon does not start recording on startup.
+- `trace start` begins a raw CDP trace capture for the selected target.
+- `trace stop` ends capture, analyzes the trace in memory, and stores a queryable trace session in the daemon.
+- `trace stop --file PATH` also exports the raw `traceEvents` JSON if you need the underlying trace file.
+- Without `--session`, trace queries read from the latest analyzed session.
+- Default trace output is intentionally compact so agents can navigate the data in chunks.
+
+## Commands
+
+```bash
+agent-cdp trace start
+agent-cdp trace stop [--file PATH]
+
+agent-cdp trace status
+agent-cdp trace list [--limit N] [--offset N]
+agent-cdp trace summary [--session ID]
+agent-cdp trace tracks [--session ID] [--limit N] [--offset N] [--text TEXT] [--group NAME]
+agent-cdp trace entries [--session ID] [--track NAME] [--type measure|mark|stamp] [--text TEXT] [--start-ms N] [--end-ms N] [--limit N] [--offset N] [--sort time|duration|name]
+agent-cdp trace entry --id ENTRY_ID [--session ID]
+```
+
+## What trace analysis can inspect
+
+- plain `performance.measure()` entries
+- plain `performance.mark()` entries
+- `console.timeStamp()` entries
+- custom track and group metadata attached through DevTools-style `detail.devtools` payloads on user timing entries
+- custom tracks emitted through `devtools.timeline` `TimeStamp` events, including React DevTools timeline data
+
+## Workflow: Capture And Inspect A Fresh Trace
+
+```bash
+agent-cdp trace start
+# reproduce the interaction you want to inspect
+agent-cdp trace stop
+agent-cdp trace summary
+agent-cdp trace tracks
+agent-cdp trace entries
+```
+
+Use this when you want the latest interaction summarized without dumping raw trace JSON into the terminal.
+
+## Workflow: Navigate In Small Chunks
+
+Start broad, then narrow.
+
+```bash
+agent-cdp trace summary
+agent-cdp trace tracks --limit 10
+agent-cdp trace entries --limit 10
+agent-cdp trace entry --id te_1
+```
+
+This is the preferred agent loop because it minimizes tokens while preserving drill-down.
+
+## Workflow: Focus On A Specific Track
+
+```bash
+agent-cdp trace tracks --group "Scheduler ⚛"
+agent-cdp trace entries --track "Blocking" --limit 10
+agent-cdp trace entries --track "Image Processing" --sort duration
+```
+
+Use `trace tracks` to discover the exact track names first, then filter `trace entries` by `--track`.
+
+## Workflow: Focus On A Specific Entry Type
+
+```bash
+agent-cdp trace entries --type measure --limit 20
+agent-cdp trace entries --type mark --text boot
+agent-cdp trace entries --type stamp --track "Console Track"
+```
+
+Guidance:
+- `measure` is usually the best default when triaging performance work
+- `mark` is useful for lifecycle waypoints and custom markers
+- `stamp` is useful for DevTools-style custom timeline entries
+
+## Workflow: Time-Window Inspection
+
+```bash
+agent-cdp trace entries --start-ms 0 --end-ms 100 --sort duration
+agent-cdp trace entries --track "Blocking" --start-ms 100 --end-ms 250
+```
+
+Use time windows to cut down noisy sessions before drilling into a specific entry id.
+
+## Workflow: Inspect One Entry Fully
+
+```bash
+agent-cdp trace entries --track "Image Processing" --limit 5
+agent-cdp trace entry --id te_16
+```
+
+`trace entry` is where you should expect to see the richest details such as tooltip text, custom properties, and any preserved user detail payload.
+
+## Workflow: Export The Raw Trace
+
+Use raw export only when the analyzed views do not answer the question or when you need to compare exact event shapes.
+
+```bash
+agent-cdp trace start
+# reproduce the interaction
+agent-cdp trace stop --file /tmp/trace.json
+```
+
+The exported file can be inspected directly or loaded in tools that understand Chrome trace JSON.
+
+## Token-Efficient Navigation Tips
+
+- Prefer `trace summary` before any list command.
+- Use `trace tracks` to discover candidate tracks before scanning entries.
+- Use `--limit` and `--offset` on `trace list`, `trace tracks`, and `trace entries`.
+- Use `--text`, `--type`, `--track`, `--start-ms`, and `--end-ms` to narrow the result set before printing.
+- Use `trace entry --id ...` for full detail on a single item rather than increasing list limits.
+
+## Output Semantics
+
+- `trace summary` reports a compact session overview with entry counts and top tracks.
+- `trace tracks` reports active time by default, not the broader span between the first and last entry on that track.
+- `trace tracks --verbose` includes the broader track span in addition to active time.
+- `trace entries` defaults to measures for a narrower, more actionable list.
+
+## Caveats
+
+- Trace analysis is optimized for CLI summaries and drill-down, not flamechart rendering.
+- Support is strongest for common user timing and DevTools custom-track shapes seen in Chrome and React DevTools.
+- Some trace producers may emit unsupported event forms.
+- Trace sessions are kept in a bounded in-memory history rather than persisted automatically.
+
+## Suggested Agent Loop
+
+When debugging a performance issue, prefer this order:
+
+```bash
+agent-cdp trace start
+# reproduce the issue
+agent-cdp trace stop
+agent-cdp trace summary
+agent-cdp trace tracks --limit 10
+agent-cdp trace entries --track TRACK_NAME --limit 10
+agent-cdp trace entry --id ENTRY_ID
+```
+
+Only export the raw file when the analyzed commands are not enough.

packages/agent-cdp/src/__tests__/cli.test.ts

@@ -23,6 +23,8 @@ describe("cli", () => {
     expect(usage()).toContain("target select <id> [--url URL]");
     expect(usage()).toContain("network start [--name NAME] [--preserve-across-navigation]");
     expect(usage()).toContain("network response-body --id REQ_ID [--session ID] [--file PATH]");
+    expect(usage()).toContain("trace status");
+    expect(usage()).toContain("trace entries [--session ID] [--track NAME]");
     expect(usage()).toContain("js-allocation start");
     expect(usage()).toContain("js-allocation-timeline start");
   });