@browserstack/mcp-server 2.2.2 → 2.3.0-beta.1

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;

package/dist/tools/capability-registry/index-loader.js

@@ -6,12 +6,23 @@
  * lets searchCapability rank across products from N single-product files.
  */
 import { readFileSync } from "node:fs";
+import appConfig from "../../config.js";
 import { basename, dirname } from "node:path";
 import { ENVELOPE_KEYS, SUPPORTED_SCHEMA_VERSION, } from "./types.js";
 export class IndexError extends Error {
 }
 /** Thrown to the caller as a tool error, so the wording is caller-facing. */
 export 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;
 }
 /** The file inside a product subdirectory, for the earlier nested layout. */
 export const INDEX_FILE = "index.json";
@@ -43,9 +54,59 @@ export function endpointKey(method, path) {
  * 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 function isDisabled(capability) {
-    return Boolean(capability.disabled);
+    if (capability.disabled)
+        return true;
+    return Boolean(capability.local_only) && Boolean(appConfig.REMOTE_MCP);
+}
+/**
+ * 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 function isReferenceOnly(capability) {
+    if (capability.disabled)
+        return false;
+    return Boolean(capability.local_only) && Boolean(appConfig.REMOTE_MCP);
+}
+/**
+ * The reference form: what it is and what to do instead, and nothing to call it with.
+ *
+ * The parameters and response shapes go because publishing them invites the attempt — a
+ * model handed a body schema will fill it in. `intent` stays, because that is what the
+ * search matched on, and `mode` stays so a reader can still see what kind of operation it
+ * would have been.
+ */
+function asReference(capability) {
+    const reference = { ...capability };
+    for (const field of [
+        "path_params",
+        "query",
+        "body",
+        "responses",
+        "returns",
+        "paginated",
+        "max_page_size",
+        "encoding",
+    ]) {
+        delete reference[field];
+    }
+    return {
+        ...reference,
+        invocable: false,
+        guidance: capability.unavailable_note
+            ? [capability.unavailable_note]
+            : ["This capability cannot be called on this server."],
+    };
 }
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -181,6 +242,16 @@ export class CapabilityRegistry {
                 // between a disabled name and a live one is still a broken artifact, and skipping
                 // the disabled half would mean re-enabling the flag could fail the load later,
                 // somewhere with less context than here.
+                if (isReferenceOnly(capability)) {
+                    // PUBLISHED, BUT NOT CALLABLE. It keeps its name and intent so the search that
+                    // should find it does, and loses everything a caller would need to invoke it.
+                    const reference = asReference(capability);
+                    enabled.push(reference);
+                    lookup.set(endpointKey(capability.method, capability.path), reference);
+                    if (capability.name)
+                        names.set(capability.name, reference);
+                    continue;
+                }
                 if (isDisabled(capability)) {
                     withheld.set(endpointKey(capability.method, capability.path), capability);
                     if (capability.name)
@@ -219,26 +290,25 @@ export class CapabilityRegistry {
         this.index = { ...index, products };
     }
     /**
-     * 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.
      */
-    withheldMatch(handle, product) {
+    isWithheld(handle, product) {
         for (const [owner, withheld] of this.withheld) {
             if (product && owner !== product)
                 continue;
-            if (!withheld.has(handle))
-                continue;
-            return (`capability_disabled: ${handle} is disabled on this surface. This is ` +
-                `deliberate — it is withheld by the ${owner} index, not missing from it — so ` +
-                `retrying will not help.`);
+            if (withheld.has(handle))
+                return true;
         }
-        return undefined;
+        return false;
     }
     /** How many capabilities each product withholds. Startup logging only. */
     disabledCounts() {
@@ -326,13 +396,13 @@ export class CapabilityRegistry {
                 matches.push({ product: owner, capability });
         }
         if (matches.length === 0) {
-            // WITHHELD IS A DIFFERENT ANSWER FROM ABSENT, and only here. Search cannot surface a
-            // disabled capability, so reaching this branch means the caller already held the
-            // exact handle — from an older index, a doc, or a human. "unknown_capability" would
-            // send it hunting for a synonym that does not exist; the reason ends the attempt.
-            const off = this.withheldMatch(name, product);
-            if (off)
-                throw new InvocationError(off);
+            // A WITHHELD HANDLE ANSWERS THE SAME WAY AS AN ABSENT ONE. Search, describe and the
+            // listings already behave as though it does not exist, and invocation is no place to
+            // contradict them: "withheld" is a fact about the artifact, not about this surface,
+            // and it invites a retry, a hunt for a synonym, or a question to the user about
+            // enabling something that cannot be enabled here. The error carries `withheld` so the
+            // attempt is still countable in telemetry.
+            const withheldHere = this.isWithheld(name, product);
             // Say whether names are published at all for the product asked about: "no such name"
             // and "this product does not name its capabilities" need different fixes.
             const unnamed = [...this.byName]
@@ -342,7 +412,10 @@ export class CapabilityRegistry {
                 ? ` ${unnamed.sort().join(", ")} ${unnamed.length > 1 ? "publish" : "publishes"} ` +
                     `no capability names yet — call those by \`method\` and \`path\` instead.`
                 : " Search again — names come from searchCapability and describeEntity.";
-            throw new InvocationError(`unknown_capability: ${name}.${hint}`);
+            const error = new InvocationError(`unknown_capability: ${name}.${hint}`);
+            if (withheldHere)
+                error.withheld = true;
+            throw error;
         }
         if (matches.length > 1 && !product) {
             const owners = matches
@@ -371,11 +444,11 @@ export class CapabilityRegistry {
                 matches.push({ product: name, capability });
         }
         if (matches.length === 0) {
-            const off = this.withheldMatch(key, product);
-            if (off)
-                throw new InvocationError(off);
-            throw new InvocationError(`unknown_endpoint: ${key}. Search again — send \`method\` and \`path\` exactly as ` +
+            const error = new InvocationError(`unknown_endpoint: ${key}. Search again — send \`method\` and \`path\` exactly as ` +
                 `searchCapability returned them, placeholders included.`);
+            if (this.isWithheld(key, product))
+                error.withheld = true;
+            throw error;
         }
         if (matches.length > 1 && !product) {
             const owners = matches

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

@@ -32,7 +32,7 @@ export interface RegistryDeps {
      * Per-product base URL. Never baked into the artifact — it is environment AND account
      * specific: tm is region-sharded, so this is resolved per call, not once at startup.
      */
-    baseUrlFor: (product: string) => Promise<string>;
+    baseUrlFor: (product: string, host?: string) => Promise<string>;
     credentialsFor: () => Credentials;
     transport?: Transport;
 }

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

@@ -81,7 +81,7 @@ export function addCapabilityRegistryToolsFromConfig(server, config) {
         registry,
         // The whole product bundle, not just its host: a region-sharded product declares
         // several candidates and the probe needs an endpoint from its own capabilities.
-        baseUrlFor: (product) => resolveBaseUrl(product, config, registry.index.products[product]),
+        baseUrlFor: (product, host) => resolveBaseUrl(product, config, registry.index.products[product], undefined, host),
         // Read per call, not captured: the remote server rebuilds config per session, so a
         // captured credential would outlive the session it belongs to.
         credentialsFor: () => ({
@@ -147,7 +147,12 @@ export function addCapabilityRegistryTools(server, deps, config) {
      * below pin each branch against the message its source actually produces; if you reword
      * a refusal, one of them will tell you.
      */
-    const invocationReason = (message) => {
+    const invocationReason = (message, error) => {
+        // A WITHHELD HANDLE IS REPORTED TO THE CALLER AS NOT FOUND, so the message cannot be
+        // what distinguishes it. The flag on the error can, which keeps the refusal countable
+        // without the wording admitting the capability exists.
+        if (error instanceof InvocationError && error.withheld)
+            return "capability_disabled";
         if (message.startsWith("unknown_capability:"))
             return "unknown_capability";
         if (message.startsWith("unknown_endpoint:"))
@@ -812,7 +817,7 @@ export function addCapabilityRegistryTools(server, deps, config) {
         }
         catch (error) {
             if (error instanceof InvocationError)
-                return refuse("describeCapability", invocationReason(error.message), error.message, undefined, identity);
+                return refuse("describeCapability", invocationReason(error.message, error), error.message, undefined, identity);
             logger.error("describeCapability failed: %s", error instanceof Error ? error.message : String(error));
             return refuse("describeCapability", "unexpected_error", "that capability could not be described", undefined, identity);
         }
@@ -910,6 +915,17 @@ export function addCapabilityRegistryTools(server, deps, config) {
                 query: input.query,
                 body: input.body,
             };
+            if (capability.invocable === false) {
+                // THE ONE PLACE describe AND invoke DIVERGE, deliberately. Everywhere else a name
+                // that describes is a name that invokes, and breaking that is its own bug class —
+                // but a reference-only capability exists precisely to be read and not called. The
+                // refusal carries the instruction, because the note is the whole point of it
+                // still being published.
+                return refuse("invokeCapability", "capability_not_invocable", `${handle} cannot be called on this server. ` +
+                    (capability.guidance?.[0] ??
+                        "Describe it for what to do instead.") +
+                    " Follow that instead of retrying.", undefined, identity);
+            }
             if (capability.mode === "destructive") {
                 // Refused before binding, so consent is never sought for something that cannot run.
                 return refuse("invokeCapability", "destructive_blocked", `${handle} is a destructive operation and is not available through this surface`, undefined, identity);
@@ -932,7 +948,7 @@ export function addCapabilityRegistryTools(server, deps, config) {
                     return refuse("invokeCapability", "change_summary_missing", "change_summary is required: state what will change", undefined, identity);
                 }
             }
-            const result = await invoke(capability, args, await deps.baseUrlFor(product), deps.credentialsFor(), transport, registry.index.products[product]?.auth, product);
+            const result = await invoke(capability, args, await deps.baseUrlFor(product, capability.host), deps.credentialsFor(), transport, registry.index.products[product]?.auth, product);
             // The one row for a completed invoke. invoke() returns a 4xx/5xx rather than
             // throwing, so `success` keeps its tool-level meaning and these two fields carry
             // whether the product call worked. Status 0 means it could not be reached.
@@ -946,7 +962,7 @@ export function addCapabilityRegistryTools(server, deps, config) {
         }
         catch (error) {
             if (error instanceof InvocationError)
-                return refuse("invokeCapability", invocationReason(error.message), error.message, undefined, identity);
+                return refuse("invokeCapability", invocationReason(error.message, error), error.message, undefined, identity);
             logger.error("invokeCapability failed: %s", error instanceof Error ? error.message : String(error));
             return refuse("invokeCapability", "unexpected_error", "that capability could not be invoked", undefined, identity);
         }

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

@@ -16,6 +16,8 @@ import { invalidateToken } from "../../lib/central-oauth.js";
 import { bind } from "./bind.js";
 import { authHeaders } from "./egress.js";
 import { resolveScope, resolveTokenUrl } from "./oauth.js";
+import { openAsBlob } from "node:fs";
+import { basename } from "node:path";
 import { InvocationError } from "./index-loader.js";
 function hasNextPage(body) {
     if (typeof body !== "object" || body === null || Array.isArray(body))
@@ -63,6 +65,30 @@ function assertTransportSafe(baseUrl) {
         `carries your BrowserStack access key, so the base URL must be https (or a local ` +
         `host for development). Check CAPABILITY_REGISTRY_BASE_URL_* for a typo.`);
 }
+/**
+ * Turn a bound body into a FormData, streaming any `file` parameter from disk.
+ *
+ * `bind` has already canonicalised and checked the path, so what arrives here is a file
+ * this server is configured to read. The blob is opened rather than buffered: an app build
+ * runs to gigabytes and reading one into memory to post it is how a server falls over.
+ */
+async function multipartBody(capability, body) {
+    const form = new FormData();
+    for (const param of capability.body || []) {
+        const value = body?.[param.name];
+        if (value === undefined || value === null)
+            continue;
+        if (param.type === "file") {
+            const path = String(value);
+            const blob = await openAsBlob(path);
+            form.append(param.name, blob, basename(path));
+        }
+        else {
+            form.append(param.name, String(value));
+        }
+    }
+    return form;
+}
 export async function invoke(capability, args, baseUrl, credentials, transport, auth, product) {
     if (!baseUrl)
         throw new InvocationError("no base URL is configured for that product");
@@ -71,7 +97,22 @@ export async function invoke(capability, args, baseUrl, credentials, transport,
     // Before binding would be wrong and after sending is too late: a scheme that mints a
     // token must not spend a round trip on a call that `bind` was going to reject anyway.
     const url = `${baseUrl.replace(/\/$/, "")}${bound.path}`;
-    const send = async () => transport(capability.method, url, await authHeaders(credentials, auth, product), bound.query, bound.body);
+    const multipart = capability.encoding === "multipart"
+        ? await multipartBody(capability, bound.body)
+        : undefined;
+    const send = async () => {
+        const headers = await authHeaders(credentials, auth, product);
+        if (multipart) {
+            // fetch writes its own Content-Type with the boundary. Leaving the JSON one on sends
+            // a body the product cannot parse, under a header that says it should be able to.
+            delete headers["Content-Type"];
+        }
+        const payload = multipart ??
+            (bound.body === undefined && capability.send_empty_body
+                ? {}
+                : bound.body);
+        return transport(capability.method, url, headers, bound.query, payload);
+    };
     let response = await send();
     /**
      * One replay, for a minted token the product rejected.