feat(telemetry): add auth_success, mcp_connect, and mcp_oauth events

Author: TheGreatAxios

src/mcp/client.ts

@@ -15,6 +15,14 @@ import type { McpToolAnnotations } from "./tool-permissions.js";
 import { buildStdioMcpProcessEnv } from "./stdio-env.js";
 import { isHttpServer } from "./is-http-server.js";
 import { MCP_CLIENT_NAME } from "../branding.js";
+import {
+  captureMcpConnect,
+  captureMcpOauth,
+  classifyMcpConnectOutcome,
+  classifyMcpOauthOutcome,
+  NOOP_TELEMETRY,
+  type Telemetry,
+} from "../telemetry/index.js";
 
 export interface MCPTool {
   name: string;
@@ -94,6 +102,9 @@ export interface MCPConnectOptions {
   // learns the transport died under a live client. Never fired for
   // intentional teardown — close() disarms it before closing the transport.
   onDisconnect?: () => void;
+  // Optional telemetry handle for enum-only connect/oauth outcome events. No
+  // globals: callers that care pass their instance; otherwise nothing emits.
+  telemetry?: Telemetry;
 }
 
 export function unwrapToolContent(content: unknown): string {
@@ -137,6 +148,7 @@ interface HTTPAuthContext {
   interactive: boolean;
   serverName: string;
   onAuthorized?: (serverName: string) => void;
+  telemetry: Telemetry;
 }
 
 interface BrowserAuthFlow {
@@ -441,16 +453,28 @@ async function driveRecovery(
   }
 
   const browserFlow = coordinator.browserFlow;
-  await browserFlow.promptEmitted;
-  const code = await waitForBrowserAuthCode(context);
-  await new StreamableHTTPClientTransport(
-    context.url,
-    streamableHTTPTransportOptions(
-      context.authProvider,
-      coordinator.lifecycle.signal,
-    ),
-  ).finishAuth(code);
-  await coordinator.probe();
+  // One enum-only outcome per browser attempt: prompt, wait, token exchange,
+  // and probe either complete together or map the failure to exactly one of
+  // cancelled (explicit abort) / timeout (expiry, cap, denial, teardown).
+  try {
+    await browserFlow.promptEmitted;
+    const code = await waitForBrowserAuthCode(context);
+    await new StreamableHTTPClientTransport(
+      context.url,
+      streamableHTTPTransportOptions(
+        context.authProvider,
+        coordinator.lifecycle.signal,
+      ),
+    ).finishAuth(code);
+    await coordinator.probe();
+  } catch (error) {
+    captureMcpOauth(
+      context.telemetry,
+      classifyMcpOauthOutcome(error, coordinator.lifecycle.signal.aborted),
+    );
+    throw error;
+  }
+  captureMcpOauth(context.telemetry, "completed");
 }
 
 function completeVerifiedRecovery(
@@ -763,6 +787,7 @@ async function connectHttp(
         ...(options.onAuthorized !== undefined
           ? { onAuthorized: options.onAuthorized }
           : {}),
+        telemetry: options.telemetry ?? NOOP_TELEMETRY,
       };
       gateRedirectToAuthorization(authContext);
     }
@@ -835,16 +860,27 @@ export async function connectMCPServers(
   onWarning: (message: string) => void,
   options: MCPConnectOptions = {},
 ): Promise<MCPClient[]> {
+  const telemetry = options.telemetry ?? NOOP_TELEMETRY;
   const results = await Promise.all(
     configs.map((c) => connectMCPServer(c, options)),
   );
   const clients: MCPClient[] = [];
-  for (const result of results) {
+  for (let index = 0; index < results.length; index += 1) {
+    const result = results[index];
+    if (result === undefined) continue;
     if (result.ok) clients.push(result.client);
     else
       onWarning(
         `[mcp] Warning: failed to connect to MCP server "${result.serverName}": ${result.error}`,
       );
+    // One enum-only event per server: the transport that was dialed and the
+    // outcome enum. Server name, URL, and error text never leave the process.
+    const config = configs[index];
+    captureMcpConnect(telemetry, {
+      transport:
+        config !== undefined && isHttpServer(config) ? "http" : "stdio",
+      result: classifyMcpConnectOutcome(result),
+    });
   }
   return clients;
 }

src/telemetry/index.ts

@@ -63,6 +63,9 @@ export type TelemetryEvent =
   | "summarizer_failure"
   | "crash"
   | "auth_failure"
+  | "auth_success"
+  | "mcp_connect"
+  | "mcp_oauth"
   // PostHog Surveys event name (space included). Intentional operator feedback
   // from /feedback — can ship when ambient product telemetry is off; still
   // blocked by env kill switches. See captureIntentional.
@@ -199,6 +202,15 @@ const EVENT_PROPERTY_ALLOWLIST: Record<TelemetryEvent, readonly string[]> = {
   // Which provider rejected the credentials, not why — the rejection detail is
   // provider-authored text and error_class means a JS constructor name.
   auth_failure: ["auth_provider"],
+  // Which provider completed sign-in. Same enum as auth_failure, no message:
+  // a success has no rejection detail to report.
+  auth_success: ["auth_provider"],
+  // Per-server connect outcome. transport is the stdio/http connect path and
+  // result is the outcome enum — never the server name, URL, or error text.
+  mcp_connect: ["transport", "result"],
+  // Per-attempt browser-OAuth outcome. result only — never the
+  // authorization URL, state, server name, or error text.
+  mcp_oauth: ["result"],
   // Intentional /feedback survey response (PostHog custom survey capture shape).
   // Free text is only sent because the operator typed it for that purpose.
   // turn_trace_id links to the last $ai_generation in this session when known.
@@ -226,7 +238,8 @@ export function aiSpansEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
 
 /**
  * Sample rate for successful `$ai_generation` events (0–1). Default 1.0 (no
- * drop). Errors (`$ai_is_error: true`), `crash`, and `auth_failure` always ship.
+ * drop). Errors (`$ai_is_error: true`), `crash`, `auth_failure`,
+ * `auth_success`, `mcp_connect`, and `mcp_oauth` always ship.
  */
 export function generationSampleRate(
   env: NodeJS.ProcessEnv = process.env,
@@ -529,3 +542,77 @@ export function createTelemetry(options: CreateTelemetryOptions): Telemetry {
     discard,
   };
 }
+
+// ---------------------------------------------------------------------------
+// Enum-only product events (CL-9017). These helpers live beside the schema
+// rather than the call sites so the values they can send stay visible next
+// to the allowlists that bound them: fixed enums in, nothing else out.
+// Sampling gates only `$ai_generation`, so every event here always ships.
+// ---------------------------------------------------------------------------
+
+export type McpTransport = "stdio" | "http";
+
+export type McpConnectOutcome = "ok" | "auth" | "timeout" | "fail";
+
+export interface McpConnectReport {
+  readonly transport: McpTransport;
+  readonly result: McpConnectOutcome;
+}
+
+// Structural subset of the connect result: the report carries the outcome
+// enum, never the server name or the error text it was classified from.
+export interface McpConnectClassificationInput {
+  readonly ok: boolean;
+  readonly serverName?: string;
+  readonly error?: string;
+  readonly authPending?: boolean;
+}
+
+const MCP_CONNECT_TIMEOUT_MESSAGE = /abort|timeout|timed out|expir/i;
+
+export function classifyMcpConnectOutcome(
+  result: McpConnectClassificationInput,
+): McpConnectOutcome {
+  if (result.ok) return "ok";
+  if (result.authPending === true) return "auth";
+  // Substring match, not word match: AbortError surfaces as "The operation
+  // was aborted", and only the timeout-vs-fail bucket rides on this — the
+  // error text itself never ships.
+  if (
+    result.error !== undefined &&
+    MCP_CONNECT_TIMEOUT_MESSAGE.test(result.error)
+  )
+    return "timeout";
+  return "fail";
+}
+
+export function captureMcpConnect(
+  telemetry: Telemetry,
+  report: McpConnectReport,
+): void {
+  telemetry.capture("mcp_connect", {
+    transport: report.transport,
+    result: report.result,
+  });
+}
+
+export type McpOauthOutcome = "completed" | "cancelled" | "timeout";
+
+// Only an explicit abort (aborted signal, AbortError) is "cancelled". Every
+// other browser-wait end without a code — wait expiry, attempt cap, denial,
+// teardown — is "timeout", so each attempt maps to exactly one outcome.
+export function classifyMcpOauthOutcome(
+  error: unknown,
+  aborted: boolean,
+): McpOauthOutcome {
+  if (aborted) return "cancelled";
+  if (error instanceof Error && error.name === "AbortError") return "cancelled";
+  return "timeout";
+}
+
+export function captureMcpOauth(
+  telemetry: Telemetry,
+  result: McpOauthOutcome,
+): void {
+  telemetry.capture("mcp_oauth", { result });
+}

src/tui/chrome-state.ts

@@ -854,6 +854,18 @@ export type SendFailureKind = "abort" | "auth" | "error";
 /** First-party auth_provider values only — never free-text provider labels. */
 export type AuthProviderId = "codex" | "xai" | "anthropic" | "other";
 
+/**
+ * Map a setup/connect provider id to its telemetry enum. Exact first-party
+ * matches only — every other catalog id (openai, ollama, custom, …) is
+ * "other", and free-text display names must never reach this function.
+ */
+export function authProviderFromConnectId(providerId: string): AuthProviderId {
+  if (providerId === "codex") return "codex";
+  if (providerId === "xai") return "xai";
+  if (providerId === "anthropic") return "anthropic";
+  return "other";
+}
+
 export interface ClassifiedSendFailure {
   readonly kind: SendFailureKind;
   readonly authProvider: AuthProviderId | null;
@@ -908,6 +920,23 @@ export function captureAuthFailure(
   telemetry.capture("auth_failure", { auth_provider: failure.authProvider });
 }
 
+// Mirrors ClassifiedSendFailure without the rejection detail: a success has
+// no message to classify, only the provider that completed sign-in. Stays
+// silent unless the sign-in actually completed, so failed attempts are never
+// counted as successes.
+export interface AuthSuccessOutcome {
+  readonly connected: boolean;
+  readonly authProvider: AuthProviderId | null;
+}
+
+export function captureAuthSuccess(
+  telemetry: Telemetry,
+  outcome: AuthSuccessOutcome,
+): void {
+  if (!outcome.connected || outcome.authProvider === null) return;
+  telemetry.capture("auth_success", { auth_provider: outcome.authProvider });
+}
+
 /** Same classification as `classifyAgentSendFailure`, from the message alone. */
 export function classifySendFailureMessage(
   message: string,

src/tui/provider/connect.ts

@@ -6,6 +6,11 @@
  */
 
 import type { Settings } from "../../config/settings.js";
+import { getTelemetry } from "../../telemetry/singleton.js";
+import {
+  authProviderFromConnectId,
+  captureAuthSuccess,
+} from "../chrome-state.js";
 import { runProviderSetup } from "./setup.js";
 import type { ProviderSetupConfig } from "./types.js";
 import {
@@ -84,5 +89,13 @@ export async function connectProviderInline(
   });
 
   if (!submitted) return { connected: false };
+  // Login-completion site: exactly one enum-only event per completed /connect
+  // sign-in. Cancelled flows return above and failed submits never set
+  // connected, so neither can emit. The setup choice id maps to the enum with
+  // other-fallback — free-text names never leave the process.
+  captureAuthSuccess(getTelemetry(), {
+    connected: result.connected,
+    authProvider: authProviderFromConnectId(input.providerId),
+  });
   return result;
 }