@browserstack/mcp-server 1.3.1-beta.1 → 1.4.0-beta.1

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

@@ -0,0 +1,134 @@
+import logger from "../../logger.js";
+/**
+ * Where Atlas lives, and the timeout ladder.
+ *
+ * The host IS compiled in, matching every other tool here — `TM_BASE_URLS`, the
+ * instrumentation endpoint — so an install needs no configuration to work. One env var
+ * overrides it. See the warning on `DEFAULT_ATLAS_URL`: the compiled-in value is currently
+ * STAGING and is a deliberate placeholder.
+ */
+/**
+ * CONTRACT §4 — the timeout ladder, outermost first. EACH LAYER MUST EXCEED THE ONE INSIDE
+ * IT, or a layer dies before the layer it is waiting on can answer:
+ *
+ *   MCP client -> tool call        longest, client-side, not ours
+ *   POST /agent HTTP request       330s   <- here
+ *   Atlas gate -> stream ask       300s   Atlas's `permission_relay_timeout`
+ *   elicitInput                    270s   <- here
+ *
+ * 300s is the browser path's existing PERMISSION_TIMEOUT, which also auto-rejects.
+ */
+export const AGENT_TIMEOUT_MS = 330_000;
+export const ELICITATION_TIMEOUT_MS = 270_000;
+/** Thrown for anything this tool refuses to attempt. Never carries a credential. */
+export class AskError extends Error {
+}
+/** Off by default is wrong for a shipped feature, but a kill switch is not. */
+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 ((process.env.ASK_BROWSERSTACK_ALLOW_REMOTE_RELAY || "").toLowerCase() ===
+        "true");
+}
+/**
+ * ============================================================================
+ * PRODUCTION DEFAULTS
+ * ============================================================================
+ *
+ * These hosts are PRODUCTION. They replace the interim staging placeholders that this
+ * package shipped with while the relay was being built ("for now lets hardcode the
+ * base_url to staging only then we will point this to prod url later") — that step is
+ * now done.
+ *
+ * `https://workflows.browserstack.com` was verified, not guessed: its `/api/profiles`
+ * answers `401 {"detail":"authentication required"}`, byte-identical to staging Atlas.
+ * The production auth endpoint is `https://auth.browserstack.com/oauth2/v2/token`.
+ *
+ * WHY THIS MATTERS: this package publishes to npm as `@browserstack/mcp-server`, so an
+ * install with no environment variables set now talks to PRODUCTION. That is correct for
+ * a production deployment, but it removes the old safety property — a misconfigured or
+ * test deployment that forgets `ASK_BROWSERSTACK_ATLAS_URL` no longer fails safe onto
+ * staging, it reads and writes REAL customer data. Non-production deployments MUST set
+ * that variable explicitly. The resolved host is logged at info on first use, naming
+ * whether it came from the env var or from here, so a deployment pointing at the wrong
+ * Atlas is visible in a log line rather than inferred later from confusing data.
+ *
+ * Staging hosts, for anyone setting the override:
+ *   ASK_BROWSERSTACK_ATLAS_URL      = https://ai-platform-service.bsstag.com
+ *   ASK_BROWSERSTACK_AUTH_TOKEN_URL = https://auth-preprod.bsstag.com/oauth2/v2/token
+ *
+ * The tests assert these literals precisely so that repointing has to be deliberate
+ * rather than something that slips through.
+ *
+ * grep: DEFAULT-PROD-HOSTS
+ */
+export const DEFAULT_ATLAS_URL = "https://workflows.browserstack.com";
+export const DEFAULT_AUTH_TOKEN_URL = "https://auth.browserstack.com/oauth2/v2/token";
+/** An operator's override may carry a trailing slash; the constants above do not. */
+function trimUrl(value) {
+    return value.trim().replace(/\/+$/, "");
+}
+/**
+ * Announced ONCE per distinct resolution, not per tool call.
+ *
+ * The point is that a deployment talking to the wrong Atlas shows up in the log; repeating it
+ * on every call would only make it easier to scroll past.
+ */
+const announced = new Set();
+/** For tests, and for anything that legitimately re-resolves. */
+export function resetHostAnnouncements() {
+    announced.clear();
+}
+function announce(what, url, source) {
+    const line = `${what}|${url}|${source}`;
+    if (announced.has(line))
+        return;
+    announced.add(line);
+    logger.info("askBrowserstackAI: %s is %s (source: %s)", what, url, source);
+}
+/**
+ * Resolve Atlas's base URL:
+ *
+ *   1. ASK_BROWSERSTACK_ATLAS_URL   explicit override
+ *   2. the built-in staging default (see the warning above)
+ *
+ * Matching every other tool here, which ships its host in the code and treats the env var as
+ * an override — `TM_BASE_URLS`, the instrumentation endpoint. There is no environment map and
+ * no selector: one default, one override.
+ */
+export function atlasBaseUrl() {
+    const explicit = process.env.ASK_BROWSERSTACK_ATLAS_URL;
+    const url = explicit && explicit.trim() ? trimUrl(explicit) : DEFAULT_ATLAS_URL;
+    announce("Atlas", url, explicit && explicit.trim() ? "env" : "default");
+    return url;
+}
+/** Resolved per call, never captured at construction. */
+export function agentUrl() {
+    return `${atlasBaseUrl()}/agent`;
+}
+/**
+ * Where a central-OAuth JWT is minted (CONTRACT v1.2 §I, as amended by task 7).
+ *
+ * The shared `delegation.token` path is gone from Atlas, so a user-attested central JWT is
+ * the only way in. Same two rungs as the host, and the same staging default.
+ */
+export function authTokenUrl() {
+    const explicit = process.env.ASK_BROWSERSTACK_AUTH_TOKEN_URL;
+    const url = explicit && explicit.trim() ? trimUrl(explicit) : DEFAULT_AUTH_TOKEN_URL;
+    announce("auth token endpoint", url, explicit && explicit.trim() ? "env" : "default");
+    return url;
+}

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

