@browserstack/mcp-server 2.0.0 → 2.1.0

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

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

@@ -0,0 +1,242 @@
+/**
+ * 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 logger from "../../logger.js";
+import { RELAY_CONTRACT, decisionUrl, parseAsk, } from "./stream.js";
+import { RELAY_OFF_DETAILS, buildResult } from "./relay.js";
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+/**
+ * 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 function parkedResult(body, product) {
+    const payload = asRecord(body);
+    if (payload.status !== "needs_approval")
+        return null;
+    const runId = String(payload.run_id || "");
+    const asks = Array.isArray(payload.asks) ? payload.asks : [];
+    // Validated, not cast, for the same reason the streaming path validates: an ask with
+    // no usable `perm_id` cannot be answered, so handing it to a caller would invite a
+    // second call that can only 404.
+    const ask = asks.length ? parseAsk(asks[0]) : null;
+    if (!runId || !ask) {
+        logger.error("askBrowserStackAI: deferred run parked without an answerable ask; treating as a plain result");
+        return null;
+    }
+    return {
+        runId,
+        ask: {
+            perm_id: ask.perm_id,
+            description: ask.description,
+            product: ask.product || product,
+            mode: ask.mode,
+        },
+    };
+}
+/** CONTRACT §5's shape, for a run that is parked rather than finished. */
+export function needsApprovalResult(runId, ask, product) {
+    return {
+        // NOT ok, and not an error either: nothing was applied and nothing failed. A caller
+        // that branches on `ok` alone must not read a parked run as a finished one.
+        ok: false,
+        status: "needs_approval",
+        // Addressed to the MODEL, and imperative, because the model is what reads it and
+        // the one thing that must happen next is not something it can do by itself.
+        answer: `A HUMAN MUST APPROVE THIS BEFORE IT CAN CONTINUE. BrowserStack AI stopped at: ` +
+            `${ask.description}. Nothing has been changed yet.\n\n` +
+            `Put this to the user and WAIT for their answer. If you have a way to ask them a ` +
+            `structured question or show a confirmation — any prompt, question or approval ` +
+            `affordance your client offers — use that; otherwise ask plainly in your reply. ` +
+            `Quote what is being done either way.\n\n` +
+            `Do NOT decide on their behalf, and do not treat "it is what they asked for" as ` +
+            `approval: they are being asked to confirm this specific change, which is a ` +
+            `different question. Once they have answered, follow \`next_step\`.`,
+        approvals: [],
+        approvals_source: "atlas",
+        elicitations: [],
+        needs_approval: [{ description: ask.description, mode: ask.mode }],
+        applied_before_stop: false,
+        permission_relay: {
+            used: true,
+            reason: "",
+            // Terse on purpose: the actionable half lives in `next_step`, and an explanation
+            // of the transport here is what the model read instead of the instruction.
+            detail: "Approval is pending a human answer; see `next_step`.",
+        },
+        atlas_response: null,
+        run_id: runId,
+        perm_id: ask.perm_id,
+        next_step: {
+            instruction: 
+            // Deliberately names no tool and no client. The affordance differs everywhere
+            // — a structured question, a confirmation dialog, an approval prompt, or
+            // nothing at all — and naming one would be wrong on every other client and
+            // would rot as clients change. Describe the ACT, let the model pick the means.
+            "AFTER the user has answered — not before — call askBrowserStackAI again " +
+                "with exactly these params, setting `decision` to what THEY said. If they " +
+                'declined, send "deny": that is a valid answer and stops the task cleanly. ' +
+                "If they have not answered yet, do not call anything.",
+            call: "askBrowserStackAI",
+            params: {
+                product,
+                run_id: runId,
+                perm_id: ask.perm_id,
+                decision: "allow | deny — the user's answer, not your own judgement",
+            },
+        },
+    };
+}
+/** The FIRST call: run until the first ask, then answer. Nothing is held open. */
+export async function runDeferred(url, headers, body, transport, mode, product) {
+    const response = await transport(url, headers, {
+        ...body,
+        permission_relay: { mode: "deferred", contract: RELAY_CONTRACT },
+    });
+    const parked = parkedResult(response.body, product);
+    if (parked) {
+        logger.info("askBrowserStackAI: run parked awaiting approval (run=%s)", parked.runId);
+        return needsApprovalResult(parked.runId, parked.ask, product);
+    }
+    // No ask: an ordinary result, passed through the same builder the streaming path
+    // uses so an entitlement refusal, a 401 and a plain failure all read identically
+    // whichever transport produced them.
+    return buildResult(response, [], mode, product);
+}
+/**
+ * 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 async function runResumed(agentUrl, headers, runId, permId, decision, transport, mode, product) {
+    // ONE CALL. This used to POST the decision, check for a 204, and then reattach to
+    // `GET /agent/{run_id}/stream` to collect what the run did next — two requests, and a
+    // reattach that only existed because the run was a paused coroutine in one pod. The
+    // ask parks in Atlas's checkpoint now, so the decision request IS the one that carries
+    // the run forward and the continuation comes back in its own reply, from any replica.
+    let response;
+    try {
+        response = await transport(decisionUrl(agentUrl, runId), headers, {
+            perm_id: permId,
+            decision,
+            reason: "",
+            // Required. The run resumes on a fresh Agent that must be scoped before it can be
+            // built, and Atlas deliberately will not take that scope from persisted state.
+            product,
+        });
+    }
+    catch {
+        // CAUGHT HERE rather than left to the handler's outer catch, which cannot tell this
+        // apart from a request that never left and so reports `not_reached` — "nothing was
+        // changed" — for a decision that may well have completed.
+        logger.warn("askBrowserStackAI: no reply to the decision on run %s; outcome unknown", runId);
+        return decisionUnknown();
+    }
+    if (response.status === 404) {
+        // The only failure worth its own words: there is no such parked run. It expired, it
+        // was already answered, or this is not the caller that owns it. None of those is an
+        // approval, and none of them changed anything.
+        return resumeFailed(`That approval could not be applied (HTTP 404). The run may have expired — ` +
+            `BrowserStack AI stops waiting after five minutes — or it may already have ` +
+            `been answered. Nothing was changed by this call. Start the task again if it ` +
+            `still needs doing.`);
+    }
+    // PARKED AGAIN: the task needs more than one approval. Handed straight back rather
+    // than answered here, because the whole point is that a human decides each one.
+    const parked = parkedResult(response.body, product);
+    if (parked) {
+        logger.info("askBrowserStackAI: run parked again after a decision (run=%s)", runId);
+        return needsApprovalResult(parked.runId, parked.ask, product);
+    }
+    // Finished. Through the SAME builder the start path uses, so an entitlement refusal,
+    // a 401 and a plain failure read identically whichever call produced them.
+    return buildResult(response, [], mode, product);
+}
+/** 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 function resumeFailed(error) {
+    return {
+        ok: false,
+        status: "error",
+        answer: null,
+        approvals: [],
+        approvals_source: "mcp",
+        elicitations: [],
+        needs_approval: [],
+        applied_before_stop: false,
+        permission_relay: { used: true, reason: "", detail: "" },
+        atlas_response: null,
+        error,
+    };
+}
+/** 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 function decisionUnknown() {
+    return {
+        ok: false,
+        status: "error",
+        answer: null,
+        approvals: [],
+        approvals_source: "mcp",
+        elicitations: [],
+        needs_approval: [],
+        applied_before_stop: null,
+        permission_relay: {
+            used: true,
+            reason: "outcome_unknown",
+            detail: RELAY_OFF_DETAILS.outcome_unknown,
+        },
+        atlas_response: null,
+        error: "The approval was sent to BrowserStack AI but no reply came back, so it is not " +
+            "known whether the step completed. Nothing should be retried on this run.",
+    };
+}
+/** 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 function missingQuery() {
+    return resumeFailed("`query` is required to start a run: say what you want in plain language. " +
+        "(It is only omitted when answering a pending approval, which also needs " +
+        "`run_id`, `perm_id` and `decision`.) Nothing was sent, so nothing changed.");
+}
+export function incompleteResume() {
+    return resumeFailed("Resuming needs all three of `run_id`, `perm_id` and `decision`. Nothing was " +
+        "sent, so nothing changed and the pending approval is still waiting — ask the " +
+        "user whether to allow it and call again with all three.");
+}

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

@@ -26,7 +26,7 @@
 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 type { AgentStreamTransport, DeferredTransport } from "./stream.js";
 import { RelayMode } from "./types.js";
 export interface AskDeps {
     /** Resolved per call: a deployment's host is configuration, not a constructor argument. */
