[kernel-1310] browser telemetry - CLI integration (#168)

Adds browser telemetry to the CLI:
- `kernel browsers create --telemetry=all|off|<list>`
- `kernel browsers update <id> --telemetry=all|off|<list>` (partial —
unspecified categories retain state)
- `kernel browsers telemetry stream <id>` with `--categories`,
`--types`, `--seq` (Last-Event-ID resume), `-o json` (NDJSON)

Full test matrix →
https://gist.github.com/archandatta/f27eb3ea93d58e932b9fd9a7b7b9090f

## Essential run steps to validate

Build:
```bash
go build -o /tmp/kernel ./cmd/kernel
export KERNEL_API_KEY=<your key>
```

**1. Config (create / update / get):**
```bash
# create with all categories enabled
ID=$(/tmp/kernel browsers create --telemetry=all -o json | jq -r .session_id)

# verify on the session
/tmp/kernel browsers get $ID -o json | jq .telemetry

# partial update — only network is changed, others retain state
/tmp/kernel browsers update $ID --telemetry=network=off
/tmp/kernel browsers get $ID -o json | jq .telemetry

# disable everything
/tmp/kernel browsers update $ID --telemetry=off
```

**2. Live stream (text + JSON):**
```bash
# in terminal A — start streaming
/tmp/kernel browsers update $ID --telemetry=all
/tmp/kernel browsers telemetry stream $ID

# in terminal B — drive traffic via CDP (use any Playwright/CDP client) to https://kernel.sh
# events appear in terminal A: 15:04:05<TAB>[network]<TAB>network_response
```

**3. Filters:**
```bash
/tmp/kernel browsers telemetry stream $ID --categories=network
/tmp/kernel browsers telemetry stream $ID --categories=system   # monitor_* events
/tmp/kernel browsers telemetry stream $ID --types=network_response
/tmp/kernel browsers telemetry stream $ID -o json                # NDJSON envelopes
```

**4. Resume from sequence:**
```bash
# pull a seq from JSON output, then resume
/tmp/kernel browsers telemetry stream $ID --seq=1     # earliest replay (resumes after seq 1; event #1 itself is not replayable)
/tmp/kernel browsers telemetry stream $ID --seq=574   # from a specific event
```

**5. Validation paths (all should error cleanly):**
```bash
/tmp/kernel browsers create --telemetry=garbage          # invalid assignment
/tmp/kernel browsers create --telemetry=foo=on           # unknown category
/tmp/kernel browsers create --telemetry=network=yes      # invalid value
/tmp/kernel browsers telemetry stream $ID --seq=-50      # negative seq rejected
/tmp/kernel browsers telemetry stream $ID --output=yaml  # unsupported output
```

Cleanup:
```bash
/tmp/kernel browsers delete $ID
```

## Tests
- 14 unit tests under `cmd/browsers_telemetry_test.go` (`go test
./cmd/...`)
- Full end-to-end matrix run against prod API → see linked gist

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> CLI-only feature wiring to existing browser APIs; no auth or core
infra changes, with broad unit test coverage for parsing and streaming
behavior.
> 
> **Overview**
> Adds **browser telemetry** to the Kernel CLI: configure it on session
**create** and **update**, and **stream** live events from a running
session.
> 
> **Configuration** — New `--telemetry` on `browsers create` and
`browsers update` accepts `all`, `off`, or per-category lists
(`network=on,page=off`). Per-category updates only send named categories
so the API can merge; `all`/`off` set the global `Enabled` flag.
`browsers update` now allows telemetry-only updates (no
proxy/profile/viewport required).
> 
> **Streaming** — New `browsers telemetry stream <id>` uses the SDK SSE
client, resolves the session ID, supports `--categories`, `--types`,
`--seq` (Last-Event-ID resume), human-readable lines or `-o json` NDJSON
via new `PrintCompactJSONLine`. Client-side filtering and category
inference (wire `category` or type-prefix, with `monitor_*` → `system`).
> 
> **Docs & tests** — README documents flags and telemetry section; unit
tests cover param wire shapes, stream validation, filters, and
create/update telemetry mapping.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
0e33313. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: archandatta

README.md

@@ -130,6 +130,7 @@ Commands with JSON output support:
 - **Deploy**: `deploy` (JSONL streaming), `history`
 - **Invoke**: `invoke` (JSONL streaming), `history`
 - **Browser Sub-commands**: `replays list/start`, `process exec/spawn`, `fs file-info/list-files`
+- **Browser NDJSON streaming**: `telemetry stream`
 
 ### Authentication
 
@@ -212,13 +213,21 @@ Commands with JSON output support:
   - `--start-url <url>` - Initial page to open on launch
   - `--pool-id <id>` - Acquire a browser from the specified pool (mutually exclusive with --pool-name; ignores other session flags)
   - `--pool-name <name>` - Acquire a browser from the pool name (mutually exclusive with --pool-id; ignores other session flags)
+  - `--telemetry=all` - Enable telemetry for all categories
+  - `--telemetry=off` - Disable telemetry
+  - `--telemetry=<list>` - Per-category config, e.g. `--telemetry=network=on,page=off`
   - `--output json`, `-o json` - Output raw JSON object
   - _Note: When a pool is specified, omit other session configuration flags—pool settings determine profile, proxy, viewport, etc._
 - `kernel browsers delete <id>` - Delete a browser
 - `kernel browsers view <id>` - Get live view URL for a browser
   - `--output json`, `-o json` - Output JSON with liveViewUrl
 - `kernel browsers get <id>` - Get detailed browser session info
   - `--output json`, `-o json` - Output raw JSON object
+- `kernel browsers update <id>` - Update a running browser session
+  - `--telemetry=all` - Enable telemetry for all categories
+  - `--telemetry=off` - Disable telemetry
+  - `--telemetry=<list>` - Per-category config, e.g. `--telemetry=network=on,page=off`
+  - `--output json`, `-o json` - Output raw JSON object
 - `kernel browsers curl <id> <url>` - Make HTTP requests through a browser session's Chrome network stack
   - `-X, --request <method>` - HTTP method (default: GET; defaults to POST when `--data` is set)
   - `-H, --header <header>` - HTTP header, repeatable (`"Key: Value"` format)
@@ -281,6 +290,23 @@ Commands with JSON output support:
 - `kernel browsers replays download <id> <replay-id>` - Download a replay video
   - `-f, --output-file <path>` - Output file path for the replay video
 
+### Browser Telemetry
+
+Telemetry config is a sub-field of the browser session. Use `browsers create` or `browsers update` to enable, disable, or configure it, and `browsers get` to inspect the current state.
+
+- Enable all categories: `kernel browsers update <id> --telemetry=all`
+- Disable: `kernel browsers update <id> --telemetry=off`
+- Per-category: `kernel browsers update <id> --telemetry=network=on,page=off` (valid: `console`, `interaction`, `network`, `page`; `system` always emits and cannot be toggled)
+
+Per-category updates are partial — only categories you name are changed; others retain their current state. `--telemetry=all` and `--telemetry=off` reset the entire config.
+
+- `kernel browsers telemetry stream <id>` - Stream live telemetry events (NDJSON with `-o json`)
+  - `--categories <list>` - Filter by event category (`api`, `console`, `interaction`, `network`, `page`, `system`); `system` matches `monitor_*` and `cdp_*` event types
+  - `--types <list>` - Filter by event type (e.g. `network_response`, `console_error`)
+  - `--seq <n>` - Resume after sequence number N (Last-Event-ID); replays events with `seq > N`. Omit to stream from now.
+  - `-o, --output json` - Output newline-delimited JSON envelopes
+  - Default output: tab-separated `<time>\t[<category>]\t<type>`, e.g. `15:04:05  [network]  network_response`
+
 ### Browser Process Control
 
 - `kernel browsers process exec <id> [--] [command...]` - Execute a command synchronously

cmd/browsers.go

@@ -175,6 +175,7 @@ type BrowsersCreateInput struct {
 	StartURL           string
 	Extensions         []string
 	Viewport           string
+	Telemetry          string
 	Output             string
 }
 
@@ -202,6 +203,7 @@ type BrowsersUpdateInput struct {
 	ProfileSaveChanges BoolFlag
 	Viewport           string
 	Force              bool
+	Telemetry          string
 	Output             string
 }
 
@@ -215,6 +217,7 @@ type BrowsersCmd struct {
 	logs       BrowserLogService
 	computer   BrowserComputerService
 	playwright BrowserPlaywrightService
+	telemetry  BrowserTelemetryService
 }
 
 type BrowsersListInput struct {
@@ -331,9 +334,6 @@ func (b BrowsersCmd) Create(ctx context.Context, in BrowsersCreateInput) error {
 		return err
 	}
 
-	if in.Output != "json" {
-		pterm.Info.Println("Creating browser session...")
-	}
 	params := kernel.BrowserNewParams{}
 	if in.TimeoutSeconds > 0 {
 		params.TimeoutSeconds = kernel.Opt(int64(in.TimeoutSeconds))
@@ -410,6 +410,17 @@ func (b BrowsersCmd) Create(ctx context.Context, in BrowsersCreateInput) error {
 		}
 	}
 
+	if in.Telemetry != "" {
+		t, err := buildNewTelemetryParam(in.Telemetry)
+		if err != nil {
+			return err
+		}
+		params.Telemetry = t
+	}
+
+	if in.Output != "json" {
+		pterm.Info.Println("Creating browser session...")
+	}
 	browser, err := b.browsers.New(ctx, params)
 	if err != nil {
 		return util.CleanedUpSdkError{Err: err}
@@ -576,8 +587,8 @@ func (b BrowsersCmd) Update(ctx context.Context, in BrowsersUpdateInput) error {
 	}
 
 	// Validate that at least one update option is provided
-	if !hasProxyChange && !hasProfileChange && !hasViewportChange {
-		return fmt.Errorf("must specify at least one of: --proxy-id, --clear-proxy, --profile-id, --profile-name, or --viewport")
+	if !hasProxyChange && !hasProfileChange && !hasViewportChange && in.Telemetry == "" {
+		return fmt.Errorf("must specify at least one of: --proxy-id, --clear-proxy, --profile-id, --profile-name, --viewport, or --telemetry")
 	}
 
 	params := kernel.BrowserUpdateParams{}
@@ -602,6 +613,15 @@ func (b BrowsersCmd) Update(ctx context.Context, in BrowsersUpdateInput) error {
 		}
 	}
 
+	// Handle telemetry changes
+	if in.Telemetry != "" {
+		t, err := buildUpdateTelemetryParam(in.Telemetry)
+		if err != nil {
+			return err
+		}
+		params.Telemetry = t
+	}
+
 	// Handle viewport changes
 	if hasViewportChange {
 		width, height, refreshRate, err := parseViewport(in.Viewport)
@@ -2229,6 +2249,7 @@ func init() {
 	browsersUpdateCmd.Flags().Bool("save-changes", false, "If set, save changes back to the profile when the session ends")
 	browsersUpdateCmd.Flags().String("viewport", "", "Browser viewport size (e.g., 1920x1080@25). Supported: 2560x1440@10, 1920x1080@25, 1920x1200@25, 1440x900@25, 1024x768@60, 1200x800@60, 1280x800@60")
 	browsersUpdateCmd.Flags().Bool("force", false, "Force viewport resize even when a live view or recording/replay is active")
+	browsersUpdateCmd.Flags().String("telemetry", "", "Update telemetry: --telemetry=all to enable, --telemetry=off to disable, --telemetry=network=on,page=off for per-category")
 
 	browsersCmd.AddCommand(browsersListCmd)
 	browsersCmd.AddCommand(browsersCreateCmd)
@@ -2494,6 +2515,7 @@ func init() {
 	browsersCreateCmd.Flags().Bool("viewport-interactive", false, "Interactively select viewport size from list")
 	browsersCreateCmd.Flags().String("pool-id", "", "Browser pool ID to acquire from (mutually exclusive with --pool-name)")
 	browsersCreateCmd.Flags().String("pool-name", "", "Browser pool name to acquire from (mutually exclusive with --pool-id)")
+	browsersCreateCmd.Flags().String("telemetry", "", "Configure telemetry: --telemetry=all to enable, --telemetry=off to disable, --telemetry=network=on,page=off for per-category")
 
 	// curl
 	curlCmd := &cobra.Command{
@@ -2520,6 +2542,15 @@ followed automatically by Chromium.`,
 	curlCmd.Flags().BoolP("silent", "s", false, "Suppress progress output")
 	browsersCmd.AddCommand(curlCmd)
 
+	telemetryRoot := &cobra.Command{Use: "telemetry", Short: "Browser telemetry operations"}
+	telemetryStream := &cobra.Command{Use: "stream <id>", Short: "Stream live telemetry events", Args: cobra.ExactArgs(1), RunE: runBrowsersTelemetryStream}
+	telemetryStream.Flags().StringSlice("categories", []string{}, "Filter by API event category (api,console,interaction,network,page,system); system covers monitor_* and cdp_* events")
+	telemetryStream.Flags().StringSlice("types", []string{}, "Filter by event type (e.g. network_response,console_error)")
+	telemetryStream.Flags().Int64("seq", -1, "Resume after sequence number N (Last-Event-ID); replays events with seq > N. Default -1 streams from now")
+	telemetryStream.Flags().StringP("output", "o", "", "Output format: json for newline-delimited JSON envelopes")
+	telemetryRoot.AddCommand(telemetryStream)
+	browsersCmd.AddCommand(telemetryRoot)
+
 	// no flags for view; it takes a single positional argument
 }
 
@@ -2563,6 +2594,7 @@ func runBrowsersCreate(cmd *cobra.Command, args []string) error {
 	viewportInteractive, _ := cmd.Flags().GetBool("viewport-interactive")
 	poolID, _ := cmd.Flags().GetString("pool-id")
 	poolName, _ := cmd.Flags().GetString("pool-name")
+	telemetry, _ := cmd.Flags().GetString("telemetry")
 	output, _ := cmd.Flags().GetString("output")
 
 	if poolID != "" && poolName != "" {
@@ -2672,6 +2704,7 @@ func runBrowsersCreate(cmd *cobra.Command, args []string) error {
 		StartURL:           startURL,
 		Extensions:         extensions,
 		Viewport:           viewport,
+		Telemetry:          telemetry,
 		Output:             output,
 	}
 
@@ -2730,6 +2763,7 @@ func runBrowsersUpdate(cmd *cobra.Command, args []string) error {
 	saveChanges, _ := cmd.Flags().GetBool("save-changes")
 	viewport, _ := cmd.Flags().GetString("viewport")
 	force, _ := cmd.Flags().GetBool("force")
+	telemetry, _ := cmd.Flags().GetString("telemetry")
 
 	svc := client.Browsers
 	b := BrowsersCmd{browsers: &svc}
@@ -2742,6 +2776,7 @@ func runBrowsersUpdate(cmd *cobra.Command, args []string) error {
 		ProfileSaveChanges: BoolFlag{Set: cmd.Flags().Changed("save-changes"), Value: saveChanges},
 		Viewport:           viewport,
 		Force:              force,
+		Telemetry:          telemetry,
 		Output:             out,
 	})
 }