@browserstack/mcp-server 2.2.3 → 2.3.0-beta.2

package/dist/lib/error.d.ts

@@ -1,14 +1,4 @@
 import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-/**
- * Returns the most specific human-readable text for an error raised by an
- * API call, capped at 500 characters. For an AxiosError with a response body
- * it prefers the body's `message`, `error` or `errors` field, serialising
- * objects, and uses the whole body when none of those fields exist. An empty,
- * whitespace-only or HTML-document body falls back to the error's own message.
- * @param err - The error object to describe
- * @param defaultText - The fallback error message
- */
-export declare function errorText(err: unknown, defaultText: string): string;
 /**
  * Formats an AxiosError into a CallToolResult with an appropriate message.
  * @param err - The error object to format

package/dist/lib/error.js

@@ -1,75 +1,23 @@
 import { AxiosError } from "axios";
-const MAX_ERROR_TEXT = 500;
-const BODY_FIELDS = ["message", "error", "errors"];
-function clip(text) {
-    return text.length > MAX_ERROR_TEXT ? text.slice(0, MAX_ERROR_TEXT) : text;
-}
-const HTML_DOCUMENT = /^\s*<(!doctype|html)\b/i;
-function stringify(value) {
-    if (typeof value === "string") {
-        return HTML_DOCUMENT.test(value) ? "" : value.trim();
-    }
-    if (value === undefined || value === null)
-        return "";
-    try {
-        const json = JSON.stringify(value);
-        return json === "{}" || json === "[]" ? "" : (json ?? "");
-    }
-    catch {
-        return "";
-    }
-}
-/**
- * Text taken from an API error body: the first non-empty `message`, `error`
- * or `errors` field when any of them is present, otherwise the whole body.
- * Returns undefined when the body carries no usable text.
- */
-function bodyText(data) {
-    if (typeof data !== "object" || data === null) {
-        const text = stringify(data);
-        return text ? clip(text) : undefined;
-    }
-    const record = data;
-    const named = BODY_FIELDS.filter((key) => key in record);
-    if (named.length > 0) {
-        for (const key of named) {
-            const text = stringify(record[key]);
-            if (text)
-                return clip(text);
-        }
-        return undefined;
-    }
-    const text = stringify(record);
-    return text ? clip(text) : undefined;
-}
-/**
- * Returns the most specific human-readable text for an error raised by an
- * API call, capped at 500 characters. For an AxiosError with a response body
- * it prefers the body's `message`, `error` or `errors` field, serialising
- * objects, and uses the whole body when none of those fields exist. An empty,
- * whitespace-only or HTML-document body falls back to the error's own message.
- * @param err - The error object to describe
- * @param defaultText - The fallback error message
- */
-export function errorText(err, defaultText) {
-    if (err instanceof AxiosError) {
-        const text = bodyText(err.response?.data);
-        if (text)
-            return text;
-        return clip(err.message || defaultText);
-    }
-    if (err instanceof Error)
-        return clip(err.message || defaultText);
-    return defaultText;
-}
 /**
  * Formats an AxiosError into a CallToolResult with an appropriate message.
  * @param err - The error object to format
  * @param defaultText - The fallback error message
  */
 export function formatAxiosError(err, defaultText) {
+    let text = defaultText;
+    if (err instanceof AxiosError && err.response?.data) {
+        const message = err.response.data.message ||
+            err.response.data.error ||
+            err.message ||
+            defaultText;
+        text = message;
+    }
+    else if (err instanceof Error) {
+        text = err.message;
+    }
     return {
-        content: [{ type: "text", text: errorText(err, defaultText) }],
+        content: [{ type: "text", text }],
         isError: true,
     };
 }

package/dist/lib/utils.js

