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

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>;

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

@@ -0,0 +1,131 @@
+import { apiClient } from "../../lib/apiClient.js";
+import { getBrowserStackAuth } from "../../lib/get-auth.js";
+import { getO11yBaseUrl, getRcaViewGuidance, RCA_CHAT_POLL_PATH, } from "./constants.js";
+import { PENDING_STATUS, TfaStatus, } from "./types.js";
+export class TfaRcaTurnError extends Error {
+}
+export function buildAuthHeader(config) {
+    const authString = getBrowserStackAuth(config);
+    return `Basic ${Buffer.from(authString).toString("base64")}`;
+}
+/** Map a raw status string from the wire onto the `TfaStatus` enum. */
+function toTfaStatus(raw) {
+    switch (raw) {
+        case "RESOLVED":
+            return TfaStatus.RESOLVED;
+        case "BLOCKED":
+            return TfaStatus.BLOCKED;
+        default:
+            return TfaStatus.NEEDS_INFO;
+    }
+}
+/** Map one wire ask (snake_case) to the client `TfaAsk` (camelCase). */
+function toAsk(raw) {
+    return {
+        what: raw?.what ?? "",
+        why: raw?.why ?? "",
+        evidenceType: raw?.evidence_type ?? "other",
+        priority: raw?.priority ?? "medium",
+    };
+}
+// The poll envelope's `status` is the lifecycle state (working/completed/failed);
+// the agent's TurnResponse under `turn` has its own status (NEEDS_INFO/RESOLVED/
+// BLOCKED). Default-fills lists so the skill never sees `undefined`.
+export function readStructuredTurn(data) {
+    const turn = data.turn ?? {};
+    const status = toTfaStatus(turn.status);
+    const needsInfo = turn.needs_info ?? {};
+    const blocked = turn.blocked ?? {};
+    return {
+        status,
+        confidence: turn.confidence ?? "unknown",
+        questions: Array.isArray(needsInfo.questions) ? needsInfo.questions : [],
+        asks: Array.isArray(needsInfo.asks) ? needsInfo.asks.map(toAsk) : [],
+        suggestions: Array.isArray(needsInfo.suggestions)
+            ? needsInfo.suggestions
+            : [],
+        hypotheses: Array.isArray(needsInfo.hypotheses) ? needsInfo.hypotheses : [],
+        rca: status === TfaStatus.RESOLVED ? (turn.rca ?? undefined) : undefined,
+        reason: status === TfaStatus.BLOCKED ? blocked.reason : undefined,
+        unmetAsks: status === TfaStatus.BLOCKED && Array.isArray(blocked.unmet_asks)
+            ? blocked.unmet_asks
+            : undefined,
+    };
+}
+// Trim a completed turn to the status-discriminated contract: NEEDS_INFO
+// carries questions/asks/suggestions/hypotheses verbatim; RESOLVED carries a
+// glimpse + viewRca pointer; BLOCKED carries reason + unmetAsks.
+export function toTrimmedResult(turn, threadId) {
+    switch (turn.status) {
+        case TfaStatus.RESOLVED: {
+            const rca = turn.rca ?? {};
+            return {
+                status: turn.status,
+                confidence: turn.confidence,
+                threadId,
+                glimpse: {
+                    root_cause: rca.root_cause,
+                    failure_type: rca.failure_type,
+                    related_prs: rca.related_prs,
+                },
+                viewRca: getRcaViewGuidance(),
+            };
+        }
+        case TfaStatus.BLOCKED:
+            return {
+                status: turn.status,
+                confidence: turn.confidence,
+                threadId,
+                reason: turn.reason,
+                unmetAsks: turn.unmetAsks,
+            };
+        default:
+            return {
+                status: turn.status,
+                confidence: turn.confidence,
+                threadId,
+                questions: turn.questions,
+                asks: turn.asks,
+                suggestions: turn.suggestions,
+                hypotheses: turn.hypotheses,
+            };
+    }
+}
+/** Build the poll (GET) URL for one already-submitted turn. */
+export function buildPollUrl(testRunId, turnId) {
+    return (getO11yBaseUrl() +
+        RCA_CHAT_POLL_PATH.replace("{testRunId}", testRunId).replace("{turnId}", turnId));
+}
+// Read an already-submitted turn once (no polling loop, no submit); a turn
+// still in flight yields the soft PENDING status carrying turnId/threadId.
+export async function getTfaTurnResult(args, config) {
+    const headers = {
+        "Content-Type": "application/json",
+        Authorization: buildAuthHeader(config),
+    };
+    const response = await apiClient.get({
+        url: buildPollUrl(args.testRunId, args.turnId),
+        headers,
+        raise_error: false,
+    });
+    if (response.status === 404) {
+        throw new TfaRcaTurnError("turn expired or not found");
+    }
+    if (!response.ok) {
+        throw new TfaRcaTurnError(`failed to read RCA turn (status ${response.status})`);
+    }
+    const data = response.data ?? {};
+    const threadId = data.threadId;
+    if (data.status === "failed") {
+        throw new TfaRcaTurnError(data.error || "TFA agent run failed");
+    }
+    if (data.status === "completed") {
+        return toTrimmedResult(readStructuredTurn(data), threadId);
+    }
+    // "working" (or any other in-progress value) → soft PENDING, read again later.
+    return {
+        status: PENDING_STATUS,
+        threadId,
+        turnId: args.turnId,
+    };
+}