@browserstack/mcp-server 1.5.1 → 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/instrumentation.d.ts

@@ -3,12 +3,25 @@ export type ClientInfo = {
     version?: string;
 };
 export type ToolOutcome = "ok" | "error_result" | "threw";
+/**
+ * Extra fields a caller may attach to its own row (the capability registry records what
+ * it invoked and how the product answered). Values are scalars so every field stays one
+ * queryable column.
+ *
+ * SOME OF IT IS FREE TEXT, and this comment used to claim the opposite. The registry
+ * records `search_query` and `change_summary`, both written by the agent from what the
+ * user asked for, and both leave the machine on every search and every write. They go
+ * through `capability-registry/redact.ts` first, which strips PII it can identify by
+ * SHAPE and caps the length — it cannot strip a person's name, and says so. Anything
+ * added here that carries user text must go through the same filter.
+ */
+export type MCPEventExtras = Record<string, string | number | boolean | undefined>;
 /**
  * Inside `withToolCall` this only records into the call's context; the single row is
  * written when the handler settles. Outside one (`started` heartbeat, unwrapped host
  * tools) it posts a row immediately, as before.
  */
-export declare function trackMCP(toolName: string, clientInfo: ClientInfo, error?: unknown, config?: any): void;
+export declare function trackMCP(toolName: string, clientInfo: ClientInfo, error?: unknown, config?: any, extras?: MCPEventExtras): void;
 /**
  * Runs a tool handler and writes one MCPInstrumentation row when it settles: success,
  * duration_ms, outcome (ok / error_result / threw), error fields on failure.

package/dist/lib/instrumentation.js

@@ -47,7 +47,7 @@ const callContext = new AsyncLocalStorage();
  * written when the handler settles. Outside one (`started` heartbeat, unwrapped host
  * tools) it posts a row immediately, as before.
  */
-export function trackMCP(toolName, clientInfo, error, config) {
+export function trackMCP(toolName, clientInfo, error, config, extras) {
     const ctx = callContext.getStore();
     if (ctx) {
         if (clientInfo?.name && !ctx.clientInfo?.name)
@@ -56,6 +56,9 @@ export function trackMCP(toolName, clientInfo, error, config) {
             ctx.config = config;
         if (error)
             ctx.error = error;
+        // Later calls win, so a handler can record an identity first and the outcome after.
+        if (extras)
+            ctx.extras = { ...ctx.extras, ...extras };
         return;
     }
     if (clientInfo?.name) {
@@ -70,6 +73,9 @@ export function trackMCP(toolName, clientInfo, error, config) {
             ...baseProperties(toolName, clientInfo),
             success: !error,
             ...(error ? errorProperties(error) : {}),
+            // Undefined entries are dropped by JSON.stringify, so an absent extra is an
+            // absent column rather than a null one.
+            ...(extras ?? {}),
         },
     };
     sendEvent(event, config);
@@ -117,6 +123,7 @@ export async function withToolCall(toolName, getClientInfo, config, fn) {
                     duration_ms: Math.max(0, Math.round(performance.now() - startedAt)),
                     outcome,
                     ...(ctx.error !== undefined ? errorProperties(ctx.error) : {}),
+                    ...(ctx.extras ?? {}),
                 },
             };
             sendEvent(event, ctx.config ?? 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/server-factory.js

@@ -17,6 +17,7 @@ import addBuildInsightsTools from "./tools/build-insights.js";
 import { setupOnInitialized } from "./oninitialized.js";
 import addRCATools from "./tools/rca-agent.js";
 import addAskBrowserStackAITool from "./tools/ask-browserstack/register.js";
+import addCapabilityRegistryTools from "./tools/capability-registry/register.js";
 import { instrumentToolLatency } from "./lib/tool-latency.js";
 import { nodeUpgradeNotice } from "./lib/node-version-notice.js";
 /**
@@ -58,6 +59,10 @@ export class BrowserStackMcpServer {
             // permission asks back to this client, so a write can be confirmed by the human
             // sitting in front of it rather than refused for want of anyone to ask.
             addAskBrowserStackAITool,
+            // Driven by a prebuilt index rather than hand-written per endpoint. Registers
+            // nothing (and logs why) when the artifact is absent, so a packaging problem cannot
+            // take the other products' tools down with it.
+            addCapabilityRegistryTools,
         ];
         toolAdders.forEach((adder) => {
             // Each adder now returns a Record<string, Tool>

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