@browserstack/mcp-server 1.4.0-beta.2 → 1.4.0

package/dist/tools/ask-browserstack/config.js

@@ -1,3 +1,4 @@
+import appConfig from "../../config.js";
 import logger from "../../logger.js";
 /**
  * Where Atlas lives, and the timeout ladder.
@@ -23,7 +24,13 @@ export const ELICITATION_TIMEOUT_MS = 270_000;
 /** Thrown for anything this tool refuses to attempt. Never carries a credential. */
 export class AskError extends Error {
 }
-/** Off by default is wrong for a shipped feature, but a kill switch is not. */
+/**
+ * Off by default is wrong for a shipped feature, but a kill switch is not.
+ *
+ * The only setting here still read from `process.env` per call, and deliberately: a kill
+ * switch that needs a process restart is slowest exactly when it is needed fastest. The
+ * other three are on the config singleton (rules/tool-design.md).
+ */
 export function isEnabled() {
     return (process.env.ASK_BROWSERSTACK_DISABLED || "").toLowerCase() !== "true";
 }
@@ -41,8 +48,7 @@ export function isEnabled() {
  * run. This flag only removes the blanket refusal.
  */
 export function allowRemoteRelay() {
-    return ((process.env.ASK_BROWSERSTACK_ALLOW_REMOTE_RELAY || "").toLowerCase() ===
-        "true");
+    return appConfig.ASK_BROWSERSTACK_ALLOW_REMOTE_RELAY;
 }
 /**
  * ============================================================================
@@ -111,7 +117,7 @@ function announce(what, url, source) {
  * no selector: one default, one override.
  */
 export function atlasBaseUrl() {
-    const explicit = process.env.ASK_BROWSERSTACK_ATLAS_URL;
+    const explicit = appConfig.ASK_BROWSERSTACK_ATLAS_URL;
     const url = explicit && explicit.trim() ? trimUrl(explicit) : DEFAULT_ATLAS_URL;
     announce("Atlas", url, explicit && explicit.trim() ? "env" : "default");
     return url;
@@ -127,7 +133,7 @@ export function agentUrl() {
  * the only way in. Same two rungs as the host, and the same staging default.
  */
 export function authTokenUrl() {
-    const explicit = process.env.ASK_BROWSERSTACK_AUTH_TOKEN_URL;
+    const explicit = appConfig.ASK_BROWSERSTACK_AUTH_TOKEN_URL;
     const url = explicit && explicit.trim() ? trimUrl(explicit) : DEFAULT_AUTH_TOKEN_URL;
     announce("auth token endpoint", url, explicit && explicit.trim() ? "env" : "default");
     return url;

package/dist/tools/ask-browserstack/register.js

@@ -312,7 +312,7 @@ export function addAskBrowserStackAITool(server, deps, config) {
     tools.askBrowserStackAI = server.tool("askBrowserStackAI", DESCRIPTION, {
         product: z
             .enum(PRODUCTS)
-            .describe("Which product to work in: tm (Test Management), a11y (Accessibility), " +
+            .describe("Which product to work in: tm (Test Management), " +
             "tra (Test Reporting & Analytics)."),
         query: z
             .string()
@@ -323,6 +323,11 @@ export function addAskBrowserStackAITool(server, deps, config) {
         // sets it false: consent is not a licence to delete.
         readOnlyHint: false,
         destructiveHint: false,
+        // openWorldHint: the agent fans out to product APIs chosen at runtime, so the set of
+        // effects is not knowable from this schema. idempotentHint false because a repeated
+        // call can create a second record — the relay asks again, it does not dedupe.
+        openWorldHint: true,
+        idempotentHint: false,
         title: "Ask BrowserStack AI (Alpha)",
     }, async ({ product, query }, extra) => {
         track("askBrowserStackAI");
@@ -371,6 +376,14 @@ export function addAskBrowserStackAITool(server, deps, config) {
                 ? error.message
                 : String(error);
             logger.error("askBrowserStackAI failed: %s", message);
+            // Error telemetry, in the same never-fatal shape as the success-path `track()`:
+            // a failing tool call must not be made worse by a failing analytics call.
+            try {
+                trackMCP("askBrowserStackAI", server.server.getClientVersion(), error, config);
+            }
+            catch {
+                /* ignore */
+            }
             // No `canElicit` argument: the request never left this process, so whether the
             // client could have been prompted is not what the reader needs to know.
             return toResult(errorResult(message, approvals));

package/dist/tools/ask-browserstack/stream.js

@@ -22,6 +22,7 @@
  * is a pipe. Keeping the judgement out of the transport is why swapping A2 for A1 does
  * not risk the fail-closed behaviour.
  */
+import { apiClient } from "../../lib/apiClient.js";
 import logger from "../../logger.js";
 import { AskError } from "./config.js";
 /**
@@ -208,15 +209,16 @@ export function fetchAgentStreamTransport(timeoutMs = WHOLE_RUN_TIMEOUT_MS) {
 /** The decision POST. 30s, because it is an ordinary short request. */
 export function fetchDecisionTransport(timeoutMs = 30_000) {
     return async (url, headers, body) => {
-        const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), timeoutMs);
         try {
-            const response = await fetch(url, {
-                method: "POST",
+            // Through `apiClient` per rules/security.md. `raise_error: false` because the caller
+            // reads the STATUS: a 404 (run gone) and a 409 (already decided) are both answers,
+            // and a thrown AxiosError would collapse them into the unreachable case below.
+            const response = await apiClient.post({
+                url,
                 headers,
-                body: JSON.stringify(body),
-                redirect: "manual",
-                signal: controller.signal,
+                body,
+                timeout: timeoutMs,
+                raise_error: false,
             });
             return response.status;
         }
@@ -226,9 +228,6 @@ export function fetchDecisionTransport(timeoutMs = 30_000) {
             // the caller can say that rather than implying a human refused.
             return 0;
         }
-        finally {
-            clearTimeout(timer);
-        }
     };
 }
 /** `POST /agent/{run_id}/permission`, built from the base URL the tool already resolved. */

package/dist/tools/ask-browserstack/types.d.ts

@@ -6,7 +6,7 @@
  * different repo, at the same time. A field renamed here to read better is a field the
  * other half will never send. Nothing here changes without changing that document first.
  */
-export declare const PRODUCTS: readonly ["tm", "a11y", "tra"];
+export declare const PRODUCTS: readonly ["tm", "tra"];
 export type Product = (typeof PRODUCTS)[number];
 /** CONTRACT §2 — what Atlas emits on the run's stream when its gate needs a human. */
 export interface PermissionAsk {

package/dist/tools/ask-browserstack/types.js

@@ -6,5 +6,9 @@
  * different repo, at the same time. A field renamed here to read better is a field the
  * other half will never send. Nothing here changes without changing that document first.
  */
-export const PRODUCTS = ["tm", "a11y", "tra"];
+// a11y is deliberately ABSENT while Ask AI is in limited alpha. Atlas itself serves the
+// product; this tool just does not offer it yet. Re-adding it means this list, the `product`
+// describe text in register.ts, and the two a11y handoffs in tool-handoff.ts — which stop
+// pointing here precisely because the call would now be rejected.
+export const PRODUCTS = ["tm", "tra"];
 export const ASK_STATUSES = ["ok", "blocked", "error", "rate_limited"];

package/dist/tools/automate-utils/list-session-ids.d.ts

@@ -0,0 +1,28 @@
+import { SessionType } from "../../lib/constants.js";
+import { BrowserStackConfig } from "../../lib/types.js";
+export declare const DEFAULT_SESSION_LIST_LIMIT = 10;
+/** The REST session list returned 404: no Automate/App Automate build has this hashed id. */
+export declare class UnknownBuildError extends Error {
+    constructor(message: string);
+}
+export interface ListSessionIdsArgs {
+    sessionType: SessionType;
+    buildId: string;
+    limit?: number;
+    offset?: number;
+    status?: string;
+}
+export interface SessionIdRecord {
+    sessionId: string;
+    name?: string;
+    status?: string;
+    os?: string;
+    osVersion?: string;
+    browser?: string;
+    device?: string | null;
+    browserUrl?: string;
+    videoUrl?: string;
+}
+export declare function sessionsListUrl(sessionType: SessionType, buildId: string): string;
+export declare function mapSessionRecords(payload: unknown, statusFilter?: string): SessionIdRecord[];
+export declare function listSessionIds(args: ListSessionIdsArgs, config: BrowserStackConfig): Promise<SessionIdRecord[]>;

package/dist/tools/automate-utils/list-session-ids.js

@@ -0,0 +1,87 @@
+import { SessionType } from "../../lib/constants.js";
+import { getBrowserStackAuth } from "../../lib/get-auth.js";
+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) {
+        super(message);
+        this.name = "UnknownBuildError";
+    }
+}
+export function sessionsListUrl(sessionType, buildId) {
+    const encodedBuildId = encodeURIComponent(buildId);
+    switch (sessionType) {
+        case SessionType.Automate:
+            return `https://api.browserstack.com/automate/builds/${encodedBuildId}/sessions.json`;
+        case SessionType.AppAutomate:
+            return `https://api-cloud.browserstack.com/app-automate/builds/${encodedBuildId}/sessions.json`;
+        default: {
+            const _exhaustive = sessionType;
+            throw new Error(`Unsupported session type: ${_exhaustive}`);
+        }
+    }
+}
+export function mapSessionRecords(payload, statusFilter) {
+    const items = Array.isArray(payload) ? payload : [];
+    const normalizedFilter = statusFilter?.trim().toLowerCase();
+    const records = [];
+    for (const item of items) {
+        const session = item?.automation_session;
+        if (!session) {
+            continue;
+        }
+        const sessionId = session.hashed_id?.trim();
+        if (!sessionId) {
+            continue;
+        }
+        if (normalizedFilter &&
+            (session.status ?? "").toLowerCase() !== normalizedFilter) {
+            continue;
+        }
+        records.push({
+            sessionId,
+            name: session.name,
+            status: session.status,
+            os: session.os,
+            osVersion: session.os_version,
+            browser: session.browser,
+            device: session.device,
+            browserUrl: session.browser_url,
+            videoUrl: session.video_url,
+        });
+    }
+    return records;
+}
+export async function listSessionIds(args, config) {
+    const buildId = args.buildId.trim();
+    if (!buildId) {
+        throw new Error("Hashed Automate/App Automate build ID is required");
+    }
+    const authString = getBrowserStackAuth(config);
+    const auth = Buffer.from(authString).toString("base64");
+    const limit = args.limit ?? DEFAULT_SESSION_LIST_LIMIT;
+    const params = { limit };
+    if (args.offset !== undefined) {
+        params.offset = args.offset;
+    }
+    const response = await apiClient.get({
+        url: sessionsListUrl(args.sessionType, buildId),
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Basic ${auth}`,
+        },
+        params,
+        raise_error: false,
+    });
+    if (!response.ok) {
+        if (response.status === 404) {
+            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(`Failed to list sessions: ${response.status} ${response.statusText}`);
+    }
+    return mapSessionRecords(response.data, args.status);
+}

package/dist/tools/automate-utils/resolve-hashed-build-id.d.ts

@@ -0,0 +1,30 @@
+import { SessionType } from "../../lib/constants.js";
+import { BrowserStackConfig } from "../../lib/types.js";
+export declare function isObservabilityBuildUuid(id: string): boolean;
+export declare function isHashedBuildId(id: string): boolean;
+export declare function sessionDetailsUrl(sessionType: SessionType, sessionId: string): string;
+/**
+ * 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 declare function resolveBuildIdFromSession(sessionId: string, sessionType: SessionType, config: BrowserStackConfig): Promise<string | 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 declare function findSessionIdForObservabilityBuild(observabilityBuildId: string, config: BrowserStackConfig): Promise<string | 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 declare function resolveHashedBuildId(observabilityBuildId: string, config: BrowserStackConfig, sessionType?: SessionType): Promise<ResolvedHashedBuildId>;

package/dist/tools/automate-utils/resolve-hashed-build-id.js

@@ -0,0 +1,124 @@
+import { SessionType } from "../../lib/constants.js";
+import { getBrowserStackAuth } from "../../lib/get-auth.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";
+// 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) {
+    return OBSERVABILITY_UUID_RE.test(id.trim());
+}
+export function isHashedBuildId(id) {
+    return HASHED_BUILD_ID_RE.test(id.trim());
+}
+export function sessionDetailsUrl(sessionType, sessionId) {
+    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 = 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, sessionType, config) {
+    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?.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, config) {
+    const authString = getBrowserStackAuth(config);
+    const auth = Buffer.from(authString).toString("base64");
+    const baseUrl = `${getAutomationBaseUrl()}/ext/v1/builds/${encodeURIComponent(observabilityBuildId)}/testRuns`;
+    let nextPage;
+    for (let page = 0; page < MAX_TEST_RUN_PAGES; page++) {
+        const response = await apiClient.get({
+            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;
+}
+/**
+ * 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, config, sessionType) {
+    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.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(", ")}).`);
+}

package/dist/tools/automate.d.ts

@@ -6,4 +6,11 @@ export declare function fetchAutomationScreenshotsTool(args: {
     sessionId: string;
     sessionType: SessionType;
 }, config: BrowserStackConfig): Promise<CallToolResult>;
+export declare function listSessionIdsTool(args: {
+    sessionType: SessionType;
+    buildId: string;
+    limit?: number;
+    offset?: number;
+    status?: string;
+}, config: BrowserStackConfig): Promise<CallToolResult>;
 export default function addAutomationTools(server: McpServer, config: BrowserStackConfig): Record<string, any>;

package/dist/tools/automate.js

@@ -1,5 +1,7 @@
 import { z } from "zod";
 import { fetchAutomationScreenshots } from "./automate-utils/fetch-screenshots.js";
+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";
@@ -48,10 +50,63 @@ export async function fetchAutomationScreenshotsTool(args, config) {
         };
     }
 }
+export async function listSessionIdsTool(args, config) {
+    try {
+        // 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;
+        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 = [
+            {
+                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;
+    }
+}
 //Registers the fetchAutomationScreenshots tool with the MCP server
 export default function addAutomationTools(server, config) {
     const tools = {};
-    tools.fetchAutomationScreenshots = server.tool("fetchAutomationScreenshots", "Fetch and process screenshots from a BrowserStack Automate session", {
+    tools.fetchAutomationScreenshots = server.tool("fetchAutomationScreenshots", "Fetch screenshots captured during an Automate/App Automate session.", {
         sessionId: z
             .string()
             .describe("The BrowserStack session ID to fetch screenshots from"),
@@ -83,5 +138,53 @@ export default function addAutomationTools(server, config) {
             };
         }
     });
+    tools.listSessions = server.tool("listSessions", "List sessions for a hashed Automate/App Automate build: session IDs, status, OS, browser/device, dashboard URL.", {
+        sessionType: z
+            .enum([SessionType.Automate, SessionType.AppAutomate])
+            .describe("Type of BrowserStack session"),
+        buildId: z
+            .string()
+            .describe("Hashed build id from the dashboard, or the observability build id from getBuildId."),
+        limit: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe(`Max sessions to return. Defaults to ${DEFAULT_SESSION_LIST_LIMIT}.`),
+        offset: z
+            .number()
+            .int()
+            .min(0)
+            .optional()
+            .describe("Pagination offset for the REST session list."),
+        status: z
+            .string()
+            .optional()
+            .describe("Optional session status filter (e.g. done, running, error). Applied client-side."),
+    }, {
+        title: "List Sessions",
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+    }, async (args) => {
+        try {
+            trackMCP("listSessions", server.server.getClientVersion(), undefined, config);
+            return await listSessionIdsTool(args, config);
+        }
+        catch (error) {
+            trackMCP("listSessions", server.server.getClientVersion(), error, config);
+            const errorMessage = error instanceof Error ? error.message : "Unknown error";
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error listing session IDs: ${errorMessage}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
     return tools;
 }

package/dist/tools/build-insights.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import logger from "../logger.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(args, config) {
     try {
@@ -15,6 +16,7 @@ export async function fetchBuildInsightsTool(args, config) {
                 return null;
             }),
         ]);
+        const { hashed_id, session_type } = await resolveInsightsHashedId(args.buildId, buildData, config);
         // Select useful fields for users
         const insights = {
             name: buildData.name,
@@ -33,6 +35,8 @@ export async function fetchBuildInsightsTool(args, config) {
             commit_sha: buildData.vcs_info?.sha,
             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((profile) => ({
             name: profile.name,
@@ -56,10 +60,45 @@ export async function fetchBuildInsightsTool(args, config) {
         throw error;
     }
 }
+/**
+ * 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, buildData, config) {
+    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) {
+    const candidates = [
+        buildData?.hashed_id,
+        buildData?.automate_hashed_id,
+        buildData?.hashedId,
+    ];
+    for (const candidate of candidates) {
+        if (typeof candidate === "string" &&
+            /^[a-z0-9]{40}$/i.test(candidate.trim()))
+            return candidate.trim();
+    }
+    return undefined;
+}
 // Registers the fetchBuildInsights tool with the MCP server
 export default function addBuildInsightsTools(server, config) {
     const tools = {};
-    tools.fetchBuildInsights = server.tool("fetchBuildInsights", "Fetches insights about a BrowserStack build by combining build details and quality gate results.", {
+    tools.fetchBuildInsights = server.tool("fetchBuildInsights", "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"),
     }, {
         title: "Fetch Build Insights",

package/dist/tools/failurelogs-utils/app-automate.js

@@ -1,6 +1,7 @@
 import { getBrowserStackAuth } from "../../lib/get-auth.js";
 import { filterLinesByKeywords, validateLogResponse } from "./utils.js";
 import { apiClient } from "../../lib/apiClient.js";
+import { wrapUntrusted } from "../../lib/untrusted-content.js";
 // DEVICE LOGS
 export async function retrieveDeviceLogs(sessionId, buildId, config) {
     const url = `https://api.browserstack.com/app-automate/builds/${buildId}/sessions/${sessionId}/deviceLogs`;
@@ -22,7 +23,7 @@ export async function retrieveDeviceLogs(sessionId, buildId, config) {
         : JSON.stringify(response.data);
     const logs = filterDeviceFailures(logText);
     return logs.length > 0
-        ? `Device Failures (${logs.length} found):\n${JSON.stringify(logs, null, 2)}`
+        ? `Device Failures (${logs.length} found):\n${wrapUntrusted("device logs", JSON.stringify(logs, null, 2))}`
         : "No device failures found";
 }
 // APPIUM LOGS
@@ -46,7 +47,7 @@ export async function retrieveAppiumLogs(sessionId, buildId, config) {
         : JSON.stringify(response.data);
     const logs = filterAppiumFailures(logText);
     return logs.length > 0
-        ? `Appium Failures (${logs.length} found):\n${JSON.stringify(logs, null, 2)}`
+        ? `Appium Failures (${logs.length} found):\n${wrapUntrusted("Appium logs", JSON.stringify(logs, null, 2))}`
         : "No Appium failures found";
 }
 // CRASH LOGS
@@ -70,7 +71,7 @@ export async function retrieveCrashLogs(sessionId, buildId, config) {
         : JSON.stringify(response.data);
     const logs = filterCrashFailures(logText);
     return logs.length > 0
-        ? `Crash Failures (${logs.length} found):\n${JSON.stringify(logs, null, 2)}`
+        ? `Crash Failures (${logs.length} found):\n${wrapUntrusted("crash logs", JSON.stringify(logs, null, 2))}`
         : "No crash failures found";
 }
 // FILTER HELPERS