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

package/capability/tra.capability-index.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
-  "version": "1.2",
-  "build_id": "tra-v1.2-add-archive-unlink",
+  "version": "1.3",
+  "build_id": "tra-v1.3-p0-eval-fixes",
   "tra": {
     "routing_terms": ["flaky", "flakiness", "workspace", "configuration", "schedule", "suite", "result"],
     "summary": "BrowserStack Test Reporting & Analytics (TRA, aka Test Observability): ingest, investigate and report on automated test runs. A build groups the test runs of one CI/SDK execution; each run carries status, logs, errors, hooks and AI root-cause analysis. Everything is scoped to a project. Read builds and runs; filter and search them; manage dashboards, custom views and saved reports; configure quality gates, webhooks, notifications, CI triggers and integrations; and read stability, performance, flakiness and unique-error analytics. Tests are REPORTED here, not executed here - execution happens in your runner or another BrowserStack product and is pushed in via the SDK. Access-key auth reaches only the /ext/v1 external API; everything else needs a session or service credential. Each run records its result on the browser, device, OS and environment it ran on, under the app version and the build tags it was pushed with, and a failure can be linked to an issue. Saved reports can be scheduled. Destructive capabilities need explicit human approval.",
@@ -4350,6 +4350,7 @@
           }
         },
         "guidance": [
+          "ALWAYS pass lowerBound/upperBound: omitting them returns the full retention window (tens of thousands of characters) and blows the tool output limit. For a single build's flaky/new-failure/muted/re-run counts read the build row (historyAggregate) via list_project_builds or get_build_details instead; this card is per build NAME over a window, not per run.",
           "Plan-feature-gated: if the flakiness widget is not in the caller's plan the call fails with 403 (FEATURE_INACCESSIBLE), NOT a 200 with empty data - do not treat that as 'no flaky tests'.",
           "The window is clamped to plan retention silently, and the bucket interval is derived from the width of the window you asked for, so a wider range yields coarser buckets.",
           "`insights.count` is the headline percentage as a STRING (one decimal), and `insights.meta` is a human sentence like 'N of M unique tests are flaky'; the per-bucket series is in `data`, each point's `y` being the flaky count for that bucket (null when no tests ran).",
@@ -8057,7 +8058,8 @@
           "All three query params are required.",
           "When no build matches you get a bare HTTP 404 with an EMPTY body (not a structured error object) \u2014 handle the status code, there is nothing to parse.",
           "The lookup is scoped to the caller's group, so a build in another group reads as not-found.",
-          "Returns just `{buildId}` (the resolved UUID); use `get_build_coordinates_from_uuid` for the inverse."
+          "Returns just `{buildId}` (the resolved UUID); use `get_build_coordinates_from_uuid` for the inverse.",
+          "`buildSerialId` is the UI #N only. If the user's number does not match (404) it may be the CI run id (`buildRunId`): resolve that with search_entities (entity Build) or list_project_builds, which return both ids."
         ],
         "responses": {
           "200": {
@@ -10087,6 +10089,7 @@
           }
         },
         "guidance": [
+          "Pages are tiny and uneven in practice (2, 5, 6 rows) and there is no name filter, so this is the WRONG route for 'find project X' or 'what projects do I have' on a large group: use list_projects_lite_paginated (`search`, 100 per page, newest activity first) or list_projects_full (whole group, capped at 30 rows).",
           "Requires the PROJECT_VIEW permission; a credential without it is refused. A user OAuth credential that holds it is accepted - a service account is not required.",
           "Up to 10 projects per page, and a page can hold fewer while has_next is still true - a short page is not the last page. There is no page-size parameter. Paginate only with the returned base64 next_page cursor, not a numeric page.",
           "pagination.has_next is computed as 'this page was non-empty', so the last full page still reports has_next=true and you get one extra EMPTY page. Stop when projects comes back empty, not when has_next turns false.",
@@ -13947,7 +13950,8 @@
           "The body is a bare JSON array of log entries, not an object wrapper \u2014 iterate it directly.",
           "`trim=true` narrows the stream to the test's own time window; the default (false) includes the whole session.",
           "Bad ids give TEST_RUN_NOT_FOUND / BUILD_NOT_FOUND (404); locked builds give FORBIDDEN_OPERATION / PLAN_FEATURE_NOT_ALLOWED (403).",
-          "On the demo-sandbox environment canned logs are returned, chosen by the test's name."
+          "On the demo-sandbox environment canned logs are returned, chosen by the test's name.",
+          "An unknown or non-existent testRunId returns HTTP 500 'Internal System Exception', not 404: do not pass a user-supplied number straight in; resolve the test run id from the build's test-run listing first (a 'run number' the user quotes is almost always a build serial or CI run id, never a testRunId)."
         ]
       },
       {
@@ -13969,7 +13973,8 @@
           "This is the heaviest of the detail reads: it assembles the run, its captured code, its meta and the related hook code from several sources, so prefer a lighter read when you only need status or metadata.",
           "testCode (and each entry of hooksCode) can have null code/language when no code was captured for that run \u2014 the row is still returned; do not treat a null code as an error.",
           "A run that does not belong to the caller's group, or does not exist, comes back as TEST_RUN_NOT_FOUND \u2014 the same answer for 'wrong group' and 'no such run'.",
-          "testMetadata here is the internal test-meta object and is shaped differently from the flatter meta returned by the baseline/similar-error map reads; read its keys from this response rather than assuming they match."
+          "testMetadata here is the internal test-meta object and is shaped differently from the flatter meta returned by the baseline/similar-error map reads; read its keys from this response rather than assuming they match.",
+          "An unknown or non-existent testRunId returns HTTP 500 'Internal System Exception', not 404: do not pass a user-supplied number straight in; resolve the test run id from the build's test-run listing first (a 'run number' the user quotes is almost always a build serial or CI run id, never a testRunId)."
         ],
         "returns": [
           "testCode",
@@ -22052,7 +22057,10 @@
           "Sort is fixed to updated_at-desc and cannot be changed by the caller.",
           "Page size is NOT caller-controlled: overlay=true fixes it to 10 and omits `pagingParams`/`totalCount`; overlay off fixes it to 30 and includes them. Page through with `pageNumber` and `pagingParams.has_next`.",
           "This is a thin pass-through to the backend global-search API; TRA only validates/sanitises the query, fixes the sort, and sets the page size.",
-          "Each result row carries its own `id`, entity `type` discriminator, and a `userName` resolved from the record's user id."
+          "Each result row carries its own `id`, entity `type` discriminator, and a `userName` resolved from the record's user id.",
+          "Keep `days` at or below 90: on a large group, windows of 365 or more returned HTTP 500 'Internal System Exception' instead of results.",
+          "entity=\"Build\" is the only cross-project way to find a build by NAME or by CI run id: each hit carries `projectName`/`projectNormalizedName`, `uuid`, `serialId` (the #N) and `buildRunId` (the CI run id). Use it when a user names a build or a run number without a project.",
+          "entity=\"Project\" is unreliable for name lookup (an existing project can return zero hits); find projects by name with list_projects_lite_paginated `search` instead."
         ]
       },
       {
@@ -24721,7 +24729,8 @@
         "guidance": [
           "Pure read: no AI consent/feature checks and no generation queued. Use this to poll for a result after triggering one elsewhere.",
           "When nothing has been generated yet this is a 400 (BAD_REQUEST, 'Test Run RCA not found for the given test run ID'), NOT a 404 or an empty 200 \u2014 treat that 400 as 'not generated yet', not as a bad request.",
-          "Group-scoped: the run is looked up within the caller's group, so a foreign run id also surfaces as not-found."
+          "Group-scoped: the run is looked up within the caller's group, so a foreign run id also surfaces as not-found.",
+          "404 'RCA not found' means no RCA has been generated for this test run yet (not a bad id): generating one is a write (get_test_rca / trigger_test_rca_via_public_api) and needs user confirmation."
         ]
       },
       {
@@ -27358,7 +27367,9 @@
           "When `date_range` is omitted the window is the LAST 7 DAYS \u2014 older builds simply will not appear unless you pass an explicit [start,end] in epoch millis.",
           "Within a page builds come back OLDEST-first: the handler reverses the fetched page (Lists.reverse) before returning.",
           "Requires automated-test-run view permission on the project.",
-          "Each build carries an `observability_url` deep link and `tcmTestRunIdentifier`; use `build_id` (the hashed uuid; there is no `uuid` key) for follow-up per-build calls."
+          "Each build carries an `observability_url` deep link and `tcmTestRunIdentifier`; use `build_id` (the hashed uuid; there is no `uuid` key) for follow-up per-build calls.",
+          "For 'the latest / last N builds' prefer list_project_builds (newest-first, `pageLimit`, project-scoped `search`): this route is oldest-first within a page, 10 per page and defaults to the last 7 days, so 'last 10 builds' can cost several calls.",
+          "Each item carries `build_number` (the serial #N) and, when the CI set one, the CI run id; a user's 'run <number>' may be the CI run id rather than `build_number`."
         ],
         "responses": {
           "200": {
@@ -27594,6 +27605,7 @@
           "closedCount"
         ],
         "guidance": [
+          "PREFERRED build listing for agents: newest-first, `pageLimit` sets the page size (keep it at or below 50 \u2014 each row is large and a big page overflows the tool output), `search` filters by build name, and rows carry buildNumber, `buildRunId` (CI run id), statusStats, historyAggregate (flaky / newFailure / alwaysFailing counts) and qualityGateStatus, so one call answers 'last N builds with status'.",
           "Takes the project's NORMALISED NAME in the path, not a numeric id. Uses the same large filter object as the build-groups listing.",
           "SIDE EFFECT: this call marks the project as subscribed for the calling user \u2014 a read that quietly changes the user's subscription state. It also applies the group's custom data-retention window for the duration of the request, so builds older than the retention window will not appear regardless of `dateRange`.",
           "Cursor pagination via `pagingParams` / `searchAfter`; page through until the paging params report no next cursor. `pageLimit` defaults to 10.",
@@ -28578,7 +28590,9 @@
         "guidance": [
           "Accepts either the numeric id or the normalised name in the one path segment \u2014 carry whichever you have, no separate lookup needed.",
           "configuration.attributes is always present; configuration.subTypes and configuration.alertConfiguration are omitted when null (the DTO is NON_NULL), so treat their absence as 'none configured', not an error.",
-          "permissions is a JSON array node reflecting the caller's rights on this project \u2014 read it to decide which mutating project actions to offer."
+          "permissions is a JSON array node reflecting the caller's rights on this project \u2014 read it to decide which mutating project actions to offer.",
+          "The numeric id must be the TRA project id (e.g. from list_projects_lite_paginated `id`), NOT the TestHub/Test Management id (`thProjectId`): a TestHub id gives 404 and an unknown id can give a bare 500 'Internal System Exception'.",
+          "`permissions` reflects the API role, which can be broader than what the UI shows for the same user; do not tell the user they can edit settings based on it alone."
         ],
         "responses": {
           "200": {
@@ -29185,6 +29199,7 @@
           "pagingParams"
         ],
         "guidance": [
+          "PREFERRED route to resolve a project by name: pass `search` with the user's words; the exact match is usually on the first page. The row carries the TRA `id` (for integer-id routes), `normalisedName` (for name routes) and `thProjectId` (TestHub/TM id, NOT accepted by TRA routes).",
           "searchAfter is an OFFSET, not a cursor \u2014 the name is misleading. Page by reading pagingParams.searchAfter back into the next request; hasNext is computed by over-fetching one row.",
           "Page size is hardcoded at 100 and cannot be changed.",
           "In demo-sandbox environments the offset is forced to 0, so you always get the first page there regardless of searchAfter.",
@@ -31239,7 +31254,8 @@
           "runInfo is a NESTED object ({duration, browser, os, device}); duration, browser, os and device do NOT appear at the top level even though they read like headline attributes \u2014 read them under runInfo.",
           "sessionId is not always a plain BrowserStack Automate session id: for App Automate non-SDK frameworks it is resolved differently, so do not assume it addresses the Automate session API directly.",
           "bsTags is the BrowserStack-side tag list (array of objects); userTags is the plain string array the user set \u2014 they are two different fields.",
-          "An unknown id is TEST_RUN_NOT_FOUND; a run whose build is retention-locked is refused with FORBIDDEN_OPERATION rather than returning partial data."
+          "An unknown id is TEST_RUN_NOT_FOUND; a run whose build is retention-locked is refused with FORBIDDEN_OPERATION rather than returning partial data.",
+          "An unknown or non-existent testRunId returns HTTP 500 'Internal System Exception', not 404: do not pass a user-supplied number straight in; resolve the test run id from the build's test-run listing first (a 'run number' the user quotes is almost always a build serial or CI run id, never a testRunId)."
         ],
         "returns": [
           "runInfo",
@@ -31350,7 +31366,9 @@
           "This is the URL-returning counterpart of the merged-logs read (get_test_run_merged_logs): browserstackLogs, sdkLogs and hookRunLogs are URLs the browser fetches itself, while failureLogs and stepLogs are returned INLINE. Use the merged-logs read when you need the log text assembled server-side.",
           "browserstackLogs is a per-channel object (text, console, selenium, appium, playwright, performance, network, device, video, terminal, telemetry, browserprofiling, ...); each present channel is a presigned URL/descriptor, not content, and presence does not prove the artefact exists. Null fields are serialised as explicit nulls (testStartedAt/testFinishedAt can be null).",
           "Retention-locked builds are refused with FORBIDDEN_OPERATION / PLAN_FEATURE_NOT_ALLOWED, not an empty body.",
-          "Whether logs are served from S3 or the BrowserStack session API is decided internally by a Redis flag and the framework \u2014 the caller cannot influence it."
+          "Whether logs are served from S3 or the BrowserStack session API is decided internally by a Redis flag and the framework \u2014 the caller cannot influence it.",
+          "An unknown or non-existent testRunId returns HTTP 500 'Internal System Exception', not 404: do not pass a user-supplied number straight in; resolve the test run id from the build's test-run listing first (a 'run number' the user quotes is almost always a build serial or CI run id, never a testRunId).",
+          "Channels are session-type specific: `appium` and `device` exist only for App Automate sessions; a web (Automate) or report-upload build has no Appium/device logs \u2014 say so rather than promising the link."
         ],
         "returns": [
           "testStartedAt",
@@ -33626,6 +33644,8 @@
           }
         },
         "guidance": [
+          "OBSERVED LIVE: `buildNames` and `query` are IGNORED by the product (200 with the unfiltered page, even when `projects` is set). Do not use this route to find a build by name; use list_project_builds (project-scoped, `search`) or search_entities (cross-project).",
+          "Only the body fields declared here are sent; the inherited filter surface mentioned in the field description (users, teams, statuses, tags, dateRange, search...) is not bindable through this capability.",
           "POST but a pure READ \u2014 the body is a filter; nothing is written.",
           "Page size is fixed server-side (BUILDS_PAGESIZE); it is NOT caller-controllable, so there is no page-size body field. Page with the afterKey/beforeKey cursors from pagingParams (hasNext/hasPrev tell you when to stop).",
           "Honours UDAC project scoping: with projects null and UDAC on, only the caller's accessible projects are returned.",
@@ -50533,9 +50553,11 @@
           "automation build",
           "test build",
           "build run",
-          "launch"
+          "launch",
+          "ci run id",
+          "build run id"
         ],
-        "id_convention": "Addressed by build UUID (an opaque string) on most routes. A few reads take the internal NUMERIC build id instead (e.g. the AI failure summary), and the two are not interchangeable. A build can also be located by its human coordinates (project normalised name + build normalised name + build serial number), which resolve to the UUID. There is no prefixed display identifier.",
+        "id_convention": "Addressed by build UUID (an opaque string) on most routes. A few reads take the internal NUMERIC build id instead (e.g. the AI failure summary), and the two are not interchangeable. A build can also be located by its human coordinates (project normalised name + build normalised name + build serial number), which resolve to the UUID. There is no prefixed display identifier. A build ALSO carries a CI run id (`buildRunId`, a string set by the CI/upload client), which is NOT the serial number (#N): users often say \"run <number>\" meaning buildRunId. Resolve a bare run number with search_entities (entity=\"Build\", days<=90): each hit carries both `buildRunId` and `serialId` plus the project; get_build_id_from_build_coordinates only understands the serial.",
         "parents": [
           "project"
         ],
@@ -52069,6 +52091,6 @@
         ]
       }
     },
