@browserstack/mcp-server 1.3.0 → 1.3.1-beta.1

package/dist/tools/tfa-rca-utils/build-failure-themes.js

@@ -0,0 +1,133 @@
+import { apiClient } from "../../lib/apiClient.js";
+import { AI_FAILURES_FLAT_PATH, AI_FAILURES_PATH, BUILD_THEMES_FAILURE_STATUSES, BUILD_THEMES_POLL_INTERVAL_MS, BUILD_THEMES_POLL_MAX_WAIT_MS, BUILD_THEMES_SUCCESS_STATUS, getO11yBaseUrl, } from "./constants.js";
+import { buildAuthHeader } from "./turn-result.js";
+export class BuildFailureThemesError extends Error {
+}
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function authHeaders(config) {
+    return {
+        "Content-Type": "application/json",
+        Authorization: buildAuthHeader(config),
+    };
+}
+// Normalize a response body to a plain object — a malformed 200 is treated as "no data".
+function asObject(data) {
+    return typeof data === "object" && data !== null && !Array.isArray(data)
+        ? data
+        : {};
+}
+function failuresUrl(buildUuid) {
+    return (getO11yBaseUrl() +
+        AI_FAILURES_PATH.replace("{buildUuid}", encodeURIComponent(buildUuid)));
+}
+async function fetchFailuresOnce(buildUuid, config) {
+    return apiClient.get({
+        url: failuresUrl(buildUuid),
+        headers: authHeaders(config),
+        raise_error: false,
+    });
+}
+// Same URL as the GET read, different verb — kicks off build-level theme computation.
+async function triggerFailuresOnce(buildUuid, config) {
+    return apiClient.post({
+        url: failuresUrl(buildUuid),
+        headers: authHeaders(config),
+        body: {},
+        raise_error: false,
+    });
+}
+// Fetch a build's server-computed failure-theme clusters, triggering computation
+// if nothing has run yet. Triggers at most once per call, then polls until
+// SUCCESS or BUILD_THEMES_POLL_MAX_WAIT_MS is spent — never blocks past that.
+export async function fetchBuildFailureThemes(buildUuid, config) {
+    const startTime = Date.now();
+    let lastStatus;
+    let triggered = false;
+    /** Attempts the one-time trigger POST; returns whether it succeeded. */
+    const triggerOnce = async () => {
+        triggered = true;
+        const triggerResponse = await triggerFailuresOnce(buildUuid, config);
+        return triggerResponse.ok;
+    };
+    while (true) {
+        const response = await fetchFailuresOnce(buildUuid, config);
+        if (response.ok) {
+            const data = asObject(response.data);
+            const status = data.buildThemeWorkflow?.status;
+            if (status === BUILD_THEMES_SUCCESS_STATUS) {
+                return {
+                    ready: true,
+                    status,
+                    buildId: data.buildId,
+                    buildThemes: data.buildThemes ?? [],
+                    buildWorkflows: data.buildWorkflows ?? [],
+                    stats: data.stats,
+                };
+            }
+            if (status && BUILD_THEMES_FAILURE_STATUSES.includes(status)) {
+                if (triggered) {
+                    // Already retried once and it failed again — a real failure, not
+                    // async lag. Nothing left to do but report it.
+                    return { ready: false, status };
+                }
+                if (!(await triggerOnce())) {
+                    return { ready: false, status: "trigger-unavailable" };
+                }
+            }
+            else {
+                // status undefined (never computed) — trigger once. An in-progress
+                // value (PENDING/PROCESSING) just keeps polling either way.
+                if (!status && !triggered && !(await triggerOnce())) {
+                    return { ready: false, status: "trigger-unavailable" };
+                }
+                lastStatus = status ?? lastStatus;
+            }
+        }
+        else if (response.status === 404) {
+            if (!triggered && !(await triggerOnce())) {
+                return { ready: false, status: "trigger-unavailable" };
+            }
+        }
+        else {
+            throw new BuildFailureThemesError(`failed to fetch build failure themes (status ${response.status})`);
+        }
+        if (Date.now() - startTime >= BUILD_THEMES_POLL_MAX_WAIT_MS) {
+            return { ready: false, status: lastStatus ?? "PENDING" };
+        }
+        await delay(BUILD_THEMES_POLL_INTERVAL_MS);
+    }
+}
+/** Paginated test-run membership for one failure theme or workflow. */
+export async function fetchTestsInFailureTheme(args, config) {
+    const params = {
+        limit: args.limit ?? 50,
+    };
+    if (args.themeId !== undefined)
+        params.buildFailureThemeId = args.themeId;
+    if (args.workflowId !== undefined)
+        params.buildFailureWorkflowId = args.workflowId;
+    if (args.cursor)
+        params.searchAfter = args.cursor;
+    const url = getO11yBaseUrl() +
+        AI_FAILURES_FLAT_PATH.replace("{buildUuid}", encodeURIComponent(args.buildUuid));
+    const response = await apiClient.get({
+        url,
+        headers: authHeaders(config),
+        params,
+        raise_error: false,
+    });
+    if (!response.ok) {
+        throw new BuildFailureThemesError(`failed to list tests in failure theme (status ${response.status})`);
+    }
+    const data = asObject(response.data);
+    const testRuns = data.testRuns ?? [];
+    return {
+        tests: testRuns.map((t) => ({
+            testRunId: t?.details?.id ?? t?.id,
+            title: t?.title,
+            status: t?.details?.status,
+            raw: t,
+        })),
+        nextCursor: data.nextCursor ?? data.searchAfter ?? data.next_search_after,
+    };
+}

