Add agent-friendly network inspection tools

packages/agent-cdp/README.md

@@ -1,6 +1,6 @@
 # agent-cdp
 
-**agent-cdp** is a command-line tool that connects to apps and pages through the **Chrome DevTools Protocol (CDP)**. Use it to list debuggable targets, stream console output, record traces, inspect JavaScript heap usage, capture and analyze heap snapshots, and run JavaScript CPU profiles—all without opening DevTools yourself.
+**agent-cdp** is a command-line tool that connects to apps and pages through the **Chrome DevTools Protocol (CDP)**. Use it to list debuggable targets, inspect network traffic, stream console output, record traces, inspect JavaScript heap usage, capture and analyze heap snapshots, and run JavaScript CPU profiles, all without opening DevTools yourself.
 
 ## Compatibility
 
@@ -91,6 +91,7 @@ agent-cdp target clear
 **3. Use the features you need**
 
 - **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
 - **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
@@ -107,4 +108,55 @@ agent-cdp stop
 
 ## Command overview
 
-Commands are grouped as **daemon**, **target**, **console**, **trace**, **memory**, **mem-snapshot**, **js-memory**, **js-allocation**, **js-allocation-timeline**, **js-profile**, and **skills** (bundled reference files). See `agent-cdp --help` for exact syntax and options.
+Commands are grouped as **daemon**, **target**, **console**, **network**, **trace**, **memory**, **mem-snapshot**, **js-memory**, **js-allocation**, **js-allocation-timeline**, **js-profile**, and **skills** (bundled reference files). See `agent-cdp --help` for exact syntax and options.
+
+## Network inspection
+
+Use `network` when you need compact request summaries first, then explicit drill-down commands for details.
+
+Quick start:
+
+```sh
+agent-cdp network status
+agent-cdp network start --name login-flow
+# reproduce the failing or slow interaction
+agent-cdp network stop
+agent-cdp network summary --session net_1
+agent-cdp network list --session net_1 --status failed
+agent-cdp network request --session net_1 --id req_12
+agent-cdp network response-headers --session net_1 --id req_12
+agent-cdp network response-body --session net_1 --id req_12 --file ./response-body.txt
+```
+
+Default behavior:
+
+- The daemon keeps an always-on live rolling buffer of the most recent `200` normalized requests for the active target.
+- `network start` begins an empty persisted recording session. It does not backfill from the live buffer.
+- When `--session` is omitted, `network` queries prefer the active or latest persisted session. If no session exists, they read from the live buffer.
+- `network request` shows metadata, timing, sizes, redirects, and availability flags only. It does not print headers or body previews by default.
+- Use `network request-headers`, `network response-headers`, `network request-body`, and `network response-body` for explicit drill-down.
+
+Examples:
+
+```sh
+agent-cdp network list --type xhr --min-ms 500
+agent-cdp network list --status 5xx --text graphql
+agent-cdp network request --id req_7
+agent-cdp network request-headers --id req_7 --name authorization
+agent-cdp network response-body --id req_7
+```
+
+Current limitations:
+
+- Network tooling depends on the target emitting usable CDP `Network.*` events.
+- Support is capability-driven, not runtime-name-driven. There is no runtime-specific fallback instrumentation in v1.
+- The live buffer is limited to the most recent `200` requests.
+- Persisted sessions start empty and do not backfill from the live buffer.
+- Default request detail omits headers and bodies.
+- No request or response body previews are printed by default.
+- Full request and response bodies may still be unavailable depending on target behavior, timing, and connection lifetime.
+- Binary bodies may be easier to consume through `--file` export.
+- No default redaction is applied in v1.
+- 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.

packages/agent-cdp/skills/core.md

@@ -1,14 +1,14 @@
 ---
 name: core
-description: Core agent-cdp usage guide. Read this before running any agent-cdp commands. Covers the daemon lifecycle, target selection, console capture, trace recording, heap snapshot analysis, JS heap monitoring, and CPU profiling workflows. Use when you need to analyze memory leaks, profile JavaScript CPU usage, capture heap snapshots, or monitor runtime behavior of a Chrome/Node.js target via Chrome DevTools Protocol.
+description: Core agent-cdp usage guide. Read this before running any agent-cdp commands. Covers the daemon lifecycle, target selection, network inspection, console capture, trace recording, heap snapshot analysis, JS heap monitoring, and CPU profiling workflows. Use when you need to analyze network failures, memory leaks, CPU hotspots, or runtime behavior of a Chrome/Node.js target via Chrome DevTools Protocol.
 allowed-tools: Bash(agent-cdp:*)
 ---
 
 # agent-cdp core
 
 CLI for deep runtime analysis of Chrome and Node.js processes via Chrome
 DevTools Protocol (CDP). Captures heap snapshots, CPU profiles, JS memory
-samples, console output, and performance traces — all without modifying
+samples, network traffic, console output, and performance traces — all without modifying
 source code.
 
 ## The core loop
@@ -79,6 +79,16 @@ agent-cdp console get <id>             # get full details of a specific message
 
 Console messages are collected while the daemon is running with an active target.
 
