@browserstack/mcp-server 2.2.0-beta.1 → 2.2.0

package/dist/config.js

@@ -47,9 +47,9 @@ export class Config {
     O11Y_TFA_RCA_BASE_URL;
     BROWSERSTACK_AUTOMATION_BASE_URL;
     BROWSERSTACK_O11Y_UI_BASE_URL;
-    ASK_BROWSERSTACK_ALLOW_REMOTE_RELAY;
     ASK_BROWSERSTACK_ATLAS_URL;
     ASK_BROWSERSTACK_AUTH_TOKEN_URL;
+    ASK_BROWSERSTACK_RELAY_TRANSPORT;
     constructor(DEV_MODE, browserstackLocalOptions, USE_OWN_LOCAL_BINARY_PROCESS, REMOTE_MCP, UPLOAD_BASE_DIR, O11Y_TFA_RCA_BASE_URL, BROWSERSTACK_AUTOMATION_BASE_URL, BROWSERSTACK_O11Y_UI_BASE_URL, 
     // askBrowserStackAI's process-startup settings. Declared here rather than read from
     // process.env inside src/tools/, per rules/tool-design.md — and so the remote wrapper,
@@ -58,7 +58,20 @@ export class Config {
     // ASK_BROWSERSTACK_DISABLED is deliberately NOT here: it is a kill switch, and reading
     // it per call keeps it effective without a restart. Fixing it at boot would mean a pod
     // roll to disable the tool, which is slowest exactly when you need it fastest.
-    ASK_BROWSERSTACK_ALLOW_REMOTE_RELAY, ASK_BROWSERSTACK_ATLAS_URL, ASK_BROWSERSTACK_AUTH_TOKEN_URL) {
+    ASK_BROWSERSTACK_ATLAS_URL, ASK_BROWSERSTACK_AUTH_TOKEN_URL, 
+    /**
+     * Which relay transport to use, overriding what the deployment implies.
+     *
+     * `relayMode` otherwise derives this from `REMOTE_MCP`, which conflates two
+     * different questions: "am I the hosted process" and "can I hold a connection open
+     * across a human". Only the second decides the transport, and they come apart the
+     * moment anyone wants to exercise the deferred, two-call flow from a local stdio
+     * install — `REMOTE_MCP=true` cannot do it, because this entrypoint exits on that
+     * flag by design (the hosted deployment runs remote-mcp-server instead).
+     *
+     * "deferred" | "elicit". Anything else is ignored.
+     */
+    ASK_BROWSERSTACK_RELAY_TRANSPORT) {
         this.DEV_MODE = DEV_MODE;
         this.browserstackLocalOptions = browserstackLocalOptions;
         this.USE_OWN_LOCAL_BINARY_PROCESS = USE_OWN_LOCAL_BINARY_PROCESS;
@@ -67,9 +80,9 @@ export class Config {
         this.O11Y_TFA_RCA_BASE_URL = O11Y_TFA_RCA_BASE_URL;
         this.BROWSERSTACK_AUTOMATION_BASE_URL = BROWSERSTACK_AUTOMATION_BASE_URL;
         this.BROWSERSTACK_O11Y_UI_BASE_URL = BROWSERSTACK_O11Y_UI_BASE_URL;
-        this.ASK_BROWSERSTACK_ALLOW_REMOTE_RELAY = ASK_BROWSERSTACK_ALLOW_REMOTE_RELAY;
         this.ASK_BROWSERSTACK_ATLAS_URL = ASK_BROWSERSTACK_ATLAS_URL;
         this.ASK_BROWSERSTACK_AUTH_TOKEN_URL = ASK_BROWSERSTACK_AUTH_TOKEN_URL;
+        this.ASK_BROWSERSTACK_RELAY_TRANSPORT = ASK_BROWSERSTACK_RELAY_TRANSPORT;
     }
 }
 const config = new Config(process.env.DEV_MODE === "true", browserstackLocalOptions, process.env.USE_OWN_LOCAL_BINARY_PROCESS === "true", process.env.REMOTE_MCP === "true", process.env.MCP_UPLOAD_BASE_DIR && process.env.MCP_UPLOAD_BASE_DIR.length > 0
@@ -83,12 +96,12 @@ const config = new Config(process.env.DEV_MODE === "true", browserstackLocalOpti
     : DEFAULT_BROWSERSTACK_AUTOMATION_BASE_URL, process.env.BROWSERSTACK_O11Y_UI_BASE_URL &&
     process.env.BROWSERSTACK_O11Y_UI_BASE_URL.length > 0
     ? process.env.BROWSERSTACK_O11Y_UI_BASE_URL
-    : DEFAULT_BROWSERSTACK_O11Y_UI_BASE_URL, (process.env.ASK_BROWSERSTACK_ALLOW_REMOTE_RELAY || "").toLowerCase() ===
-    "true", process.env.ASK_BROWSERSTACK_ATLAS_URL &&
+    : DEFAULT_BROWSERSTACK_O11Y_UI_BASE_URL, process.env.ASK_BROWSERSTACK_ATLAS_URL &&
     process.env.ASK_BROWSERSTACK_ATLAS_URL.trim().length > 0
     ? process.env.ASK_BROWSERSTACK_ATLAS_URL
     : undefined, process.env.ASK_BROWSERSTACK_AUTH_TOKEN_URL &&
     process.env.ASK_BROWSERSTACK_AUTH_TOKEN_URL.trim().length > 0
     ? process.env.ASK_BROWSERSTACK_AUTH_TOKEN_URL
-    : undefined);
+    : undefined, (process.env.ASK_BROWSERSTACK_RELAY_TRANSPORT || "").trim().toLowerCase() ||
+    undefined);
 export default config;

package/dist/lib/instrumentation.js

@@ -6,6 +6,7 @@ const require = createRequire(import.meta.url);
 const packageJson = require("../../package.json");
 import { apiClient } from "./apiClient.js";
 import globalConfig from "../config.js";
+import { redact } from "../tools/capability-registry/redact.js";
 const INSTRUMENTATION_ENDPOINT = "https://api.browserstack.com/sdk/v1/event";
 function baseProperties(toolName, clientInfo) {
     return {
@@ -25,8 +26,13 @@ function errorProperties(error) {
 function sendEvent(event, config) {
     let authHeader;
     if (config) {
-        const authString = getBrowserStackAuth(config);
-        authHeader = `Basic ${Buffer.from(authString).toString("base64")}`;
+        try {
+            const authString = getBrowserStackAuth(config);
+            authHeader = `Basic ${Buffer.from(authString).toString("base64")}`;
+        }
+        catch {
+            // noop
+        }
     }
     apiClient
         .post({
@@ -80,6 +86,19 @@ export function trackMCP(toolName, clientInfo, error, config, extras) {
     };
     sendEvent(event, config);
 }
+/** The text a tool showed the user. */
+function errorTextOf(result) {
+    const content = result?.content;
+    if (!Array.isArray(content))
+        return undefined;
+    const text = content
+        .map((part) => typeof part?.text === "string"
+        ? part.text
+        : "")
+        .filter(Boolean)
+        .join(" ");
+    return redact(text);
+}
 function isErrorResult(result) {
     return (typeof result === "object" &&
         result !== null &&
@@ -93,10 +112,14 @@ export async function withToolCall(toolName, getClientInfo, config, fn) {
     const ctx = { toolName, clientInfo: {}, config };
     const startedAt = performance.now();
     let outcome = "ok";
+    let errorText;
     try {
         const result = await callContext.run(ctx, fn);
-        if (isErrorResult(result))
+        if (isErrorResult(result)) {
             outcome = "error_result";
+            // A returned failure never sets ctx.error, so the reason is read off the result.
+            errorText ??= errorTextOf(result);
+        }
         return result;
     }
     catch (error) {
@@ -123,6 +146,9 @@ export async function withToolCall(toolName, getClientInfo, config, fn) {
                     duration_ms: Math.max(0, Math.round(performance.now() - startedAt)),
                     outcome,
                     ...(ctx.error !== undefined ? errorProperties(ctx.error) : {}),
+                    ...(outcome === "error_result" && ctx.error === undefined && errorText
+                        ? { error_message: errorText }
+                        : {}),
                     ...(ctx.extras ?? {}),
                 },
             };

package/dist/lib/utils.js

@@ -1,11 +1,13 @@
 import { getBrowserStackAuth } from "./get-auth.js";
 import { trackMCP } from "../index.js";
 import logger from "../logger.js";
+import globalConfig from "../config.js";
 export function sanitizeUrlParam(param) {
     // Remove any characters that could be used for command injection
     return param.replace(/[;&|`$(){}[\]<>]/g, "");
 }
 const ONE_MB = 1048576;
+let sharpConfigured = false;
 //Compresses a base64 image intelligently to keep it under 1 MB if needed.
 export async function maybeCompressBase64(base64) {
     const buffer = Buffer.from(base64, "base64");
@@ -17,6 +19,12 @@ export async function maybeCompressBase64(base64) {
     const quality = Math.min(95, Math.max(30, estimatedQuality));
     try {
         const { default: sharp } = await import("sharp");
+        if (!sharpConfigured && globalConfig.REMOTE_MCP) {
+            // Bound memory on constrained hosted pods: no libvips cache, single worker thread.
+            sharp.cache(false);
+            sharp.concurrency(1);
+            sharpConfigured = true;
+        }
         const compressedBuffer = await sharp(buffer).png({ quality }).toBuffer();
         return compressedBuffer.toString("base64");
     }

package/dist/tools/accessiblity-utils/scanner.js

@@ -74,7 +74,7 @@ export class AccessibilityScanner {
             });
             const data = response.data;
             if (!data.success)
-                throw new Error(`Unable to start scan: ${data.errors?.join(", ")}`);
+                throw new Error(`Unable to start scan: ${data.errors?.join(", ") || JSON.stringify(data)}`);
             return data;
         }
         catch (err) {

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

@@ -1,15 +1,5 @@
 /**
- * Atlas's view of the central-OAuth mint.
- *
- * The MECHANISM — the form, the transport, the classification, the cache — moved to
- * `src/lib/central-oauth.ts` when the capability registry needed the same exchange for
- * products whose APIs take a Bearer JWT rather than `Api-Token`. Two minters would have
- * drifted, and the one that drifted would have been the one with fewer tests.
- *
- * What stays here is everything ATLAS-SPECIFIC and nothing else: the scope pair, the skew
- * that exists because Atlas holds the token for a whole run, and the messages — which say
- * "nothing reached the agent" and name `ai_agent_notify`, and would be actively wrong in
- * front of a capability-registry user.
+ * 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
@@ -17,17 +7,20 @@
  * 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, mintCentralToken as mintShared } from "../../lib/central-oauth.js";
-export { fetchTokenTransport, refusalIsAboutScope, REQUESTED_EXPIRES_IN, resetTokenCache, TOKEN_TIMEOUT_MS, type TokenResponse, type TokenTransport, } from "../../lib/central-oauth.js";
+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 — measured, not assumed: the paired scope mints, and the
- * other half alone comes back `400 invalid_request`. `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.
+ * 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):
@@ -49,11 +42,10 @@ export { fetchTokenTransport, refusalIsAboutScope, REQUESTED_EXPIRES_IN, resetTo
  * 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.
- *
- * Named here rather than taken from the shared default, so that changing the registry's
- * scopes can never silently change what Atlas is authorised for.
  */
 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.
  *
@@ -64,6 +56,26 @@ export declare const CENTRAL_SCOPE = "oauth_user_profile ai_agent_notify";
  * 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.
  *
@@ -87,13 +99,22 @@ export declare const AUTH_UNREACHABLE_DETAIL: string;
  */
 export declare const AUTH_SERVER_ERROR_DETAIL: (status: number) => string;
 export declare const AUTH_UNUSABLE_DETAIL: (status: number) => string;
-/** The exact form body of the `client_credentials` grant, at Atlas's scope. */
+/** 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.
  *
- * 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.
+ * 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: Parameters<typeof mintShared>[0]["transport"], now?: number): Promise<string>;
+export declare function mintCentralToken(url: string, credentials: Credentials, transport: TokenTransport, now?: number): Promise<string>;

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

@@ -1,15 +1,5 @@
 /**
- * Atlas's view of the central-OAuth mint.
- *
- * The MECHANISM — the form, the transport, the classification, the cache — moved to
- * `src/lib/central-oauth.ts` when the capability registry needed the same exchange for
- * products whose APIs take a Bearer JWT rather than `Api-Token`. Two minters would have
- * drifted, and the one that drifted would have been the one with fewer tests.
- *
- * What stays here is everything ATLAS-SPECIFIC and nothing else: the scope pair, the skew
- * that exists because Atlas holds the token for a whole run, and the messages — which say
- * "nothing reached the agent" and name `ai_agent_notify`, and would be actively wrong in
- * front of a capability-registry user.
+ * 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
@@ -17,20 +7,24 @@
  * 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 { CentralAuthError, mintCentralToken as mintShared, mintForm as mintFormShared, REQUESTED_EXPIRES_IN, } from "../../lib/central-oauth.js";
+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";
-export { fetchTokenTransport, refusalIsAboutScope, REQUESTED_EXPIRES_IN, resetTokenCache, TOKEN_TIMEOUT_MS, } from "../../lib/central-oauth.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 — measured, not assumed: the paired scope mints, and the
- * other half alone comes back `400 invalid_request`. `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.
+ * 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):
@@ -52,11 +46,10 @@ export { fetchTokenTransport, refusalIsAboutScope, REQUESTED_EXPIRES_IN, resetTo
  * 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.
- *
- * Named here rather than taken from the shared default, so that changing the registry's
- * scopes can never silently change what Atlas is authorised for.
  */
 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.
  *
@@ -67,6 +60,49 @@ export const CENTRAL_SCOPE = "oauth_user_profile ai_agent_notify";
  * 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.
  *
@@ -105,51 +141,137 @@ export const AUTH_SERVER_ERROR_DETAIL = (status) => `BrowserStack auth is unavai
     `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.`;
-/** The exact form body of the `client_credentials` grant, at Atlas's scope. */
+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 mintFormShared(credentials, CENTRAL_SCOPE, REQUESTED_EXPIRES_IN);
+    return {
+        grant_type: "client_credentials",
+        username: credentials.username,
+        access_key: credentials.accessKey,
+        scope: CENTRAL_SCOPE,
+        expires_in: String(REQUESTED_EXPIRES_IN),
+    };
 }
-/** Every failure kind gets Atlas's own sentence; none of them carries the response body. */
-function toAskError(error) {
-    if (!(error instanceof CentralAuthError))
-        return error;
-    switch (error.kind) {
-        case "no_credentials":
-            return new AskError("BrowserStack AI is not authenticated: BROWSERSTACK_USERNAME and " +
-                "BROWSERSTACK_ACCESS_KEY are required to sign in");
-        case "unreachable":
-            return new AskError(AUTH_UNREACHABLE_DETAIL);
-        case "server_error":
-            return new AskError(AUTH_SERVER_ERROR_DETAIL(error.status));
-        case "refused_scope":
-            return new AskError(AUTH_SCOPE_REFUSED_DETAIL(error.status));
-        case "refused_credentials":
-            return new AskError(AUTH_REJECTED_DETAIL(error.status));
-        default:
-            return new AskError(AUTH_UNUSABLE_DETAIL(error.status));
+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.
  *
- * 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.
+ * 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()) {
-    try {
-        return await mintShared({
-            url,
-            scope: CENTRAL_SCOPE,
-            credentials,
-            transport,
-            refreshSkewMs: REFRESH_SKEW_MS,
-            cacheEnabled: !appConfig.REMOTE_MCP,
-            now,
-            onMinted: (lifetimeMs) => logger.info("askBrowserStackAI: signed in as %s (lifetime %ss)", credentials.username, Math.round(lifetimeMs / 1000)),
+    // 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;
         });
     }
-    catch (error) {
-        throw toAskError(error);
+    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;
 }

package/dist/tools/ask-browserstack/config.d.ts

@@ -30,20 +30,6 @@ export declare class AskError extends Error {
  * other three are on the config singleton (rules/tool-design.md).
  */
 export declare function isEnabled(): boolean;
-/**
- * May the relay be offered in the hosted (`REMOTE_MCP`) deployment?
- *
- * OFF BY DEFAULT, because it depends on something outside this package: the host has to
- * keep one `McpServer` alive per session. Stateless hosts build a fresh server per POST,
- * and an elicitation answer — which arrives as a SEPARATE POST — then reaches an instance
- * that never asked anything, leaving the real one suspended until it times out. So this
- * must stay opt-in per deployment rather than become a default that silently hangs.
- *
- * Turning it on does NOT force the relay on: `relayMode` still asks whether THIS client
- * declared the `elicitation` capability, and a client that did not still gets a read-only
- * run. This flag only removes the blanket refusal.
- */
-export declare function allowRemoteRelay(): boolean;
 /**
  * ============================================================================
  * PRODUCTION DEFAULTS

package/dist/tools/ask-browserstack/config.js

@@ -34,22 +34,6 @@ export class AskError extends Error {
 export function isEnabled() {
     return (process.env.ASK_BROWSERSTACK_DISABLED || "").toLowerCase() !== "true";
 }
-/**
- * May the relay be offered in the hosted (`REMOTE_MCP`) deployment?
- *
- * OFF BY DEFAULT, because it depends on something outside this package: the host has to
- * keep one `McpServer` alive per session. Stateless hosts build a fresh server per POST,
- * and an elicitation answer — which arrives as a SEPARATE POST — then reaches an instance
- * that never asked anything, leaving the real one suspended until it times out. So this
- * must stay opt-in per deployment rather than become a default that silently hangs.
- *
- * Turning it on does NOT force the relay on: `relayMode` still asks whether THIS client
- * declared the `elicitation` capability, and a client that did not still gets a read-only
- * run. This flag only removes the blanket refusal.
- */
-export function allowRemoteRelay() {
-    return appConfig.ASK_BROWSERSTACK_ALLOW_REMOTE_RELAY;
-}
 /**
  * ============================================================================
  * PRODUCTION DEFAULTS