package/dist/tools/tfa-rca-utils/constants.d.ts

@@ -0,0 +1,67 @@
+import { z } from "zod";
+export declare function getO11yBaseUrl(): string;
+export declare function getO11yUiBaseUrl(): string;
+export declare const O11Y_UI_BUILD_PATH = "/builds/{buildUuid}?tab=ai_report&subTab=aitfa";
+/** Human-facing TRA UI link for one build's full report. */
+export declare function getO11yUiBuildUrl(buildUuid: string): string;
+export declare function getRcaViewGuidance(): string;
+/** Trigger (or read, when already complete) a build's Release Readiness report. */
+export declare const RELEASE_READINESS_TRIGGER_PATH = "/ext/v1/ai/builds/{buildUuid}/releaseReadiness/trigger";
+/** Read a build's server-computed failure-theme clusters. */
+export declare const AI_FAILURES_PATH = "/ext/v1/ai/failures/{buildUuid}";
+/** Paginated test-run membership for one failure theme / workflow. */
+export declare const AI_FAILURES_FLAT_PATH = "/ext/v1/ai/failures/{buildUuid}/flat";
+export declare const BUILD_THEMES_SUCCESS_STATUS = "SUCCESS";
+export declare const BUILD_THEMES_FAILURE_STATUSES: string[];
+/** Interval between in-call polls of the build-failure-themes readiness. */
+export declare const BUILD_THEMES_POLL_INTERVAL_MS = 3000;
+export declare const BUILD_THEMES_POLL_MAX_WAIT_MS: number;
+export declare const GET_BUILD_FAILURE_THEMES_PARAMS: {
+    buildUuid: z.ZodString;
+};
+export declare const LIST_TESTS_IN_FAILURE_THEME_PARAMS: {
+    buildUuid: z.ZodString;
+    themeId: z.ZodOptional<z.ZodNumber>;
+    workflowId: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    cursor: z.ZodOptional<z.ZodString>;
+};
+/** Submit one collaborative turn for a test run. */
+export declare const RCA_CHAT_SUBMIT_PATH = "/ext/v1/testRuns/{testRunId}/rcaChat";
+/** Poll a submitted turn to completion. */
+export declare const RCA_CHAT_POLL_PATH = "/ext/v1/testRuns/{testRunId}/rcaChat/{turnId}";
+/** Initial wait before the first poll GET. */
+export declare const POLL_INITIAL_DELAY_MS = 2000;
+/** Interval between poll GETs. */
+export declare const POLL_INTERVAL_MS = 3000;
+/** Wall-clock cap for the in-call poll; exceeding it yields a soft PENDING. */
+export declare const POLL_MAX_WAIT_MS: number;
+/** Max length of the digest message, matching o11y's request `@Size`. */
+export declare const MESSAGE_MAX_LENGTH = 5000;
+/** Max chars of `root_cause` surfaced in the RESOLVED glimpse. */
+export declare const RCA_GLIMPSE_ROOT_CAUSE_MAX = 220;
+export declare const TFA_RCA_TURN_PARAMS: {
+    testRunId: z.ZodString;
+    message: z.ZodString;
+    threadId: z.ZodOptional<z.ZodString>;
+    turnId: z.ZodOptional<z.ZodString>;
+    prDetails: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        repo: z.ZodString;
+        number: z.ZodNumber;
+        title: z.ZodString;
+        author: z.ZodString;
+        link: z.ZodString;
+        tag: z.ZodEnum<{
+            latent: "latent";
+            regression: "regression";
+        }>;
+    }, z.core.$strip>>>;
+};
+export declare const GET_TFA_TURN_RESULT_PARAMS: {
+    testRunId: z.ZodString;
+    turnId: z.ZodString;
+};
+export declare const TRIGGER_RCA_REPORT_PARAMS: {
+    buildUuid: z.ZodString;
+    force: z.ZodOptional<z.ZodBoolean>;
+};

