kernel
diff --git a/‎server/lib/cdpmonitor/README.md‎
Lines changed: 6 additions & 5 deletions b/‎server/lib/cdpmonitor/README.md‎
Lines changed: 6 additions & 5 deletions
diff --git a/‎server/lib/cdpmonitor/chrome_e2e_test.go‎
Lines changed: 51 additions & 0 deletions b/‎server/lib/cdpmonitor/chrome_e2e_test.go‎
Lines changed: 51 additions & 0 deletions
diff --git a/‎server/lib/cdpmonitor/handlers.go‎
Lines changed: 131 additions & 7 deletions b/‎server/lib/cdpmonitor/handlers.go‎
Lines changed: 131 additions & 7 deletions
@@ -10,7 +10,7 @@ Chrome can restart independently of the monitor. When that happens, `UpstreamPro
 
 ## Event taxonomy
 
-**CDP-derived** (1-to-1 with a CDP notification): `console_log`, `console_error`, `network_request`, `network_response`, `network_loading_failed`, `page_tab_opened`, `page_navigation`, `page_dom_content_loaded`, `page_load`, `page_layout_shift`, `page_lcp`
+**CDP-derived** (1-to-1 with a CDP notification): `console_log`, `console_error`, `network_request`, `network_response`, `network_loading_failed`, `proxy_error` (classified from a branded 5xx response carrying the `X-Kernel-Proxy-Error` header), `page_tab_opened`, `page_navigation`, `page_dom_content_loaded`, `page_load`, `page_layout_shift`, `page_lcp`. `proxy_error` is an opt-in per-session/per-URL refinement of the raw `network` events: it is only observable while the network category (CDP collector) is running, so it is not a default-on alerting signal.
 
 **Computed** (inferred from sequences of CDP events): `network_idle` (fires when in-flight requests drop to zero), `page_layout_settled` (1 s after `page_load` with no intervening layout shifts), `page_navigation_settled` (fires once `page_dom_content_loaded` and `page_layout_settled` have both fired for the same navigation; intentionally independent of `network_idle` so that a single hung request cannot stall the event).
 
@@ -156,10 +156,10 @@ target_id          <- one per tab/window; stable across navigations
 | --- | --- | --- |
 | `target_id` | `source.metadata`, most `data` objects | The browser tab. Use this to group all events from one tab session. |
 | `cdp_session_id` | `source.metadata` | The WebSocket sub-channel. Not stable across reconnects. |
-| `frame_id` | `page_navigation`, `network_request`, `network_response`, `network_loading_failed` | The frame the request or navigation belongs to. Top-level frame has no `parent_frame_id`. |
+| `frame_id` | `page_navigation`, `network_request`, `network_response`, `network_loading_failed`, `proxy_error` | The frame the request or navigation belongs to. Top-level frame has no `parent_frame_id`. |
 | `source_frame_id` | `page_layout_shift`, `page_lcp` | The frame where the layout shift or LCP element occurred. Distinct from the nav context `frame_id`, which is always the top-level navigated frame. |
-| `loader_id` | `page_navigation`, `network_request`, `network_response` | The document load that owns a request. Join `network_request.loader_id` to `page_navigation.loader_id` to correlate requests with the navigation that triggered them. |
-| `request_id` | `network_request`, `network_response`, `network_loading_failed` | A single request chain (including redirects). Links request to its eventual response or failure. |
+| `loader_id` | `page_navigation`, `network_request`, `network_response`, `proxy_error` | The document load that owns a request. Join `network_request.loader_id` to `page_navigation.loader_id` to correlate requests with the navigation that triggered them. |
+| `request_id` | `network_request`, `network_response`, `network_loading_failed`, `proxy_error` | A single request chain (including redirects). Links request to its eventual response or failure. |
 
 ### Navigation context fields
 
@@ -171,7 +171,7 @@ Most event `data` objects include a nav context block stamped at the last `page_
 | `frame_id` | Frame ID of the navigated top-level frame. |
 | `loader_id` | Loader ID of the current document. |
 | `url` | URL of the current page at the time of the last navigation. |
