Add RCA failure clustering tools and build insights improvements

src/config.ts

@@ -30,6 +30,17 @@ for (const key of BROWSERSTACK_LOCAL_OPTION_KEYS) {
   }
 }
 
+// Overridable via O11Y_TFA_RCA_BASE_URL to target a staging tenant.
+const DEFAULT_O11Y_TFA_RCA_BASE_URL = "https://api-automation.browserstack.com";
+
+// Overridable via BROWSERSTACK_AUTOMATION_BASE_URL to target a non-prod env.
+const DEFAULT_BROWSERSTACK_AUTOMATION_BASE_URL =
+  "https://api-automation.browserstack.com";
+
+// Overridable via BROWSERSTACK_O11Y_UI_BASE_URL to point at a staging UI.
+const DEFAULT_BROWSERSTACK_O11Y_UI_BASE_URL =
+  "https://automation.browserstack.com";
+
 /**
  * USE_OWN_LOCAL_BINARY_PROCESS:
  *   If true, the system will not start a new local binary process, but will use the user's own process.
@@ -41,6 +52,9 @@ export class Config {
     public readonly USE_OWN_LOCAL_BINARY_PROCESS: boolean,
     public readonly REMOTE_MCP: boolean,
     public readonly UPLOAD_BASE_DIR: string | undefined,
+    public readonly O11Y_TFA_RCA_BASE_URL: string,
+    public readonly BROWSERSTACK_AUTOMATION_BASE_URL: string,
+    public readonly BROWSERSTACK_O11Y_UI_BASE_URL: string,
   ) {}
 }
 
@@ -52,6 +66,18 @@ const config = new Config(
   process.env.MCP_UPLOAD_BASE_DIR && process.env.MCP_UPLOAD_BASE_DIR.length > 0
     ? process.env.MCP_UPLOAD_BASE_DIR
     : undefined,
+  process.env.O11Y_TFA_RCA_BASE_URL &&
+    process.env.O11Y_TFA_RCA_BASE_URL.length > 0
+    ? process.env.O11Y_TFA_RCA_BASE_URL
+    : DEFAULT_O11Y_TFA_RCA_BASE_URL,
+  process.env.BROWSERSTACK_AUTOMATION_BASE_URL &&
+    process.env.BROWSERSTACK_AUTOMATION_BASE_URL.length > 0
+    ? process.env.BROWSERSTACK_AUTOMATION_BASE_URL
+    : DEFAULT_BROWSERSTACK_AUTOMATION_BASE_URL,
+  process.env.BROWSERSTACK_O11Y_UI_BASE_URL &&
+    process.env.BROWSERSTACK_O11Y_UI_BASE_URL.length > 0
+    ? process.env.BROWSERSTACK_O11Y_UI_BASE_URL
+    : DEFAULT_BROWSERSTACK_O11Y_UI_BASE_URL,
 );
 
 export default config;

src/index.ts

@@ -51,4 +51,5 @@ process.on("exit", () => {
 export { setLogger } from "./logger.js";
 export { BrowserStackMcpServer } from "./server-factory.js";
 export { trackMCP } from "./lib/instrumentation.js";
+export { default as addTfaRcaCollaborationTools } from "./tools/tfa-rca-collaboration.js";
 export const PackageJsonVersion = packageJson.version;

src/tools/build-insights.ts

@@ -15,9 +15,13 @@ export async function fetchBuildInsightsTool(
     const buildUrl = `https://api-automation.browserstack.com/ext/v1/builds/${args.buildId}`;
     const qualityGateUrl = `https://api-automation.browserstack.com/ext/v1/quality-gates/${args.buildId}`;
 
+    // Quality gate data is optional — a failure there should not block build insights
     const [buildData, qualityData] = await Promise.all([
       fetchFromBrowserStackAPI(buildUrl, config),
-      fetchFromBrowserStackAPI(qualityGateUrl, config),
+      fetchFromBrowserStackAPI(qualityGateUrl, config).catch((error) => {
+        logger.warn("Failed to fetch quality gate data", error);
+        return null;
+      }),
     ]);
 
     // Select useful fields for users
@@ -34,10 +38,13 @@ export async function fetchBuildInsightsTool(
       unique_errors: buildData.unique_errors?.overview,
       observability_url: buildData?.observability_url,
       ci_build_url: buildData.ci_info?.build_url,
-      quality_gate_result: qualityData.quality_gate_result,
+      branch: buildData.vcs_info?.branch,
+      commit_sha: buildData.vcs_info?.sha,
+      vcs_name: buildData.vcs_info?.name,
+      quality_gate_result: qualityData?.quality_gate_result,
     };
 
-    const qualityProfiles = qualityData.quality_profiles?.map(
+    const qualityProfiles = qualityData?.quality_profiles?.map(
       (profile: any) => ({
         name: profile.name,
         result: profile.result,

src/tools/rca-agent-utils/constants.ts

@@ -1,6 +1,11 @@
 import { z } from "zod";
+import appConfig from "../../config.js";
 import { TestStatus } from "./types.js";
 
+export function getAutomationBaseUrl(): string {
+  return appConfig.BROWSERSTACK_AUTOMATION_BASE_URL;
+}
+
 export const FETCH_RCA_PARAMS = {
   testId: z
     .array(z.number().int())
@@ -34,4 +39,8 @@ export const LIST_TEST_IDS_PARAMS = {
     .describe(
       "Filter tests by status. If not provided, all tests are returned. Example for RCA usecase always use failed status",
     ),
+  includeFailureDetail: z
+    .boolean()
+    .optional()
+    .describe("Add per-test failure signature for clustering. Default false."),
 };

src/tools/rca-agent-utils/get-failed-test-id.ts

@@ -1,14 +1,29 @@
 import logger from "../../logger.js";
-import { TestStatus, FailedTestInfo, TestRun, TestDetails } from "./types.js";
+import { getAutomationBaseUrl } from "./constants.js";
+import {
+  TestStatus,
+  FailedTestInfo,
+  TestRun,
+  TestDetails,
+  TestFailureSignature,
+} from "./types.js";
+
+// Keeps the response payload lean — never full stack traces.
+const ERROR_SUMMARY_MAX = 200;
+
+// Safety bound on pagination; hitting it is logged, never silent.
+const MAX_PAGES = 100;
 
 export async function getTestIds(
   buildId: string,
   authString: string,
   status?: TestStatus,
+  includeFailureDetail = false,
 ): Promise<FailedTestInfo[]> {
-  const baseUrl = `https://api-automation.browserstack.com/ext/v1/builds/${buildId}/testRuns`;
+  // No `status` → returns ALL tests; a `status` narrows the query.
+  const baseUrl = `${getAutomationBaseUrl()}/ext/v1/builds/${buildId}/testRuns`;
   let url = status ? `${baseUrl}?test_statuses=${status}` : baseUrl;
-  let allFailedTests: FailedTestInfo[] = [];
+  let allTests: FailedTestInfo[] = [];
   let requestNumber = 0;
 
   // Construct Basic auth header
@@ -34,18 +49,23 @@ export async function getTestIds(
 
       const data = (await response.json()) as TestRun;
 
-      // Extract failed IDs from current page
+      // Extract test IDs from the current page (all tests unless narrowed).
       if (data.hierarchy && data.hierarchy.length > 0) {
-        const currentFailedTests = extractFailedTestIds(data.hierarchy, status);
-        allFailedTests = allFailedTests.concat(currentFailedTests);
+        const currentTests = extractTestIds(
+          data.hierarchy,
+          status,
+          includeFailureDetail,
+        );
+        allTests = allTests.concat(currentTests);
       }
 
-      // Check for pagination termination conditions
-      if (
-        !data.pagination?.has_next ||
-        !data.pagination.next_page ||
-        requestNumber >= 5
-      ) {
+      if (!data.pagination?.has_next || !data.pagination.next_page) {
+        break;
+      }
+      if (requestNumber >= MAX_PAGES) {
+        logger.warn(
+          `listTestIds: hit MAX_PAGES (${MAX_PAGES}) for build ${buildId}; result may be partial`,
+        );
         break;
       }
 
@@ -57,39 +77,105 @@ export async function getTestIds(
       url = `${baseUrl}?${new URLSearchParams(params).toString()}`;
     }
 
-    // Return unique failed test IDs
-    return allFailedTests;
+    return allTests;
   } catch (error) {
-    logger.error("Error fetching failed tests:", error);
+    logger.error("Error fetching test runs:", error);
     throw error;
   }
 }
 
-export function extractFailedTestIds(
+export function extractTestIds(
   hierarchy: TestDetails[],
   status?: TestStatus,
+  includeFailureDetail = false,
 ): FailedTestInfo[] {
-  let failedTests: FailedTestInfo[] = [];
+  let tests: FailedTestInfo[] = [];
 
   for (const node of hierarchy) {
-    if (node.details?.status === status) {
-      if (node.details?.observability_url) {
-        const idMatch = node.details.observability_url.match(/details=(\d+)/);
-        if (idMatch) {
-          failedTests.push({
-            test_id: idMatch[1],
-            test_name: node.display_name || `Test ${idMatch[1]}`,
-          });
+    // observability_url `details=<id>` filters out suite/hook nodes. run_count
+    // is not required — JUnit-uploaded builds report run_count=0 for real tests too.
+    const nodeStatus = node.details?.status;
+    const statusMatches = status === undefined || nodeStatus === status;
+    if (statusMatches && node.details?.observability_url) {
+      const idMatch = node.details.observability_url.match(/details=(\d+)/);
+      if (idMatch) {
+        const entry: FailedTestInfo = {
+          test_id: idMatch[1],
+          test_name: node.display_name || `Test ${idMatch[1]}`,
+          status: nodeStatus,
+        };
+        // Failure signatures only exist for failed tests; include when asked.
+        if (includeFailureDetail && nodeStatus === TestStatus.FAILED) {
+          const signature = buildFailureSignature(node.details);
+          if (signature) entry.failure = signature;
         }
+        tests.push(entry);
       }
     }
 
     if (node.children && node.children.length > 0) {
-      failedTests = failedTests.concat(
-        extractFailedTestIds(node.children, status),
+      tests = tests.concat(
+        extractTestIds(node.children, status, includeFailureDetail),
       );
     }
   }
 
-  return failedTests;
+  return tests;
+}
+
+// Back-compat alias — prefer extractTestIds. Kept so existing imports/tests
+// referencing the old name continue to resolve.
+export const extractFailedTestIds = extractTestIds;
+
+// Build a trimmed failure signature from a test node's `details`. Returns
+// undefined when no signal is available so the field is simply omitted.
+function buildFailureSignature(details: any): TestFailureSignature | undefined {
+  if (!details) return undefined;
+
+  const signature: TestFailureSignature = {};
+
+  if (details.failure_categories != null) {
+    signature.category = Array.isArray(details.failure_categories)
+      ? details.failure_categories.filter(Boolean).join(", ")
+      : String(details.failure_categories);
+  }
+
+  const errorSummary = extractFirstFailureLine(details);
+  if (errorSummary) signature.error_summary = errorSummary;
+
+  if (details.file_path) signature.file_path = String(details.file_path);
+  if (typeof details.is_flaky === "boolean")
+    signature.is_flaky = details.is_flaky;
+  if (typeof details.is_always_failing === "boolean")
+    signature.is_always_failing = details.is_always_failing;
+  if (typeof details.is_new_failure === "boolean")
+    signature.is_new_failure = details.is_new_failure;
+
+  return Object.keys(signature).length > 0 ? signature : undefined;
+}
+
+// First non-empty line of the first retry's TEST_FAILURE log, capped. Handles
+// both string entries and object entries ({ message } / { text }).
+function extractFirstFailureLine(details: any): string | undefined {
+  const retries = details?.retries;
+  if (!Array.isArray(retries)) return undefined;
+
+  for (const retry of retries) {
+    const failures = retry?.logs?.TEST_FAILURE;
+    if (!failures) continue;
+    const entries = Array.isArray(failures) ? failures : [failures];
+    for (const failure of entries) {
+      const text =
+        typeof failure === "string"
+          ? failure
+          : (failure?.message ?? failure?.text ?? "");
+      const firstLine = String(text)
+        .split("\n")
+        .map((line) => line.trim())
+        .find((line) => line.length > 0);
+      if (firstLine) return firstLine.slice(0, ERROR_SUMMARY_MAX);
+    }
+  }
+
+  return undefined;
 }

src/tools/rca-agent-utils/types.ts

@@ -20,9 +20,26 @@ export interface TestRun {
   };
 }
 
+// Trimmed per-test failure signature for downstream clustering.
+// Never carries full stack traces — error_summary is a single capped line.
+export interface TestFailureSignature {
+  category?: string;
+  error_summary?: string;
+  file_path?: string;
+  is_flaky?: boolean;
+  is_always_failing?: boolean;
+  is_new_failure?: boolean;
+}
+
 export interface FailedTestInfo {
   test_id: number;
   test_name: string;
+  // The test's own status (passed/failed/pending/skipped). listTestIds returns
+  // ALL tests by default, so consumers rely on this to filter/group.
+  status?: TestStatus;
+  // Present only when listTestIds is called with includeFailureDetail=true
+  // (only failed tests carry a signature).
+  failure?: TestFailureSignature;
 }
 
 export enum RCAState {

src/tools/rca-agent.ts

@@ -145,15 +145,21 @@ export async function listTestIdsTool(
   args: {
     buildId: string;
     status?: TestStatus;
+    includeFailureDetail?: boolean;
   },
   config: BrowserStackConfig,
 ): Promise<CallToolResult> {
   try {
-    const { buildId, status } = args;
+    const { buildId, status, includeFailureDetail } = args;
     const authString = getBrowserStackAuth(config);
 
     // Get test IDs
-    const testIds = await getTestIds(buildId, authString, status);
+    const testIds = await getTestIds(
+      buildId,
+      authString,
+      status,
+      includeFailureDetail,
+    );
 
     return {
       content: [
@@ -244,7 +250,7 @@ export default function addRCATools(
 
   tools.listTestIds = server.tool(
     "listTestIds",
-    "List test IDs from a BrowserStack Automate build, optionally filtered by status",
+    "List all tests of a BrowserStack build (each with its status); optional status filter.",
     LIST_TEST_IDS_PARAMS,
     async (args) => {
       try {