@@ -52,7 +52,8 @@ export interface AskDeps {
      * — ask, elicit, decide, result — without a socket.
      */
     streamTransport?: AgentStreamTransport;
-    decisionTransport?: DecisionTransport;
+    /** The deferred START (one request, one JSON response). Substituted in tests. */
+    deferredTransport?: DeferredTransport;
 }
 export declare function relayMode(server: McpServer): RelayMode;
 export declare function addAskBrowserStackAITool(server: McpServer, deps: AskDeps, config?: BrowserStackConfig): Record<string, RegisteredTool>;

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

@@ -28,10 +28,11 @@ 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 { AskError, ELICITATION_TIMEOUT_MS, agentUrl, 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 { EVENT_PERMISSION, EVENT_RESULT, EVENT_RUN, decisionUrl, RELAY_CONTRACT, fetchAgentStreamTransport, fetchDeferredTransport, parseAsk, } from "./stream.js";
+import { decisionUnknown, incompleteResume, missingQuery, parkedResult, resumeFailed, runDeferred, runResumed, } from "./deferred.js";
 import { buildResult, decide, elicitationMessage, elicitationShape, errorResult, } from "./relay.js";
 import { PRODUCTS, } from "./types.js";
 /**
@@ -61,9 +62,10 @@ const DESCRIPTION =
     "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.";
+    "change data pauses and asks you to confirm it first; deletes are refused outright. " +
+    "Put that confirmation to the user and answer with what THEY say — never decide on " +
+    "their behalf. If it cannot be put to anyone, 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.
  *
@@ -161,36 +163,6 @@ async function relayOneAsk(server, ask, approvals, relatedRequestId) {
     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.
  *
@@ -208,13 +180,90 @@ async function relayOneAsk(server, ask, approvals, relatedRequestId) {
  * 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) {
+async function runStreamed(server, streamTransport, postTransport, 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;
+    let pending = null;
+    // Set once a decision reply carries the run, which only a converged Atlas does. When
+    // it is set it is the authoritative outcome and the stream's own `result` is stale.
+    let carried = null;
+    /**
+     * Put ONE ask to the human and deliver their answer. Shared by both loops so the two
+     * servers cannot drift apart in how an approval is asked for or recorded.
+     *
+     * Returns exactly one of:
+     *   `terminal` — stop, with this result (a lost reply, or a run that is not there).
+     *   `carried`  — the reply contained the run: `next` is the following ask, if any.
+     *   neither    — a bare 204; this server continues on the stream.
+     */
+    const answerAsk = async (ask) => {
+        // `relayOneAsk` RETHROWS on an unexpected elicitation failure. Letting it escape
+        // would abandon the run and leave Atlas parked until its gate expires — turning a
+        // client hiccup into a five-minute stall — so it is caught 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" };
+        }
+        let response;
+        try {
+            response = await postTransport(decisionUrl(url, runId), headers, {
+                perm_id: decision.perm_id,
+                decision: decision.decision,
+                reason: decision.reason || "",
+                product,
+            });
+        }
+        catch {
+            // This request can carry the continuation, so a lost reply is NOT "nothing
+            // happened". Letting it reach the outer catch would report `not_reached` — which
+            // says nothing was changed — for a write that may well have landed.
+            logger.warn("askBrowserStackAI: no reply to the decision on run %s; outcome unknown", runId);
+            return { terminal: decisionUnknown() };
+        }
+        if (response.status === 404) {
+            // No such parked run: expired, already answered, or not ours. None of those is
+            // an approval and none of them changed anything — but a denial we could not
+            // deliver is not a denial either, so say which.
+            return {
+                terminal: resumeFailed("That approval could not be applied (HTTP 404). The run may have expired — " +
+                    "BrowserStack AI stops waiting after five minutes — or it may already " +
+                    "have been answered. Nothing was changed beyond any step you already " +
+                    "approved."),
+            };
+        }
+        // 204 MEANS AN OLDER SERVER: it acknowledged the decision and is continuing on the
+        // stream, so there is no continuation to read here and nothing to supersede.
+        if (response.status === 204)
+            return {};
+        const parked = parkedResult(response.body, product);
+        return {
+            carried: true,
+            response,
+            // Another ask: the task needs more than one approval, and each is a separate
+            // question for the human.
+            next: parked
+                ? {
+                    perm_id: parked.ask.perm_id,
+                    description: parked.ask.description,
+                    product: parked.ask.product,
+                    mode: parked.ask.mode,
+                }
+                : null,
+        };
+    };
+    // PHASE 1 — the start, streamed. Kept a stream rather than folded into the decision
+    // loop below because a long turn needs the heartbeats: a proxy that gives up
+    // mid-thinking looks exactly like a hang.
     for await (const event of streamTransport(url, headers, body)) {
         if (event.event === EVENT_RUN) {
             runId = String(event.data?.run_id || "");
@@ -243,34 +292,55 @@ async function runStreamed(server, streamTransport, decisionTransport, url, head
             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" };
+        // ANSWERED HERE, ON THE STREAM, and that placement is a compatibility decision
+        // rather than a preference.
+        //
+        // A converged Atlas emits its asks as the stream ENDS and carries the run forward
+        // on the decision request. An Atlas that predates that holds the stream OPEN
+        // waiting for the decision to arrive, and acknowledges it with a bare 204 before
+        // continuing on the same socket. Collecting asks and answering only after the
+        // stream closed worked against the first and DEADLOCKED against the second: both
+        // sides waited, until the server's own five-minute gate denied the ask and the
+        // user got a refusal nobody made.
+        //
+        // Answering as each ask arrives works against both, and the reply says which one
+        // we are talking to: a 204 carries nothing, so the run continues on the stream,
+        // while anything else IS the continuation and the stream is already over. That
+        // removes the deploy ordering constraint in both directions — this client is safe
+        // to publish before or after the server changes.
+        const answered = await answerAsk(ask);
+        if (answered.terminal)
+            return answered.terminal;
+        if (answered.carried) {
+            // The reply carried the run: a converged Atlas. Anything still on the stream is
+            // the tail of a response that has already been superseded by this one.
+            pending = answered.next ?? null;
+            carried = answered.response ?? null;
+            break;
         }
-        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);
+        // A bare 204: this server continues on the stream, so keep reading it.
+    }
+    // PHASE 2 — only reachable against a converged Atlas, where the decision reply IS the
+    // run. Each further ask comes back in a reply rather than on the stream, so the
+    // prompt-and-post pair repeats here instead of in the loop above.
+    while (pending) {
+        const answered = await answerAsk(pending);
+        if (answered.terminal)
+            return answered.terminal;
+        if (!answered.carried) {
+            // A 204 cannot arise here: only a converged Atlas reaches phase 2, and it always
+            // replies with the continuation. Treated as a run that ended without saying
+            // anything rather than assumed away.
+            break;
         }
+        pending = answered.next ?? null;
+        carried = answered.response ?? null;
     }
+    // The decision reply supersedes the stream's own `result`, which said "needs
+    // approval" — true when it was written, and the question it asked has since been
+    // answered.
+    if (carried)
+        return buildResult(carried, approvals, mode, product);
     if (!sawResult) {
         return errorResult("BrowserStack AI ended the run without a result. Nothing was changed " +
             "beyond any step you already approved.", approvals);
@@ -280,13 +350,35 @@ async function runStreamed(server, streamTransport, decisionTransport, url, head
     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
+    // An explicit transport wins over whatever the deployment implies. `REMOTE_MCP`
+    // cannot select `deferred` from a local stdio install — that flag makes this
+    // entrypoint exit, because the hosted deployment runs remote-mcp-server instead — so
+    // without this there is no way to exercise the two-call flow anywhere it can be
+    // watched. "elicit" forces the other direction for the same reason.
+    const forced = appConfig.ASK_BROWSERSTACK_RELAY_TRANSPORT;
+    if (forced === "deferred")
+        return "deferred";
+    if (forced !== "elicit" && appConfig.REMOTE_MCP) {
+        // DEFERRED, unconditionally, and not because elicitation would be worse here — it
+        // would be better. It 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 would have to keep sessions, pin requests to a
+        // pod and cap how many can be alive. Deferred removes the suspension, and with it
+        // the reason any of that exists.
+        //
+        // THERE IS NO OPT-IN ANY MORE. `ASK_BROWSERSTACK_ALLOW_REMOTE_RELAY` gated this
+        // while relaying meant elicitation — it was a guard against switching on the
+        // stateful thing, and that thing is gone. Two better switches remain: this tool's
+        // own `ASK_BROWSERSTACK_DISABLED`, which is read per call and so does not need a
+        // pod roll, and Atlas's `delegation.permission_relay`, which turns the relay off
+        // for every client at once from a config change.
+        return "deferred";
+    }
+    // stdio keeps elicitation, deliberately: one process, nothing to pin, and the client
+    // renders the prompt so the model cannot fabricate the answer. Nothing is gained by
+    // making a local install pay the two-call cost.
+    //
+    // The real gate here: 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"
@@ -298,7 +390,9 @@ export function addAskBrowserStackAITool(server, deps, config) {
     // 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();
+    // Resolved here with the others: one place decides which transports this
+    // registration uses, so a test substituting one is not surprised by another.
+    const deferredTransport = deps.deferredTransport || fetchDeferredTransport();
     const tools = {};
     /** Instrumentation in the house style, and never fatal to the call it wraps. */
     const track = (name) => {
@@ -314,9 +408,35 @@ export function addAskBrowserStackAITool(server, deps, config) {
             .enum(PRODUCTS)
             .describe("Which product to work in: tm (Test Management), " +
             "tra (Test Reporting & Analytics)."),
+        // OPTIONAL, because a resume does not carry one. `next_step` tells the model to
+        // call again "with exactly these params" — `product`, `run_id`, `perm_id`,
+        // `decision` — and a required `query` made following that instruction literally
+        // fail schema validation before the handler ever ran. It is still required to
+        // START a run; the handler enforces that, where a useful message can be given
+        // instead of an InvalidParams from the SDK.
         query: z
             .string()
+            .optional()
             .describe("What you want, in plain language. One thing per call."),
+        // --- resuming a parked run (the hosted, deferred path only) ---
+        //
+        // Both together or neither. They exist because that deployment cannot hold a
+        // prompt open mid-run: it returns the pending approval instead, and the caller
+        // comes back. On a local stdio install these are never needed — the prompt
+        // appears inside the first call — so they are optional and unmentioned in the
+        // description's main flow.
+        run_id: z
+            .string()
+            .optional()
+            .describe("`run_id` from a needs_approval result."),
+        perm_id: z
+            .string()
+            .optional()
+            .describe("`perm_id` from that same result."),
+        decision: z
+            .enum(["allow", "deny"])
+            .optional()
+            .describe("The user's answer. Never assume allow — ask them."),
     }, {
         // 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
@@ -329,7 +449,7 @@ export function addAskBrowserStackAITool(server, deps, config) {
         openWorldHint: true,
         idempotentHint: false,
         title: "Ask BrowserStack AI (Alpha)",
-    }, async ({ product, query }, extra) => {
+    }, async ({ product, query, run_id, perm_id, decision }, extra) => {
         track("askBrowserStackAI");
         const approvals = [];
         // Negotiated before anything else so the failure paths below report the mode they
@@ -341,6 +461,27 @@ export function addAskBrowserStackAITool(server, deps, config) {
             // 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());
+            // RESUMING a parked run: no new run, no task — just the decision and the
+            // remainder. FIRST, because the arguments are mutually exclusive with starting
+            // one and a caller that sent both meant to resume — and because `query` is not
+            // required on this path, so nothing above may depend on it.
+            if (run_id) {
+                if (!perm_id || !decision) {
+                    return toResult(incompleteResume());
+                }
+                // A `query` sent here is ignored rather than rejected: the run's task is in
+                // Atlas's checkpoint, so a model that resent it is redundant, not wrong.
+                return toResult(await runResumed(url, headers, run_id, perm_id, decision, 
+                // The SAME transport the start uses: since the converged gate both calls
+                // POST and read back either a parked run or a finished one.
+                deferredTransport, mode, product));
+            }
+            // STARTING one, which is the only path that needs a task. Enforced here rather
+            // than in the schema so the model gets a sentence it can act on instead of an
+            // SDK InvalidParams — and so `next_step`, which omits `query`, stays valid.
+            if (!query || !query.trim()) {
+                return toResult(missingQuery());
+            }
             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
@@ -351,12 +492,18 @@ export function addAskBrowserStackAITool(server, deps, config) {
             const username = (deps.credentialsFor().username || "").trim();
             if (username)
                 body.user_id = username;
+            // DEFERRED: the hosted shape. One request, one JSON answer, nothing held open
+            // while a human decides — see `deferred.ts` for why that matters here and why
+            // stdio does not use it.
+            if (mode === "deferred") {
+                return toResult(await runDeferred(url, headers, body, deferredTransport, mode, product));
+            }
             // 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" };
+                body.permission_relay = { mode: "stream", contract: RELAY_CONTRACT };
             }
             else {
                 // Omitted ENTIRELY, not sent empty: its absence is what selects Atlas's
@@ -366,7 +513,7 @@ export function addAskBrowserStackAITool(server, deps, config) {
             // `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, 
+            return toResult(await runStreamed(server, streamTransport, deferredTransport, 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));

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

@@ -48,13 +48,6 @@ export const RELAY_OFF_DETAILS = {
     malformed: "BrowserStack could not use the approval channel this client offered and ran read-only. " +
         "That is a bug on this side, not something you did; everything in `needs_approval` was " +
         "refused because of it.",
-    // Neither the human nor the client is the constraint here — the DEPLOYMENT is, and no
-    // change either of them can make will help.
-    remote_mode: "NOBODY DECLINED THIS, AND YOUR CLIENT IS NOT THE PROBLEM. This BrowserStack MCP server " +
-        "is running in its hosted, multi-tenant mode, which has no way to put an approval " +
-        "prompt in front of you, so it ran read-only and everything in `needs_approval` was " +
-        "refused for that reason alone. Mid-run approval works when the server runs locally over stdio; retrying " +
-        "against this deployment will keep failing the same way.",
     // Not a refusal by anyone and not a relay problem at all: the account is not on the
     // product's agent flag. The product-specific sentence and what to do about it live in
     // `error`, so this one points there rather than duplicating the plumbing.
@@ -63,6 +56,17 @@ export const RELAY_OFF_DETAILS = {
         "refused before the agent started. `error` names the product. This is an entitlement on " +
         "the account, not a problem with your credentials and not a decision anyone made about " +
         "your request.",
+    // THE ONE CASE WHERE WE DO NOT KNOW. The decision was put on the wire and the reply
+    // never came back — a timeout, or a proxy cutting an idle connection. Since the
+    // converged gate the decision request carries the whole continuation, so "no reply"
+    // spans everything from "it never arrived" to "the write succeeded and we lost the
+    // answer". `not_reached` claims the first of those, which is exactly the claim that
+    // gets a write done twice, so this exists to stop the two being collapsed.
+    outcome_unknown: "THE ANSWER WAS DELIVERED BUT ITS OUTCOME IS UNKNOWN. The approval reached " +
+        "BrowserStack and the reply was lost before it came back, so the step may or may " +
+        "not have completed. DO NOT repeat this task — a retry could perform the same " +
+        "change a second time. Check the state in the product, and only then decide " +
+        "whether anything still needs doing.",
     // The request never got as far as the agent. Distinct from `disabled` (the agent ran, with
     // the relay switched off) and from a decline (someone was asked and said no), because the
     // three call for completely different things from whoever reads them.
@@ -413,16 +417,6 @@ function relayVerdict(payload, mode, reachedAgent, notEntitled) {
             detail: RELAY_OFF_DETAILS.not_reached,
         };
     }
-    // BEFORE `no_human`, deliberately, when both are true. In the hosted deployment even a
-    // client that CAN be prompted is of no use, so the deployment is the binding constraint and
-    // the one the reader can act on; telling them to switch clients would waste their time.
-    if (mode === "remote_mode") {
-        return {
-            used: false,
-            reason: "remote_mode",
-            detail: RELAY_OFF_DETAILS.remote_mode,
-        };
-    }
     if (mode === "no_human") {
         // CONTRACT §7's last row: no elicitation capability means the field was never sent.
         return {

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

@@ -48,6 +48,14 @@ export declare const WHOLE_RUN_TIMEOUT_MS = 1800000;
 export declare const EVENT_RUN = "run";
 export declare const EVENT_PERMISSION = "permission";
 export declare const EVENT_RESULT = "result";
+/**
+ * The wire version this client speaks, sent in `permission_relay`. See
+ * `PermissionRelay.contract` for why Atlas cannot infer it.
+ *
+ * Bump only when a change leaves an older client unable to COMPLETE the exchange —
+ * not merely unaware of a new field.
+ */
+export declare const RELAY_CONTRACT = 2;
 /** Atlas's `f"perm-{uuid.uuid4().hex}"`, and nothing else. */
 export declare const PERM_ID_PATTERN: RegExp;
 /**
@@ -75,12 +83,15 @@ export declare function parseAsk(data: unknown): PermissionAsk | null;
  * was: the tests must be able to drive a whole approval round trip without a socket.
  */
 export type AgentStreamTransport = (url: string, headers: Record<string, string>, body: AgentRequest) => AsyncIterable<StreamEvent>;
-/** Posts one decision. Separate seam because it is a separate connection. */
-export type DecisionTransport = (url: string, headers: Record<string, string>, body: {
+/** What a decision POST carries. `product` is required: the run comes back on a fresh
+ *  Agent that has to be scoped to a harness before it can be built, and scoping is the
+ *  one thing that must not be re-derived from persisted state. */
+export interface DecisionBody {
     perm_id: string;
     decision: string;
     reason: string;
-}) => Promise<number>;
+    product: string;
+}
 /**
  * Split a buffer into complete SSE frames, returning the leftover.
  *
@@ -110,7 +121,18 @@ export declare function parseFrame(frame: string): StreamEvent | null;
  * is unchanged and still enforced where it belongs.
  */
 export declare function fetchAgentStreamTransport(timeoutMs?: number): AgentStreamTransport;
-/** The decision POST. 30s, because it is an ordinary short request. */
-export declare function fetchDecisionTransport(timeoutMs?: number): DecisionTransport;
 /** `POST /agent/{run_id}/permission`, built from the base URL the tool already resolved. */
 export declare function decisionUrl(agentUrl: string, runId: string): string;
+/**
+ * One POST, one JSON response, nothing held open.
+ *
+ * Used for BOTH calls of the two-call shape — the start (`POST /agent`) and every
+ * decision (`POST /agent/{run_id}/permission`) — because since the converged gate they
+ * answer the same thing: a parked run, or a finished one. A separate seam from the
+ * streaming transport because it is a different kind of call, not a different URL.
+ */
+export type DeferredTransport = (url: string, headers: Record<string, string>, body: AgentRequest | DecisionBody) => Promise<{
+    status: number;
+    body: unknown;
+}>;
+export declare function fetchDeferredTransport(timeoutMs?: number): DeferredTransport;

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

@@ -35,6 +35,14 @@ export const WHOLE_RUN_TIMEOUT_MS = 1_800_000;
 export const EVENT_RUN = "run";
 export const EVENT_PERMISSION = "permission";
 export const EVENT_RESULT = "result";
+/**
+ * The wire version this client speaks, sent in `permission_relay`. See
+ * `PermissionRelay.contract` for why Atlas cannot infer it.
+ *
+ * Bump only when a change leaves an older client unable to COMPLETE the exchange —
+ * not merely unaware of a new field.
+ */
+export const RELAY_CONTRACT = 2;
 /** Atlas's `f"perm-{uuid.uuid4().hex}"`, and nothing else. */
 export const PERM_ID_PATTERN = /^perm-[0-9a-f]{32}$/;
 /**
@@ -206,13 +214,21 @@ export function fetchAgentStreamTransport(timeoutMs = WHOLE_RUN_TIMEOUT_MS) {
         };
     };
 }
-/** The decision POST. 30s, because it is an ordinary short request. */
-export function fetchDecisionTransport(timeoutMs = 30_000) {
+/** `POST /agent/{run_id}/permission`, built from the base URL the tool already resolved. */
+export function decisionUrl(agentUrl, runId) {
+    return `${agentUrl.replace(/\/+$/, "")}/${encodeURIComponent(runId)}/permission`;
+}
+// Bounded by the WHOLE RUN, like the streaming transport, because that is what these
+// requests now contain. 120s was sized for a request that returned as soon as the run
+// parked; since the converged gate the DECISION request carries everything after the
+// approval — the write and the rest of the task — so the old bound cut off successful
+// runs partway and reported them as unreachable.
+export function fetchDeferredTransport(timeoutMs = WHOLE_RUN_TIMEOUT_MS) {
     return async (url, headers, body) => {
         try {
-            // Through `apiClient` per rules/security.md. `raise_error: false` because the caller
-            // reads the STATUS: a 404 (run gone) and a 409 (already decided) are both answers,
-            // and a thrown AxiosError would collapse them into the unreachable case below.
+            // `raise_error: false` for the same reason the decision transport does it: the
+            // caller reads the STATUS, and a thrown AxiosError would collapse a 403
+            // (not entitled) and a 503 (delegation off) into the unreachable case below.
             const response = await apiClient.post({
                 url,
                 headers,
@@ -220,17 +236,12 @@ export function fetchDecisionTransport(timeoutMs = 30_000) {
                 timeout: timeoutMs,
                 raise_error: false,
             });
-            return response.status;
+            return { status: response.status, body: response.data };
         }
         catch {
-            // The gate on the far side is still waiting and will deny on its own expiry, so
-            // a lost decision is safe — it is never an approval. 0 says "never delivered" so
-            // the caller can say that rather than implying a human refused.
-            return 0;
+            // Same sentence as the streaming transport, and for the same reason: the upstream
+            // detail names our plumbing rather than anything the reader can act on.
+            throw new AskError("BrowserStack AI could not be reached");
         }
     };
 }
-/** `POST /agent/{run_id}/permission`, built from the base URL the tool already resolved. */
-export function decisionUrl(agentUrl, runId) {
-    return `${agentUrl.replace(/\/+$/, "")}/${encodeURIComponent(runId)}/permission`;
-}

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

@@ -57,6 +57,16 @@ export interface PermissionDecision {
  */
 export interface PermissionRelay {
     mode?: string;
+    /**
+     * The wire this client speaks. Atlas reads an absent or lower value as a build that
+     * CANNOT complete an approval and refuses to park rather than offering one.
+     *
+     * Declared, not inferred, because the two are identical on the way in: this client's
+     * stdio path sends `{"mode": "stream"}` exactly as 1.5.1 does. Measured against
+     * 1.5.1 talking to a converged Atlas — it answers a decision without `product`, gets
+     * a 400, logs it to stderr and then reports `ok: true` for a run that did nothing.
+     */
+    contract?: number;
 }
 /**
  * CONTRACT §1 — the `POST /agent` body.
@@ -122,9 +132,23 @@ export type RelayMode =
 "offered"
 /** The client declares no `elicitation` capability, so nobody could be prompted. */
  | "no_human"
-/** This process is the hosted multi-tenant server, which cannot prompt a human. */
- | "remote_mode";
-export declare const ASK_STATUSES: readonly ["ok", "blocked", "error", "rate_limited"];
+/**
+ * The hosted server, relaying WITHOUT holding anything open.
+ *
+ * Elicitation is what makes this process stateful: a suspended `elicitation/create`
+ * pins an McpServer in one pod's heap until the answer arrives, which is why the
+ * hosted deployment needs sessions, ingress affinity and a session cap. `deferred`
+ * removes the suspension instead of routing around it — Atlas returns at its first
+ * ask, this tool hands that ask back, and the caller returns with the decision in a
+ * second call. Nothing is held between the two, so any pod can serve either.
+ *
+ * The trade, stated because it is real: approval rides the CLIENT's own permission
+ * prompt on that second call rather than an elicitation, so a client configured not
+ * to prompt (`--permission-mode auto`) approves without a human. Elicitation fails
+ * closed by construction; this fails closed only if the client asks.
+ */
+ | "deferred";
+export declare const ASK_STATUSES: readonly ["ok", "blocked", "error", "rate_limited", "needs_approval"];
 export type AskStatus = (typeof ASK_STATUSES)[number];
 /** CONTRACT §5 — the single tool result. */
 export interface AskResult {
@@ -185,6 +209,33 @@ export interface AskResult {
      * side would otherwise silently become `null` here rather than reaching the caller.
      */
     atlas_response: unknown;
+    /**
+     * Deferred only: the parked run, and the ask waiting on it.
+     *
+     * Present exactly when `status === "needs_approval"`. Both are echoed back on the
+     * caller's second call — `perm_id` alongside `run_id` so the answer names WHICH ask it
+     * answers, which matters the moment a task needs more than one.
+     */
+    run_id?: string;
+    perm_id?: string;
+    /**
+     * Deferred only: what the caller must do next, and with what.
+     *
+     * Carried as its own field rather than buried in prose because the model reads this
+     * result and decides what to do from it. The first version explained the TRANSPORT
+     * ("this deployment cannot hold a prompt open…") which is true and useless: it told
+     * the model how the plumbing works, not that a person has to answer. Measured
+     * consequence — the model read the ask, judged it matched the user's request, and
+     * answered `allow` itself in the same turn without asking anyone.
+     *
+     * This cannot MAKE a model ask; nothing in the protocol can, which is the standing
+     * argument for elicitation. It removes the excuse.
+     */
+    next_step?: {
+        instruction: string;
+        call: string;
+        params: Record<string, string>;
+    };
     /**
      * Why the call failed, when it did.
      *

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

@@ -11,4 +11,14 @@
 // describe text in register.ts, and the two a11y handoffs in tool-handoff.ts — which stop
 // pointing here precisely because the call would now be rejected.
 export const PRODUCTS = ["tm", "tra"];
-export const ASK_STATUSES = ["ok", "blocked", "error", "rate_limited"];
+export const ASK_STATUSES = [
+    "ok",
+    "blocked",
+    "error",
+    "rate_limited",
+    // Deferred only: the run reached an ask and is PARKED, not finished. Distinct from
+    // `blocked` (a human said no) and from `error` (nothing is waiting) — this one is the
+    // only status a caller is invited to come back from, and the only one carrying a
+    // `run_id`.
+    "needs_approval",
+];

package/dist/tools/automate-utils/fetch-screenshots.js

@@ -2,6 +2,7 @@ import { assertOkResponse, maybeCompressBase64 } from "../../lib/utils.js";
 import { SessionType } from "../../lib/constants.js";
 import { getBrowserStackAuth } from "../../lib/get-auth.js";
 import { apiClient } from "../../lib/apiClient.js";
+import globalConfig from "../../config.js";
 async function extractScreenshotUrls(sessionId, sessionType, config) {
     const authString = getBrowserStackAuth(config);
     const auth = Buffer.from(authString).toString("base64");
@@ -36,23 +37,24 @@ async function extractScreenshotUrls(sessionId, sessionType, config) {
     }
     return urls;
 }
+async function fetchAndCompress(url) {
+    const response = await apiClient.get({ url, responseType: "arraybuffer" });
+    // Axios returns response.data as a Buffer for binary data
+    const base64 = Buffer.from(response.data).toString("base64");
+    return { url, base64: await maybeCompressBase64(base64) };
+}
 //Converts screenshot URLs to base64 encoded images
 async function convertUrlsToBase64(urls) {
-    const screenshots = await Promise.all(urls.map(async (url) => {
-        const response = await apiClient.get({
-            url,
-            responseType: "arraybuffer",
-        });
-        // Axios returns response.data as a Buffer for binary data
-        const base64 = Buffer.from(response.data).toString("base64");
-        // Compress the base64 image if needed
-        const compressedBase64 = await maybeCompressBase64(base64);
-        return {
-            url,
-            base64: compressedBase64,
-        };
-    }));
-    return screenshots;
+    // Hosted pods are memory-constrained: process one image at a time. Local runs
+    // keep the concurrent path.
+    if (globalConfig.REMOTE_MCP) {
+        const screenshots = [];
+        for (const url of urls) {
+            screenshots.push(await fetchAndCompress(url));
+        }
+        return screenshots;
+    }
+    return Promise.all(urls.map(fetchAndCompress));
 }
 //Fetches and converts screenshot URLs to base64 encoded images
 export async function fetchAutomationScreenshots(sessionId, sessionType = SessionType.Automate, config) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserstack/mcp-server",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "BrowserStack's Official MCP Server",
   "mcpName": "io.github.browserstack/mcp-server",
   "main": "dist/index.js",