@browserstack/mcp-server 1.5.0-beta.9 → 1.5.1-beta.1

package/dist/tools/get-failure-logs.js

@@ -1,8 +1,11 @@
 import { z } from "zod";
 import { trackMCP } from "../lib/instrumentation.js";
+import { NEEDS_SESSION_ID } from "./tool-handoff.js";
 import { retrieveNetworkFailures, retrieveSessionFailures, retrieveConsoleFailures, } from "./failurelogs-utils/automate.js";
 import { retrieveDeviceLogs, retrieveAppiumLogs, retrieveCrashLogs, } from "./failurelogs-utils/app-automate.js";
-import { AppAutomateLogType, AutomateLogType, SessionType, } from "../lib/constants.js";
+import { resolveAppAutomateBuildId } from "./failurelogs-utils/resolve-app-build-id.js";
+import { retrieveSessionVideo } from "./failurelogs-utils/video.js";
+import { AppAutomateLogType, AutomateLogType, SessionType, SessionVideoLogType, } from "../lib/constants.js";
 // Main log fetcher function
 export async function getFailureLogs(args, config) {
     const results = [];
@@ -11,17 +14,16 @@ export async function getFailureLogs(args, config) {
     if (!args.sessionId) {
         throw new Error("Session ID is required");
     }
-    if (args.sessionType === SessionType.AppAutomate && !args.buildId) {
-        throw new Error("Build ID is required for app-automate sessions");
-    }
     // Validate log types and collect errors
     validLogTypes = args.logTypes.filter((logType) => {
         const isAutomate = Object.values(AutomateLogType).includes(logType);
         const isAppAutomate = Object.values(AppAutomateLogType).includes(logType);
         if (!isAutomate && !isAppAutomate) {
             errors.push(`Invalid log type '${logType}'. Valid log types are: ${[
-                ...Object.values(AutomateLogType),
-                ...Object.values(AppAutomateLogType),
+                ...new Set([
+                    ...Object.values(AutomateLogType),
+                    ...Object.values(AppAutomateLogType),
+                ]),
             ].join(", ")}`);
             return false;
         }
@@ -46,11 +48,26 @@ export async function getFailureLogs(args, config) {
             isError: true,
         };
     }
+    let buildId = args.buildId;
+    const needsBuildId = validLogTypes.some((logType) => logType !== SessionVideoLogType);
+    if (args.sessionType === SessionType.AppAutomate &&
+        needsBuildId &&
+        !buildId) {
+        buildId = await resolveAppAutomateBuildId(args.sessionId, config);
+        if (!buildId) {
+            throw new Error("Build ID is required for app-automate sessions");
+        }
+    }
     let response;
     // eslint-disable-next-line no-useless-catch
     try {
         for (const logType of validLogTypes) {
             switch (logType) {
+                case SessionVideoLogType: {
+                    response = await retrieveSessionVideo(args.sessionId, args.sessionType, config);
+                    results.push({ type: "text", text: response });
+                    break;
+                }
                 case AutomateLogType.NetworkLogs: {
                     response = await retrieveNetworkFailures(args.sessionId, config);
                     results.push({ type: "text", text: response });
@@ -67,17 +84,17 @@ export async function getFailureLogs(args, config) {
                     break;
                 }
                 case AppAutomateLogType.DeviceLogs: {
-                    response = await retrieveDeviceLogs(args.sessionId, args.buildId, config);
+                    response = await retrieveDeviceLogs(args.sessionId, buildId, config);
                     results.push({ type: "text", text: response });
                     break;
                 }
                 case AppAutomateLogType.AppiumLogs: {
-                    response = await retrieveAppiumLogs(args.sessionId, args.buildId, config);
+                    response = await retrieveAppiumLogs(args.sessionId, buildId, config);
                     results.push({ type: "text", text: response });
                     break;
                 }
                 case AppAutomateLogType.CrashLogs: {
-                    response = await retrieveCrashLogs(args.sessionId, args.buildId, config);
+                    response = await retrieveCrashLogs(args.sessionId, buildId, config);
                     results.push({ type: "text", text: response });
                     break;
                 }
@@ -98,7 +115,8 @@ export async function getFailureLogs(args, config) {
 // Register tool with the MCP server
 export default function registerGetFailureLogs(server, config) {
     const tools = {};
-    tools.getFailureLogs = server.tool("getFailureLogs", "Fetch various types of logs from a BrowserStack session. Supports both automate and app-automate sessions.", {
+    tools.getFailureLogs = server.tool("getFailureLogs", "Fetch logs, or the session video URL, for an Automate/App Automate session." +
+        NEEDS_SESSION_ID, {
         sessionType: z
             .enum([SessionType.Automate, SessionType.AppAutomate])
             .describe("Type of BrowserStack session. Must be explicitly provided by the user."),
@@ -108,7 +126,7 @@ export default function registerGetFailureLogs(server, config) {
         buildId: z
             .string()
             .optional()
-            .describe("Required only when sessionType is 'app-automate'. If sessionType is 'app-automate', always ask the user to provide the build ID before proceeding."),
+            .describe("App Automate build ID. Optional — resolved from the session if omitted."),
         logTypes: z
             .array(z.enum([
             AutomateLogType.NetworkLogs,
@@ -117,6 +135,7 @@ export default function registerGetFailureLogs(server, config) {
             AppAutomateLogType.DeviceLogs,
             AppAutomateLogType.AppiumLogs,
             AppAutomateLogType.CrashLogs,
+            SessionVideoLogType,
         ]))
             .describe("The types of logs to fetch."),
     }, {

package/dist/tools/observability.js

@@ -1,3 +1,4 @@
+import { wrapUntrusted } from "../lib/untrusted-content.js";
 import { z } from "zod";
 import { getLatestO11YBuildInfo } from "../lib/api.js";
 import { trackMCP } from "../lib/instrumentation.js";
@@ -26,7 +27,8 @@ export async function getFailuresInLastRun(buildName, projectName, config) {
         content: [
             {
                 type: "text",
-                text: `Observability URL: ${observabilityUrl}\nOverview: ${overview}\nError Details: ${details}`,
+                text: `Observability URL: ${observabilityUrl}\n` +
+                    wrapUntrusted("observability failure report", `Overview: ${overview}\nError Details: ${details}`),
             },
         ],
     };

package/dist/tools/percy-sdk.js

@@ -38,11 +38,11 @@ export function registerPercyTools(server, config) {
         idempotentHint: true,
     }, async (args) => {
         try {
-            trackMCP("VisualTestIntegrationAgent", server.server.getClientVersion(), config);
+            trackMCP("percyVisualTestIntegrationAgent", server.server.getClientVersion(), undefined, config);
             return simulatePercyChangeHandler(args, config);
         }
         catch (error) {
-            return handleMCPError("VisualTestIntegrationAgent", server, config, error);
+            return handleMCPError("percyVisualTestIntegrationAgent", server, config, error);
         }
     });
     tools.setupPercyVisualTesting = server.tool("expandPercyVisualTesting", SETUP_PERCY_DESCRIPTION, SetUpPercyParamsShape, {
@@ -53,11 +53,11 @@ export function registerPercyTools(server, config) {
         idempotentHint: true,
     }, async (args) => {
         try {
-            trackMCP("setupPercyVisualTesting", server.server.getClientVersion(), config);
+            trackMCP("expandPercyVisualTesting", server.server.getClientVersion(), undefined, config);
             return setUpPercyHandler(args, config);
         }
         catch (error) {
-            return handleMCPError("setupPercyVisualTesting", server, config, error);
+            return handleMCPError("expandPercyVisualTesting", server, config, error);
         }
     });
     tools.addPercySnapshotCommands = server.tool("addPercySnapshotCommands", PERCY_SNAPSHOT_COMMANDS_DESCRIPTION, UpdateTestFileWithInstructionsParams, {
@@ -68,7 +68,7 @@ export function registerPercyTools(server, config) {
         idempotentHint: true,
     }, async (args) => {
         try {
-            trackMCP("addPercySnapshotCommands", server.server.getClientVersion(), config);
+            trackMCP("addPercySnapshotCommands", server.server.getClientVersion(), undefined, config);
             return await updateTestsWithPercyCommands(args);
         }
         catch (error) {
@@ -83,7 +83,7 @@ export function registerPercyTools(server, config) {
         idempotentHint: true,
     }, async () => {
         try {
-            trackMCP("listTestFiles", server.server.getClientVersion(), config);
+            trackMCP("listTestFiles", server.server.getClientVersion(), undefined, config);
             return addListTestFiles();
         }
         catch (error) {
@@ -98,7 +98,7 @@ export function registerPercyTools(server, config) {
         idempotentHint: true,
     }, async (args) => {
         try {
-            trackMCP("runPercyScan", server.server.getClientVersion(), config);
+            trackMCP("runPercyScan", server.server.getClientVersion(), undefined, config);
             return runPercyScan(args);
         }
         catch (error) {
@@ -113,7 +113,7 @@ export function registerPercyTools(server, config) {
         idempotentHint: true,
     }, async (args) => {
         try {
-            trackMCP("fetchPercyChanges", server.server.getClientVersion(), config);
+            trackMCP("fetchPercyChanges", server.server.getClientVersion(), undefined, config);
             return await fetchPercyChanges(args, config);
         }
         catch (error) {
@@ -128,7 +128,7 @@ export function registerPercyTools(server, config) {
         idempotentHint: true,
     }, async (args) => {
         try {
-            trackMCP("managePercyBuildApproval", server.server.getClientVersion(), config);
+            trackMCP("managePercyBuildApproval", server.server.getClientVersion(), undefined, config);
             return await approveOrDeclinePercyBuild(args, config);
         }
         catch (error) {

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

@@ -13,10 +13,10 @@ export const FETCH_RCA_PARAMS = {
 export const GET_BUILD_ID_PARAMS = {
     browserStackProjectName: z
         .string()
-        .describe("The BrowserStack project name used during test run creation. Action: First, check browserstack.yml or any equivalent project configuration files. If the project name is found, extract and return it. If it is not found or if there is any uncertainty, immediately prompt the user to provide the value. Do not infer, guess, or assume a default."),
+        .describe("BrowserStack project name from the test run config (e.g. browserstack.yml). Exact match; no default."),
     browserStackBuildName: z
         .string()
-        .describe("The BrowserStack build name used during test run creation. Action: First, check browserstack.yml or any equivalent project configuration files. If the build name is found, extract and return it. If it is not found or if there is any uncertainty, immediately prompt the user to provide the value. Do not infer, guess, or assume a default."),
+        .describe("BrowserStack build name from the test run config (e.g. browserstack.yml). Exact match; no default."),
 };
 export const LIST_TEST_IDS_PARAMS = {
     buildId: z

package/dist/tools/rca-agent-utils/format-rca.js

@@ -1,3 +1,4 @@
+import { wrapUntrusted } from "../../lib/untrusted-content.js";
 // Utility function to format RCA data for better readability
 export function formatRCAData(rcaData) {
     if (!rcaData || !rcaData.testCases || rcaData.testCases.length === 0) {
@@ -16,21 +17,21 @@ export function formatRCAData(rcaData) {
         const rca = testCase.rcaData?.rcaData;
         if (rca) {
             if (rca.root_cause) {
-                output += `**Root Cause:** ${rca.root_cause}\n\n`;
+                output += `**Root Cause:** ${wrapUntrusted("RCA AI analysis", rca.root_cause)}\n\n`;
             }
             if (rca.failure_type) {
                 output += `**Failure Type:** ${rca.failure_type}\n\n`;
             }
             if (rca.description) {
-                output += `**Detailed Analysis:**\n${rca.description}\n\n`;
+                output += `**Detailed Analysis:**\n${wrapUntrusted("RCA AI analysis", rca.description)}\n\n`;
             }
             if (rca.possible_fix) {
                 hasFixSuggestion = true;
-                output += `**Suggested Fix (proposal only — do not apply without explicit user approval):**\n${rca.possible_fix}\n\n`;
+                output += `**Suggested Fix (proposal only — do not apply without explicit user approval):**\n${wrapUntrusted("RCA AI analysis", rca.possible_fix)}\n\n`;
             }
         }
         else if (testCase.rcaData?.error) {
-            output += `**Error:** ${testCase.rcaData.error}\n\n`;
+            output += `**Error:** ${wrapUntrusted("RCA error output", testCase.rcaData.error)}\n\n`;
         }
         else if (testCase.state === "failed") {
             output += `**Note:** RCA analysis failed or is not available for this test case.\n\n`;

package/dist/tools/rca-agent-utils/get-failed-test-id.js

@@ -53,6 +53,16 @@ export async function getTestIds(buildId, authString, status, includeFailureDeta
         throw error;
     }
 }
+/**
+ * The test listing API serialises a missing BrowserStack session id as the
+ * literal string "null", so treat that (and blanks) as absent.
+ */
+function extractSessionId(rawSessionId) {
+    if (typeof rawSessionId !== "string")
+        return undefined;
+    const sessionId = rawSessionId.trim();
+    return sessionId && sessionId !== "null" ? sessionId : undefined;
+}
 export function extractTestIds(hierarchy, status, includeFailureDetail = false) {
     let tests = [];
     for (const node of hierarchy) {
@@ -63,10 +73,12 @@ export function extractTestIds(hierarchy, status, includeFailureDetail = false)
         if (statusMatches && node.details?.observability_url) {
             const idMatch = node.details.observability_url.match(/details=(\d+)/);
             if (idMatch) {
+                const sessionId = extractSessionId(node.details.session_id);
                 const entry = {
                     test_id: idMatch[1],
                     test_name: node.display_name || `Test ${idMatch[1]}`,
                     status: nodeStatus,
+                    ...(sessionId && { session_id: sessionId }),
                 };
                 // Failure signatures only exist for failed tests; include when asked.
                 if (includeFailureDetail && nodeStatus === TestStatus.FAILED) {

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

@@ -30,6 +30,7 @@ export interface FailedTestInfo {
     test_name: string;
     status?: TestStatus;
     failure?: TestFailureSignature;
+    session_id?: string;
 }
 export declare enum RCAState {
     PENDING = "pending",

package/dist/tools/rca-agent.js

@@ -7,7 +7,17 @@ import { getRCAData } from "./rca-agent-utils/rca-data.js";
 import { formatRCAData } from "./rca-agent-utils/format-rca.js";
 import { handleMCPError } from "../lib/utils.js";
 import { trackMCP } from "../index.js";
+import { NEEDS_BUILD_ID, NEEDS_TEST_IDS } from "./tool-handoff.js";
 import { FETCH_RCA_PARAMS, GET_BUILD_ID_PARAMS, LIST_TEST_IDS_PARAMS, } from "./rca-agent-utils/constants.js";
+function describeBuildIdError(error, args) {
+    const status = error?.response
+        ?.status;
+    const message = error instanceof Error ? error.message : "Unknown error";
+    if (status === 404 || /\b404\b/.test(message)) {
+        return `No build found for project "${args.browserStackProjectName}" and build "${args.browserStackBuildName}". Both names must match the BrowserStack Automate dashboard exactly.`;
+    }
+    return message;
+}
 // Tool function to fetch build ID
 export async function getBuildIdTool(args, config) {
     try {
@@ -25,8 +35,8 @@ export async function getBuildIdTool(args, config) {
         };
     }
     catch (error) {
-        logger.error("Error fetching build ID", error);
-        const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        const errorMessage = describeBuildIdError(error, args);
+        logger.error("Error fetching build ID: %s", errorMessage);
         return {
             content: [
                 {
@@ -55,8 +65,8 @@ export async function listBuildIdTool(args, config) {
         };
     }
     catch (error) {
-        logger.error("Error fetching build ID", error);
-        const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        const errorMessage = describeBuildIdError(error, args);
+        logger.error("Error fetching build ID: %s", errorMessage);
         return {
             content: [
                 {
@@ -130,7 +140,8 @@ export async function listTestIdsTool(args, config) {
 }
 export default function addRCATools(server, config) {
     const tools = {};
-    tools.fetchRCA = server.tool("fetchRCA", "Fetch AI Root Cause Analysis for the current user's failed BrowserStack Automate/App-Automate tests. Suggests fixes only; never auto-apply, require explicit user approval.", FETCH_RCA_PARAMS, {
+    tools.fetchRCA = server.tool("fetchRCA", "Fetch AI Root Cause Analysis for the current user's failed BrowserStack Automate/App-Automate tests. Suggests fixes only; never auto-apply, require explicit user approval." +
+        NEEDS_TEST_IDS, FETCH_RCA_PARAMS, {
         title: "Fetch Root Cause Analysis",
         readOnlyHint: true,
         openWorldHint: false,
@@ -175,7 +186,8 @@ export default function addRCATools(server, config) {
             return handleMCPError("listBuildId", server, config, error);
         }
     });
-    tools.listTestIds = server.tool("listTestIds", "List all tests of a BrowserStack build (each with its status); optional status filter.", LIST_TEST_IDS_PARAMS, {
+    tools.listTestIds = server.tool("listTestIds", "List all tests of a BrowserStack build (each with its status and session id); optional status filter." +
+        NEEDS_BUILD_ID, LIST_TEST_IDS_PARAMS, {
         title: "List Test IDs",
         readOnlyHint: true,
         openWorldHint: false,

package/dist/tools/review-agent.js

@@ -1,3 +1,4 @@
+import { wrapUntrusted } from "../lib/untrusted-content.js";
 import { getBrowserStackAuth } from "../lib/get-auth.js";
 import { getPercyBuildCount } from "./review-agent-utils/build-counts.js";
 import { getChangedPercySnapshotIds } from "./review-agent-utils/percy-snapshots.js";
@@ -50,7 +51,7 @@ export async function fetchPercyChanges(args, config) {
     return {
         content: allDiffs.map((diff) => ({
             type: "text",
-            text: `${diff.name} → ${diff.title}: ${diff.description ?? ""}`,
+            text: wrapUntrusted("Percy AI visual-diff description", `${diff.name} → ${diff.title}: ${diff.description ?? ""}`),
         })),
     };
 }

package/dist/tools/sdk-utils/common/constants.d.ts

@@ -1,4 +1,4 @@
-export declare const IMPORTANT_SETUP_WARNING = "IMPORTANT: DO NOT SKIP ANY STEP. All the setup steps described below MUST be executed regardless of any existing configuration or setup. This ensures proper BrowserStack SDK setup.";
+export declare const IMPORTANT_SETUP_WARNING: string;
 export declare const SETUP_PERCY_DESCRIPTION = "Set up or expand Percy visual testing configuration with comprehensive coverage for existing projects that might have Percy integrated. This supports both Percy Web Standalone and Percy Automate. Example prompts: Expand percy coverage for this project {project_name}";
 export declare const LIST_TEST_FILES_DESCRIPTION = "Lists all test files for a given set of directories.";
 export declare const PERCY_SNAPSHOT_COMMANDS_DESCRIPTION = "Adds Percy snapshot commands to the specified test files.";

package/dist/tools/sdk-utils/common/constants.js

@@ -1,4 +1,5 @@
-export const IMPORTANT_SETUP_WARNING = "IMPORTANT: DO NOT SKIP ANY STEP. All the setup steps described below MUST be executed regardless of any existing configuration or setup. This ensures proper BrowserStack SDK setup.";
+export const IMPORTANT_SETUP_WARNING = "IMPORTANT: DO NOT SKIP ANY STEP. All the setup steps described below MUST be executed regardless of any existing configuration or setup. This ensures proper BrowserStack SDK setup. " +
+    "If you cannot run commands or edit files in the user's project (e.g. a chat-only client), present every step below to the user in full — including each shell command, the package.json changes, and the complete browserstack.yml contents — instead of summarizing them.";
 export const SETUP_PERCY_DESCRIPTION = "Set up or expand Percy visual testing configuration with comprehensive coverage for existing projects that might have Percy integrated. This supports both Percy Web Standalone and Percy Automate. Example prompts: Expand percy coverage for this project {project_name}";
 export const LIST_TEST_FILES_DESCRIPTION = "Lists all test files for a given set of directories.";
 export const PERCY_SNAPSHOT_COMMANDS_DESCRIPTION = "Adds Percy snapshot commands to the specified test files.";

package/dist/tools/sdk-utils/common/utils.js

@@ -51,7 +51,7 @@ export async function formatToolResult(resultPromise, runType) {
     if (runType != "percy-web") {
         finalContent.push({
             type: "text",
-            text: "CRITICAL: After the build is run, you MUST explicitly ask the user if they want to perform RCA (Root Cause Analysis) for any failed tests using the RCA tool. This step is mandatory and should not be skipped.",
+            text: "After the build has run, root cause analysis (RCA) is available for any failed tests: getBuildId, then listTestIds, then fetchRCA.",
         });
     }
     return {

package/dist/tools/selfheal-utils/fetch-test-code.d.ts

@@ -39,11 +39,10 @@ export interface SessionTestCode {
  */
 export declare function fetchTestCodeBySession(sessionId: string, config: BrowserStackConfig): Promise<SessionTestCode>;
 /**
- * Builds a directive guidance block for the calling LLM when one or more
- * sessions did not return usable test code. Each status block contains:
+ * Builds per-status notes when one or more sessions did not return usable
+ * test code. Each status block contains:
  *   - A diagnosis (what happened, per BrowserStack)
- *   - An explicit "do NOT paraphrase this as X" constraint
- *   - A ready-to-say phrasing the LLM can quote when replying to the user
+ *   - The next step
  *
  * Returns empty string when every session returned `status: ok`.
  */

package/dist/tools/selfheal-utils/fetch-test-code.js

@@ -82,11 +82,10 @@ export async function fetchTestCodeBySession(sessionId, config) {
     }
 }
 /**
- * Builds a directive guidance block for the calling LLM when one or more
- * sessions did not return usable test code. Each status block contains:
+ * Builds per-status notes when one or more sessions did not return usable
+ * test code. Each status block contains:
  *   - A diagnosis (what happened, per BrowserStack)
- *   - An explicit "do NOT paraphrase this as X" constraint
- *   - A ready-to-say phrasing the LLM can quote when replying to the user
+ *   - The next step
  *
  * Returns empty string when every session returned `status: ok`.
  */
@@ -107,21 +106,14 @@ export function describeTestCodeFetchIssues(sessionTestCodes) {
             `### Non-SDK build — session(s): ${ids}`,
             "",
             "Diagnosis: BrowserStack's test-code API returned HTTP 200 with rows " +
-                "where `code` and `filename` are null. This is the KNOWN signature " +
-                "of a BrowserStack run that was NOT instrumented with the " +
-                "BrowserStack SDK / Observability. The API literally has no source " +
-                "code to return for these sessions — this is by design.",
-            "",
-            "DO NOT tell the user any of the following (all are wrong for this " +
-                "status): 'credentials issue', 'credentials or session issue', " +
-                "'could not fetch from the API due to auth', '401', 'unauthorized'. " +
-                "The credentials are fine; the build just isn't SDK-enabled.",
-            "",
-            "Say this (or very close to it) to the user, then wait for their reply:",
-            '  "This is a non-SDK BrowserStack build, so the test-code API has ' +
-                "no source to return for it (this is expected, not a credentials " +
-                "problem). Can you tell me the local file path where these tests live? " +
-                "Once I have the file, I'll apply the healed locators listed in the plan.\"",
+                "where `code` and `filename` are null. This is the signature of a " +
+                "BrowserStack run that was not instrumented with the BrowserStack " +
+                "SDK / Observability, so the API has no source code to return for " +
+                "these sessions. Credentials are not involved; this is not an auth " +
+                "failure or a session problem.",
+            "",
+            "Next step: the healed locators can be applied once the user shares " +
+                "the local file path where these tests live.",
         ].join("\n"));
     }
     const unauthorized = byStatus.get("unauthorized");
@@ -131,23 +123,16 @@ export function describeTestCodeFetchIssues(sessionTestCodes) {
             `### Unauthorized (HTTP 401) — session(s): ${ids}`,
             "",
             "Diagnosis: BrowserStack's test-code API rejected the credentials " +
-                "(HTTP 401). This IS an authentication problem for this specific " +
-                "API — the healing report endpoint and test-code endpoint use the " +
+                "(HTTP 401). This is an authentication problem for this specific " +
+                "API. The healing report endpoint and test-code endpoint use the " +
                 "same BrowserStack auth, so if the report fetch above succeeded " +
-                "with the same creds, suspect that the access key configured on " +
-                "the MCP server was rotated.",
-            "",
-            "DO NOT say 'credentials or session issue' (that hides the real cause). " +
-                "Name the 401 explicitly and offer the user a choice. Do NOT ask " +
-                "the user to paste a BrowserStack username or access key in chat — " +
-                "the MCP server reads credentials from its own environment.",
+                "with the same creds, the access key configured on the MCP server " +
+                "was likely rotated.",
             "",
-            "Say this (or very close to it) to the user, then wait for their reply:",
-            '  "The BrowserStack test-code API returned 401 Unauthorized for ' +
-                `session(s) ${ids}. Would you like to: (a) update the BrowserStack ` +
-                "username and access key on the MCP server (BROWSERSTACK_USERNAME / " +
-                "BROWSERSTACK_ACCESS_KEY) and restart it, or (b) skip the API and " +
-                'point me at the local test file so I can apply the healed locators there?"',
+            "Next step: either update BROWSERSTACK_USERNAME / " +
+                "BROWSERSTACK_ACCESS_KEY on the MCP server and restart it, or apply " +
+                "the healed locators to the local test file if the user shares its " +
+                "path. Credentials are read from the server environment, not from chat.",
         ].join("\n"));
     }
     const forbidden = byStatus.get("forbidden");
@@ -159,16 +144,10 @@ export function describeTestCodeFetchIssues(sessionTestCodes) {
             "Diagnosis: BrowserStack's test-code API accepted the credentials " +
                 "but denied access to the session's source (HTTP 403). Typically " +
                 "the user does not own this session, or the account does not have " +
-                "Observability enabled.",
+                "Observability enabled. The credentials themselves were accepted.",
             "",
-            "Do NOT blame the credentials broadly — say 'access denied for this " +
-                "session' and move on.",
-            "",
-            "Say this (or very close to it) to the user:",
-            `  "BrowserStack denied access (HTTP 403) to session(s) ${ids}. ` +
-                "This usually means the account does not own these sessions or " +
-                "does not have Observability enabled. Can you either share the " +
-                'local test file path, or confirm which account these sessions belong to?"',
+            "Next step: confirm which account owns these sessions, or apply the " +
+                "healed locators to the local test file if the user shares its path.",
         ].join("\n"));
     }
     const notFound = byStatus.get("not_found");
@@ -178,14 +157,11 @@ export function describeTestCodeFetchIssues(sessionTestCodes) {
             `### Not found (HTTP 404) — session(s): ${ids}`,
             "",
             "Diagnosis: BrowserStack returned HTTP 404 — the session id is most " +
-                "likely wrong, or the session has been purged.",
-            "",
-            "Do NOT say 'credentials'. Ask the user to verify the id.",
+                "likely wrong, or the session has been purged. Credentials are not " +
+                "involved.",
             "",
-            "Say this (or very close to it) to the user:",
-            `  "I couldn't find session(s) ${ids} on BrowserStack (HTTP 404). ` +
-                "Can you double-check the session id(s), or share the local test " +
-                'file directly so I can apply the healed locators?"',
+            "Next step: verify the session id(s), or apply the healed locators to " +
+                "the local test file if the user shares its path.",
         ].join("\n"));
     }
     const empty = byStatus.get("empty");
@@ -198,9 +174,8 @@ export function describeTestCodeFetchIssues(sessionTestCodes) {
                 "no test code was captured (e.g. a raw Selenium session not linked " +
                 "to a test framework).",
             "",
-            "Say this (or very close to it) to the user:",
-            `  "BrowserStack has no test code recorded for session(s) ${ids}. ` +
-                'Can you point me at the local test file where these locators live?"',
+            "Next step: the healed locators can be applied once the user shares " +
+                "the local test file where these locators live.",
         ].join("\n"));
     }
     const errored = byStatus.get("error");
@@ -215,10 +190,8 @@ export function describeTestCodeFetchIssues(sessionTestCodes) {
             `Diagnosis: network/transport failure — ${details}. This is not an ` +
                 "auth issue.",
             "",
-            "Say this (or very close to it) to the user:",
-            `  "I hit a transport error fetching test code from BrowserStack ` +
-                `(${details}). Want me to retry, or would you prefer to share the ` +
-                'local test file directly?"',
+            "Next step: retry the fetch, or apply the healed locators to the " +
+                "local test file if the user shares its path.",
         ].join("\n"));
     }
     return notes.join("\n\n");