package/dist/tools/tfa-rca-utils/constants.js

@@ -0,0 +1,103 @@
+import { z } from "zod";
+import appConfig from "../../config.js";
+export function getO11yBaseUrl() {
+    return appConfig.O11Y_TFA_RCA_BASE_URL;
+}
+export function getO11yUiBaseUrl() {
+    return appConfig.BROWSERSTACK_O11Y_UI_BASE_URL;
+}
+// TRA UI deep-link for a build's AI-TFA sub-tab.
+export const O11Y_UI_BUILD_PATH = "/builds/{buildUuid}?tab=ai_report&subTab=aitfa";
+/** Human-facing TRA UI link for one build's full report. */
+export function getO11yUiBuildUrl(buildUuid) {
+    return (getO11yUiBaseUrl() +
+        O11Y_UI_BUILD_PATH.replace("{buildUuid}", encodeURIComponent(buildUuid)));
+}
+// Generic TRA UI pointer for RESOLVED turns where only a testRunId is known.
+export function getRcaViewGuidance() {
+    return `${getO11yUiBaseUrl()} — open the build's AI report (tab=ai_report, subTab=aitfa) to view the full RCA`;
+}
+/** Trigger (or read, when already complete) a build's Release Readiness report. */
+export const RELEASE_READINESS_TRIGGER_PATH = "/ext/v1/ai/builds/{buildUuid}/releaseReadiness/trigger";
+/** Read a build's server-computed failure-theme clusters. */
+export const AI_FAILURES_PATH = "/ext/v1/ai/failures/{buildUuid}";
+/** Paginated test-run membership for one failure theme / workflow. */
+export const AI_FAILURES_FLAT_PATH = "/ext/v1/ai/failures/{buildUuid}/flat";
+export const BUILD_THEMES_SUCCESS_STATUS = "SUCCESS";
+export const BUILD_THEMES_FAILURE_STATUSES = ["FAILED", "ERROR"];
+/** Interval between in-call polls of the build-failure-themes readiness. */
+export const BUILD_THEMES_POLL_INTERVAL_MS = 3000;
+export const BUILD_THEMES_POLL_MAX_WAIT_MS = 90 * 1000;
+export const GET_BUILD_FAILURE_THEMES_PARAMS = {
+    buildUuid: z
+        .string()
+        .describe("Automate build UUID to fetch failure themes for."),
+};
+export const LIST_TESTS_IN_FAILURE_THEME_PARAMS = {
+    buildUuid: z
+        .string()
+        .describe("Automate build UUID the theme/workflow belongs to."),
+    themeId: z.number().optional().describe("buildFailureThemeId to filter by."),
+    workflowId: z
+        .number()
+        .optional()
+        .describe("buildFailureWorkflowId to filter by."),
+    limit: z.number().optional().describe("Max tests to return, default 50."),
+    cursor: z
+        .string()
+        .optional()
+        .describe("searchAfter cursor from a prior call."),
+};
+/** Submit one collaborative turn for a test run. */
+export const RCA_CHAT_SUBMIT_PATH = "/ext/v1/testRuns/{testRunId}/rcaChat";
+/** Poll a submitted turn to completion. */
+export const RCA_CHAT_POLL_PATH = "/ext/v1/testRuns/{testRunId}/rcaChat/{turnId}";
+/** Initial wait before the first poll GET. */
+export const POLL_INITIAL_DELAY_MS = 2000;
+/** Interval between poll GETs. */
+export const POLL_INTERVAL_MS = 3000;
+/** Wall-clock cap for the in-call poll; exceeding it yields a soft PENDING. */
+export const POLL_MAX_WAIT_MS = 90 * 1000;
+/** Max length of the digest message, matching o11y's request `@Size`. */
+export const MESSAGE_MAX_LENGTH = 5000;
+/** Max chars of `root_cause` surfaced in the RESOLVED glimpse. */
+export const RCA_GLIMPSE_ROOT_CAUSE_MAX = 220;
+export const TFA_RCA_TURN_PARAMS = {
+    testRunId: z.string().describe("Test run id to run RCA collaboration on."),
+    message: z
+        .string()
+        .max(MESSAGE_MAX_LENGTH)
+        .describe("Digested analysis to send this turn; no raw logs."),
+    threadId: z
+        .string()
+        .optional()
+        .describe("Thread id from prior turn; omit on first turn."),
+    turnId: z
+        .string()
+        .optional()
+        .describe("Turn id to resume a pending poll; usually omit."),
+    prDetails: z
+        .array(z.object({
+        repo: z.string().describe("owner/name, e.g. browserstack/ai-sdk."),
+        number: z.number().describe("PR number (unique only within repo)."),
+        title: z.string().describe("PR title."),
+        author: z.string().describe("PR author."),
+        link: z
+            .string()
+            .describe("Canonical URL: https://github.com/<repo>/pull/<number>."),
+        tag: z.enum(["latent", "regression"]).describe("latent | regression."),
+    }))
+        .optional()
+        .describe("Suspect PRs; identity is repo+number. Each needs repo, number, title, author, link, tag."),
+};
+export const GET_TFA_TURN_RESULT_PARAMS = {
+    testRunId: z.string().describe("Test run id the turn was submitted on."),
+    turnId: z.string().describe("Turn id returned by tfaRcaTurn."),
+};
+export const TRIGGER_RCA_REPORT_PARAMS = {
+    buildUuid: z.string().describe("Automate build UUID to analyze."),
+    force: z
+        .boolean()
+        .optional()
+        .describe("Re-run even if a completed report exists."),
+};

