@browserstack/mcp-server 1.5.1-beta.2 → 2.0.0-beta.1

package/dist/tools/capability-registry/config.js

@@ -0,0 +1,218 @@
+/**
+ * Where the index comes from, and where each product lives.
+ *
+ * A product may DECLARE its host in its own index file (`<product>.base_url`, authored in
+ * the harness's product.yaml and carried through by the export). That is the default, not
+ * the last word: config overrides it, and for a region-sharded product account discovery
+ * outranks it — see `resolveBaseUrl`. The same artifact therefore still ships to every
+ * environment, because anything environment- or account-specific is resolved here.
+ */
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+import logger from "../../logger.js";
+import { getTMBaseURL } from "../../lib/tm-base-url.js";
+import { discoverBaseUrl } from "./discovery.js";
+import { fetchTransport } from "./egress.js";
+import { FLAT_SUFFIX, INDEX_FILE, InvocationError } from "./index-loader.js";
+/**
+ * The environment this DEPLOYMENT points at, e.g. "preprod".
+ *
+ * Process-level on purpose, and the distinction from region matters: an environment is a
+ * property of the deployment (this instance talks to preprod), whereas a REGION is a
+ * property of the account (this user's data lives in EU). That is why region discovery is
+ * per request and never cached under REMOTE_MCP, while the environment is read once here.
+ */
+export function selectedEnvironment() {
+    return (process.env.CAPABILITY_REGISTRY_ENV || "").trim();
+}
+/** product -> env -> host, the analogue of Atlas's `harness.extra_environments`. */
+function environmentMap() {
+    const raw = process.env.CAPABILITY_REGISTRY_BASE_URLS;
+    if (!raw)
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        // A malformed map must not silently mean "no override" — that would send a preprod
+        // deployment at production.
+        throw new InvocationError("CAPABILITY_REGISTRY_BASE_URLS is not valid JSON; expected {product: {env: url}}");
+    }
+}
+/**
+ * Built-in host discovery, for a product whose regional hosts are not in its index yet.
+ *
+ * The general mechanism lives in `discovery.ts` and is driven by the index's `base_urls`.
+ * This map is the bridge for products that predate that: tm's hosts are still hardcoded in
+ * `lib/tm-base-url.ts` and shared with the hand-written Test Management tools. Once tm's
+ * product.yaml declares `base_urls`, this entry can go and nothing else changes.
+ */
+const BUILTIN_DISCOVERY = {
+    tm: getTMBaseURL,
+};
+/** True when this product's host is account-specific and must be discovered per call. */
+export function isRegionSharded(product, source) {
+    return (source?.base_urls?.length ?? 0) > 1 || product in BUILTIN_DISCOVERY;
+}
+function credentialsFrom(config) {
+    return {
+        username: config["browserstack-username"],
+        accessKey: config["browserstack-access-key"],
+    };
+}
+/**
+ * Resolve a product's host.
+ *
+ * Atlas resolves: an explicit per-session override, then the host for the session's
+ * environment (`harness.extra_environments[env][product]`), then the profile's own
+ * `base_url`. The same rungs, in the same order, with one addition:
+ *
+ *   1. CAPABILITY_REGISTRY_BASE_URL_<PRODUCT>            explicit, environment-agnostic
+ *   2. CAPABILITY_REGISTRY_BASE_URL_<PRODUCT>_<ENV>      this environment's host
+ *   3. CAPABILITY_REGISTRY_BASE_URLS {product:{env:url}} the same, as one map
+ *   4. account discovery — the index's `base_urls`, probed
+ *   5. the single host declared in the index, `base_url`
+ *   6. refuse, by name
+ *
+ * DISCOVERY OUTRANKS THE DECLARED HOST, which is where this departs from Atlas. A declared
+ * host is one fixed origin, so for a region-sharded product it would send every account
+ * outside the default region to the wrong host — a failure that only shows up on those
+ * accounts, and so passes any test run from inside the default one. Discovery answers with
+ * the region the account is actually on; `base_url` is the fallback for when the probe
+ * cannot answer at all.
+ *
+ * Refusing rather than guessing is deliberate: a guessed host fails as a DNS error or a 404
+ * that reads like the caller's problem, when it is our missing configuration.
+ */
+export async function resolveBaseUrl(product, config, source, transport) {
+    const key = product.toUpperCase();
+    const environment = selectedEnvironment();
+    const trim = (url) => url.replace(/\/$/, "");
+    const explicit = process.env[`CAPABILITY_REGISTRY_BASE_URL_${key}`];
+    if (explicit)
+        return trim(explicit);
+    if (environment) {
+        const suffixed = process.env[`CAPABILITY_REGISTRY_BASE_URL_${key}_${environment.toUpperCase()}`];
+        if (suffixed)
+            return trim(suffixed);
+        const mapped = environmentMap()[product]?.[environment];
+        if (mapped)
+            return trim(String(mapped));
+        // An environment was named and nothing defines its host. Falling back to discovery or
+        // to the declared production host here would send a preprod deployment at production,
+        // silently.
+        throw new InvocationError(`environment '${environment}' has no host for product '${product}'. Set ` +
+            `CAPABILITY_REGISTRY_BASE_URL_${key}_${environment.toUpperCase()} or add it to ` +
+            `CAPABILITY_REGISTRY_BASE_URLS.`);
+    }
+    /** A declared host is a better answer than none — but only after discovery has tried. */
+    const fallback = (error) => {
+        if (!source?.base_url)
+            throw error;
+        logger.warn("host discovery failed for product %s (%s); falling back to the declared host %s", product, error instanceof Error ? error.message : String(error), source.base_url);
+        return trim(source.base_url);
+    };
+    if ((source?.base_urls?.length ?? 0) > 0) {
+        try {
+            return await discoverBaseUrl(product, source, credentialsFrom(config), transport || fetchTransport());
+        }
+        catch (error) {
+            return fallback(error);
+        }
+    }
+    const builtin = BUILTIN_DISCOVERY[product];
+    if (builtin) {
+        try {
+            return trim(await builtin(config));
+        }
+        catch (error) {
+            return fallback(error);
+        }
+    }
+    if (source?.base_url)
+        return trim(source.base_url);
+    throw new InvocationError(`no host is configured for product '${product}': its index declares none and there ` +
+        `is no override. Set CAPABILITY_REGISTRY_BASE_URL_${key}.`);
+}
+/** The directory holding one subdirectory per product. */
+const INDEX_ROOT = "capability";
+function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Every product index under one directory, sorted so load order is stable.
+ *
+ * `<product>.capability-index.json` is the stored layout — the export publishes that exact
+ * filename, so an artifact drops in unrenamed. `<product>/index.json` is also accepted, so
+ * a checkout using the earlier nested layout keeps working.
+ */
+function filesIn(directory) {
+    if (!isDirectory(directory))
+        return [];
+    const found = [];
+    for (const entry of readdirSync(directory).sort()) {
+        const path = join(directory, entry);
+        if (entry.endsWith(FLAT_SUFFIX)) {
+            found.push(path);
+        }
+        else if (isDirectory(path) && existsSync(join(path, INDEX_FILE))) {
+            found.push(join(path, INDEX_FILE));
+        }
+    }
+    return found;
+}
+/**
+ * Locate the artifact(s).
+ *
+ * ONE FILE PER PRODUCT, so this returns a list. Explicit env wins; otherwise look for a
+ * `capability/` directory beside the compiled module and at the package root, then fall
+ * back to a single `capability-index.json` for the pre-release layout. The package-root
+ * candidates exist because `tsc` compiles TS and does not copy JSON into `dist`.
+ *
+ * Returns an empty list when nothing is found — the caller logs that and registers no
+ * tools, rather than throwing.
+ */
+export function indexPaths() {
+    const configuredFile = process.env.CAPABILITY_REGISTRY_INDEX;
+    if (configuredFile) {
+        return existsSync(configuredFile) ? [resolve(configuredFile)] : [];
+    }
+    const configuredDir = process.env.CAPABILITY_REGISTRY_INDEX_DIR;
+    if (configuredDir)
+        return filesIn(resolve(configuredDir));
+    const here = dirname(fileURLToPath(import.meta.url));
+    const roots = [
+        here,
+        join(here, "..", "..", ".."), // dist/ or src/ -> package root
+        join(here, "..", "..", "..", ".."),
+    ];
+    for (const root of roots) {
+        // `capabilities` (plural) is the layout this shipped with before the move to
+        // `capability/<product>/index.json`; still read so an existing checkout keeps working.
+        for (const name of [INDEX_ROOT, "capabilities"]) {
+            const found = filesIn(join(root, name));
+            if (found.length > 0)
+                return found;
+        }
+        const loose = filesIn(root);
+        if (loose.length > 0)
+            return loose;
+    }
+    for (const root of roots) {
+        const legacy = join(root, "capability-index.json");
+        if (existsSync(legacy))
+            return [legacy];
+    }
+    return [];
+}
+/** Off by default is wrong for a shipped feature, but a kill switch is not. */
+export function isEnabled() {
+    return ((process.env.CAPABILITY_REGISTRY_DISABLED || "").toLowerCase() !== "true");
+}

