From 21e2038595047a1ab2dfb2c79489acbb7c94d519 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miguel=20=C3=81ngel?= Date: Wed, 4 Nov 2026 21:13:20 +0000 Subject: [PATCH] fix(cli): report why a reverse session could not be recorded (#7186) --- packages/cli/src/heygen/reverse.test.ts | 57 ++++++++++++++++++++++++- packages/cli/src/heygen/reverse.ts | 26 ++++++++--- packages/cli/src/telemetry/events.ts | 17 ++++++++ 3 files changed, 94 insertions(+), 6 deletions(-) diff --git a/packages/cli/src/heygen/reverse.test.ts b/packages/cli/src/heygen/reverse.test.ts index 3ca00903ab..9eb53cee83 100644 --- a/packages/cli/src/heygen/reverse.test.ts +++ b/packages/cli/src/heygen/reverse.test.ts @@ -10,6 +10,9 @@ vi.mock("../cloud/auth.js", () => ({ resolveCloudBaseUrl: () => "https://api.example.test", })); +const track = vi.hoisted(() => vi.fn()); +vi.mock("../telemetry/events.js", () => ({ trackReverseStartUnrecorded: track })); + const { reverseSurface, reverseUpgradeUrl, startReverseSession } = await import("./reverse.js"); const START_URL = "https://api2.example.test/v1/hyperframes/reverse/start"; @@ -38,6 +41,7 @@ const freePlan = () => Response.json({ code: 100, data: { subscription: null, us beforeEach(() => { calls = []; + track.mockClear(); auth.signedIn = true; vi.stubEnv("HYPERFRAMES_CLIENT", ""); vi.stubEnv("HYPERFRAMES_MOCK_PLAN", ""); @@ -118,6 +122,7 @@ describe("startReverseSession", () => { expect(await startReverseSession()).toEqual({ recorded: false, reason: "unavailable", + cause: "http_4xx", plan: "free", }); expect(calls.map((c) => c.url)).toEqual([START_URL, PLAN_URL]); @@ -127,7 +132,11 @@ describe("startReverseSession", () => { vi.stubGlobal("fetch", async () => { throw new TypeError("fetch failed"); }); - expect(await startReverseSession()).toEqual({ recorded: false, reason: "unavailable" }); + expect(await startReverseSession()).toEqual({ + recorded: false, + reason: "unavailable", + cause: "network", + }); }); it.each([ @@ -145,6 +154,52 @@ describe("startReverseSession", () => { serve({ [START_URL]: () => new Response("boom", { status: 500 }) }); expect(await startReverseSession()).toMatchObject({ recorded: false, reason: "unavailable" }); }); + + it.each([ + [500, "http_5xx"], + [401, "http_4xx"], + [403, "http_4xx"], + ])("reports status %i as %s", async (status, cause) => { + serve({ [START_URL]: () => new Response("no", { status }) }); + expect(await startReverseSession()).toMatchObject({ recorded: false, cause }); + expect(track).toHaveBeenCalledExactlyOnceWith({ cause, status }); + }); + + it("reports a network failure", async () => { + vi.stubGlobal("fetch", async () => { + throw new TypeError("fetch failed"); + }); + await startReverseSession(); + expect(track).toHaveBeenCalledExactlyOnceWith({ cause: "network", status: undefined }); + }); + + it("reports a timeout as a network failure", async () => { + vi.stubGlobal("fetch", async () => { + throw new DOMException("timed out", "TimeoutError"); + }); + await startReverseSession(); + expect(track).toHaveBeenCalledExactlyOnceWith({ cause: "network", status: undefined }); + }); + + it("reports a 200 whose body is not a session", async () => { + serve({ [START_URL]: () => new Response("", { status: 200 }) }); + await startReverseSession(); + expect(track).toHaveBeenCalledExactlyOnceWith({ cause: "bad_body", status: undefined }); + }); + + it("reports nothing when the session is recorded", async () => { + serve({ + [START_URL]: () => Response.json({ session_id: SESSION, plan: "pro", gate: "record" }), + }); + await startReverseSession(); + expect(track).not.toHaveBeenCalled(); + }); + + it("reports not_signed_in", async () => { + auth.signedIn = false; + await startReverseSession(); + expect(track).toHaveBeenCalledExactlyOnceWith({ cause: "not_signed_in" }); + }); }); describe("reverseUpgradeUrl", () => { diff --git a/packages/cli/src/heygen/reverse.ts b/packages/cli/src/heygen/reverse.ts index f1e24e7ccc..8b837e0c40 100644 --- a/packages/cli/src/heygen/reverse.ts +++ b/packages/cli/src/heygen/reverse.ts @@ -1,5 +1,6 @@ // The reverse session the server opens when a reverse run starts, and the plan it read for the account. import { resolveCloudAuthHeaders, resolveCloudBaseUrl } from "../cloud/auth.js"; +import { trackReverseStartUnrecorded, type ReverseUnrecordedCause } from "../telemetry/events.js"; import { normalizeReverseSessionId } from "../utils/projectConfig.js"; import { pageUrl, readPlan } from "./plan.js"; @@ -16,7 +17,12 @@ export interface ReverseSession { export type ReverseStart = | { recorded: true; session: ReverseSession } - | { recorded: false; reason: "not_signed_in" | "unavailable"; plan?: "free" | "pro" }; + | { + recorded: false; + reason: "not_signed_in" | "unavailable"; + cause?: ReverseUnrecordedCause; + plan?: "free" | "pro"; + }; const isRecord = (v: unknown): v is Record => typeof v === "object" && v !== null && !Array.isArray(v); @@ -75,8 +81,11 @@ export async function startReverseSession( try { headers = await resolveCloudAuthHeaders(); } catch { + trackReverseStartUnrecorded({ cause: "not_signed_in" }); return { recorded: false, reason: "not_signed_in" }; } + let cause: ReverseUnrecordedCause; + let status: number | undefined; try { const res = await fetch(`${api2BaseUrl()}/v1/hyperframes/reverse/start`, { method: "POST", @@ -87,11 +96,18 @@ export async function startReverseSession( }), signal: AbortSignal.timeout(10_000), }); - const session = res.ok ? parseSession(await res.json().catch(() => null)) : undefined; - if (session) return { recorded: true, session }; + if (res.ok) { + const session = parseSession(await res.json().catch(() => null)); + if (session) return { recorded: true, session }; + cause = "bad_body"; + } else { + status = res.status; + cause = res.status >= 500 ? "http_5xx" : res.status >= 400 ? "http_4xx" : "http_other"; + } } catch { - // Fall through to the unrecorded answer below. + cause = "network"; } + trackReverseStartUnrecorded({ cause, status }); const plan = await fallbackPlan().catch(() => undefined); - return { recorded: false, reason: "unavailable", ...(plan ? { plan } : {}) }; + return { recorded: false, reason: "unavailable", cause, ...(plan ? { plan } : {}) }; } diff --git a/packages/cli/src/telemetry/events.ts b/packages/cli/src/telemetry/events.ts index 3ed0beada3..ea7d8a8324 100644 --- a/packages/cli/src/telemetry/events.ts +++ b/packages/cli/src/telemetry/events.ts @@ -993,6 +993,23 @@ export function trackTranscribeUnavailable(props: { optional: boolean }): void { trackEvent("transcribe_unavailable", { optional: props.optional }); } +// A reverse session could not be recorded. `cause` is a closed set (never free text) so an +// alert can page on a failing start route; `status` is the HTTP status when there was one. +export type ReverseUnrecordedCause = + | "not_signed_in" + | "http_4xx" + | "http_5xx" + | "http_other" + | "network" + | "bad_body"; + +export function trackReverseStartUnrecorded(props: { + cause: ReverseUnrecordedCause; + status?: number; +}): void { + trackEvent("cli_reverse_start_unrecorded", { cause: props.cause, status: props.status }); +} + // grade-compare / compare stand up headless Chrome and render up to 16 cells. // Cell count, truncation-cap hits, and whether the render-ready timeout fired // are the signals needed before safely lifting the cap. Low-cardinality only.