package/dist/tools/tfa-rca-utils/submit-turn.d.ts

@@ -0,0 +1,29 @@
+import { BrowserStackConfig } from "../../lib/types.js";
+import { TfaRcaTurnResult } from "./types.js";
+import { TfaRcaTurnError } from "./turn-result.js";
+export { TfaRcaTurnError };
+interface TurnContext {
+    sendNotification?: (notification: any) => Promise<void>;
+    _meta?: {
+        progressToken?: string | number;
+    };
+}
+export type PrTag = "latent" | "regression";
+export interface PrDetail {
+    repo: string;
+    number: number;
+    title: string;
+    author: string;
+    link: string;
+    tag: PrTag;
+}
+export interface TfaRcaTurnArgs {
+    testRunId: string;
+    message: string;
+    /** Suspect PRs as context. Optional, but each entry must satisfy PrDetail. */
+    prDetails?: PrDetail[];
+    threadId?: string;
+    /** Resume polling an already-submitted turn without re-submitting. */
+    turnId?: string;
+}
+export declare function submitTfaRcaTurn(args: TfaRcaTurnArgs, config: BrowserStackConfig, context?: TurnContext): Promise<TfaRcaTurnResult>;

package/dist/tools/tfa-rca-utils/submit-turn.js

@@ -0,0 +1,188 @@
+import { apiClient } from "../../lib/apiClient.js";
+import { getO11yBaseUrl, MESSAGE_MAX_LENGTH, POLL_INITIAL_DELAY_MS, POLL_INTERVAL_MS, POLL_MAX_WAIT_MS, RCA_CHAT_SUBMIT_PATH, } from "./constants.js";
+import { PENDING_STATUS } from "./types.js";
+import { buildAuthHeader, buildPollUrl, readStructuredTurn, TfaRcaTurnError, toTrimmedResult, } from "./turn-result.js";
+// Re-exported so existing importers keep a single entry point for the error type.
+export { TfaRcaTurnError };
+const PR_TAGS = ["latent", "regression"];
+// Any PR entry present MUST carry every field; a partial one is rejected.
+function validatePrDetails(prDetails) {
+    prDetails.forEach((pr, i) => {
+        if (!pr || typeof pr !== "object") {
+            throw new TfaRcaTurnError(`prDetails[${i}] is not an object`);
+        }
+        const missing = [];
+        if (!pr.repo)
+            missing.push("repo");
+        if (pr.number === undefined || pr.number === null)
+            missing.push("number");
+        if (!pr.title)
+            missing.push("title");
+        if (!pr.author)
+            missing.push("author");
+        if (!pr.link)
+            missing.push("link");
+        if (!pr.tag)
+            missing.push("tag");
+        if (missing.length > 0) {
+            throw new TfaRcaTurnError(`prDetails[${i}] missing required field(s): ${missing.join(", ")}`);
+        }
+        if (!PR_TAGS.includes(pr.tag)) {
+            throw new TfaRcaTurnError(`prDetails[${i}].tag must be one of: ${PR_TAGS.join(", ")}`);
+        }
+        // link must be the canonical PR URL for repo+number.
+        if (!pr.link.includes(`/${pr.repo}/pull/${pr.number}`)) {
+            throw new TfaRcaTurnError(`prDetails[${i}].link must be the canonical URL for ${pr.repo}#${pr.number} ` +
+                `(https://github.com/${pr.repo}/pull/${pr.number})`);
+        }
+    });
+}
+// Structured PR payload for the request's `clientContext` digest channel
+// (size-capped at 100_000 bytes) — kept out of `message`, which is capped at 5000.
+function buildPrClientContext(prDetails) {
+    if (!prDetails || prDetails.length === 0)
+        return undefined;
+    return { pr_details: prDetails };
+}
+// Append a compact PR marker (`repo#number [tag]` refs) to the message; the
+// full objects travel in `clientContext`. Downgraded/dropped if it would push
+// the message past MESSAGE_MAX_LENGTH — nothing is lost since clientContext has it.
+function composeMessageWithPrMarker(message, prDetails) {
+    const fits = (suffix) => message.length + suffix.length <= MESSAGE_MAX_LENGTH;
+    if (!prDetails || prDetails.length === 0) {
+        const noneFull = "\n\nPR_DETAILS: none provided — no client-supplied PR this turn. Do not" +
+            " infer a repo, URL or author from prose; leave related_prs empty and state" +
+            " what was searched.";
+        if (fits(noneFull))
+            return `${message}${noneFull}`;
+        const none = "\n\nPR_DETAILS: none provided — do not infer PRs from prose.";
+        return fits(none) ? `${message}${none}` : message;
+    }
+    const refs = prDetails
+        .map((pr) => `${pr.repo}#${pr.number} [${pr.tag}]`)
+        .join(", ");
+    const legend = " — regression = the PR introduced the fault; latent = the fault predates the" +
+        " PR and the PR exposed it. Carry the distinction into the RCA.";
+    const full = `\n\nPR_DETAILS: ${prDetails.length} in clientContext (${refs})${legend}`;
+    if (fits(full))
+        return `${message}${full}`;
+    const noLegend = `\n\nPR_DETAILS: ${prDetails.length} in clientContext (${refs})`;
+    if (fits(noLegend))
+        return `${message}${noLegend}`;
+    const terse = `\n\nPR_DETAILS: ${prDetails.length} in clientContext`;
+    return fits(terse) ? `${message}${terse}` : message;
+}
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function notify(context, message, progress) {
+    if (!context?.sendNotification)
+        return;
+    await context.sendNotification({
+        method: "notifications/progress",
+        params: {
+            progressToken: context._meta?.progressToken?.toString() ?? "tfa-rca-turn",
+            message,
+            progress,
+            total: 100,
+        },
+    });
+}
+/** Map a submit (POST) non-2xx into a clean, group-scope-safe domain error. */
+function mapSubmitError(status) {
+    if (status === 403) {
+        return new TfaRcaTurnError("AI consent not enabled for this group");
+    }
+    if (status === 404) {
+        return new TfaRcaTurnError("test run not found for your group");
+    }
+    return new TfaRcaTurnError(`failed to submit RCA turn (status ${status})`);
+}
+// Submit one collaborative RCA turn to the o11y `rcaChat` proxy and poll to
+// completion, returning a trimmed structured result.
+export async function submitTfaRcaTurn(args, config, context) {
+    const authHeader = buildAuthHeader(config);
+    const headers = {
+        "Content-Type": "application/json",
+        Authorization: authHeader,
+    };
+    const baseUrl = getO11yBaseUrl();
+    let turnId = args.turnId;
+    let threadId = args.threadId;
+    // Submit only when we are not resuming an existing turn.
+    if (!turnId) {
+        const submitUrl = baseUrl + RCA_CHAT_SUBMIT_PATH.replace("{testRunId}", args.testRunId);
+        await notify(context, "Submitting RCA turn to TFA agent...", 5);
+        // Validate the PR contract before sending; a partial PR object is rejected
+        // rather than forwarded as misleading context.
+        if (args.prDetails) {
+            validatePrDetails(args.prDetails);
+        }
+        // PR context travels as structured data in the `clientContext` digest lane;
+        // the message carries only a bounded marker naming the PRs.
+        const composedMessage = composeMessageWithPrMarker(args.message, args.prDetails);
+        const prClientContext = buildPrClientContext(args.prDetails);
+        const body = {
+            message: composedMessage,
+        };
+        if (prClientContext) {
+            body.clientContext = prClientContext;
+        }
+        if (args.threadId) {
+            body.thread_id = args.threadId;
+        }
+        const submitResponse = await apiClient.post({
+            url: submitUrl,
+            headers,
+            body,
+            raise_error: false,
+        });
+        if (!submitResponse.ok) {
+            throw mapSubmitError(submitResponse.status);
+        }
+        const data = submitResponse.data ?? {};
+        turnId = data.turnId;
+        threadId = data.threadId ?? threadId;
+        if (!turnId) {
+            throw new TfaRcaTurnError("turn expired or not found");
+        }
+    }
+    // Poll to completion, soft-PENDING on wall-clock cap.
+    const pollUrl = buildPollUrl(args.testRunId, turnId);
+    await delay(POLL_INITIAL_DELAY_MS);
+    const startTime = Date.now();
+    while (true) {
+        const pollResponse = await apiClient.get({
+            url: pollUrl,
+            headers,
+            raise_error: false,
+        });
+        if (pollResponse.status === 404) {
+            throw new TfaRcaTurnError("turn expired or not found");
+        }
+        if (pollResponse.ok) {
+            const data = pollResponse.data ?? {};
+            const status = data.status;
+            threadId = data.threadId ?? threadId;
+            if (status === "failed") {
+                throw new TfaRcaTurnError(data.error || "TFA agent run failed");
+            }
+            if (status === "completed") {
+                const turn = readStructuredTurn(data);
+                await notify(context, "TFA agent turn complete.", 100);
+                return toTrimmedResult(turn, threadId);
+            }
+            // status === "working" (or any other in-progress value) → keep polling.
+        }
+        // Transient non-2xx (other than 404) during polling: classify and continue.
+        if (Date.now() - startTime >= POLL_MAX_WAIT_MS) {
+            await notify(context, "TFA agent still working; will resume later.", 90);
+            // PENDING keeps only what the skill needs to resume polling.
+            return {
+                status: PENDING_STATUS,
+                threadId,
+                turnId,
+            };
+        }
+        await notify(context, "Waiting for TFA agent reply...", 50);
+        await delay(POLL_INTERVAL_MS);
+    }
+}