@@ -0,0 +1,34 @@
+/**
+ * The pieces of the outbound `POST /agent` that are not the transport itself.
+ *
+ * The transport moved to `stream.ts` when A2 was removed: `/agent` is read as an event
+ * stream now, so a one-request-one-response `AgentTransport` has nothing left to describe.
+ * What stays here is what both halves always shared — the header set, the credential pair,
+ * and the response shape `relay.ts` reads to tell a refusal from an unreachable service
+ * apart, which the stream's JSON-degrade path still produces.
+ *
+ * AUTH HERE IS NOT THE PRODUCT-API AUTH. `/agent` accepts exactly two credentials, both in
+ * `Authorization`: the shared delegation token or a BrowserStack central JWT. There is no
+ * `Api-Token` path on this route (CONTRACT v1.2 §I), so sending one would not merely be
+ * useless — it would push the user's `access_key` across a trust boundary to an endpoint
+ * that has no use for it, and into every request log on the way. The capability registry's
+ * `authHeaders` remains right for PRODUCT calls; it is simply not the header set for this
+ * one, and is deliberately not imported here.
+ */
+export interface Credentials {
+    username: string;
+    accessKey: string;
+}
+/**
+ * The complete header set for `POST /agent` (CONTRACT v1.2 §4). Three headers, no more.
+ *
+ * The token is a secret and appears nowhere else: not in a log line, not in a result, not in
+ * an error message.
+ */
+export declare function agentHeaders(token: string): Record<string, string>;
+export interface AgentResponse {
+    status: number;
+    body: unknown;
+    /** Only when there was no response at all to speak for itself. */
+    error?: string;
+}

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

