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

package/dist/tools/testmanagement.js

@@ -19,7 +19,6 @@ import { getTestPlan, GetTestPlanSchema, } from "./testmanagement-utils/get-test
 import { listSubTestPlans, ListSubTestPlansSchema, } from "./testmanagement-utils/list-sub-testplans.js";
 import { getSubTestPlan, GetSubTestPlanSchema, } from "./testmanagement-utils/get-sub-testplan.js";
 import { elicitCredentialsIfSupported } from "../lib/elicit-credentials.js";
-import { NEEDS_PROJECT_ID, NEEDS_TEST_PLAN_ID, PLAN_WRITES_VIA_AGENT, PROJECT_ID_ONLY_FOR_FOLDER, } from "./tool-handoff.js";
 //TODO: Moving the traceMCP and catch block to the parent(server) function
 /**
  * Wrapper to call createProjectOrFolder util.
@@ -433,40 +432,35 @@ export async function getSubTestPlanTool(args, config, server) {
  */
 export default function addTestManagementTools(server, config) {
     const tools = {};
-    tools.createProjectOrFolder = server.tool("createProjectOrFolder", "Create a project and/or folder in BrowserStack Test Management." +
-        PROJECT_ID_ONLY_FOR_FOLDER, CreateProjFoldSchema.shape, {
+    tools.createProjectOrFolder = server.tool("createProjectOrFolder", "Create a project and/or folder in BrowserStack Test Management.", CreateProjFoldSchema.shape, {
         title: "Create Project or Folder",
         readOnlyHint: false,
         openWorldHint: false,
         destructiveHint: false,
         idempotentHint: false,
     }, (args) => createProjectOrFolderTool(args, config, server));
-    tools.createTestCase = server.tool("createTestCase", "Use this tool to create a test case in BrowserStack Test Management." +
-        NEEDS_PROJECT_ID, CreateTestCaseSchema.shape, {
+    tools.createTestCase = server.tool("createTestCase", "Use this tool to create a test case in BrowserStack Test Management.", CreateTestCaseSchema.shape, {
         title: "Create Test Case",
         readOnlyHint: false,
         openWorldHint: false,
         destructiveHint: false,
         idempotentHint: false,
     }, (args) => createTestCaseTool(args, config, server));
-    tools.updateTestCase = server.tool("updateTestCase", "Update an existing test case in BrowserStack Test Management. Any subset of the following fields may be changed: name, description, preconditions, test_case_steps, owner, priority, case_type, automation_status, status, tags, issues, custom_fields. Only the supplied fields are modified." +
-        NEEDS_PROJECT_ID, UpdateTestCaseSchema.shape, {
+    tools.updateTestCase = server.tool("updateTestCase", "Update an existing test case in BrowserStack Test Management. Any subset of the following fields may be changed: name, description, preconditions, test_case_steps, owner, priority, case_type, automation_status, status, tags, issues, custom_fields. Only the supplied fields are modified.", UpdateTestCaseSchema.shape, {
         title: "Update Test Case",
         readOnlyHint: false,
         openWorldHint: false,
         destructiveHint: true,
         idempotentHint: true,
     }, (args) => updateTestCaseTool(args, config, server));
-    tools.listTestCases = server.tool("listTestCases", "List test cases in a project, optionally scoped to a specific folder. Omit folder_id to list all test cases in the project; provide folder_id (discoverable via listFolders) to list only that folder's cases. Supports filters: case_type, priority, pagination." +
-        NEEDS_PROJECT_ID, ListTestCasesSchema.shape, {
+    tools.listTestCases = server.tool("listTestCases", "List test cases in a project, optionally scoped to a specific folder. Omit folder_id to list all test cases in the project; provide folder_id (discoverable via listFolders) to list only that folder's cases. Supports filters: case_type, priority, pagination.", ListTestCasesSchema.shape, {
         title: "List Test Cases",
         readOnlyHint: true,
         openWorldHint: false,
         destructiveHint: false,
         idempotentHint: true,
     }, (args) => listTestCasesTool(args, config, server));
-    tools.listFolders = server.tool("listFolders", "List folders in a BrowserStack Test Management project, returning each folder's id and name (plus case counts and sub-folder counts). Pass parent_id to list sub-folders under a specific folder instead of top-level folders." +
-        NEEDS_PROJECT_ID, ListFoldersSchema.shape, {
+    tools.listFolders = server.tool("listFolders", "List folders in a BrowserStack Test Management project, returning each folder's id and name (plus case counts and sub-folder counts). Pass parent_id to list sub-folders under a specific folder instead of top-level folders.", ListFoldersSchema.shape, {
         title: "List Folders",
         readOnlyHint: true,
         openWorldHint: false,
@@ -480,39 +474,35 @@ export default function addTestManagementTools(server, config) {
         destructiveHint: false,
         idempotentHint: true,
     }, (args) => listTemplatesTool(args, config, server));
-    tools.createTestRun = server.tool("createTestRun", "Create a test run in BrowserStack Test Management." + NEEDS_PROJECT_ID, CreateTestRunSchema.shape, {
+    tools.createTestRun = server.tool("createTestRun", "Create a test run in BrowserStack Test Management.", CreateTestRunSchema.shape, {
         title: "Create Test Run",
         readOnlyHint: false,
         openWorldHint: false,
         destructiveHint: false,
         idempotentHint: false,
     }, (args) => createTestRunTool(args, config, server));
-    tools.listTestRuns = server.tool("listTestRuns", "List test runs in a project with optional filters (date ranges, assignee, state, etc.)" +
-        NEEDS_PROJECT_ID, ListTestRunsSchema.shape, {
+    tools.listTestRuns = server.tool("listTestRuns", "List test runs in a project with optional filters (date ranges, assignee, state, etc.)", ListTestRunsSchema.shape, {
         title: "List Test Runs",
         readOnlyHint: true,
         openWorldHint: false,
         destructiveHint: false,
         idempotentHint: true,
     }, (args) => listTestRunsTool(args, config, server));
-    tools.updateTestRun = server.tool("updateTestRun", "Update a test run's metadata and/or add test cases to it." +
-        NEEDS_PROJECT_ID, UpdateTestRunSchema.shape, {
+    tools.updateTestRun = server.tool("updateTestRun", "Update a test run's metadata and/or add test cases to it.", UpdateTestRunSchema.shape, {
         title: "Update Test Run",
         readOnlyHint: false,
         openWorldHint: false,
         destructiveHint: true,
         idempotentHint: true,
     }, (args) => updateTestRunTool(args, config, server));
-    tools.addTestResult = server.tool("addTestResult", "Add a test result to a specific test run via BrowserStack Test Management API." +
-        NEEDS_PROJECT_ID, AddTestResultSchema.shape, {
+    tools.addTestResult = server.tool("addTestResult", "Add a test result to a specific test run via BrowserStack Test Management API.", AddTestResultSchema.shape, {
         title: "Add Test Result",
         readOnlyHint: false,
         openWorldHint: false,
         destructiveHint: false,
         idempotentHint: false,
     }, (args) => addTestResultTool(args, config, server));
-    tools.uploadProductRequirementFile = server.tool("uploadProductRequirementFile", "Upload files (e.g., PDRs, PDFs) to BrowserStack Test Management and retrieve a file mapping ID. This is utilized for generating test cases from files and is part of the Test Case Generator AI Agent in BrowserStack." +
-        NEEDS_PROJECT_ID, UploadFileSchema.shape, {
+    tools.uploadProductRequirementFile = server.tool("uploadProductRequirementFile", "Upload files (e.g., PDRs, PDFs) to BrowserStack Test Management and retrieve a file mapping ID. This is utilized for generating test cases from files and is part of the Test Case Generator AI Agent in BrowserStack.", UploadFileSchema.shape, {
         title: "Upload Product Requirement File",
         readOnlyHint: false,
         openWorldHint: false,
@@ -526,47 +516,35 @@ export default function addTestManagementTools(server, config) {
         destructiveHint: false,
         idempotentHint: false,
     }, (args, context) => createTestCasesFromFileTool(args, context, config, server));
-    tools.createLCASteps = server.tool("createLCASteps", "Generate Low Code Automation (LCA) steps for a test case in BrowserStack Test Management using the Low Code Automation Agent." +
-        NEEDS_PROJECT_ID, CreateLCAStepsSchema.shape, {
+    tools.createLCASteps = server.tool("createLCASteps", "Generate Low Code Automation (LCA) steps for a test case in BrowserStack Test Management using the Low Code Automation Agent.", CreateLCAStepsSchema.shape, {
         title: "Create LCA Steps",
         readOnlyHint: false,
         openWorldHint: false,
         destructiveHint: false,
         idempotentHint: false,
     }, (args, context) => createLCAStepsTool(args, context, config, server));
-    tools.listTestPlans = server.tool("listTestPlans", "List test plans in a BrowserStack Test Management project. Returns each plan's identifier (TP-*), name, status, description, dates, and active/closed test-run counts. Supports pagination." +
-        NEEDS_PROJECT_ID +
-        PLAN_WRITES_VIA_AGENT, ListTestPlansSchema.shape, {
+    tools.listTestPlans = server.tool("listTestPlans", "List test plans in a BrowserStack Test Management project. Returns each plan's identifier (TP-*), name, status, description, dates, and active/closed test-run counts. Supports pagination.", ListTestPlansSchema.shape, {
         title: "List Test Plans",
         readOnlyHint: true,
         openWorldHint: false,
         destructiveHint: false,
         idempotentHint: true,
     }, (args) => listTestPlansTool(args, config, server));
-    tools.getTestPlan = server.tool("getTestPlan", "Fetch a test plan by identifier (TP-*) from BrowserStack Test Management. Returns plan metadata, the full list of linked test runs, total test-case count across runs, and a status summary — suitable for generating test documentation or QA status reports." +
-        NEEDS_PROJECT_ID +
-        NEEDS_TEST_PLAN_ID +
-        PLAN_WRITES_VIA_AGENT, GetTestPlanSchema.shape, {
+    tools.getTestPlan = server.tool("getTestPlan", "Fetch a test plan by identifier (TP-*) from BrowserStack Test Management. Returns plan metadata, the full list of linked test runs, total test-case count across runs, and a status summary — suitable for generating test documentation or QA status reports.", GetTestPlanSchema.shape, {
         title: "Get Test Plan",
         readOnlyHint: true,
         openWorldHint: false,
         destructiveHint: false,
         idempotentHint: true,
     }, (args) => getTestPlanTool(args, config, server));
-    tools.listSubTestPlans = server.tool("listSubTestPlans", "List sub-test-plans under a parent test plan (TP-*) in a Test Management project. Supports pagination." +
-        NEEDS_PROJECT_ID +
-        NEEDS_TEST_PLAN_ID +
-        PLAN_WRITES_VIA_AGENT, ListSubTestPlansSchema.shape, {
+    tools.listSubTestPlans = server.tool("listSubTestPlans", "List sub-test-plans under a parent test plan (TP-*) in a Test Management project. Supports pagination.", ListSubTestPlansSchema.shape, {
         title: "List Sub Test Plans",
         readOnlyHint: true,
         openWorldHint: false,
         destructiveHint: false,
         idempotentHint: true,
     }, (args) => listSubTestPlansTool(args, config, server));
-    tools.getSubTestPlan = server.tool("getSubTestPlan", "Fetch a sub-test-plan (STP-*) under a parent plan (TP-*). Returns metadata and linked test runs." +
-        NEEDS_PROJECT_ID +
-        NEEDS_TEST_PLAN_ID +
-        PLAN_WRITES_VIA_AGENT, GetSubTestPlanSchema.shape, {
+    tools.getSubTestPlan = server.tool("getSubTestPlan", "Fetch a sub-test-plan (STP-*) under a parent plan (TP-*). Returns metadata and linked test runs.", GetSubTestPlanSchema.shape, {
         title: "Get Sub Test Plan",
         readOnlyHint: true,
         openWorldHint: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserstack/mcp-server",
-  "version": "1.4.0-beta.3",
+  "version": "1.5.0-beta.2",
   "description": "BrowserStack's Official MCP Server",
   "mcpName": "io.github.browserstack/mcp-server",
   "main": "dist/index.js",
@@ -21,7 +21,8 @@
     "browserstack-mcp-server": "dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "capability"
   ],
   "keywords": [
     "mcp",

package/dist/tools/ask-browserstack/central-oauth.d.ts

@@ -1,120 +0,0 @@
-/**
- * Mint a BrowserStack central-OAuth JWT from the caller's username and access key.
- *
- * This replaces a shared delegation token, and the upgrade is not cosmetic.
- * `validate_delegation_token` refuses any token without `user.user_id`/`user.group_id`, so
- * what we mint here is USER-ATTESTED: Atlas sets `principal_verified=True`, takes the acting
- * user from signed claims rather than from anything we put in the request body, and reuses
- * this same JWT as its `egress_token` — so the product call a human approves runs as that
- * human, not as a shared service account.
- *
- * SECRET HYGIENE IS THE WHOLE POINT OF THIS MODULE, and Atlas's `central_oauth.py` learned
- * it the hard way: "The body can echo the credential back on some errors, so it is NOT
- * logged or raised — only the status." Neither the access key nor the minted token is ever
- * logged, returned, or put in an error message. Only a status code is.
- */
-import { Credentials } from "./egress.js";
-/**
- * BOTH PARTS ARE REQUIRED, AND THERE IS NO FALLBACK TO ANOTHER SCOPE.
- *
- * `oauth_user_profile` stays because it is what makes the pair obtainable through the
- * username+access_key flow at all. `ai_agent_notify` is what Atlas matches on
- * (`delegation.required_scope`, checked as exact membership of the token's `scopes` claim in
- * `web/oauth.py`); both halves move together with Atlas.
- *
- * THIS SCOPE MAY SIMPLY NOT BE ISSUABLE TO US, and the reasons are worth stating rather than
- * discovering. From the merged `browserstack/railsApp#175367` (2026-08-24):
- *
- *   - `ai_agent_notify` is documented there as CLIENT_ID/SECRET auth, and
- *     `USERNAME_ACCESS_KEY_ONLY_SCOPES` remains only `user_management, oauth_user_profile`.
- *     We are on the username+access_key flow, which those restrictions are not written for.
- *   - It is additionally covered by a new
- *     `APP_REGISTERED_SCOPE_REQUIRED = %w[ai_agent ai_agent_notify]` gate, requiring the
- *     calling APPLICATION to be registered for it — though that gate sits in the
- *     `client_id + client_secret` path, not ours.
- *   - railsApp defines it as the PRODUCT -> AGENT direction: "a product reporting progress
- *     back to an AI agent for work the agent dispatched." We use it in the opposite
- *     direction, as an agent -> Atlas inbound credential.
- *   - `central_ai_s2s`, which this replaces, was deliberately EXCLUDED from that new gate.
- *
- * So this is strictly more restricted than what it replaces. If the endpoint refuses it, that
- * is a PROVISIONING problem — the scope is not available to this credential type or this
- * application — and it is reported as one, naming the scope. It is never retried with a
- * different scope: a silent downgrade to a different authorization is exactly the kind of
- * thing nobody notices until it matters.
- */
-export declare const CENTRAL_SCOPE = "oauth_user_profile ai_agent_notify";
-/** What we ask for. The endpoint clamps to its own maximum, so the response wins. */
-export declare const REQUESTED_EXPIRES_IN = 3600;
-/**
- * Treat a token as stale this long before it actually expires.
- *
- * NOT the usual small skew. This token is not merely used to open the request — Atlas holds
- * it for the life of the run and re-uses it for product egress, so it has to outlive the
- * whole call, and our own `/agent` budget is already 330s. Handing out a token with 61
- * seconds left would mean a human approves a write and the egress that follows fails on an
- * expired credential, which is the exact mid-flight expiry this cache exists to prevent.
- */
-export declare const REFRESH_SKEW_MS: number;
-/** The token endpoint gets its own, much shorter budget than `/agent`. */
-export declare const TOKEN_TIMEOUT_MS = 15000;
-export interface TokenResponse {
-    status: number;
-    body: unknown;
-    /** Only when there was no response at all to speak for itself. */
-    error?: string;
-}
-export type TokenTransport = (url: string, form: Record<string, string>) => Promise<TokenResponse>;
-/**
- * Was this refusal about the SCOPE or about the CREDENTIAL?
- *
- * The two need completely different fixes — provisioning versus a password — so collapsing
- * them into one message sends someone to the wrong place entirely. Our form has five fields
- * and four of them are constants, so a refusal of the REQUEST (as opposed to the caller) can
- * only really be about the scope.
- *
- * Nothing from the body is ever surfaced; the code is used to classify and then discarded.
- */
-export declare function refusalIsAboutScope(status: number, body: unknown): boolean;
-/**
- * The ways authentication can fail, kept apart because a user cannot act on them otherwise.
- *
- * `scope refused` is a provisioning problem; `rejected` is "your credentials are wrong";
- * `unreachable` is "auth is down". A fourth — Atlas refusing a token we minted successfully —
- * is a server misconfiguration and lives in `relay.ts`, because it is discovered from
- * `/agent`. Four different fixes, so four different sentences.
- */
-export declare const AUTH_SCOPE_REFUSED_DETAIL: (status: number) => string;
-export declare const AUTH_REJECTED_DETAIL: (status: number) => string;
-export declare const AUTH_UNREACHABLE_DETAIL: string;
-/**
- * A 5xx from auth: their service is down, not your password.
- *
- * Split out because routing 5xx to `AUTH_REJECTED_DETAIL` actively misdirects the reader,
- * and did: a preprod outage returned 503 and the tool answered "Your BrowserStack
- * credentials were rejected … Check BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY",
- * sending someone to audit env vars that had worked minutes earlier. The status alone
- * settles it — OAuth2 says a bad client is 401/403 and a bad request is 400, so nothing in
- * the 5xx range is ever a statement about the caller.
- */
-export declare const AUTH_SERVER_ERROR_DETAIL: (status: number) => string;
-export declare const AUTH_UNUSABLE_DETAIL: (status: number) => string;
-/** Drop every cached token. For tests, and for a credential rotation. */
-export declare function resetTokenCache(): void;
-/**
- * The token endpoint, through `apiClient` per rules/security.md — no bare `fetch`.
- *
- * `raise_error: false` keeps the status-first contract this transport has always had: the
- * caller distinguishes a 400 scope refusal from a 401 rejection from an unreachable host,
- * so a thrown AxiosError on any non-2xx would destroy the only signal it reads.
- */
-export declare function fetchTokenTransport(timeoutMs?: number): TokenTransport;
-/** The exact form body of the `client_credentials` grant. */
-export declare function mintForm(credentials: Credentials): Record<string, string>;
-/**
- * Return a valid token, minting one only when the cache has nothing fresh.
- *
- * Minting per tool call would add a round trip to every request and make the token endpoint
- * a hot dependency of the whole surface.
- */
-export declare function mintCentralToken(url: string, credentials: Credentials, transport: TokenTransport, now?: number): Promise<string>;

package/dist/tools/ask-browserstack/central-oauth.js

@@ -1,277 +0,0 @@
-/**
- * Mint a BrowserStack central-OAuth JWT from the caller's username and access key.
- *
- * This replaces a shared delegation token, and the upgrade is not cosmetic.
- * `validate_delegation_token` refuses any token without `user.user_id`/`user.group_id`, so
- * what we mint here is USER-ATTESTED: Atlas sets `principal_verified=True`, takes the acting
- * user from signed claims rather than from anything we put in the request body, and reuses
- * this same JWT as its `egress_token` — so the product call a human approves runs as that
- * human, not as a shared service account.
- *
- * SECRET HYGIENE IS THE WHOLE POINT OF THIS MODULE, and Atlas's `central_oauth.py` learned
- * it the hard way: "The body can echo the credential back on some errors, so it is NOT
- * logged or raised — only the status." Neither the access key nor the minted token is ever
- * logged, returned, or put in an error message. Only a status code is.
- */
-import { createHash } from "node:crypto";
-import { apiClient } from "../../lib/apiClient.js";
-import appConfig from "../../config.js";
-import logger from "../../logger.js";
-import { AGENT_TIMEOUT_MS, AskError } from "./config.js";
-/**
- * BOTH PARTS ARE REQUIRED, AND THERE IS NO FALLBACK TO ANOTHER SCOPE.
- *
- * `oauth_user_profile` stays because it is what makes the pair obtainable through the
- * username+access_key flow at all. `ai_agent_notify` is what Atlas matches on
- * (`delegation.required_scope`, checked as exact membership of the token's `scopes` claim in
- * `web/oauth.py`); both halves move together with Atlas.
- *
- * THIS SCOPE MAY SIMPLY NOT BE ISSUABLE TO US, and the reasons are worth stating rather than
- * discovering. From the merged `browserstack/railsApp#175367` (2026-08-24):
- *
- *   - `ai_agent_notify` is documented there as CLIENT_ID/SECRET auth, and
- *     `USERNAME_ACCESS_KEY_ONLY_SCOPES` remains only `user_management, oauth_user_profile`.
- *     We are on the username+access_key flow, which those restrictions are not written for.
- *   - It is additionally covered by a new
- *     `APP_REGISTERED_SCOPE_REQUIRED = %w[ai_agent ai_agent_notify]` gate, requiring the
- *     calling APPLICATION to be registered for it — though that gate sits in the
- *     `client_id + client_secret` path, not ours.
- *   - railsApp defines it as the PRODUCT -> AGENT direction: "a product reporting progress
- *     back to an AI agent for work the agent dispatched." We use it in the opposite
- *     direction, as an agent -> Atlas inbound credential.
- *   - `central_ai_s2s`, which this replaces, was deliberately EXCLUDED from that new gate.
- *
- * So this is strictly more restricted than what it replaces. If the endpoint refuses it, that
- * is a PROVISIONING problem — the scope is not available to this credential type or this
- * application — and it is reported as one, naming the scope. It is never retried with a
- * different scope: a silent downgrade to a different authorization is exactly the kind of
- * thing nobody notices until it matters.
- */
-export const CENTRAL_SCOPE = "oauth_user_profile ai_agent_notify";
-/** What we ask for. The endpoint clamps to its own maximum, so the response wins. */
-export const REQUESTED_EXPIRES_IN = 3600;
-/**
- * Treat a token as stale this long before it actually expires.
- *
- * NOT the usual small skew. This token is not merely used to open the request — Atlas holds
- * it for the life of the run and re-uses it for product egress, so it has to outlive the
- * whole call, and our own `/agent` budget is already 330s. Handing out a token with 61
- * seconds left would mean a human approves a write and the egress that follows fails on an
- * expired credential, which is the exact mid-flight expiry this cache exists to prevent.
- */
-export const REFRESH_SKEW_MS = AGENT_TIMEOUT_MS + 60_000;
-/** The token endpoint gets its own, much shorter budget than `/agent`. */
-export const TOKEN_TIMEOUT_MS = 15_000;
-/**
- * The OAuth2 error codes we are willing to read out of a failure body.
- *
- * `error` is a fixed enum token in the spec, so it cannot carry a credential; `error_description`
- * is free text and demonstrably CAN ("access_key <key> is invalid"), which is why only the
- * code is ever looked at and only when it is one of these. Anything else is ignored entirely
- * and the classification falls back to the status.
- */
-const SCOPE_ERROR_CODES = [
-    "invalid_scope",
-    "unauthorized_client",
-    "invalid_request",
-];
-const CREDENTIAL_ERROR_CODES = [
-    "invalid_client",
-    "invalid_grant",
-    "access_denied",
-];
-/**
- * Was this refusal about the SCOPE or about the CREDENTIAL?
- *
- * The two need completely different fixes — provisioning versus a password — so collapsing
- * them into one message sends someone to the wrong place entirely. Our form has five fields
- * and four of them are constants, so a refusal of the REQUEST (as opposed to the caller) can
- * only really be about the scope.
- *
- * Nothing from the body is ever surfaced; the code is used to classify and then discarded.
- */
-export function refusalIsAboutScope(status, body) {
-    const payload = typeof body === "object" && body !== null
-        ? body
-        : {};
-    const code = typeof payload.error === "string" ? payload.error : "";
-    if (SCOPE_ERROR_CODES.includes(code))
-        return true;
-    if (CREDENTIAL_ERROR_CODES.includes(code))
-        return false;
-    // No usable code. OAuth2 answers a bad REQUEST with 400 and a bad CLIENT with 401/403, so
-    // the status is the next best evidence.
-    return status === 400;
-}
-/**
- * The ways authentication can fail, kept apart because a user cannot act on them otherwise.
- *
- * `scope refused` is a provisioning problem; `rejected` is "your credentials are wrong";
- * `unreachable` is "auth is down". A fourth — Atlas refusing a token we minted successfully —
- * is a server misconfiguration and lives in `relay.ts`, because it is discovered from
- * `/agent`. Four different fixes, so four different sentences.
- */
-export const AUTH_SCOPE_REFUSED_DETAIL = (status) => `BrowserStack auth would not issue a token for the scope "${CENTRAL_SCOPE}" (HTTP ${status}). ` +
-    `YOUR CREDENTIALS ARE NOT THE PROBLEM — this is a provisioning problem: \`ai_agent_notify\` ` +
-    `is documented as a client_id/secret scope, it is not in the username+access_key allow ` +
-    `list, and it carries an application-registration requirement. It has to be enabled for ` +
-    `this account or application; a different password will not help, and this server will ` +
-    `NOT quietly retry with a weaker scope. NOTHING REACHED THE AGENT — no request was made, ` +
-    `no prompt appeared and nothing was changed.`;
-export const AUTH_REJECTED_DETAIL = (status) => `Your BrowserStack credentials were rejected by BrowserStack auth (HTTP ${status}). ` +
-    `NOTHING REACHED THE AGENT — no request was made, no prompt appeared and nothing was ` +
-    `changed. Check BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY.`;
-export const AUTH_UNREACHABLE_DETAIL = "Could not reach BrowserStack auth to sign in. NOTHING REACHED THE AGENT — no request " +
-    "was made, no prompt appeared and nothing was changed. This is a connectivity or " +
-    "auth-server problem, not a problem with your credentials.";
-/**
- * A 5xx from auth: their service is down, not your password.
- *
- * Split out because routing 5xx to `AUTH_REJECTED_DETAIL` actively misdirects the reader,
- * and did: a preprod outage returned 503 and the tool answered "Your BrowserStack
- * credentials were rejected … Check BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY",
- * sending someone to audit env vars that had worked minutes earlier. The status alone
- * settles it — OAuth2 says a bad client is 401/403 and a bad request is 400, so nothing in
- * the 5xx range is ever a statement about the caller.
- */
-export const AUTH_SERVER_ERROR_DETAIL = (status) => `BrowserStack auth is unavailable (HTTP ${status}). YOUR CREDENTIALS ARE NOT THE ` +
-    `PROBLEM — a 5xx is the auth service failing, not a rejection, so there is nothing to ` +
-    `change on your side and nothing to retry differently. NOTHING REACHED THE AGENT — no ` +
-    `request was made, no prompt appeared and nothing was changed. Try again once ` +
-    `BrowserStack auth is back.`;
-export const AUTH_UNUSABLE_DETAIL = (status) => `BrowserStack auth answered HTTP ${status} without issuing a token. NOTHING REACHED THE ` +
-    `AGENT — no request was made, no prompt appeared and nothing was changed.`;
-const cache = new Map();
-/** Drop every cached token. For tests, and for a credential rotation. */
-export function resetTokenCache() {
-    cache.clear();
-}
-/**
- * The cache key.
- *
- * Keyed on the access key so that ROTATING it mints immediately rather than leaving a
- * revoked credential working until expiry — but on a SHA-256 of it, never the value, so the
- * secret is not left sitting in a map key for the life of the process.
- */
-function cacheKey(url, credentials) {
-    const digest = createHash("sha256")
-        .update(credentials.accessKey)
-        .digest("hex");
-    return `${url} ${credentials.username} ${CENTRAL_SCOPE} ${digest}`;
-}
-/**
- * The token endpoint, through `apiClient` per rules/security.md — no bare `fetch`.
- *
- * `raise_error: false` keeps the status-first contract this transport has always had: the
- * caller distinguishes a 400 scope refusal from a 401 rejection from an unreachable host,
- * so a thrown AxiosError on any non-2xx would destroy the only signal it reads.
- */
-export function fetchTokenTransport(timeoutMs = TOKEN_TIMEOUT_MS) {
-    return async (url, form) => {
-        try {
-            const response = await apiClient.post({
-                url,
-                headers: {
-                    "Content-Type": "application/x-www-form-urlencoded",
-                    Accept: "application/json",
-                },
-                body: new URLSearchParams(form).toString(),
-                timeout: timeoutMs,
-                raise_error: false,
-            });
-            return { status: response.status, body: response.data ?? null };
-        }
-        catch {
-            // DNS, TLS, timeout — all of them mean "no token". The reason is deliberately not
-            // carried: it can name the URL and, on some stacks, echo the request body.
-            return { status: 0, body: null, error: "auth could not be reached" };
-        }
-    };
-}
-/** The exact form body of the `client_credentials` grant. */
-export function mintForm(credentials) {
-    return {
-        grant_type: "client_credentials",
-        username: credentials.username,
-        access_key: credentials.accessKey,
-        scope: CENTRAL_SCOPE,
-        expires_in: String(REQUESTED_EXPIRES_IN),
-    };
-}
-async function mintOnce(url, credentials, transport) {
-    const response = await transport(url, mintForm(credentials));
-    if (response.status === 0)
-        throw new AskError(AUTH_UNREACHABLE_DETAIL);
-    // 5xx BEFORE the refusal branch: a server error is not a refusal, and reading it as one
-    // is worse than saying nothing — it names the caller's credentials as the fault.
-    if (response.status >= 500) {
-        throw new AskError(AUTH_SERVER_ERROR_DETAIL(response.status));
-    }
-    if (response.status !== 200) {
-        // ONLY THE STATUS CROSSES. The body is read solely to tell a provisioning problem from a
-        // credential one, and nothing out of it is ever put in the message — a non-200 body can
-        // echo the access key straight back.
-        throw new AskError(refusalIsAboutScope(response.status, response.body)
-            ? AUTH_SCOPE_REFUSED_DETAIL(response.status)
-            : AUTH_REJECTED_DETAIL(response.status));
-    }
-    const body = typeof response.body === "object" && response.body !== null
-        ? response.body
-        : {};
-    const token = body.access_token;
-    if (typeof token !== "string" || !token) {
-        throw new AskError(AUTH_UNUSABLE_DETAIL(response.status));
-    }
-    // Trust the SERVER's lifetime over what we asked for — it clamps to its own maximum, and
-    // caching for the requested hour when it granted less would hand out a dead token.
-    const granted = Number(body.expires_in);
-    const seconds = Number.isFinite(granted) && granted > 0 ? granted : REQUESTED_EXPIRES_IN;
-    return { token, lifetimeMs: seconds * 1000 };
-}
-/**
- * Return a valid token, minting one only when the cache has nothing fresh.
- *
- * Minting per tool call would add a round trip to every request and make the token endpoint
- * a hot dependency of the whole surface.
- */
-export async function mintCentralToken(url, credentials, transport, now = Date.now()) {
-    // Refused before any network call, and by name: these ARE the auth credential now, not
-    // merely attribution, so an empty one is our missing configuration rather than the user's
-    // rejected password, and must not read like one.
-    if (!credentials?.username || !credentials?.accessKey) {
-        throw new AskError("BrowserStack AI is not authenticated: BROWSERSTACK_USERNAME and " +
-            "BROWSERSTACK_ACCESS_KEY are required to sign in");
-    }
-    // NOT CACHED IN HOSTED MODE. These tokens are per-user, attested credentials, and the
-    // process is shared by every tenant — `rules/multi-tenant-safety.md` forbids holding user
-    // data in module-level state there, so remote mode mints per call. Keying on
-    // username + sha256(accessKey) already means one user can never be SERVED another's token,
-    // but containment is not the contract; not holding it at all is.
-    if (appConfig.REMOTE_MCP) {
-        return mintOnce(url, credentials, transport).then(({ token }) => {
-            logger.info("askBrowserStackAI: signed in as %s", credentials.username);
-            return token;
-        });
-    }
-    const key = cacheKey(url, credentials);
-    const entry = cache.get(key);
-    if (entry && entry.token && now < entry.expiresAt - REFRESH_SKEW_MS) {
-        return entry.token;
-    }
-    // Double-checked through a shared promise: concurrent callers await the same mint.
-    if (entry?.inflight)
-        return entry.inflight;
-    const pending = mintOnce(url, credentials, transport)
-        .then(({ token, lifetimeMs }) => {
-        cache.set(key, { token, expiresAt: now + lifetimeMs });
-        logger.info("askBrowserStackAI: signed in as %s (lifetime %ss)", credentials.username, Math.round(lifetimeMs / 1000));
-        return token;
-    })
-        .catch((error) => {
-        // Never leave a rejected promise cached, or every later call inherits this failure.
-        cache.delete(key);
-        throw error;
-    });
-    cache.set(key, { token: "", expiresAt: 0, inflight: pending });
-    return pending;
-}