feat(automate): resolve observability build id to hashed build id for listSessions

README.md

@@ -444,7 +444,7 @@ As of now we support 45 tools.
   Get the Appium logs for App Automate session ID <session id>
   ```
 
- 20. `fetchBuildInsights` — Fetch insights about a BrowserStack build by combining build details and quality-gate results. Includes `hashed_id` (the hashed build id `listSessions` takes) when the build payload reports one.
+ 20. `fetchBuildInsights` — Fetch insights about a BrowserStack build by combining build details and quality-gate results. Includes `hashed_id` (the hashed build id `listSessions` takes) and `session_type`, resolved through the build's sessions when the build ran on Automate / App Automate.
   **Prompt example**
 
   ```text

src/tools/automate-utils/list-session-ids.ts

@@ -5,6 +5,14 @@ import { apiClient } from "../../lib/apiClient.js";
 
 export const DEFAULT_SESSION_LIST_LIMIT = 10;
 
+/** The REST session list returned 404: no Automate/App Automate build has this hashed id. */
+export class UnknownBuildError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "UnknownBuildError";
+  }
+}
+
 export interface ListSessionIdsArgs {
   sessionType: SessionType;
   buildId: string;
@@ -125,12 +133,11 @@ export async function listSessionIds(
 
   if (!response.ok) {
     if (response.status === 404) {
-      throw new Error(
-        `Invalid hashed build ID "${buildId}" for ${args.sessionType}. ` +
-          "Use the Automate/App Automate dashboard hashed build id " +
-          "(same family as App Automate getFailureLogs buildId), not the " +
-          "observability UUID from getBuildId or listBuildId. " +
-          "If you only have an observability UUID, call fetchBuildInsights and use hashed_id when present.",
+      throw new UnknownBuildError(
+        `No ${args.sessionType} build found for id "${buildId}". ` +
+          "Pass the Automate/App Automate dashboard hashed build id or the " +
+          "observability build id from getBuildId / listBuildId, and check that " +
+          "sessionType matches the product the build ran on.",
       );
     }
     throw new Error(

src/tools/automate-utils/resolve-hashed-build-id.ts

@@ -0,0 +1,183 @@
+import { SessionType } from "../../lib/constants.js";
+import { getBrowserStackAuth } from "../../lib/get-auth.js";
+import { BrowserStackConfig } from "../../lib/types.js";
+import { apiClient } from "../../lib/apiClient.js";
+import logger from "../../logger.js";
+import { getAutomationBaseUrl } from "../rca-agent-utils/constants.js";
+import { extractTestIds } from "../rca-agent-utils/get-failed-test-id.js";
+import { TestRun } from "../rca-agent-utils/types.js";
+
+// Observability (Test Reporting & Analytics) build ids are usually UUIDs but
+// some are 40-char hex, the same shape as Automate / App Automate "hashed ids".
+// The two are never interchangeable, and the observability build API does not
+// expose the hashed id. The deterministic bridge is any BrowserStack session that belongs to the
+// build: the session detail endpoint reports its parent `build_hashed_id`.
+const OBSERVABILITY_UUID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const HASHED_BUILD_ID_RE = /^[a-f0-9]{40}$/i;
+
+// Only the first session id is needed; most builds surface one on page one.
+const MAX_TEST_RUN_PAGES = 5;
+
+export function isObservabilityBuildUuid(id: string): boolean {
+  return OBSERVABILITY_UUID_RE.test(id.trim());
+}
+
+export function isHashedBuildId(id: string): boolean {
+  return HASHED_BUILD_ID_RE.test(id.trim());
+}
+
+export function sessionDetailsUrl(
+  sessionType: SessionType,
+  sessionId: string,
+): string {
+  const encoded = encodeURIComponent(sessionId);
+  switch (sessionType) {
+    case SessionType.Automate:
+      return `https://api.browserstack.com/automate/sessions/${encoded}.json`;
+    case SessionType.AppAutomate:
+      return `https://api.browserstack.com/app-automate/sessions/${encoded}.json`;
+    default: {
+      const _exhaustive: never = sessionType;
+      throw new Error(`Unsupported session type: ${_exhaustive}`);
+    }
+  }
+}
+
+/**
+ * Resolve the hashed build id that a session belongs to via the Automate /
+ * App Automate session detail endpoint. Returns undefined when the session
+ * cannot be fetched or does not report a build.
+ */
+export async function resolveBuildIdFromSession(
+  sessionId: string,
+  sessionType: SessionType,
+  config: BrowserStackConfig,
+): Promise<string | undefined> {
+  const authString = getBrowserStackAuth(config);
+  const auth = Buffer.from(authString).toString("base64");
+
+  const response = await apiClient.get({
+    url: sessionDetailsUrl(sessionType, sessionId),
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Basic ${auth}`,
+    },
+    raise_error: false,
+  });
+
+  if (!response.ok) {
+    logger.warn(
+      `Could not resolve build id for ${sessionType} session ${sessionId}: ${response.status}`,
+    );
+    return undefined;
+  }
+
+  const session = (response.data as any)?.automation_session;
+  const buildId = session?.build_hashed_id;
+  return typeof buildId === "string" && buildId.trim()
+    ? buildId.trim()
+    : undefined;
+}
+
+/**
+ * Find any BrowserStack session id attached to an observability build by
+ * walking its test runs. Returns undefined when no test reports a session
+ * (e.g. JUnit-uploaded builds that never ran on BrowserStack).
+ */
+export async function findSessionIdForObservabilityBuild(
+  observabilityBuildId: string,
+  config: BrowserStackConfig,
+): Promise<string | undefined> {
+  const authString = getBrowserStackAuth(config);
+  const auth = Buffer.from(authString).toString("base64");
+  const baseUrl = `${getAutomationBaseUrl()}/ext/v1/builds/${encodeURIComponent(observabilityBuildId)}/testRuns`;
+
+  let nextPage: string | undefined;
+  for (let page = 0; page < MAX_TEST_RUN_PAGES; page++) {
+    const response = await apiClient.get<TestRun>({
+      url: baseUrl,
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Basic ${auth}`,
+      },
+      ...(nextPage ? { params: { next_page: nextPage } } : {}),
+      raise_error: false,
+    });
+
+    if (!response.ok) {
+      throw new Error(
+        `Failed to fetch test runs for observability build "${observabilityBuildId}": ` +
+          `${response.status} ${response.statusText}`,
+      );
+    }
+
+    const data = response.data;
+    const withSession = extractTestIds(data?.hierarchy ?? []).find(
+      (test) => test.session_id,
+    );
+    if (withSession?.session_id) {
+      return withSession.session_id;
+    }
+
+    if (!data?.pagination?.has_next || !data.pagination.next_page) {
+      return undefined;
+    }
+    nextPage = data.pagination.next_page;
+  }
+
+  logger.warn(
+    `resolveHashedBuildId: no session id in first ${MAX_TEST_RUN_PAGES} pages of build ${observabilityBuildId}`,
+  );
+  return undefined;
+}
+
+export interface ResolvedHashedBuildId {
+  hashedBuildId: string;
+  sessionId: string;
+  sessionType: SessionType;
+}
+
+/**
+ * Convert an observability build UUID into the Automate / App Automate hashed
+ * build id in two deterministic API calls: pick any session of the build from
+ * its test runs, then read `build_hashed_id` from that session's details.
+ *
+ * When `sessionType` is omitted, Automate is tried first, then App Automate.
+ */
+export async function resolveHashedBuildId(
+  observabilityBuildId: string,
+  config: BrowserStackConfig,
+  sessionType?: SessionType,
+): Promise<ResolvedHashedBuildId> {
+  const buildId = observabilityBuildId.trim();
+
+  const sessionId = await findSessionIdForObservabilityBuild(buildId, config);
+  if (!sessionId) {
+    throw new Error(
+      `No BrowserStack sessions found for observability build "${buildId}". ` +
+        "Only builds that ran on Automate or App Automate have sessions to list; " +
+        "uploaded-report builds (e.g. JUnit) do not.",
+    );
+  }
+
+  const candidates: SessionType[] = sessionType
+    ? [sessionType]
+    : [SessionType.Automate, SessionType.AppAutomate];
+
+  for (const candidate of candidates) {
+    const hashedBuildId = await resolveBuildIdFromSession(
+      sessionId,
+      candidate,
+      config,
+    );
+    if (hashedBuildId) {
+      return { hashedBuildId, sessionId, sessionType: candidate };
+    }
+  }
+
+  throw new Error(
+    `Could not resolve the hashed build id for observability build "${buildId}" ` +
+      `from session "${sessionId}" (tried: ${candidates.join(", ")}).`,
+  );
+}

src/tools/automate.ts

@@ -5,7 +5,12 @@ import { fetchAutomationScreenshots } from "./automate-utils/fetch-screenshots.j
 import {
   DEFAULT_SESSION_LIST_LIMIT,
   listSessionIds,
+  UnknownBuildError,
 } from "./automate-utils/list-session-ids.js";
+import {
+  isObservabilityBuildUuid,
+  resolveHashedBuildId,
+} from "./automate-utils/resolve-hashed-build-id.js";
 import { SessionType } from "../lib/constants.js";
 import { trackMCP } from "../lib/instrumentation.js";
 import logger from "../logger.js";
@@ -81,26 +86,59 @@ export async function listSessionIdsTool(
   config: BrowserStackConfig,
 ): Promise<CallToolResult> {
   try {
-    const sessions = await listSessionIds(args, config);
-    if (sessions.length === 0) {
-      return {
-        content: [
-          {
-            type: "text",
-            text: "No sessions found for this hashed build ID.",
-          },
-        ],
-      };
-    }
+    // Accept the observability build id too. Observability ids are usually
+    // UUIDs but can also be 40-char hex like Automate hashed ids, so shape
+    // alone is not enough: try the REST list first and resolve on a miss.
+    const inputId = args.buildId.trim();
+    let buildId = inputId;
+    let resolvedNote: string | undefined;
 
-    return {
-      content: [
-        {
-          type: "text",
-          text: JSON.stringify(sessions, null, 2),
-        },
-      ],
+    const resolve = async () => {
+      const resolved = await resolveHashedBuildId(
+        inputId,
+        config,
+        args.sessionType,
+      );
+      buildId = resolved.hashedBuildId;
+      resolvedNote = `Resolved observability build ${inputId} to hashed build id ${buildId}.`;
     };
+
+    let sessions;
+    if (isObservabilityBuildUuid(inputId)) {
+      await resolve();
+      sessions = await listSessionIds({ ...args, buildId }, config);
+    } else {
+      try {
+        sessions = await listSessionIds({ ...args, buildId }, config);
+      } catch (error) {
+        if (!(error instanceof UnknownBuildError)) throw error;
+        try {
+          await resolve();
+        } catch (resolveError) {
+          logger.debug(
+            "listSessions: id is neither a known hashed build nor a resolvable observability build",
+            resolveError,
+          );
+          throw error;
+        }
+        sessions = await listSessionIds({ ...args, buildId }, config);
+      }
+    }
+
+    const content: CallToolResult["content"] = [
+      {
+        type: "text",
+        text:
+          sessions.length === 0
+            ? "No sessions found for this hashed build ID."
+            : JSON.stringify(sessions, null, 2),
+      },
+    ];
+    if (resolvedNote) {
+      content.push({ type: "text", text: resolvedNote });
+    }
+
+    return { content };
   } catch (error) {
     logger.error("Error listing session IDs", error);
     throw error;
@@ -173,7 +211,7 @@ export default function addAutomationTools(
       buildId: z
         .string()
         .describe(
-          "Dashboard hashed build id or fetchBuildInsights hashed_id — not the getBuildId UUID.",
+          "Hashed build id from the dashboard, or the observability build id from getBuildId.",
         ),
       limit: z
         .number()

src/tools/build-insights.ts

@@ -5,6 +5,7 @@ import logger from "../logger.js";
 import { BrowserStackConfig } from "../lib/types.js";
 import { fetchFromBrowserStackAPI, handleMCPError } from "../lib/utils.js";
 import { trackMCP } from "../lib/instrumentation.js";
+import { resolveHashedBuildId } from "./automate-utils/resolve-hashed-build-id.js";
 
 // Tool function that fetches build insights from two APIs
 export async function fetchBuildInsightsTool(
@@ -24,7 +25,11 @@ export async function fetchBuildInsightsTool(
       }),
     ]);
 
-    const hashed_id = extractHashedBuildId(buildData);
+    const { hashed_id, session_type } = await resolveInsightsHashedId(
+      args.buildId,
+      buildData,
+      config,
+    );
 
     // Select useful fields for users
     const insights = {
@@ -45,6 +50,7 @@ export async function fetchBuildInsightsTool(
       vcs_name: buildData.vcs_info?.name,
       quality_gate_result: qualityData?.quality_gate_result,
       ...(hashed_id ? { hashed_id } : {}),
+      ...(session_type ? { session_type } : {}),
     };
 
     const qualityProfiles = qualityData?.quality_profiles?.map(
@@ -74,6 +80,32 @@ export async function fetchBuildInsightsTool(
   }
 }
 
+/**
+ * The observability build payload does not carry the Automate hashed build id
+ * today. Prefer it if the API ever adds one; otherwise resolve it through any
+ * session of the build (two deterministic REST calls). Never blocks insights.
+ */
+async function resolveInsightsHashedId(
+  observabilityBuildId: string,
+  buildData: unknown,
+  config: BrowserStackConfig,
+): Promise<{ hashed_id?: string; session_type?: string }> {
+  const direct = extractHashedBuildId(buildData);
+  if (direct) {
+    return { hashed_id: direct };
+  }
+  try {
+    const resolved = await resolveHashedBuildId(observabilityBuildId, config);
+    return {
+      hashed_id: resolved.hashedBuildId,
+      session_type: resolved.sessionType,
+    };
+  } catch (error) {
+    logger.warn("Could not resolve hashed build id for build insights", error);
+    return {};
+  }
+}
+
 function extractHashedBuildId(buildData: any): string | undefined {
   const candidates = [
     buildData?.hashed_id,
@@ -99,7 +131,7 @@ export default function addBuildInsightsTools(
 
   tools.fetchBuildInsights = server.tool(
     "fetchBuildInsights",
-    "Fetch build details and quality gate results. Includes hashed_id, the build id listSessions takes.",
+    "Fetch build details and quality gate results. Includes hashed_id and session_type for listSessions.",
     {
       buildId: z.string().describe("The build UUID of the BrowserStack build"),
     },