@@ -0,0 +1,31 @@
+/**
+ * The pieces of the outbound `POST /agent` that are not the transport itself.
+ *
+ * The transport moved to `stream.ts` when A2 was removed: `/agent` is read as an event
+ * stream now, so a one-request-one-response `AgentTransport` has nothing left to describe.
+ * What stays here is what both halves always shared — the header set, the credential pair,
+ * and the response shape `relay.ts` reads to tell a refusal from an unreachable service
+ * apart, which the stream's JSON-degrade path still produces.
+ *
+ * AUTH HERE IS NOT THE PRODUCT-API AUTH. `/agent` accepts exactly two credentials, both in
+ * `Authorization`: the shared delegation token or a BrowserStack central JWT. There is no
+ * `Api-Token` path on this route (CONTRACT v1.2 §I), so sending one would not merely be
+ * useless — it would push the user's `access_key` across a trust boundary to an endpoint
+ * that has no use for it, and into every request log on the way. The capability registry's
+ * `authHeaders` remains right for PRODUCT calls; it is simply not the header set for this
+ * one, and is deliberately not imported here.
+ */
+/**
+ * The complete header set for `POST /agent` (CONTRACT v1.2 §4). Three headers, no more.
+ *
+ * The token is a secret and appears nowhere else: not in a log line, not in a result, not in
+ * an error message.
+ */
+export function agentHeaders(token) {
+    return {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json",
+        // Attribution, so the downstream service can see the call came from an agent.
+        "request-source": "ai-chatbot",
+    };
+}

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

@@ -0,0 +1,61 @@
+/**
+ * `askBrowserstackAI` — one tool call in, one tool result out, with a human's approval
+ * relayed through the middle of it.
+ *
+ * The shape, and why:
+ *
+ *   1. NEGOTIATE FIRST. `relayMode()` is consulted BEFORE Atlas is called, so Atlas learns
+ *      whether a human is reachable before it starts rather than discovering it at the gate.
+ *      Anything other than "offered" means `permission_relay` is omitted entirely and Atlas
+ *      runs read-only — today's exact behaviour, and the path opencode and goose stay on.
+ *      That also covers the hosted `REMOTE_MCP` deployment, where the relay cannot work at
+ *      all; see `relayMode` for why. Nothing here depends on `sampling`, which Claude Code
+ *      does not declare.
+ *   2. LISTEN ON LOOPBACK. Transport is A2, so Atlas calls US back; because it initiates,
+ *      the decision returns on the same connection to the same pod and PLAN.md's affinity
+ *      problem never arises for this stdio deployment.
+ *   3. ELICIT, ONCE. Atlas's `description` is the message, nothing is requested in the form,
+ *      and the ACTION is mapped by CONTRACT §7 with no second chances.
+ *   4. RETURN THE TRAIL. `approvals` and `applied_before_stop` are what let a caller tell
+ *      "nothing happened" from "some steps applied, then stopped".
+ *
+ * FAIL CLOSED THROUGHOUT. A decline, a cancel, a timeout, a bad token, a body we cannot
+ * parse, a handler that throws — every one of them denies. An unattended run cannot approve
+ * itself because a headless client returns `cancel`, which is a deny.
+ */
+import { McpServer, RegisteredTool } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BrowserStackConfig } from "../../lib/types.js";
+import { Credentials } from "./egress.js";
+import type { AgentStreamTransport, DecisionTransport } from "./stream.js";
+import { RelayMode } from "./types.js";
+export interface AskDeps {
+    /** Resolved per call: a deployment's host is configuration, not a constructor argument. */
+    agentUrl: () => string;
+    /**
+     * Sign in and return a bearer for `POST /agent`. Cached behind this, not minted per call.
+     *
+     * A function rather than a value because it is resolved per call for the same reason the
+     * host is, and because it can fail in ways a caller needs told apart.
+     */
+    mintToken: () => Promise<string>;
+    /**
+     * Read per call, not captured: the remote server rebuilds config per session, so a
+     * captured credential would outlive the session it belongs to.
+     *
+     * These are now THE AUTH CREDENTIAL, not merely attribution: the access key is exchanged
+     * for a user-attested central JWT, which is what lets Atlas run the approved product call
+     * as the human rather than as a shared service account.
+     */
+    credentialsFor: () => Credentials;
+    /**
+     * The two transport seams, injectable so a test can drive a whole approval round trip
+     * — ask, elicit, decide, result — without a socket.
+     */
+    streamTransport?: AgentStreamTransport;
+    decisionTransport?: DecisionTransport;
+}
+export declare function relayMode(server: McpServer): RelayMode;
+export declare function addAskBrowserstackAITool(server: McpServer, deps: AskDeps, config?: BrowserStackConfig): Record<string, RegisteredTool>;
+/** The tool-adder the server factory calls. */
+export declare function addAskBrowserstackAIToolFromConfig(server: McpServer, config: BrowserStackConfig): Record<string, RegisteredTool>;
+export default addAskBrowserstackAIToolFromConfig;

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

