fix: address review on telemetry events command

- Multi-category filtering: send each category as a repeated query param
  via option.WithQueryAdd. The SDK serializes []string as one comma-joined
  value, which the endpoint reads as a single bogus category; repeating the
  param matches the endpoint's expected form.
- Validate --limit client-side (1-100) instead of silently passing invalid
  values to the server.
- Add a client-side --types filter for parity with telemetry stream.
- Durable read: make the identifier-to-session lookup best-effort and fall
  back to the identifier when Get 404s, so an ended session's archive stays
  readable (verified live against staging).
- Frame the default vs --all paging in help, and document the events
  command in the README.

Author: archandatta

README.md

@@ -130,7 +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`
+- **Browser telemetry**: `telemetry stream` (live NDJSON), `telemetry events` (recorded archive)
 
 ### Authentication
 
@@ -320,6 +320,16 @@ Per-category updates are partial — only categories you name are changed; other
   - `-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`
 
+- `kernel browsers telemetry events <id>` - Read recorded telemetry events from the archive (the durable counterpart to live `stream`)
+  - By default returns the first page of events in the window; use `--all` to walk every page and dump the full archive
+  - `--limit <n>` - Max events per page (1-100, default 20)
+  - `--since <t>` / `--until <t>` - Window bounds as an RFC-3339 timestamp or a duration like `5m` (default window: last 5m)
+  - `--categories <list>` - Filter by event category (`console`, `network`, `page`, `interaction`, `control`, `connection`, `system`, `screenshot`, `captcha`, `monitor`)
+  - `--types <list>` - Filter by event type (e.g. `network_response`, `console_error`)
+  - `--all` - Fetch every page in the window instead of just the first
+  - `-o, --output json` - Output newline-delimited JSON envelopes
+  - Default output: tab-separated `<time>\t<seq>\t[<category>]\t<type>`
+
 ### Browser Process Control
 
 - `kernel browsers process exec <id> [--] [command...]` - Execute a command synchronously

cmd/browsers.go

@@ -2750,12 +2750,21 @@ followed automatically by Chromium.`,
 	telemetryStream.Flags().StringP("output", "o", "", "Output format: json for newline-delimited JSON envelopes")
 	telemetryRoot.AddCommand(telemetryStream)
 
-	telemetryEvents := &cobra.Command{Use: "events <id>", Short: "Read recorded telemetry events", Args: cobra.ExactArgs(1), RunE: runBrowsersTelemetryEvents}
+	telemetryEvents := &cobra.Command{
+		Use:   "events <id>",
+		Short: "Read recorded telemetry events",
+		Long: "Read recorded telemetry events for a browser session, in ascending sequence order.\n\n" +
+			"By default this returns the first page of events in the window (most recent window is the\n" +
+			"last 5m; adjust with --since/--until). Use --all to walk every page and dump the full archive.",
+		Args: cobra.ExactArgs(1),
+		RunE: runBrowsersTelemetryEvents,
+	}
 	telemetryEvents.Flags().Int64("limit", 0, "Max events per page (1-100, default 20)")
 	telemetryEvents.Flags().String("since", "", "Window start: RFC-3339 timestamp or duration like 5m (default 5m)")
 	telemetryEvents.Flags().String("until", "", "Window end (exclusive): RFC-3339 timestamp or duration like 5m")
 	telemetryEvents.Flags().StringSlice("categories", []string{}, "Filter by event category (console,network,page,interaction,control,connection,system,screenshot,captcha,monitor)")
-	telemetryEvents.Flags().Bool("all", false, "Fetch every page instead of just the first")
+	telemetryEvents.Flags().StringSlice("types", []string{}, "Filter by event type (e.g. network_response,console_error)")
+	telemetryEvents.Flags().Bool("all", false, "Fetch every page (the full archive in the window) instead of just the first")
 	telemetryEvents.Flags().StringP("output", "o", "", "Output format: json for newline-delimited JSON envelopes")
 	telemetryRoot.AddCommand(telemetryEvents)
 

cmd/browsers_telemetry.go

@@ -242,6 +242,7 @@ type BrowsersTelemetryEventsInput struct {
 	Since      string
 	Until      string
 	Categories []string
+	Types      []string
 	All        bool
 	Output     string
 }
