Add in-memory trace analysis commands (#13)

## Summary
- add in-memory trace sessions so `trace stop` analyzes captured events
and agents can inspect them without reading raw trace files
- add `trace status|list|summary|tracks|entries|entry` commands with
compact, filterable output for user timings and custom DevTools tracks
- keep raw trace recording opt-in and backward-compatible by preserving
`trace start` / `trace stop [--file PATH]` while routing parsing into a
separate `src/trace/` module

## Backward Compatibility
- Existing trace capture remains explicit: tracing still starts only
when `trace start` is invoked.
- `trace stop --file PATH` still exports raw `traceEvents` JSON; it now
also creates an in-memory analyzed session and returns a richer summary.
- Existing daemon lifecycle, target/session flow, and newline-delimited
IPC remain unchanged.
- The CLI surface only adds new `trace` subcommands and does not change
defaults for other command families.

## Risks
- User timing parsing currently relies on a lightweight normalization
layer rather than a full DevTools handler port, so uncommon trace event
shapes may still be missed.
- Track grouping and console timestamp range reconstruction are derived
from recorded trace data; unusual producer behavior could land entries
on the default track.
- In-memory session retention is bounded, which keeps token and memory
usage under control but means older trace sessions are evicted after the
cap is reached.

## Manual testing
- Setup: run the daemon, select a Chrome target, and load a page that
emits `performance.measure`, `performance.mark`, and optional custom
DevTools track metadata.
- Start capture: run `agent-cdp trace start`, exercise the page, then
run `agent-cdp trace stop --file /tmp/trace.json`.
- Verify summary: run `agent-cdp trace summary` and confirm it reports a
new session with entry counts and top tracks.
- Verify navigation: run `agent-cdp trace tracks`, then `agent-cdp trace
entries --track Timings`, and finally `agent-cdp trace entry --id
<ENTRY_ID>` to confirm drill-down output stays compact and filterable.
- Verify compatibility: open `/tmp/trace.json` and confirm raw
`traceEvents` were still exported.

## Validation
- `pnpm format`
- `pnpm lint`
- `pnpm typecheck`
- `pnpm test`
- `pnpm build`

Closes #12

Author: V3RON

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

@@ -24,6 +24,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");
   });