@@ -0,0 +1,394 @@
+/**
+ * `askBrowserstackAI` — one tool call in, one tool result out, with a human's approval
+ * relayed through the middle of it.
+ *
+ * The shape, and why:
+ *
+ *   1. NEGOTIATE FIRST. `relayMode()` is consulted BEFORE Atlas is called, so Atlas learns
+ *      whether a human is reachable before it starts rather than discovering it at the gate.
+ *      Anything other than "offered" means `permission_relay` is omitted entirely and Atlas
+ *      runs read-only — today's exact behaviour, and the path opencode and goose stay on.
+ *      That also covers the hosted `REMOTE_MCP` deployment, where the relay cannot work at
+ *      all; see `relayMode` for why. Nothing here depends on `sampling`, which Claude Code
+ *      does not declare.
+ *   2. LISTEN ON LOOPBACK. Transport is A2, so Atlas calls US back; because it initiates,
+ *      the decision returns on the same connection to the same pod and PLAN.md's affinity
+ *      problem never arises for this stdio deployment.
+ *   3. ELICIT, ONCE. Atlas's `description` is the message, nothing is requested in the form,
+ *      and the ACTION is mapped by CONTRACT §7 with no second chances.
+ *   4. RETURN THE TRAIL. `approvals` and `applied_before_stop` are what let a caller tell
+ *      "nothing happened" from "some steps applied, then stopped".
+ *
+ * FAIL CLOSED THROUGHOUT. A decline, a cancel, a timeout, a bad token, a body we cannot
+ * parse, a handler that throws — every one of them denies. An unattended run cannot approve
+ * itself because a headless client returns `cancel`, which is a deny.
+ */
+import { ErrorCode, McpError, } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import appConfig from "../../config.js";
+import { trackMCP } from "../../lib/instrumentation.js";
+import logger from "../../logger.js";
+import { AskError, ELICITATION_TIMEOUT_MS, agentUrl, allowRemoteRelay, authTokenUrl, isEnabled, } from "./config.js";
+import { fetchTokenTransport, mintCentralToken } from "./central-oauth.js";
+import { agentHeaders } from "./egress.js";
+import { EVENT_PERMISSION, EVENT_RESULT, EVENT_RUN, decisionUrl, fetchAgentStreamTransport, fetchDecisionTransport, parseAsk, } from "./stream.js";
+import { buildResult, decide, elicitationMessage, elicitationShape, errorResult, } from "./relay.js";
+import { PRODUCTS, } from "./types.js";
+/**
+ * THE FALLBACK POSITIONING IN THE FIRST SENTENCE IS LOAD-BEARING.
+ *
+ * This server registers 45 tools, most of them hand-written for one endpoint each. Those are
+ * faster, cheaper and more predictable than handing a task to an agent that has to work out
+ * its own API calls, so they should win whenever one of them actually fits. What this tool
+ * covers is the gap: a task nothing here has a tool for, or one where the specific tools were
+ * tried and did not get there.
+ *
+ * A description is the ONLY thing steering that choice — the client picks a tool from these
+ * words alone, before any call is made — so the ordering is deliberate: when to reach for it
+ * first, what it does second, and the consent behaviour last.
+ */
+const DESCRIPTION = "Use this when no other BrowserStack tool here fits the task, or when the ones you tried " +
+    "did not get you there. Prefer a specific tool whenever one fits: it is faster and more " +
+    "predictable than handing the job to an agent. " +
+    "Otherwise, describe what you want in plain language and BrowserStack's agent decides " +
+    "which calls to make, then returns its answer plus the steps it took. Anything that would " +
+    "change data pauses and asks you to confirm it first, in your own client; deletes are " +
+    "refused outright. If your client cannot show you a prompt, the run is read-only and " +
+    "everything it wanted to change comes back in `needs_approval` instead. One task per call.";
+/**
+ * `isError` marks a call that FAILED, not one that was refused.
+ *
+ * A `blocked` run is the feature working: the agent asked, a human said no, and the trail
+ * says so. Flagging that as a tool error makes a client render a correct refusal in red and
+ * — worse — invites it to retry, which is exactly the "retry forever" loop the distinct
+ * `permission_relay` reasons exist to prevent. `ok` still means `status === "ok"`.
+ */
+function toResult(payload) {
+    const failed = payload.status === "error" || payload.status === "rate_limited";
+    return {
+        content: [{ type: "text", text: JSON.stringify(payload) }],
+        ...(failed ? { isError: true } : {}),
+    };
+}
+function isTimeout(error) {
+    return error instanceof McpError && error.code === ErrorCode.RequestTimeout;
+}
+/**
+ * Relay one ask to the human and record what they said.
+ *
+ * The elicitation is NEVER retried. A client that timed out or errored has told us it
+ * cannot get an answer, and asking again only produces a second prompt for the same action.
+ */
+async function relayOneAsk(server, ask, approvals, relatedRequestId) {
+    let answer;
+    try {
+        // `relatedRequestId` IS LOAD-BEARING OVER HTTP, and its absence fails silently.
+        // Streamable HTTP routes a server->client message onto the stream of the request it
+        // relates to (`_requestToStreamMapping`). With no id the SDK falls back to the
+        // standalone SSE stream, and a host that answers GET /mcp with 405 has none — so the
+        // SDK drops the message with "Stream is disconnected", the tool waits out its 270s,
+        // and Atlas's gate expires into `reason: "timeout"`. The human is told they did not
+        // answer a question they were never shown.
+        //
+        // Measured exactly that way against the hosted server before this was threaded
+        // through. On stdio it is irrelevant — one pipe, nothing to route — which is why no
+        // local test could have caught it.
+        answer = await server.server.elicitInput({
+            mode: "form",
+            // Framed with the PRODUCT and nothing else (v1.1 §G): a bare sentence with no
+            // attribution is a worse prompt than a framed one, and `product` is all the
+            // ask carries — the route, method, path and op_key never reach this side by design,
+            // and that is the whole privacy boundary (the ask is four named fields). The
+            // description goes through VERBATIM: paraphrasing it would mean the human approves
+            // something other than what the model actually said. Atlas no longer rewrites it
+            // either — it used to replace a route-shaped one with a placeholder, which asked a
+            // person to approve a sentence they could not read; CONTRACT v2 §3 was amended and
+            // that guard removed. An older Atlas can still send the placeholder, which is why
+            // the framing is tested against it.
+            message: elicitationMessage(ask.product, ask.description),
+            requestedSchema: {
+                // NOTHING IS REQUESTED. The action IS the answer: `accept` already means the human
+                // approved, and `decline` already gives them an unambiguous refusal in the same
+                // dialog. A `confirm` boolean used to live here and produced a FALSE DENIAL — a
+                // user approved on preprod and was told they had refused, because a client renders
+                // a form field and submits its unset value. We cannot distinguish that from a
+                // deliberate untick, so the field is gone rather than guessed at.
+                //
+                // Fail-closed is untouched by this and never rested on the boolean: a headless
+                // client with nobody at the terminal returns `cancel` (measured, HANDOFF.md), and
+                // `cancel` is a deny. That is what stops an unattended run self-approving.
+                type: "object",
+                properties: {},
+            },
+        }, 
+        // The inner rung of CONTRACT §4's ladder, strictly shorter than Atlas's 300s gate.
+        { timeout: ELICITATION_TIMEOUT_MS, relatedRequestId });
+    }
+    catch (error) {
+        if (isTimeout(error)) {
+            approvals.push({
+                description: ask.description,
+                decision: "deny",
+                reason: "timeout",
+            });
+            return { perm_id: ask.perm_id, decision: "deny", reason: "timeout" };
+        }
+        // An unexpected failure has no honest `reason` in CONTRACT §2's vocabulary, so it is
+        // not given one on the wire: the throw says "this side broke" without claiming a human
+        // decided anything. `runStreamed` catches it and sends the explicit deny the throw
+        // implies — see the comment there for why A1 cannot let it escape.
+        approvals.push({
+            description: ask.description,
+            decision: "deny",
+            reason: "error",
+        });
+        throw error;
+    }
+    // The SHAPE of the answer only — a fixed action enum and a boolean, never the description
+    // or anything a user typed. Logged so that what a client actually submits can be read next
+    // time rather than inferred from a compiled binary.
+    logger.info("askBrowserstackAI: elicitation answered %s", elicitationShape(answer));
+    const { decision, reason } = decide(answer);
+    approvals.push({ description: ask.description, decision, reason });
+    return { perm_id: ask.perm_id, decision, reason };
+}
+/**
+ * Decide whether to offer the approval channel at all.
+ *
+ * STDIO ALWAYS. HOSTED ONLY WHEN ITS OPERATOR OPTS IN — and the reason is a property of
+ * the HOST, not of this tool.
+ *
+ * Elicitation is a SERVER-INITIATED message whose answer arrives on a SEPARATE POST. A
+ * stateless host builds a fresh `McpServer` per POST, so that answer reaches an instance
+ * which never asked anything, while the one actually suspended on `await` waits out its
+ * timeout. Nothing in this package can fix that; what it holds is a live Promise resolver
+ * and a paused function in the host's heap, and a paused call cannot be moved.
+ *
+ * This is why `841c6358` was right to remove sessions from the hosted server on the
+ * grounds that "we use neither server-initiated messages nor subscriptions/sampling" —
+ * this feature is the exception that commit did not have to consider.
+ *
+ * MEASURED, not assumed: with the host keeping one server per session
+ * (browserstack/remote-mcp-server#96), a tool call and its elicitation answer were served
+ * by the same instance over hosted Streamable HTTP, and the relay completed. So the
+ * refusal below is now conditional rather than absolute.
+ *
+ * It stays OFF by default because it depends on a deployment property this package cannot
+ * observe. A hosted operator turns it on only once their host keeps sessions AND pins a
+ * session to a pod — sessions are per-process, so without affinity the answer POST can
+ * land on a replica that has never seen it. That failure is intermittent and reads like a
+ * client bug, which is exactly why it must not be the default.
+ *
+ * When refused, Atlas runs read-only — a supported path that already works — and
+ * `permission_relay.reason` says `remote_mode` so nobody mistakes it for a human's no.
+ */
+/**
+ * CONTRACT v2 (A1) — drive one run over the stream.
+ *
+ * The loop is the whole orchestration: read events, elicit on each `permission`, POST
+ * the decision, hand the `result` to `buildResult`. It decides nothing itself —
+ * `relayOneAsk` owns the elicitation and the allow/deny mapping, unchanged from the
+ * transport it replaced. That is deliberate: the transport changed, the judgement did
+ * not, and the judgement is the part that is dangerous to get wrong.
+ *
+ * Reading pauses while a human is being prompted, which is correct rather than merely
+ * tolerable: Atlas is blocked on that decision and will emit nothing but heartbeats
+ * until it arrives, and heartbeats are dropped by the parser.
+ *
+ * A run that ends with no `result` is an error, not an empty success. A stream that
+ * simply stops is indistinguishable from a network drop, and reporting it as a finished
+ * run with no answer would be the transport quietly speaking for the agent.
+ */
+async function runStreamed(server, streamTransport, decisionTransport, url, headers, body, approvals, mode, product, relatedRequestId) {
+    let runId = "";
+    let result;
+    let sawResult = false;
+    // 200 unless the reply was not a stream at all, in which case the transport carries
+    // the real status — `relay.ts` needs it to tell 401 from 403 from a plain failure.
+    let resultStatus = 200;
+    for await (const event of streamTransport(url, headers, body)) {
+        if (event.event === EVENT_RUN) {
+            runId = String(event.data?.run_id || "");
+            continue;
+        }
+        if (event.event === EVENT_RESULT) {
+            result = event.data;
+            sawResult = true;
+            if (typeof event.status === "number")
+                resultStatus = event.status;
+            continue;
+        }
+        if (event.event !== EVENT_PERMISSION)
+            continue;
+        // Validated, not cast: a frame missing a usable `perm_id` or carrying a blank
+        // description cannot produce an answerable prompt, so it must not produce a prompt.
+        const ask = parseAsk(event.data);
+        if (!ask) {
+            logger.error("askBrowserstackAI: unusable permission ask on the stream; ignoring");
+            continue;
+        }
+        if (!runId) {
+            // Atlas emits `run` before any ask precisely so this cannot happen. If it does,
+            // there is nowhere to send a decision — so do not prompt a human for an answer
+            // that could never be delivered.
+            logger.error("askBrowserstackAI: permission ask arrived before run_id; cannot answer");
+            continue;
+        }
+        // `relayOneAsk` RETHROWS on an unexpected elicitation failure. Under A2 that was
+        // load-bearing: the throw made the inbound callback answer 500, which Atlas's
+        // fail-closed rule read as a deny. Under A1 there is no inbound request to fail, so
+        // letting it escape would abandon the run and leave Atlas waiting out its full 300s
+        // gate — turning a client hiccup into a five-minute stall. So it is caught here and
+        // converted into the explicit deny the throw used to imply. `relayOneAsk` has
+        // already recorded the approvals entry, so only the wire decision is missing.
+        let decision;
+        try {
+            decision = await relayOneAsk(server, ask, approvals, relatedRequestId);
+        }
+        catch (error) {
+            logger.warn("askBrowserstackAI: elicitation failed, denying explicitly: %s", error instanceof Error ? error.message : String(error));
+            decision = { perm_id: ask.perm_id, decision: "deny", reason: "error" };
+        }
+        const status = await decisionTransport(decisionUrl(url, runId), headers, {
+            perm_id: decision.perm_id,
+            decision: decision.decision,
+            reason: decision.reason || "",
+        });
+        if (status !== 204) {
+            // Never fatal, and never re-sent. Atlas's gate is still waiting and denies on its
+            // own expiry, so a lost decision is safe — it can only cost an approval, never
+            // grant one. Retrying risks the opposite: a duplicate that 409s, or worse, an
+            // approval applied to a step the run has already moved past.
+            logger.warn("askBrowserstackAI: decision for %s was not accepted (HTTP %s)", decision.perm_id, status);
+        }
+    }
+    if (!sawResult) {
+        return errorResult("BrowserStack AI ended the run without a result. Nothing was changed " +
+            "beyond any step you already approved.", approvals);
+    }
+    // Shaped as an `AgentResponse` so `buildResult` — written for the transport A1 replaced
+    // and unchanged — sees exactly what it always saw.
+    return buildResult({ status: resultStatus, body: result }, approvals, mode, product);
+}
+export function relayMode(server) {
+    // The hosted deployment refuses UNLESS its operator has opted in, because whether an
+    // elicitation can be answered there depends on the host keeping one server alive per
+    // session — see `allowRemoteRelay`. Verified working against the hosted Streamable
+    // HTTP server once it does (browserstack/remote-mcp-server#96).
+    if (appConfig.REMOTE_MCP && !allowRemoteRelay())
+        return "remote_mode";
+    // The real gate either way: can THIS client be asked? A client that never declared
+    // `elicitation` gets a read-only run whatever the deployment.
+    return server.server.getClientCapabilities()?.elicitation
+        ? "offered"
+        : "no_human";
+}
+export function addAskBrowserstackAITool(server, deps, config) {
+    // A1 (CONTRACT v2) is the only path; A2 is gone. No version flag is needed to talk to
+    // an Atlas that predates the stream: such a server answers `POST /agent` with ordinary
+    // JSON, the parser sees no `text/event-stream`, and the run degrades to a read-only
+    // answer carrying that response's own status.
+    const streamTransport = deps.streamTransport || fetchAgentStreamTransport();
+    const decisionTransport = deps.decisionTransport || fetchDecisionTransport();
+    const tools = {};
+    /** Instrumentation in the house style, and never fatal to the call it wraps. */
+    const track = (name) => {
+        try {
+            trackMCP(name, server.server.getClientVersion(), undefined, config);
+        }
+        catch {
+            // Telemetry must not decide whether a tool call succeeds.
+        }
+    };
+    tools.askBrowserstackAI = server.tool("askBrowserstackAI", DESCRIPTION, {
+        product: z
+            .enum(PRODUCTS)
+            .describe("Which product to work in: tm (Test Management), a11y (Accessibility), " +
+            "tra (Test Reporting & Analytics)."),
+        query: z
+            .string()
+            .describe("What you want, in plain language. One thing per call."),
+    }, {
+        // It can write now, which is the whole point of the relay. Destructive operations
+        // stay refused, so `destructiveHint` is false for the same reason invokeEndpoint
+        // sets it false: consent is not a licence to delete.
+        readOnlyHint: false,
+        destructiveHint: false,
+        title: "Ask BrowserStack AI",
+    }, async ({ product, query }, extra) => {
+        track("askBrowserstackAI");
+        const approvals = [];
+        // Negotiated before anything else so the failure paths below report the mode they
+        // would have run in.
+        const mode = relayMode(server);
+        try {
+            const url = deps.agentUrl();
+            // Signed in BEFORE the listener is opened and before the run starts. Minting
+            // lazily mid-call would put a token round-trip inside the window where a human is
+            // being prompted, and a mint that failed there would strand an open port.
+            const headers = agentHeaders(await deps.mintToken());
+            const body = { task: query, product };
+            // Attribution, and now belt-and-braces rather than the source of truth: the minted
+            // JWT is user-attested, so Atlas sets `principal_verified=True` and takes the acting
+            // user from signed claims instead of this field. It is still sent because it is part
+            // of the frozen wire format (CONTRACT v1.2 §3) and dropping it would be a one-sided
+            // change — but nothing should trust it, and Atlas no longer does.
+            // Omitted ENTIRELY when unset, never sent as "".
+            const username = (deps.credentialsFor().username || "").trim();
+            if (username)
+                body.user_id = username;
+            // A1: asking for a stream costs nothing to set up — no port, no listener, no
+            // per-run bearer, because nothing dials in. Which is the whole point: the
+            // callback this replaces could never reach a laptop behind NAT, so the feature
+            // was read-only for every real user regardless of what was configured.
+            if (mode === "offered") {
+                body.permission_relay = { mode: "stream" };
+            }
+            else {
+                // Omitted ENTIRELY, not sent empty: its absence is what selects Atlas's
+                // read-only HeadlessGate.
+                logger.info("askBrowserstackAI: no permission relay (%s); running read-only", mode);
+            }
+            // `product` reaches the result so an entitlement refusal can name it: the flags
+            // are per product, and a bare "not enabled" sends the user to their admin
+            // asking about the wrong thing.
+            return toResult(await runStreamed(server, streamTransport, decisionTransport, url, headers, body, approvals, mode, product, 
+            // The tool call's own id, so each elicitation is routed onto THIS request's
+            // stream. Over Streamable HTTP there is nowhere else for it to go.
+            extra?.requestId));
+        }
+        catch (error) {
+            const message = error instanceof AskError || error instanceof Error
+                ? error.message
+                : String(error);
+            logger.error("askBrowserstackAI failed: %s", message);
+            // No `canElicit` argument: the request never left this process, so whether the
+            // client could have been prompted is not what the reader needs to know.
+            return toResult(errorResult(message, approvals));
+        }
+        // No teardown: A1 opens no port and binds nothing, so there is nothing that can
+        // leak across calls or survive an error. The stream is closed by its own
+        // iteration ending, and Atlas drops the run when the response completes.
+    });
+    return tools;
+}
+/** The tool-adder the server factory calls. */
+export function addAskBrowserstackAIToolFromConfig(server, config) {
+    if (!isEnabled()) {
+        logger.info("askBrowserstackAI disabled by ASK_BROWSERSTACK_DISABLED");
+        return {};
+    }
+    const credentials = () => ({
+        username: config["browserstack-username"],
+        accessKey: config["browserstack-access-key"],
+    });
+    const tokenTransport = fetchTokenTransport();
+    return addAskBrowserstackAITool(server, {
+        // Both resolved per call. An unconfigured host surfaces as a named error from the
+        // tool rather than as a missing tool, so the cause is visible to whoever hits it.
+        agentUrl,
+        mintToken: () => mintCentralToken(authTokenUrl(), credentials(), tokenTransport),
+        credentialsFor: credentials,
+    }, config);
+}
+export default addAskBrowserstackAIToolFromConfig;