@@ -7,9 +7,6 @@ export function sanitizeUrlParam(param) {
     return param.replace(/[;&|`$(){}[\]<>]/g, "");
 }
 const ONE_MB = 1048576;
-// sharp's default (~268M px) lets one image decode to ~1 GB of RGBA; 25M px caps it near 100 MB.
-const MAX_INPUT_PIXELS = 25_000_000;
-const MAX_IMAGE_DIMENSION = 1920;
 let sharpConfigured = false;
 //Compresses a base64 image intelligently to keep it under 1 MB if needed.
 export async function maybeCompressBase64(base64) {
@@ -28,19 +25,11 @@ export async function maybeCompressBase64(base64) {
             sharp.concurrency(1);
             sharpConfigured = true;
         }
-        const image = globalConfig.REMOTE_MCP
-            ? sharp(buffer, { limitInputPixels: MAX_INPUT_PIXELS }).resize({
-                width: MAX_IMAGE_DIMENSION,
-                height: MAX_IMAGE_DIMENSION,
-                fit: "inside",
-                withoutEnlargement: true,
-            })
-            : sharp(buffer);
-        const compressedBuffer = await image.png({ quality }).toBuffer();
+        const compressedBuffer = await sharp(buffer).png({ quality }).toBuffer();
         return compressedBuffer.toString("base64");
     }
     catch (err) {
-        logger.warn("Image compression failed; returning the uncompressed image. %s", err instanceof Error ? err.message : String(err));
+        logger.warn("Image compression unavailable (sharp failed to load); returning the uncompressed image. %s", err instanceof Error ? err.message : String(err));
         return base64;
     }
 }

package/dist/tools/automate-utils/fetch-screenshots.d.ts

@@ -1,10 +1,6 @@
 import { SessionType } from "../../lib/constants.js";
 import { BrowserStackConfig } from "../../lib/types.js";
-export declare const MAX_SCREENSHOT_BYTES: number | undefined;
-export declare function parseScreenshotUrls(text: string): string[];
-export type Screenshot = {
+export declare function fetchAutomationScreenshots(sessionId: string, sessionType: SessionType | undefined, config: BrowserStackConfig): Promise<{
     url: string;
     base64: string;
-    mimeType: string;
-};
-export declare function fetchAutomationScreenshots(sessionId: string, sessionType: SessionType | undefined, config: BrowserStackConfig): Promise<Screenshot[]>;
+}[]>;

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

@@ -3,10 +3,6 @@ import { SessionType } from "../../lib/constants.js";
 import { getBrowserStackAuth } from "../../lib/get-auth.js";
 import { apiClient } from "../../lib/apiClient.js";
 import globalConfig from "../../config.js";
-import { MAX_LOG_BYTES } from "../failurelogs-utils/utils.js";
-export const MAX_SCREENSHOT_BYTES = globalConfig.REMOTE_MCP
-    ? 10 * 1024 * 1024
-    : undefined;
 async function extractScreenshotUrls(sessionId, sessionType, config) {
     const authString = getBrowserStackAuth(config);
     const auth = Buffer.from(authString).toString("base64");
@@ -18,112 +14,47 @@ async function extractScreenshotUrls(sessionId, sessionType, config) {
             "Content-Type": "application/json",
             Authorization: `Basic ${auth}`,
         },
-        maxContentLength: MAX_LOG_BYTES,
         raise_error: false,
     });
-    if (response.status === 413) {
-        throw new Error("The logs for this session are too large (over 5 MB) to find screenshots here. Open the session in the BrowserStack dashboard to view them.");
-    }
     await assertOkResponse(response, "Session");
     const text = typeof response.data === "string"
         ? response.data
         : JSON.stringify(response.data);
-    return parseScreenshotUrls(text);
-}
-const LOG_PREFIX = String.raw `^\d{4}-\d{2}-\d{2} \d{1,2}:\d{1,2}:\d{1,2}:\d{1,3} `;
-const LINE_TYPE_PATTERN = new RegExp(`${LOG_PREFIX}([A-Z_]+) `);
-const SCREENSHOT_REQUEST_PATTERN = new RegExp(String.raw `${LOG_PREFIX}REQUEST \[[^\]]+\] GET /session/[^/\s]+/screenshot(\s|$)`);
-const RESPONSE_VALUE_PATTERN = new RegExp(String.raw `${LOG_PREFIX}RESPONSE \{"value"\s*:\s*"(https://[^"]+)"`);
-const DEBUG_SCREENSHOT_PATTERN = new RegExp(String.raw `${LOG_PREFIX}DEBUG (https://\S+)$`);
-const TRUSTED_HOST_PATTERN = /(^|\.)browserstack\.com$|\.s3([.-][a-z0-9-]+)*\.amazonaws\.com$|\.backblazeb2\.com$/;
-function isTrustedScreenshotUrl(value) {
-    try {
-        const url = new URL(value);
-        return url.protocol === "https:" && TRUSTED_HOST_PATTERN.test(url.hostname);
-    }
-    catch {
-        return false;
-    }
-}
-export function parseScreenshotUrls(text) {
     const urls = [];
-    const lines = text.split("\n").map((line) => line.trimEnd());
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i];
-        const debugMatch = line.match(DEBUG_SCREENSHOT_PATTERN);
-        if (debugMatch) {
-            urls.push(debugMatch[1]);
-            continue;
-        }
-        if (!SCREENSHOT_REQUEST_PATTERN.test(line)) {
-            continue;
-        }
-        for (let j = i + 1; j < lines.length; j++) {
-            const lineType = lines[j].match(LINE_TYPE_PATTERN)?.[1];
-            if (lineType === "REQUEST") {
-                break;
-            }
-            if (lineType === "RESPONSE") {
-                const valueMatch = lines[j].match(RESPONSE_VALUE_PATTERN);
-                if (valueMatch) {
-                    urls.push(valueMatch[1]);
-                }
-                break;
+    const SCREENSHOT_PATTERN = /REQUEST.*GET.*\/screenshot/;
+    const RESPONSE_VALUE_PATTERN = /"value"\s*:\s*"([^"]+)"/;
+    // Split logs into lines and process them
+    const lines = text.split("\n");
+    for (let i = 0; i < lines.length - 1; i++) {
+        const currentLine = lines[i];
+        const nextLine = lines[i + 1];
+        if (SCREENSHOT_PATTERN.test(currentLine)) {
+            const match = nextLine.match(RESPONSE_VALUE_PATTERN);
+            if (match && match[1]) {
+                urls.push(match[1]);
             }
         }
     }
-    return [...new Set(urls)].filter(isTrustedScreenshotUrl);
-}
-function detectImageMimeType(buffer) {
-    if (buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff) {
-        return "image/jpeg";
-    }
-    return "image/png";
+    return urls;
 }