+## Network inspection
+
+For network workflows, run:
+
+```bash
+agent-cdp skills get network
+```
+
+That skill contains session behavior, common workflows, body inspection guidance, and network-specific troubleshooting.
+
 ## Trace recording
 
 ```bash

packages/agent-cdp/skills/network.md

@@ -0,0 +1,165 @@
+---
+name: network
+description: Network inspection workflows for agent-cdp. Use after reading the core skill and selecting a target. Covers session lifecycle, failed-request triage, body inspection, binary export, and practical guidance for agent-friendly network debugging.
+allowed-tools: Bash(agent-cdp:*)
+---
+
+# agent-cdp network
+
+Focused guide for network 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
+
+- After `target select`, the daemon starts an initial active network session automatically.
+- That initial session appears in `network sessions` and can be stopped with `network stop`.
+- `network start` creates a fresh empty session and does not backfill earlier requests.
+- Only one active network session exists at a time.
+- Without `--session`, queries prefer the active session, then the latest stored session, then the live rolling buffer if no session exists.
+- The live buffer keeps only the most recent `200` requests.
+
+## Commands
+
+```bash
+agent-cdp network status
+
+agent-cdp network start [--name NAME] [--preserve-across-navigation]
+agent-cdp network stop
+agent-cdp network sessions [--limit N] [--offset N]
+
+agent-cdp network summary [--session ID]
+agent-cdp network list [--session ID] [--limit N] [--offset N] [--type TYPE] [--status STATUS] [--method METHOD] [--text TEXT] [--min-ms N] [--max-ms N] [--min-bytes N] [--max-bytes N]
+agent-cdp network request --id REQ_ID [--session ID]
+agent-cdp network request-headers --id REQ_ID [--session ID] [--name TEXT]
+agent-cdp network response-headers --id REQ_ID [--session ID] [--name TEXT]
+agent-cdp network request-body --id REQ_ID [--session ID] [--file PATH]
+agent-cdp network response-body --id REQ_ID [--session ID] [--file PATH]
+```
+
+## Workflow: Quick Triage
+
+Use this when you want a fast overview of an interaction.
+
+```bash
+agent-cdp network summary
+agent-cdp network list --status failed
+agent-cdp network list --min-ms 1000
+```
+
+What to look for:
+- failed requests
+- slow requests
+- unusually large responses
+- request type concentration such as repeated `xhr` or `fetch`
+
+## Workflow: Capture A Repro In A Fresh Session
+
+Use this when you want a clean session for a specific bug reproduction.
+
+```bash
+agent-cdp network stop
+agent-cdp network start --name login-repro --preserve-across-navigation
+# reproduce the issue in the app
+agent-cdp network stop
+agent-cdp network sessions
+agent-cdp network summary --session net_2
+```
+
+Notes:
+- Stop the current session first if one is already active.
+- Use `--preserve-across-navigation` when the repro crosses page loads or full-document navigations.
+
+## Workflow: Investigate A Failed Request
+
+```bash
+agent-cdp network list --status failed
+agent-cdp network request --id req_12
+agent-cdp network request-headers --id req_12
+agent-cdp network response-headers --id req_12
+agent-cdp network response-body --id req_12
+```
+
+Typical checks:
+- request URL and method are correct
+- auth, cookie, and content-type headers are present
+- response status and headers match expectations
+- response body contains server-side error details
+
+## Workflow: Inspect JSON APIs
+
+```bash
+agent-cdp network list --type fetch --text /api/
+agent-cdp network request --id req_12
+agent-cdp network request-body --id req_12
+agent-cdp network response-body --id req_12
+```
+
+Body handling behavior:
+- Text-like content types are decoded to text when CDP returns them as base64.
+- Binary content types remain base64 in terminal output.
+- JSON is currently shown as raw text, not pretty-printed.
+
+## Workflow: Export Binary Or Large Bodies
+
+Use file export for images, downloads, large payloads, or anything you do not want inline in the terminal.
+
+```bash
+agent-cdp network response-body --id req_12 --file ./response.bin
+agent-cdp network request-body --id req_12 --file ./request.bin
+```
+
+Use `--file` when:
+- the content type is binary
+- the body is large
+- you want exact bytes instead of terminal rendering
+
+## Workflow: Search By Endpoint, Method, Or Payload Size
+
+```bash
+agent-cdp network list --text checkout
+agent-cdp network list --method POST
+agent-cdp network list --status 5xx
+agent-cdp network list --min-bytes 1000000
+agent-cdp network list --min-ms 500 --max-ms 5000
+```
+
+This is useful for narrowing the session before drilling into a specific request id.
+
+## Body Caveats
+
+- `network request` intentionally omits headers and bodies; use the explicit follow-up commands.
+- Request bodies depend on target support for `Network.getRequestPostData`.
+- Multipart form-data is not parsed into fields. CDP returns multipart request body text without files when available.
+- Response and request bodies may be unavailable after disconnects or on targets with partial CDP support.
+- Binary response bodies are best exported with `--file`.
+
+## Target Compatibility
+
+- CDP `Network.*` support varies by runtime and target.
+- There is no runtime-specific fallback instrumentation in v1.
+- WebSocket support is handshake-only in v1.
+- No HAR export, request blocking, throttling, mocking, replay, or redaction is included in v1.
+
+## Suggested Agent Loop
+
+When debugging a network issue, prefer this order:
+
+```bash
+agent-cdp network summary
+agent-cdp network list --status failed
+agent-cdp network list --min-ms 1000
+agent-cdp network request --id REQ_ID
+agent-cdp network request-headers --id REQ_ID
+agent-cdp network response-headers --id REQ_ID
+agent-cdp network response-body --id REQ_ID
+```
+
+If the issue is noisy or mixed with unrelated traffic, start a fresh named session and reproduce again.

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

@@ -21,6 +21,8 @@ describe("cli", () => {
     expect(usage()).toContain("stop");
     expect(usage()).toContain("target list [--url URL]");
     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("js-allocation start");
     expect(usage()).toContain("js-allocation-timeline start");
   });