@browserstack/mcp-server 1.3.0 → 1.3.1

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,
+    };
+}

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

@@ -0,0 +1,61 @@
+export declare enum TfaStatus {
+    NEEDS_INFO = "NEEDS_INFO",
+    RESOLVED = "RESOLVED",
+    BLOCKED = "BLOCKED"
+}
+export declare const PENDING_STATUS: "PENDING";
+export type Confidence = "low" | "medium" | "high" | "unknown";
+export type EvidenceType = "test_logs" | "product_code" | "k8s" | "kibana" | "metrics" | "deploy" | "ci" | "other";
+/** A typed request for evidence; the skill routes it by `evidenceType`. */
+export interface TfaAsk {
+    what: string;
+    why: string;
+    evidenceType: EvidenceType;
+    priority: "high" | "medium" | "low";
+}
+export interface TfaRca {
+    root_cause?: string;
+    description?: string;
+    possible_fix?: string;
+    failure_type?: string;
+    alternatives_considered?: string[];
+    related_prs?: unknown[];
+    [key: string]: unknown;
+}
+export interface TurnResponse {
+    status: TfaStatus;
+    confidence: Confidence;
+    questions: string[];
+    asks: TfaAsk[];
+    suggestions: string[];
+    hypotheses: string[];
+    rca?: TfaRca;
+    /** Present on BLOCKED turns: why TFA cannot proceed. */
+    reason?: string;
+    /** Present on BLOCKED turns: the asks that went unmet. */
+    unmetAsks?: string[];
+}
+export interface TfaRcaGlimpse {
+    /** Truncated to `RCA_GLIMPSE_ROOT_CAUSE_MAX` chars. */
+    root_cause?: string;
+    failure_type?: string;
+    related_prs?: unknown[];
+}
+export interface TfaRcaTurnResult {
+    status: TfaStatus | typeof PENDING_STATUS;
+    confidence?: Confidence;
+    threadId?: string;
+    /** Present on PENDING turns: resume via the tool's `turnId` arg. */
+    turnId?: string;
+    questions?: string[];
+    asks?: TfaAsk[];
+    suggestions?: string[];
+    hypotheses?: string[];
+    /** Present on RESOLVED turns: trimmed root-cause glimpse. */
+    glimpse?: TfaRcaGlimpse;
+    rca?: unknown;
+    /** Present on RESOLVED turns: where the full RCA report lives. */
+    viewRca?: string;
+    reason?: string;
+    unmetAsks?: string[];
+}

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

@@ -0,0 +1,9 @@
+// Collaboration status emitted by the TFA agent for one RCA turn.
+export var TfaStatus;
+(function (TfaStatus) {
+    TfaStatus["NEEDS_INFO"] = "NEEDS_INFO";
+    TfaStatus["RESOLVED"] = "RESOLVED";
+    TfaStatus["BLOCKED"] = "BLOCKED";
+})(TfaStatus || (TfaStatus = {}));
+// Soft, tool-emitted status when an in-call poll exceeds its wall-clock cap.
+export const PENDING_STATUS = "PENDING";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserstack/mcp-server",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "BrowserStack's Official MCP Server",
   "mcpName": "io.github.browserstack/mcp-server",
   "main": "dist/index.js",