-// Returns null for a screenshot over MAX_SCREENSHOT_BYTES so the rest still load.
 async function fetchAndCompress(url) {
-    const response = await apiClient.get({
-        url,
-        responseType: "arraybuffer",
-        maxContentLength: MAX_SCREENSHOT_BYTES,
-        raise_error: false,
-    });
-    if (response.status === 413) {
-        return null;
-    }
-    if (!response.ok) {
-        throw new Error(`Failed to download screenshot: ${response.status} ${response.statusText}`);
-    }
+    const response = await apiClient.get({ url, responseType: "arraybuffer" });
     // Axios returns response.data as a Buffer for binary data
-    const buffer = Buffer.from(response.data);
-    const base64 = await maybeCompressBase64(buffer.toString("base64"));
-    // Detect AFTER compression: sharp re-encodes anything over 1 MB to PNG, so
-    // reading the original bytes would label a large JPEG with the wrong type.
-    return {
-        url,
-        base64,
-        mimeType: detectImageMimeType(Buffer.from(base64, "base64")),
-    };
+    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) {
-    let results;
     // Hosted pods are memory-constrained: process one image at a time. Local runs
     // keep the concurrent path.
     if (globalConfig.REMOTE_MCP) {
-        results = [];
+        const screenshots = [];
         for (const url of urls) {
-            results.push(await fetchAndCompress(url));
+            screenshots.push(await fetchAndCompress(url));
         }
+        return screenshots;
     }
-    else {
-        results = await Promise.all(urls.map(fetchAndCompress));
-    }
-    const screenshots = results.filter((s) => s !== null);
-    if (urls.length > 0 && screenshots.length === 0) {
-        throw new Error("The screenshots in this session are too large (over 10 MB each) to fetch here. Open the session in the BrowserStack dashboard to view them.");
-    }
-    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/dist/tools/automate.js

@@ -14,7 +14,7 @@ export async function fetchAutomationScreenshotsTool(args, config) {
                 content: [
                     {
                         type: "text",
-                        text: "No screenshots found in the session logs. Run with browserstack.debug: true to capture visual-log screenshots.",
+                        text: "No screenshots found in the session or some unexpected error occurred",
                     },
                 ],
                 isError: true,
@@ -23,7 +23,7 @@ export async function fetchAutomationScreenshotsTool(args, config) {
         const results = screenshots.map((screenshot, index) => ({
             type: "image",
             data: screenshot.base64,
-            mimeType: screenshot.mimeType,
+            mimeType: "image/png",
             _meta: { url: screenshot.url, index: index + 1 },
         }));
         return {

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

@@ -7,6 +7,8 @@
  * one is meant, which is exactly why the Python side used to rename body fields `body_*`.
  * Grouping removes the collision AND the rename, so a caller sends the spec's own names.
  */
+import appConfig from "../../config.js";
+import { APP_BINARY_EXTENSIONS, MAX_APP_UPLOAD_BYTES, validateUploadPath, } from "../../lib/upload-validator.js";
 import { InvocationError } from "./index-loader.js";
 /**
  * String formats worth ENFORCING, as opposed to merely publishing.
@@ -202,6 +204,34 @@ export function coerce(value, param) {
 }
 function coerceType(value, param, label = param.name) {
     const expected = param.type;
+    if (expected === "any") {
+        // PASSES THROUGH UNTOUCHED, which is the whole point of declaring it. A polymorphic
+        // parameter reached the string branch and arrived as text: WebDriver's frame id takes a
+        // number, an element reference or null, and `null` sent as "null" is refused as an
+        // invalid argument — a failure that reads like the caller chose the wrong frame.
+        return value;
+    }
+    if (expected === "file") {
+        // CHECKED HERE, not at egress: `bind` runs dry before the write-consent gate, so a path
+        // that does not exist — or a base directory nobody configured — is refused before the
+        // user is asked to approve an upload that was never going to happen.
+        //
+        // The rules are the ones the server already applies to every other upload, so the
+        // answer does not depend on which surface asked.
+        const given = String(value ?? "").trim();
+        if (!given)
+            throw new InvocationError(`'${label}' must be a path to a file`);
+        try {
+            return validateUploadPath(given, {
+                allowedExtensions: APP_BINARY_EXTENSIONS,
+                maxSizeBytes: MAX_APP_UPLOAD_BYTES,
+                allowedBaseDir: appConfig.UPLOAD_BASE_DIR,
+            });
+        }
+        catch (error) {
+            throw new InvocationError(error instanceof Error ? error.message : String(error));
+        }
+    }
     if (expected === "object" || expected === "array") {
         // An opaque body object is passed through as given: the spec does not describe its
         // fields, so validating or reshaping it would mean inventing a contract.
@@ -267,6 +297,32 @@ function coerceType(value, param, label = param.name) {
     if (untyped && (typeof value === "object" || typeof value === "boolean")) {
         return value;
     }
+    // A DECLARED STRING IS NOT A LICENCE TO STRINGIFY ANYTHING.
+    //
+    // The untyped case above was fixed because `String(value)` destroyed objects the spec had
+    // declined to describe. A DECLARED string was left stringifying whatever arrived, and it
+    // is the worse of the two: an object sent for `create_test_case_comment`'s `comment` was
+    // serialised to the literal text "[object Object]", the API accepted it, the write
+    // returned 200, and the agent reported success in good faith. tm exposes no comment
+    // delete, so that text is now permanently on the case.
+    //
+    // A 400 teaches the caller what it got wrong. A 200 that stores "[object Object]" teaches
+    // it nothing and cannot be undone, so refuse here rather than let it reach the wire.
+    //
+    // `null` passes through instead of becoming the five characters "null", which no API has
+    // ever wanted: several string parameters document null as the way to CLEAR a field —
+    // `test_plan_id` says "send null or '' to unlink" — and stringifying it silently sent a
+    // value where the caller meant to send an absence.
+    if (expected === "string") {
+        if (value === null || value === undefined)
+            return value;
+        if (typeof value === "object") {
+            throw new InvocationError(`'${label}' must be a string, and was ${Array.isArray(value) ? "a list" : "an object"}. ` +
+                `Serialising it would send the text ` +
+                `${JSON.stringify(Array.isArray(value) ? "[object Array]" : "[object Object]")} ` +
+                `rather than its contents, and the call would succeed with that stored.`);
+        }
+    }
     const text = String(value);
     if (param.values && param.values.length > 0) {
         const allowed = param.values.map((v) => String(v));

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

@@ -21,31 +21,7 @@ import { Transport } from "./egress.js";
 export declare function selectedEnvironment(): string;
 /** True when this product's host is account-specific and must be discovered per call. */
 export declare function isRegionSharded(product: string, source?: HostSource): boolean;
-/**
- * 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 declare function resolveBaseUrl(product: string, config: BrowserStackConfig, source?: HostSource, transport?: Transport): Promise<string>;
+export declare function resolveBaseUrl(product: string, config: BrowserStackConfig, source?: HostSource, transport?: Transport, host?: string): Promise<string>;
 /**
  * Locate the artifact(s).
  *

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

@@ -86,10 +86,49 @@ function credentialsFrom(config) {
  * 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) {
+/**
+ * The host a capability named, as opposed to the product's own.
+ *
+ * `_HOST_` is in the override variable deliberately. The environment-suffixed form is
+ * `CAPABILITY_REGISTRY_BASE_URL_<PRODUCT>_<ENV>`, so a bare
+ * `CAPABILITY_REGISTRY_BASE_URL_APPAUTOMATE_HUB` would mean the hub host or the "hub"
+ * environment depending on which the reader had in mind — and whichever the code chose,
+ * the other reading sends a call to the wrong origin silently.
+ *
+ * A named environment refuses rather than falling back to the declared host, for the same
+ * reason the product-level resolver does: a preprod session must not reach production
+ * because nobody defined preprod's hub.
+ */
+function resolveNamedHost(product, key, host, source, environment) {
+    const trim = (url) => url.replace(/\/$/, "");
+    const suffix = `${key}_HOST_${host.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}`;
+    const override = process.env[`CAPABILITY_REGISTRY_BASE_URL_${suffix}`];
+    if (override)
+        return trim(override);
+    if (environment) {
+        throw new InvocationError(`environment '${environment}' has no '${host}' host for product '${product}'. Set ` +
+            `CAPABILITY_REGISTRY_BASE_URL_${suffix}.`);
+    }
+    const declared = source?.hosts?.[host];
+    if (declared)
+        return trim(declared);
+    const known = Object.keys(source?.hosts ?? {});
+    throw new InvocationError(`that capability is served from the '${host}' host, which product '${product}' does ` +
+        `not declare. ` +
+        (known.length
+            ? `Its index defines: ${known.join(", ")}.`
+            : `Its index defines no named hosts.`) +
+        ` Set CAPABILITY_REGISTRY_BASE_URL_${suffix} to override.`);
+}
+export async function resolveBaseUrl(product, config, source, transport, host) {
     const key = product.toUpperCase();
     const environment = selectedEnvironment();
     const trim = (url) => url.replace(/\/$/, "");
+    // A capability that names a host is asking for one fixed origin, so none of the rungs
+    // below apply: discovery answers with the product's own host, and the declared
+    // `base_url` cannot serve this capability's paths at all.
+    if (host)
+        return resolveNamedHost(product, key, host, source, environment);
     const explicit = process.env[`CAPABILITY_REGISTRY_BASE_URL_${key}`];
     if (explicit)
         return trim(explicit);

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

@@ -14,7 +14,7 @@
 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"> & {
+export type HostSource = Pick<ProductIndex, "base_url" | "base_urls" | "hosts" | "probe_path" | "auth"> & {
     capabilities?: Capability[];
 };
 /** Exposed for tests; a long-lived process must not pin a stale region forever. */

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

@@ -135,7 +135,19 @@ async function readBody(response) {
         const size = response.headers.get("content-length");
         return `<non-text response: ${contentType}${size ? `, ${size} bytes` : ""}>`;
     }
-    const raw = await response.text().catch(() => "");
+    // A FAILED READ IS NOT AN EMPTY BODY. `fetch` resolves as soon as the headers arrive, so
+    // the abort timer can fire while the body is still streaming. Swallowing that here
+    // returned the status line with no payload — a slow session create came back as a 200
+    // carrying null, which reads as a successful start that forgot to mention the session id.
+    // The device was really allocated, so the caller then had a session it could not name and
+    // could not release. Re-throwing lets the transport report the call as failed.
+    let raw;
+    try {
+        raw = await response.text();
+    }
+    catch (error) {
+        throw new Error(`the response body could not be read: ${error instanceof Error ? error.message : String(error)}`);
+    }
     if (!raw.trim())
         return null;
     if (contentType.includes("json")) {
@@ -169,8 +181,14 @@ export function fetchTransport(timeoutMs = 45_000) {
                 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),
+                // content-type is rejected by several endpoints. A FormData goes through as it is —
+                // stringifying it yields "[object FormData]", which uploads nothing and reads as a
+                // product error rather than ours.
+                body: body === undefined
+                    ? undefined
+                    : body instanceof FormData
+                        ? body
+                        : 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.

package/dist/tools/capability-registry/index-loader.d.ts

@@ -10,6 +10,16 @@ export declare class IndexError extends Error {
 }
 /** Thrown to the caller as a tool error, so the wording is caller-facing. */
 export declare class InvocationError extends Error {
+    /**
+     * Set when the handle exists in the artifact but this surface withholds it.
+     *
+     * The MESSAGE deliberately does not say so — a caller is told the capability does not
+     * exist, because "withheld" invites a retry, a search for synonyms, or a question to the
+     * user about enabling it, none of which can succeed here. The flag keeps the distinction
+     * for telemetry, where knowing how often a withheld handle is reached for is how we learn
+     * whether withholding it was the right call.
+     */
+    withheld?: boolean;
 }
 /** The file inside a product subdirectory, for the earlier nested layout. */
 export declare const INDEX_FILE = "index.json";
@@ -32,8 +42,22 @@ export declare function endpointKey(method: string, path: string): string;
  * FAILS CLOSED: any truthy `disabled` hides it, not just `=== true`. The flag exists to
  * suppress something that cannot work, so an unexpected shape must hide it rather than be
  * ignored — the opposite default would turn a typo into a silently re-enabled capability.
+ *
+ * `local_only` withholds on a remote server only, for a capability that reads the caller's
+ * own machine: there, the path it would take resolves against the operator's disk instead.
+ * Read at call time rather than captured, because the remote server builds its config per
+ * session and a value captured at module load would outlive the deployment it described.
  */
 export declare function isDisabled(capability: Capability): boolean;
+/**
+ * Is this capability published for reference only on this surface?
+ *
+ * `local_only` on a remote server. The capability is real and the caller may well be asking
+ * for exactly it, so hiding it leaves the agent concluding no such route exists. Publishing
+ * it without the means to call it, and with a note saying what to do instead, answers the
+ * question it was asked.
+ */
+export declare function isReferenceOnly(capability: Capability): boolean;
 export interface LoadedProduct {
     name: string;
     product: ProductIndex;
@@ -66,16 +90,18 @@ export declare class CapabilityRegistry {
     private readonly withheld;
     constructor(index: RegistryIndex, provenance?: Record<string, Provenance>);
     /**
-     * The `capability_disabled` message for a handle this build withholds, if it is one.
+     * Does this build withhold the handle?
      *
-     * Says THAT it is disabled and nothing about why. The reason is documentation and lives
-     * with the decision; repeating it here would put four copies of a paragraph in the
-     * shipped artifact to serve a path the flag itself makes rare.
+     * WHAT THE CALLER IS TOLD IS THAT IT DOES NOT EXIST, which is why this returns a boolean
+     * rather than a message. Saying "withheld" describes the artifact rather than the
+     * surface, and every action it invites — retry, hunt for a synonym, ask the user to turn
+     * it on — fails here. A capability absent from search, describe and every listing should
+     * read the same way at invocation as it does everywhere else.
      *
-     * Returns undefined for anything else, so the caller falls through to its own
-     * not-found wording.
+     * The caller raises its own not-found error and marks it `withheld`, so the distinction
+     * survives in telemetry without reaching the agent.
      */
-    private withheldMatch;
+    private isWithheld;
     /** How many capabilities each product withholds. Startup logging only. */
     disabledCounts(): Record<string, number>;
     static fromFile(file: string): CapabilityRegistry;