-| `nav_seq` | Monotonically increasing counter, incremented on each `page_navigation`. Use it to detect that the page has navigated between two events in the same session. For `network_request`/`network_response`/`network_loading_failed`, the `nav_seq` is captured at request-send time and carried forward to the response so a request/response pair always shares an epoch. |
+| `nav_seq` | Monotonically increasing counter, incremented on each `page_navigation`. Use it to detect that the page has navigated between two events in the same session. For `network_request`/`network_response`/`network_loading_failed`/`proxy_error`, the `nav_seq` is captured at request-send time and carried forward to the response so a request/response pair always shares an epoch. |
 
 ### Events that do not compose `BrowserEventContext`
 
@@ -202,6 +202,7 @@ Unless otherwise noted, events also include the nav context fields described abo
 | `network_request` | `request_id`, `loader_id`, `frame_id`, `document_url`, `method`, `url`, `headers`, `initiator_type`. Optional: `post_data`, `resource_type`, `is_redirect` + `redirect_url`. |
 | `network_response` | `request_id`, `loader_id`, `frame_id`, `method`, `url`, `status`, `headers`. Optional: `status_text`, `mime_type`, `resource_type`, `body` (truncated text body for textual MIME types). |
 | `network_loading_failed` | `request_id`, `error_text`, `canceled`. Optional (absent when the request record was not found): `url`, `loader_id`, `frame_id`, `resource_type`. |
+| `proxy_error` | `request_id`, `code` (typed enum matching the metro header values), `status` (502). Optional: `url`, `loader_id`, `frame_id`, `method`, `resource_type`. Emitted when a 502 response carries the `X-Kernel-Proxy-Error` header; unknown codes are dropped and emission is sampled to at most one per session+code+resource_type per second. WebSocket handshakes are not classified (documented non-goal). |
 
 #### Page events
 
 
@@ -4,6 +4,8 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"net/http"
+	"net/http/httptest"
 	"os"
 	"os/exec"
 	"strings"
@@ -14,6 +16,7 @@ import (
 
 	"github.com/coder/websocket"
 	"github.com/coder/websocket/wsjson"
+	"github.com/kernel/kernel-images/server/lib/events"
 	"github.com/stretchr/testify/require"
 )
 
@@ -307,3 +310,51 @@ func (c *cdpConn) evalRect(t *testing.T, ctx context.Context, sessionID, selecto
 	require.NoError(t, json.Unmarshal([]byte(resp.Result.Result.Value), &rect))
 	return rect
 }
+
+// TestProxyErrorE2E drives a real browser to a stub origin that serves a branded
+// 502 with the X-Kernel-Proxy-Error header and asserts the CDP collector emits a
+// proxy_error telemetry event. It exercises the image-side detection
+// (Network.responseReceived header classification) end to end through a real
+// browser, without needing the metro host-proxy.
+func TestProxyErrorE2E(t *testing.T) {
+	if os.Getenv("KERNEL_CDPMONITOR_CHROME_E2E") == "" {
+		t.Skip("set KERNEL_CDPMONITOR_CHROME_E2E=1 to run the real-Chromium proxy error test")
+	}
+	chrome := findChromium(t)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
+	defer cancel()
+
+	stub := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("X-Kernel-Proxy-Error", "provider_blacklisted")
+		w.WriteHeader(http.StatusBadGateway)
+		fmt.Fprintln(w, "<html><body>proxy error</body></html>")
+	}))
+	defer stub.Close()
+
+	browserWS := launchChromium(t, ctx, chrome)
+	cdp := dialCDP(t, ctx, browserWS)
+	defer cdp.close()
+
+	ec := newEventCollector()
+	m := New(&staticUpstream{url: browserWS}, ec.publishFn(), 99, discardLogger, nil)
+	require.NoError(t, m.Start(ctx))
+	defer m.Stop()
+
+	// A fresh page target the monitor auto-attaches to and enables Network on.
+	targetID := cdp.call(t, ctx, "", "Target.createTarget", map[string]any{"url": "about:blank"}).targetID(t)
+	ec.waitFor(t, EventTabOpened, 5*time.Second)
+
+	// Drive navigation from a separate flat session on the same target.
+	sessionID := cdp.call(t, ctx, "", "Target.attachToTarget", map[string]any{"targetId": targetID, "flatten": true}).sessionID(t)
+	cdp.call(t, ctx, sessionID, "Page.enable", nil)
+	cdp.call(t, ctx, sessionID, "Page.navigate", map[string]any{"url": stub.URL})
+
+	ev := ec.waitFor(t, EventProxyError, 10*time.Second)
+	require.Equal(t, events.Network, ev.Category)
+	require.Equal(t, "Network.responseReceived", *ev.Source.Event)
+	var data map[string]any
+	require.NoError(t, json.Unmarshal(ev.Data, &data))
+	require.Equal(t, "provider_blacklisted", data["code"])
+	require.Equal(t, float64(502), data["status"])
+}
@@ -491,16 +491,57 @@ func (m *Monitor) handleNetworkRequest(p cdpNetworkRequestWillBeSentParams, sess
 	}
 }
 