-    "version": "1.2"
+    "version": "1.3"
   }
 }

package/dist/config.d.ts

@@ -11,10 +11,35 @@ export declare class Config {
     readonly O11Y_TFA_RCA_BASE_URL: string;
     readonly BROWSERSTACK_AUTOMATION_BASE_URL: string;
     readonly BROWSERSTACK_O11Y_UI_BASE_URL: string;
-    readonly ASK_BROWSERSTACK_ALLOW_REMOTE_RELAY: boolean;
     readonly ASK_BROWSERSTACK_ATLAS_URL: string | undefined;
     readonly ASK_BROWSERSTACK_AUTH_TOKEN_URL: string | undefined;
-    constructor(DEV_MODE: boolean, browserstackLocalOptions: Record<string, any>, USE_OWN_LOCAL_BINARY_PROCESS: boolean, REMOTE_MCP: boolean, UPLOAD_BASE_DIR: string | undefined, O11Y_TFA_RCA_BASE_URL: string, BROWSERSTACK_AUTOMATION_BASE_URL: string, BROWSERSTACK_O11Y_UI_BASE_URL: string, ASK_BROWSERSTACK_ALLOW_REMOTE_RELAY: boolean, ASK_BROWSERSTACK_ATLAS_URL: string | undefined, ASK_BROWSERSTACK_AUTH_TOKEN_URL: string | undefined);
+    /**
+     * 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.
+     */
+    readonly ASK_BROWSERSTACK_RELAY_TRANSPORT: string | undefined;
+    constructor(DEV_MODE: boolean, browserstackLocalOptions: Record<string, any>, USE_OWN_LOCAL_BINARY_PROCESS: boolean, REMOTE_MCP: boolean, UPLOAD_BASE_DIR: string | undefined, O11Y_TFA_RCA_BASE_URL: string, BROWSERSTACK_AUTOMATION_BASE_URL: string, BROWSERSTACK_O11Y_UI_BASE_URL: string, ASK_BROWSERSTACK_ATLAS_URL: string | undefined, ASK_BROWSERSTACK_AUTH_TOKEN_URL: string | undefined, 
+    /**
+     * 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: string | undefined);
 }
 declare const config: Config;
 export default config;

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

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

@@ -0,0 +1,74 @@
+/**
+ * The two-call shape: ask now, decide later, with nothing held open in between.
+ *
+ * WHY IT EXISTS. Elicitation is what makes this process stateful — a suspended
+ * `elicitation/create` pins an McpServer in one pod's heap until the answer arrives, so
+ * the hosted deployment needs sessions, ingress affinity keyed on the caller's
+ * credentials, and a cap on how many sessions may be alive. Deferred removes the
+ * suspension rather than routing around it: Atlas returns at its first ask, we hand that
+ * ask back, and the caller returns with the decision in a SECOND call. Between the two
+ * this process holds nothing, so any pod can serve either.
+ *
+ * WHAT IT COSTS, stated plainly because it is not free:
+ *   - Approval rides the CLIENT's own permission prompt on the second call, not an
+ *     elicitation. A client configured not to prompt (`--permission-mode auto`) approves
+ *     with no human. Elicitation fails closed by construction; this fails closed only if
+ *     the client asks. That is the trade, and it is why stdio keeps elicitation.
+ *   - One extra round trip per APPROVAL, not per task. Atlas's gate is serial, so a task
+ *     with five writes is five approvals and six calls.
+ *
+ * The run itself is parked on Atlas's side for the gate's own 300s, kept alive exactly as
+ * a dropped reader leaves it (CONTRACT v2 §4.2). Nothing here has to manage that.
+ */
+import { DeferredTransport } from "./stream.js";
+import { AgentRequest, AskResult, RelayMode } from "./types.js";
+/** What a parked run needs the caller to send back. */
+export interface ParkedAsk {
+    perm_id: string;
+    description: string;
+    product: string;
+    mode: string;
+}
+/**
+ * Atlas's `needs_approval` payload → our result, or `null` when it is not one.
+ *
+ * Null rather than a throw: a deferred request whose run never needed approval comes
+ * back as an ORDINARY result, and that is a success to pass straight through — not an
+ * unexpected shape. A read-only task must cost one call, not two.
+ */
+export declare function parkedResult(body: unknown, product: string): {
+    runId: string;
+    ask: ParkedAsk;
+} | null;
+/** CONTRACT §5's shape, for a run that is parked rather than finished. */
+export declare function needsApprovalResult(runId: string, ask: ParkedAsk, product: string): AskResult;
+/** The FIRST call: run until the first ask, then answer. Nothing is held open. */
+export declare function runDeferred(url: string, headers: Record<string, string>, body: AgentRequest, transport: DeferredTransport, mode: RelayMode, product: string): Promise<AskResult>;
+/**
+ * The SECOND call: deliver the decision, then pick the run back up.
+ *
+ * Two requests, in this order, and the order is the safety property: the decision is
+ * posted FIRST so that a reattach which then fails cannot leave the gate waiting on an
+ * answer we already have. A lost reattach costs the caller the answer; a lost decision
+ * would cost them the run.
+ */
+export declare function runResumed(agentUrl: string, headers: Record<string, string>, runId: string, permId: string, decision: "allow" | "deny", transport: DeferredTransport, mode: RelayMode, product: string): Promise<AskResult>;
+/** A resume that did not happen. Every field says "nothing changed", because in each
+ *  case nothing did — and a caller that cannot tell a failed resume from a refusal
+ *  either retries a write that landed or abandons one that never did. */
+export declare function resumeFailed(error: string): AskResult;
+/** A decision that went out and whose reply never came back.
+ *
+ *  Deliberately NOT `resumeFailed`: every field there says "nothing changed", and that
+ *  is a claim this case cannot make. The decision request carries the continuation now,
+ *  so a lost reply covers everything from "it never arrived" to "the write landed and
+ *  the answer was lost" — and telling a model nothing happened is what gets the change
+ *  made twice.
+ *
+ *  `applied_before_stop: null` for the same reason: null is "not measured", which is
+ *  true, where false would be a measurement nobody took. */
+export declare function decisionUnknown(): AskResult;
+/** Starting a run with no task. Only reachable now that `query` is optional, which it
+ *  has to be so a model can follow `next_step` — which omits it — literally. */
+export declare function missingQuery(): AskResult;
+export declare function incompleteResume(): AskResult;