package/dist/tools/tfa-rca-utils/trigger-report.d.ts

@@ -0,0 +1,22 @@
+import { BrowserStackConfig } from "../../lib/types.js";
+export interface TriggerRcaReportArgs {
+    buildUuid: string;
+    /** Re-run even if a completed report already exists. */
+    force?: boolean;
+}
+export declare class TriggerRcaReportError extends Error {
+}
+export interface RcaReportGlimpse {
+    state?: string;
+    verdict?: string;
+    verdictProvisional?: boolean;
+    partial?: boolean;
+    analyzedCount?: number;
+    totalFailedCount?: number;
+    totalPrs?: number;
+    faultyPrNumbers?: unknown[];
+    failureReason?: string;
+    /** TRA UI link where the full report lives. */
+    viewReport: string;
+}
+export declare function triggerRcaReport(args: TriggerRcaReportArgs, config: BrowserStackConfig): Promise<RcaReportGlimpse>;

package/dist/tools/tfa-rca-utils/trigger-report.js

@@ -0,0 +1,61 @@
+import { apiClient } from "../../lib/apiClient.js";
+import { getBrowserStackAuth } from "../../lib/get-auth.js";
+import { getO11yBaseUrl, getO11yUiBuildUrl, RELEASE_READINESS_TRIGGER_PATH, } from "./constants.js";
+export class TriggerRcaReportError extends Error {
+}
+/** Pull a machine error code out of a non-2xx body, wherever it rides. */
+function extractErrorCode(data) {
+    const candidate = data?.code ?? data?.error ?? data?.errorCode ?? data?.message;
+    return typeof candidate === "string" ? candidate : "";
+}
+/** Map a trigger (POST) non-2xx into a clean, group-scope-safe domain error. */
+function mapTriggerError(status, data) {
+    const code = extractErrorCode(data);
+    if (code.includes("REPO_NOT_CONFIGURED")) {
+        return new TriggerRcaReportError("repository not configured for Release Readiness; connect the repo in Test Observability settings");
+    }
+    if (code.includes("RELEASE_READINESS_NOT_FOUND")) {
+        return new TriggerRcaReportError("no Release Readiness report found for this build");
+    }
+    if (status === 403) {
+        return new TriggerRcaReportError("Release Readiness AI is not enabled for this group (plan or feature flag)");
+    }
+    if (status === 404) {
+        return new TriggerRcaReportError("build not found for your group");
+    }
+    return new TriggerRcaReportError(`failed to trigger Release Readiness report (status ${status})`);
+}
+export async function triggerRcaReport(args, config) {
+    const authString = getBrowserStackAuth(config);
+    const headers = {
+        "Content-Type": "application/json",
+        Authorization: `Basic ${Buffer.from(authString).toString("base64")}`,
+    };
+    const url = getO11yBaseUrl() +
+        RELEASE_READINESS_TRIGGER_PATH.replace("{buildUuid}", encodeURIComponent(args.buildUuid)) +
+        `?force=${args.force === true}`;
+    const response = await apiClient.post({
+        url,
+        headers,
+        body: {},
+        raise_error: false,
+    });
+    if (!response.ok) {
+        throw mapTriggerError(response.status, response.data);
+    }
+    const data = response.data ?? {};
+    const summary = data.summary ?? {};
+    // Trimmed glimpse only — never the raw response, never prs[]/workflows[].
+    return {
+        state: summary.state ?? data.state,
+        verdict: summary.verdict,
+        verdictProvisional: summary.verdictProvisional,
+        partial: summary.partial,
+        analyzedCount: summary.analyzedCount,
+        totalFailedCount: summary.totalFailedCount,
+        totalPrs: summary.totalPrs,
+        faultyPrNumbers: summary.faultyPrNumbers,
+        failureReason: summary.failureReason,
+        viewReport: getO11yUiBuildUrl(args.buildUuid),
+    };
+}

package/dist/tools/tfa-rca-utils/turn-result.d.ts

@@ -0,0 +1,14 @@
+import { BrowserStackConfig } from "../../lib/types.js";
+import { TfaRcaTurnResult, TurnResponse } from "./types.js";
+export declare class TfaRcaTurnError extends Error {
+}
+export interface GetTfaTurnResultArgs {
+    testRunId: string;
+    turnId: string;
+}
+export declare function buildAuthHeader(config: BrowserStackConfig): string;
+export declare function readStructuredTurn(data: any): TurnResponse;
+export declare function toTrimmedResult(turn: TurnResponse, threadId: string | undefined): TfaRcaTurnResult;
+/** Build the poll (GET) URL for one already-submitted turn. */
+export declare function buildPollUrl(testRunId: string, turnId: string): string;
+export declare function getTfaTurnResult(args: GetTfaTurnResultArgs, config: BrowserStackConfig): Promise<TfaRcaTurnResult>;