-func (m *Monitor) handleResponseReceived(p cdpNetworkResponseReceivedParams, _ string) {
+func (m *Monitor) handleResponseReceived(p cdpNetworkResponseReceivedParams, sessionID string) {
 	m.pendReqMu.Lock()
-	if state, ok := m.pendingRequests[p.RequestID]; ok {
-		state.status = p.Response.Status
-		state.statusText = p.Response.StatusText
-		state.resHeaders = p.Response.Headers
-		state.mimeType = p.Response.MimeType
-		m.pendingRequests[p.RequestID] = state
+	var (
+		state networkReqState
+		ok    bool
+	)
+	if st, present := m.pendingRequests[p.RequestID]; present {
+		st.status = p.Response.Status
+		st.statusText = p.Response.StatusText
+		st.resHeaders = p.Response.Headers
+		st.mimeType = p.Response.MimeType
+		m.pendingRequests[p.RequestID] = st
+		state, ok = st, true
 	}
 	m.pendReqMu.Unlock()
+
+	// Branded proxy error pages are always served as 502 (the producer
+	// hardcodes that status), so gate detection on it exactly and leave every
+	// other response paying nothing extra beyond the status compare.
+	code, isProxyErr := "", false
+	if p.Response.Status == 502 {
+		code, isProxyErr = proxyErrorCode(p.Response.Headers)
+	}
+	if !isProxyErr {
+		return
+	}
+
+	var (
+		navSeq  int64
+		method  string
+		url     *string
+		frame   *string
+		loader  *string
+		resType string
+	)
+	if ok {
+		navSeq, method = state.navSeq, state.method
+		url, frame, loader = optPtr(state.url), optPtr(state.frameID), optPtr(state.loaderID)
+		resType = state.resourceType
+	} else {
+		// A branded response with no tracked pending request (e.g. in flight
+		// when CDP attached) still carries its context on the params; fall back
+		// to the current nav sequence like Network.loadingFailed so the event
+		// stays correlateable by nav_seq.
+		url, frame, loader = optPtr(p.Response.URL), optPtr(p.FrameID), optPtr(p.LoaderID)
+		resType = p.Type
+		if cs := m.computedFor(sessionID); cs != nil {
+			navSeq = int64(cs.currentNavSeq())
+		}
+	}
+	m.publishProxyError(sessionID, p.RequestID, code, p.Response.Status, navSeq, method, resType, url, frame, loader)
 }
 
 func (m *Monitor) handleLoadingFinished(ctx context.Context, p cdpNetworkLoadingFinishedParams, sessionID string) {
@@ -622,13 +663,96 @@ func (m *Monitor) handleLoadingFailed(p cdpNetworkLoadingFailedParams, sessionID
 	}
 	data, _ := json.Marshal(failPayload)
 	m.publishEvent(EventNetworkLoadingFailed, events.Network, oapi.BrowserEventSource{Kind: oapi.Cdp}, "Network.loadingFailed", data, sessionID)
+
 	if ok {
 		if cs := m.computedFor(state.sessionID); cs != nil {
 			cs.onLoadingFinished()
 		}
 	}
 }
 
+// proxyErrorHeader is the response header the metro egress host-proxy sets on
+// branded 502 error pages to signal a proxy-layer failure to automation clients.
+const proxyErrorHeader = "x-kernel-proxy-error"
+
+// proxyErrorCode returns the X-Kernel-Proxy-Error header value from a CDP
+// response header map, if present. Callers gate on 5xx status before reaching
+// here, so the full header map decode is already off the common path.
+func proxyErrorCode(resHeaders json.RawMessage) (string, bool) {
+	if len(resHeaders) == 0 {
+		return "", false
+	}
+	var hdrs map[string]any
+	if err := json.Unmarshal(resHeaders, &hdrs); err != nil {
+		return "", false
+	}
+	for k, v := range hdrs {
+		if strings.EqualFold(k, proxyErrorHeader) {
+			if s, ok := v.(string); ok && s != "" {
+				return s, true
+			}
+		}
+	}
+	return "", false
+}
+
+// proxyErrorMinInterval bounds proxy_error volume: proxy failures repeat per
+// request during an outage, and a single typed signal per code is enough to
+// alert on while keeping the fixed-capacity ring usable at peak.
+const proxyErrorMinInterval = time.Second
+
+// proxyErrorRateLimited reports whether a proxy_error for the given session,
+// code, and resource type should be dropped. Codes are validated against the
+// published enum (kept in lockstep with the metro egressproxy header codes in
+// kernel/kernel packages/metro-api/lib/egressproxy/proxy_error.go), so unknown
+// wire values are dropped and never occupy a rate-limit slot. At most one event
+// per session+code+resource_type per interval is emitted; the interval is a
+// sampling bound, not a per-URL dedup.
+func (m *Monitor) proxyErrorRateLimited(sessionID, code, resourceType string) bool {
+	if !oapi.BrowserProxyErrorEventDataCode(code).Valid() {
+		m.log.Warn("cdpmonitor: dropping proxy_error with unknown code", "code", code)
+		return true
+	}
+	now := time.Now()
+	key := sessionID + ":" + code + ":" + resourceType
+	m.proxyRateMu.Lock()
+	defer m.proxyRateMu.Unlock()
+	last, ok := m.proxyLastEmit[key]
+	if ok && now.Sub(last) < proxyErrorMinInterval {
+		return true
+	}
+	m.proxyLastEmit[key] = now
+	return false
+}
+
+// publishProxyError emits a typed proxy_error event for a branded proxy-layer
+// failure observed on the browser's network path (a 5xx response carrying the
+// X-Kernel-Proxy-Error header). The code is the header value, validated against
+// the published enum.
+func (m *Monitor) publishProxyError(sessionID, requestID, code string, status int, navSeq int64, method, resourceType string, url, frameID, loaderID *string) {
+	if m.proxyErrorRateLimited(sessionID, code, resourceType) {
+		return
+	}
+	m.sessionsMu.RLock()
+	info := m.sessions[sessionID]
+	m.sessionsMu.RUnlock()
+	data, _ := json.Marshal(oapi.BrowserProxyErrorEventData{
+		SessionId:    sessionID,
+		TargetId:     info.targetID,
+		TargetType:   oapi.BrowserTargetType(info.targetType),
+		NavSeq:       navSeq,
+		RequestId:    requestID,
+		Url:          url,
+		FrameId:      frameID,
+		LoaderId:     loaderID,
+		Method:       optPtr(method),
+		Status:       status,
+		Code:         oapi.BrowserProxyErrorEventDataCode(code),
+		ResourceType: optPtr(resourceType),
+	})
+	m.publishEvent(EventProxyError, events.Network, oapi.BrowserEventSource{Kind: oapi.Cdp}, "Network.responseReceived", data, sessionID)
+}
+
 func (m *Monitor) handleFrameNavigated(p cdpPageFrameNavigatedParams, sessionID string) {
 	// Pre-fetch target info and computedState before acquiring pendReqMu to
 	// avoid a pendReqMu → sessionsMu ordering cycle.