package/dist/tools/capability-registry/discovery.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Which regional host does THIS account live on?
+ *
+ * Generalised from `lib/tm-base-url.ts`, which asks the question for Test Management by
+ * walking test-management{,-eu,-in}.browserstack.com and keeping the one that authenticates.
+ * The mechanism is not tm-specific — any product sharded by region answers the same way —
+ * so the candidate hosts move into the product's own index (`base_urls`) and this module
+ * performs the walk for all of them.
+ *
+ * A PROBE, NOT A LOOKUP. An account's data lives in exactly one region and the other regions
+ * reject its credentials, so the right host identifies itself. There is no mapping table to
+ * keep in sync, which is the point: a table would go stale silently.
+ */
+import { Credentials, Transport } from "./egress.js";
+import { Capability, ProductIndex } from "./types.js";
+/** What the resolver needs from a product's index to find its host. */
+export type HostSource = Pick<ProductIndex, "base_url" | "base_urls" | "probe_path" | "auth"> & {
+    capabilities?: Capability[];
+};
+/** Exposed for tests; a long-lived process must not pin a stale region forever. */
+export declare function clearDiscoveryCache(): void;
+/**
+ * Pick the endpoint to probe with.
+ *
+ * An explicit `probe_path` in the index wins. Otherwise derive one, and derive it
+ * CONSERVATIVELY — the probe reads a 2xx as "this is the account's region", so an endpoint
+ * that can fail for a reason unrelated to region would walk straight past the right host:
+ *
+ *  * reads only, and never with a path placeholder — there is no id to supply yet;
+ *  * no required query parameters, for the same reason;
+ *  * paginated, because a paged listing is a primary collection by construction;
+ *  * nothing under /admin, which 403s for an ordinary user;
+ *  * shortest path, to prefer the root collection over its variants.
+ *
+ * For tm this lands on `/api/v1/projects`, the same family as the hand-written probe.
+ */
+export declare function probePath(source: HostSource): string | undefined;
+/**
+ * Return the first candidate host that accepts the caller's credentials.
+ *
+ * Probed with the SAME auth the real calls use (`Api-Token`), not a second scheme, so a
+ * host that answers here is one that will answer for the invocation that follows.
+ */
+export declare function discoverBaseUrl(product: string, source: HostSource, credentials: Credentials, transport: Transport): Promise<string>;

