@browserstack/mcp-server 1.4.0-beta.3 → 1.5.0-beta.2

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

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

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

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

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

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

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

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

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

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