@@ -253,6 +254,9 @@ func (b BrowsersCmd) TelemetryEvents(ctx context.Context, in BrowsersTelemetryEv
 	if err := validateJSONOutput(in.Output); err != nil {
 		return err
 	}
+	if in.Limit != 0 && (in.Limit < 1 || in.Limit > 100) {
+		return fmt.Errorf("invalid --limit value %d: must be between 1 and 100", in.Limit)
+	}
 	for _, c := range in.Categories {
 		if !slices.Contains(streamFilterCategories, c) {
 			return fmt.Errorf("invalid --categories value %q: must be one of %s", c, strings.Join(streamFilterCategories, ", "))
@@ -269,16 +273,27 @@ func (b BrowsersCmd) TelemetryEvents(ctx context.Context, in BrowsersTelemetryEv
 	if in.Until != "" {
 		params.Until = kernel.Opt(in.Until)
 	}
-	if len(in.Categories) > 0 {
-		params.Category = in.Categories
+	// Send each category as a repeated query param. The SDK serializes a []string
+	// field as a single comma-joined value, but the endpoint expects the parameter
+	// repeated, so a comma-joined value matches no category.
+	opts := make([]option.RequestOption, 0, len(in.Categories))
+	for _, c := range in.Categories {
+		opts = append(opts, option.WithQueryAdd("category", c))
 	}
 
-	br, err := b.browsers.Get(ctx, in.Identifier, kernel.BrowserGetParams{})
-	if err != nil {
-		return util.CleanedUpSdkError{Err: err}
+	// Resolve a name to a session ID when possible, but fall back to the identifier
+	// as-is: the events archive outlives the session, so Get can 404 for an ended
+	// session whose telemetry is still readable.
+	sessionID := in.Identifier
+	if br, gerr := b.browsers.Get(ctx, in.Identifier, kernel.BrowserGetParams{}); gerr == nil {
+		sessionID = br.SessionID
 	}
 
 	emit := func(ev kernel.BrowserTelemetryEventsResponse) error {
+		// Category filtering is server-side; types are filtered here, matching stream.
+		if !shouldEmit(ev.Event.Category, ev.Event.Type, nil, in.Types) {
+			return nil
+		}
 		if in.Output == "json" {
 			return util.PrintCompactJSONLine(ev)
 		}
@@ -288,7 +303,7 @@ func (b BrowsersCmd) TelemetryEvents(ctx context.Context, in BrowsersTelemetryEv
 	}
 
 	if in.All {
-		pager := b.telemetry.EventsAutoPaging(ctx, br.SessionID, params)
+		pager := b.telemetry.EventsAutoPaging(ctx, sessionID, params, opts...)
 		for pager.Next() {
 			if err := emit(pager.Current()); err != nil {
 				return err
@@ -300,7 +315,7 @@ func (b BrowsersCmd) TelemetryEvents(ctx context.Context, in BrowsersTelemetryEv
 		return nil
 	}
 
-	page, err := b.telemetry.Events(ctx, br.SessionID, params)
+	page, err := b.telemetry.Events(ctx, sessionID, params, opts...)
 	if err != nil {
 		return util.CleanedUpSdkError{Err: err}
 	}
@@ -322,6 +337,7 @@ func runBrowsersTelemetryEvents(cmd *cobra.Command, args []string) error {
 	since, _ := cmd.Flags().GetString("since")
 	until, _ := cmd.Flags().GetString("until")
 	categories, _ := cmd.Flags().GetStringSlice("categories")
+	types, _ := cmd.Flags().GetStringSlice("types")
 	all, _ := cmd.Flags().GetBool("all")
 	b := BrowsersCmd{browsers: &svc, telemetry: &svc.Telemetry}
 	return b.TelemetryEvents(cmd.Context(), BrowsersTelemetryEventsInput{
@@ -330,6 +346,7 @@ func runBrowsersTelemetryEvents(cmd *cobra.Command, args []string) error {
 		Since:      since,
 		Until:      until,
 		Categories: categories,
+		Types:      types,
 		All:        all,
 		Output:     out,
 	})

cmd/browsers_telemetry_test.go

@@ -36,7 +36,7 @@ func captureStdout(t *testing.T, fn func()) string {
 
 type FakeBrowserTelemetryService struct {
 	StreamFunc           func() *ssestream.Stream[kernel.BrowserTelemetryStreamResponse]
-	EventsFunc           func(id string, query kernel.BrowserTelemetryEventsParams) (*pagination.OffsetPagination[kernel.BrowserTelemetryEventsResponse], error)
+	EventsFunc           func(id string, query kernel.BrowserTelemetryEventsParams, opts ...option.RequestOption) (*pagination.OffsetPagination[kernel.BrowserTelemetryEventsResponse], error)
 	EventsAutoPagingFunc func() *pagination.OffsetPaginationAutoPager[kernel.BrowserTelemetryEventsResponse]
 }
 
@@ -49,7 +49,7 @@ func (f *FakeBrowserTelemetryService) StreamStreaming(ctx context.Context, id st
 
 func (f *FakeBrowserTelemetryService) Events(ctx context.Context, id string, query kernel.BrowserTelemetryEventsParams, opts ...option.RequestOption) (*pagination.OffsetPagination[kernel.BrowserTelemetryEventsResponse], error) {
 	if f.EventsFunc != nil {
-		return f.EventsFunc(id, query)
+		return f.EventsFunc(id, query, opts...)
 	}
 	return &pagination.OffsetPagination[kernel.BrowserTelemetryEventsResponse]{}, nil
 }
@@ -108,8 +108,9 @@ func TestTelemetryEvents_SinglePageTextAndParams(t *testing.T) {
 	}}
 	var gotID string
 	var gotQuery kernel.BrowserTelemetryEventsParams
-	fakeTelemetry := &FakeBrowserTelemetryService{EventsFunc: func(id string, query kernel.BrowserTelemetryEventsParams) (*pagination.OffsetPagination[kernel.BrowserTelemetryEventsResponse], error) {
-		gotID, gotQuery = id, query
+	var gotOpts []option.RequestOption
+	fakeTelemetry := &FakeBrowserTelemetryService{EventsFunc: func(id string, query kernel.BrowserTelemetryEventsParams, opts ...option.RequestOption) (*pagination.OffsetPagination[kernel.BrowserTelemetryEventsResponse], error) {
+		gotID, gotQuery, gotOpts = id, query, opts
 		return telemetryEventsPage(t,
 			`{"event":{"type":"network_response","category":"network","ts":1000000},"seq":7}`,
 			`{"event":{"type":"network_request","category":"network","ts":2000000},"seq":8}`,
@@ -122,15 +123,17 @@ func TestTelemetryEvents_SinglePageTextAndParams(t *testing.T) {
 		Limit:      5,
 		Since:      "5m",
 		Until:      "2020-01-01T00:00:00Z",
-		Categories: []string{"network"},
+		Categories: []string{"console", "network"},
 	})
 
 	assert.NoError(t, err)
 	assert.Equal(t, "session123", gotID)
 	assert.Equal(t, int64(5), gotQuery.Limit.Value)
 	assert.Equal(t, "5m", gotQuery.Since.Value)
 	assert.Equal(t, "2020-01-01T00:00:00Z", gotQuery.Until.Value)
-	assert.Equal(t, []string{"network"}, gotQuery.Category)
+	// Categories go out as repeated query params, not the comma-joined typed field.
+	assert.Empty(t, gotQuery.Category)
+	assert.Len(t, gotOpts, 2)
 	out := outBuf.String()
 	assert.Contains(t, out, "network_response")
 	assert.Contains(t, out, "network_request")
@@ -142,7 +145,7 @@ func TestTelemetryEvents_SinglePageJSON(t *testing.T) {
 	fakeBrowsers := &FakeBrowsersService{GetFunc: func(ctx context.Context, id string, query kernel.BrowserGetParams, opts ...option.RequestOption) (*kernel.BrowserGetResponse, error) {
 		return &kernel.BrowserGetResponse{SessionID: id}, nil
 	}}
-	fakeTelemetry := &FakeBrowserTelemetryService{EventsFunc: func(id string, query kernel.BrowserTelemetryEventsParams) (*pagination.OffsetPagination[kernel.BrowserTelemetryEventsResponse], error) {
+	fakeTelemetry := &FakeBrowserTelemetryService{EventsFunc: func(id string, query kernel.BrowserTelemetryEventsParams, opts ...option.RequestOption) (*pagination.OffsetPagination[kernel.BrowserTelemetryEventsResponse], error) {
 		return telemetryEventsPage(t, `{"event":{"type":"network_response","ts":1000000},"seq":1}`), nil
 	}}
 	b := BrowsersCmd{browsers: fakeBrowsers, telemetry: fakeTelemetry}
@@ -156,15 +159,58 @@ func TestTelemetryEvents_SinglePageJSON(t *testing.T) {
 	assert.Contains(t, out, "network_response")
 }
 
-func TestTelemetryEvents_GetErrorSurfaces(t *testing.T) {
+func TestTelemetryEvents_InvalidLimitErrors(t *testing.T) {
+	b := BrowsersCmd{browsers: &FakeBrowsersService{}, telemetry: &FakeBrowserTelemetryService{}}
+
+	for _, lim := range []int64{-1, 101} {
+		err := b.TelemetryEvents(context.Background(), BrowsersTelemetryEventsInput{Identifier: "session123", Limit: lim})
+		assert.Error(t, err)
+		assert.Contains(t, err.Error(), "invalid --limit value")
+	}
+}
+
+func TestTelemetryEvents_TypesFilterDropsNonMatching(t *testing.T) {
+	setupStdoutCapture(t)
 	fakeBrowsers := &FakeBrowsersService{GetFunc: func(ctx context.Context, id string, query kernel.BrowserGetParams, opts ...option.RequestOption) (*kernel.BrowserGetResponse, error) {
-		return nil, fmt.Errorf("boom")
+		return &kernel.BrowserGetResponse{SessionID: id}, nil
 	}}
-	b := BrowsersCmd{browsers: fakeBrowsers, telemetry: &FakeBrowserTelemetryService{}}
+	fakeTelemetry := &FakeBrowserTelemetryService{EventsFunc: func(id string, query kernel.BrowserTelemetryEventsParams, opts ...option.RequestOption) (*pagination.OffsetPagination[kernel.BrowserTelemetryEventsResponse], error) {
+		return telemetryEventsPage(t,
+			`{"event":{"type":"network_request","category":"network","ts":1000000},"seq":1}`,
+			`{"event":{"type":"network_response","category":"network","ts":2000000},"seq":2}`,
+		), nil
+	}}
+	b := BrowsersCmd{browsers: fakeBrowsers, telemetry: fakeTelemetry}
 
-	err := b.TelemetryEvents(context.Background(), BrowsersTelemetryEventsInput{Identifier: "session123"})
+	err := b.TelemetryEvents(context.Background(), BrowsersTelemetryEventsInput{
+		Identifier: "session123",
+		Types:      []string{"network_response"},
+	})
 
-	assert.Error(t, err)
+	assert.NoError(t, err)
+	assert.Contains(t, outBuf.String(), "network_response")
+	assert.NotContains(t, outBuf.String(), "network_request")
+}
+
+func TestTelemetryEvents_FallsBackToIdentifierWhenGetFails(t *testing.T) {
+	setupStdoutCapture(t)
+	// Get 404s (e.g. an ended session); the events archive is still readable, so the
+	// command falls back to the identifier as the session id rather than failing.
+	fakeBrowsers := &FakeBrowsersService{GetFunc: func(ctx context.Context, id string, query kernel.BrowserGetParams, opts ...option.RequestOption) (*kernel.BrowserGetResponse, error) {
+		return nil, fmt.Errorf("not found")
+	}}
+	var gotID string
+	fakeTelemetry := &FakeBrowserTelemetryService{EventsFunc: func(id string, query kernel.BrowserTelemetryEventsParams, opts ...option.RequestOption) (*pagination.OffsetPagination[kernel.BrowserTelemetryEventsResponse], error) {
+		gotID = id
+		return telemetryEventsPage(t, `{"event":{"type":"cdp_disconnect","category":"connection","ts":1000000},"seq":1}`), nil
+	}}
+	b := BrowsersCmd{browsers: fakeBrowsers, telemetry: fakeTelemetry}
+
+	err := b.TelemetryEvents(context.Background(), BrowsersTelemetryEventsInput{Identifier: "ended-session-id"})
+
+	assert.NoError(t, err)
+	assert.Equal(t, "ended-session-id", gotID)
+	assert.Contains(t, outBuf.String(), "cdp_disconnect")
 }
 
 func TestTelemetryStream_NilTelemetryErrors(t *testing.T) {