package/dist/tools/capability-registry/discovery.js

@@ -0,0 +1,101 @@
+/**
+ * Which regional host does THIS account live on?
+ *
+ * Generalised from `lib/tm-base-url.ts`, which asks the question for Test Management by
+ * walking test-management{,-eu,-in}.browserstack.com and keeping the one that authenticates.
+ * The mechanism is not tm-specific — any product sharded by region answers the same way —
+ * so the candidate hosts move into the product's own index (`base_urls`) and this module
+ * performs the walk for all of them.
+ *
+ * A PROBE, NOT A LOOKUP. An account's data lives in exactly one region and the other regions
+ * reject its credentials, so the right host identifies itself. There is no mapping table to
+ * keep in sync, which is the point: a table would go stale silently.
+ */
+import appConfig from "../../config.js";
+import logger from "../../logger.js";
+import { authHeaders } from "./egress.js";
+import { InvocationError } from "./index-loader.js";
+/**
+ * Cached per product AND per user, so the answer cannot cross accounts.
+ *
+ * `lib/tm-base-url.ts` disables its cache entirely under REMOTE_MCP because a process-wide
+ * single slot would serve the first user's region to everyone after them. Keying by user
+ * fixes that by construction, so the cache stays useful in remote mode too.
+ */
+const cache = new Map();
+/** Exposed for tests; a long-lived process must not pin a stale region forever. */
+export function clearDiscoveryCache() {
+    cache.clear();
+}
+/**
+ * Pick the endpoint to probe with.
+ *
+ * An explicit `probe_path` in the index wins. Otherwise derive one, and derive it
+ * CONSERVATIVELY — the probe reads a 2xx as "this is the account's region", so an endpoint
+ * that can fail for a reason unrelated to region would walk straight past the right host:
+ *
+ *  * reads only, and never with a path placeholder — there is no id to supply yet;
+ *  * no required query parameters, for the same reason;
+ *  * paginated, because a paged listing is a primary collection by construction;
+ *  * nothing under /admin, which 403s for an ordinary user;
+ *  * shortest path, to prefer the root collection over its variants.
+ *
+ * For tm this lands on `/api/v1/projects`, the same family as the hand-written probe.
+ */
+export function probePath(source) {
+    if (source.probe_path)
+        return source.probe_path;
+    const usable = (source.capabilities || []).filter((capability) => capability.mode === "read" &&
+        capability.paginated &&
+        !capability.path.includes("{") &&
+        !capability.path.includes("/admin") &&
+        !(capability.query || []).some((param) => param.required));
+    usable.sort((a, b) => a.path.length - b.path.length || a.path.localeCompare(b.path));
+    return usable[0]?.path;
+}
+/**
+ * Return the first candidate host that accepts the caller's credentials.
+ *
+ * Probed with the SAME auth the real calls use (`Api-Token`), not a second scheme, so a
+ * host that answers here is one that will answer for the invocation that follows.
+ */
+export async function discoverBaseUrl(product, source, credentials, transport) {
+    const candidates = (source.base_urls || []).map((url) => url.replace(/\/$/, ""));
+    if (candidates.length === 0) {
+        throw new InvocationError(`product '${product}' declares no base_urls to probe`);
+    }
+    // One candidate is not a region question; skip the round trip.
+    if (candidates.length === 1)
+        return candidates[0];
+    const key = `${product}\n${credentials.username}`;
+    const cached = cache.get(key);
+    if (cached) {
+        logger.debug("using cached %s host for this account: %s", product, cached);
+        return cached;
+    }
+    const path = probePath(source);
+    if (!path) {
+        throw new InvocationError(`product '${product}' declares several base_urls but no endpoint to probe them with; ` +
+            `set probe_path in its index`);
+    }
+    // The same scheme the invocation will use, so a host that answers here answers there.
+    // Minted ONCE for the whole probe, not per candidate: the token is the caller's identity
+    // and does not vary by which region answers.
+    const headers = await authHeaders(credentials, source.auth, product);
+    const failures = [];
+    for (const candidate of candidates) {
+        const response = await transport("GET", `${candidate}${path}`, headers, {});
+        if (response.status >= 200 && response.status < 300) {
+            // Under REMOTE_MCP the key already carries the user, so this is safe to keep.
+            if (!appConfig.REMOTE_MCP || credentials.username)
+                cache.set(key, candidate);
+            logger.info("resolved %s to %s for this account", product, candidate);
+            return candidate;
+        }
+        failures.push(`${candidate}: HTTP ${response.status || "unreachable"}`);
+    }
+    // Every region refused. Saying which, and with what, is the difference between a
+    // debuggable report and "it did not work".
+    throw new InvocationError(`could not determine which region this account's ${product} lives on. Probed ${path} ` +
+        `on each host — ${failures.join("; ")}`);
+}

package/dist/tools/capability-registry/egress.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The outbound call: auth, attribution, and one HTTP request.
+ *
+ * AUTH IS THE CALLER'S OWN CREDENTIALS, FORWARDED — never a token this server mints. How
+ * they are presented is the PRODUCT's to declare, in the OpenAPI `securityScheme` terms its
+ * own spec already uses. Absent a declaration the default is tm's: `Api-Token:
+ * <username>:<access_key>`, accepted by every /api/v1 route and validated against IAAM
+ * OAuth2 v2 — the same identity resolution a minted bearer token produces, one hop earlier.
+ * Verified in browserstack/teststack: the 59 v1 controllers inheriting
+ * ApplicationApiController resolve it in `current_user`, the 5 inheriting
+ * Api::V1::ApiController in `authenticate_token`.
+ *
+ * That default is right for tm and wrong to assume of everyone. Load Testing's
+ * /api/v1/agent/* surface is reported to take HTTP Basic, and before this there was nowhere
+ * to say so: the requirement lived in a pull request description while the server sent
+ * Api-Token regardless, and the mismatch surfaced as a 401 that reads like the user's
+ * credentials are wrong.
+ */
+import { TokenTransport } from "../../lib/central-oauth.js";
+import { AuthScheme } from "./types.js";
+export type { Credentials } from "../../lib/central-oauth.js";
+import type { Credentials } from "../../lib/central-oauth.js";
+export interface HttpResponse {
+    status: number;
+    body: unknown;
+    error?: string;
+}
+export type Transport = (method: string, url: string, headers: Record<string, string>, query: Record<string, unknown>, body?: unknown) => Promise<HttpResponse>;
+/** The historical default, and what an index without an `auth` block still gets. */
+export declare const DEFAULT_AUTH: AuthScheme;
+/**
+ * Fill a credential template.
+ *
+ * An unknown placeholder is REFUSED, never passed through. Emitting `{user_id}` literally
+ * would send a header that looks well-formed and comes back 401 — indistinguishable from
+ * bad credentials, which is the failure this whole mechanism exists to remove. The harness
+ * really does carry templates this server cannot fill (`{user_id}_{group_id}`), so this is
+ * the common case, not a hypothetical.
+ */
+export declare function renderTemplate(template: string, credentials: Credentials): string;
+/**
+ * The headers for one outbound call.
+ *
+ * ASYNC BECAUSE ONE SCHEME NEEDS A ROUND TRIP. `apiKey` and `http` are pure string work, but
+ * `oauth2` exchanges the caller's credentials for a JWT before anything can be sent, and
+ * there was nowhere to put that while this was synchronous. Both call sites were already
+ * inside async functions, so the cost is two `await`s.
+ */
+export declare function authHeaders(credentials: Credentials, auth?: AuthScheme, product?: string, tokenTransport?: TokenTransport): Promise<Record<string, string>>;
+/** A fetch-based transport. Redirects are NOT followed. */
+export declare function fetchTransport(timeoutMs?: number): Transport;

package/dist/tools/capability-registry/egress.js

@@ -0,0 +1,197 @@
+/**
+ * The outbound call: auth, attribution, and one HTTP request.
+ *
+ * AUTH IS THE CALLER'S OWN CREDENTIALS, FORWARDED — never a token this server mints. How
+ * they are presented is the PRODUCT's to declare, in the OpenAPI `securityScheme` terms its
+ * own spec already uses. Absent a declaration the default is tm's: `Api-Token:
+ * <username>:<access_key>`, accepted by every /api/v1 route and validated against IAAM
+ * OAuth2 v2 — the same identity resolution a minted bearer token produces, one hop earlier.
+ * Verified in browserstack/teststack: the 59 v1 controllers inheriting
+ * ApplicationApiController resolve it in `current_user`, the 5 inheriting
+ * Api::V1::ApiController in `authenticate_token`.
+ *
+ * That default is right for tm and wrong to assume of everyone. Load Testing's
+ * /api/v1/agent/* surface is reported to take HTTP Basic, and before this there was nowhere
+ * to say so: the requirement lived in a pull request description while the server sent
+ * Api-Token regardless, and the mismatch surfaced as a 401 that reads like the user's
+ * credentials are wrong.
+ */
+import { fetchTokenTransport, } from "../../lib/central-oauth.js";
+import { InvocationError } from "./index-loader.js";
+import { bearerToken } from "./oauth.js";
+/** What this server can put into a credential template. Nothing else is fillable. */
+const PLACEHOLDERS = ["username", "access_key"];
+/** The historical default, and what an index without an `auth` block still gets. */
+export const DEFAULT_AUTH = {
+    type: "apiKey",
+    in: "header",
+    name: "Api-Token",
+    template: "{username}:{access_key}",
+};
+/**
+ * Fill a credential template.
+ *
+ * An unknown placeholder is REFUSED, never passed through. Emitting `{user_id}` literally
+ * would send a header that looks well-formed and comes back 401 — indistinguishable from
+ * bad credentials, which is the failure this whole mechanism exists to remove. The harness
+ * really does carry templates this server cannot fill (`{user_id}_{group_id}`), so this is
+ * the common case, not a hypothetical.
+ */
+export function renderTemplate(template, credentials) {
+    const unknown = [...template.matchAll(/\{([a-z_]+)\}/g)]
+        .map((match) => match[1])
+        .filter((nameed) => !PLACEHOLDERS.includes(nameed));
+    if (unknown.length > 0) {
+        throw new InvocationError(`auth template uses placeholder(s) this server cannot fill: ` +
+            `${[...new Set(unknown)].sort().join(", ")}. Available: ` +
+            `${PLACEHOLDERS.map((placeholder) => `{${placeholder}}`).join(", ")}`);
+    }
+    return template
+        .replaceAll("{username}", credentials.username)
+        .replaceAll("{access_key}", credentials.accessKey);
+}
+/**
+ * The headers for one outbound call.
+ *
+ * ASYNC BECAUSE ONE SCHEME NEEDS A ROUND TRIP. `apiKey` and `http` are pure string work, but
+ * `oauth2` exchanges the caller's credentials for a JWT before anything can be sent, and
+ * there was nowhere to put that while this was synchronous. Both call sites were already
+ * inside async functions, so the cost is two `await`s.
+ */
+export async function authHeaders(credentials, auth = DEFAULT_AUTH, product = "this product", tokenTransport = fetchTokenTransport()) {
+    if (!credentials?.username || !credentials?.accessKey) {
+        // Refusing here beats sending unauthenticated and surfacing the product's 401, which
+        // reads like the user's problem when it is our missing configuration.
+        throw new InvocationError("this request is not authenticated: BrowserStack username and access key are required");
+    }
+    const common = {
+        // Attribution, so the downstream service can see the call came from an agent.
+        "request-source": "ai-chatbot",
+        "Content-Type": "application/json",
+    };
+    if (auth.type === "oauth2") {
+        // Refused rather than ignored, which is the same call `in: cookie` and `in: query` get
+        // below: a field that looks like it selects behaviour and does not is how someone
+        // spends an afternoon on a 401 they were never going to be able to explain.
+        const stray = ["in", "name", "template"].filter((field) => auth[field] !== undefined);
+        if (stray.length > 0) {
+            throw new InvocationError(`oauth2 auth does not take ${stray.join(", ")}: a bearer token's presentation is ` +
+                `fixed at 'Authorization: Bearer' (RFC 6750). Remove ${stray.length > 1 ? "them" : "it"}, ` +
+                `or use apiKey if this product really does read a different header.`);
+        }
+        const token = await bearerToken(product, auth, credentials, tokenTransport);
+        return { Authorization: `Bearer ${token}`, ...common };
+    }
+    const value = renderTemplate(auth.template || DEFAULT_AUTH.template, credentials);
+    if (auth.type === "apiKey") {
+        // Header only. `cookie` needs a session this server does not have, and `query` would
+        // put the credential in a URL, where access logs and proxies keep it.
+        if (auth.in && auth.in !== "header") {
+            throw new InvocationError(`unsupported auth location '${auth.in}': this server can only send credentials ` +
+                `in a header`);
+        }
+        if (!auth.name) {
+            throw new InvocationError("apiKey auth declares no header name");
+        }
+        return { [auth.name]: value, ...common };
+    }
+    if (auth.type === "http" && (auth.scheme || "").toLowerCase() === "basic") {
+        return {
+            Authorization: `Basic ${Buffer.from(value).toString("base64")}`,
+            ...common,
+        };
+    }
+    // By name, and refusing: sending nothing would be a 401 the caller reads as their own
+    // fault, and guessing a scheme is how credentials end up somewhere they should not be.
+    throw new InvocationError(`unsupported auth scheme for this product: ` +
+        `${JSON.stringify({ type: auth.type, scheme: auth.scheme })}`);
+}
+/** Longest response text kept when it is not JSON. Enough for an error, not a whole page. */
+const TEXT_BODY_LIMIT = 2000;
+/**
+ * Read the response, and NEVER silently discard it.
+ *
+ * This used to parse the body only when the content-type said JSON and return `null`
+ * otherwise, which meant an error could arrive as `{status: 500, body: null}` — a status
+ * code and nothing else. That is worse than it sounds: an unhandled exception in a Rails
+ * app renders `text/html`, so the one case where you most need the message is exactly the
+ * case where the content-type is not JSON. It also made two very different situations
+ * indistinguishable — "the product sent no message" and "we threw the message away" — and
+ * a live probe of `get_test_case_linked_issues` had to leave that ambiguity open in its findings
+ * because nothing downstream could tell which had happened.
+ *
+ * So: JSON is parsed as before. Anything textual is kept as a truncated string. Malformed
+ * JSON keeps its raw text rather than becoming `null`, because a body that fails to parse
+ * is itself the diagnosis. Binary is described rather than decoded — dumping PDF bytes
+ * into an agent's context helps nobody, but knowing a PDF arrived does.
+ */
+async function readBody(response) {
+    const contentType = response.headers.get("content-type") || "";
+    // Anything that is not plausibly text: report what came back without decoding it.
+    const textual = !contentType ||
+        /^text\//i.test(contentType) ||
+        /\b(json|xml|yaml|csv|javascript|x-www-form-urlencoded)\b/i.test(contentType);
+    if (!textual) {
+        const size = response.headers.get("content-length");
+        return `<non-text response: ${contentType}${size ? `, ${size} bytes` : ""}>`;
+    }
+    const raw = await response.text().catch(() => "");
+    if (!raw.trim())
+        return null;
+    if (contentType.includes("json")) {
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            // Declared JSON that is not JSON. The text is the evidence; keep it.
+            return truncate(raw);
+        }
+    }
+    return truncate(raw);
+}
+function truncate(text) {
+    return text.length <= TEXT_BODY_LIMIT
+        ? text
+        : `${text.slice(0, TEXT_BODY_LIMIT)}… [truncated, ${text.length} chars total]`;
+}
+/** A fetch-based transport. Redirects are NOT followed. */
+export function fetchTransport(timeoutMs = 45_000) {
+    return async (method, url, headers, query, body) => {
+        const target = new URL(url);
+        for (const [key, value] of Object.entries(query || {})) {
+            if (value !== undefined && value !== null)
+                target.searchParams.set(key, String(value));
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const response = await fetch(target.toString(), {
+                method,
+                headers,
+                // Only send a body when there IS one: a literal `null` payload with a JSON
+                // content-type is rejected by several endpoints.
+                body: body === undefined ? undefined : JSON.stringify(body),
+                // A redirect from an authenticated API is usually a login bounce, and following it
+                // turns a clear 401/302 into a 200 carrying an HTML sign-in page — which the
+                // resolver would then read as an empty result set rather than a failure.
+                redirect: "manual",
+                signal: controller.signal,
+            });
+            return {
+                status: response.status,
+                body: await readBody(response),
+            };
+        }
+        catch {
+            // Upstream detail stays out of the reply; the resolver treats status 0 as a failed call.
+            return {
+                status: 0,
+                body: null,
+                error: "the product could not be reached",
+            };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+}