@browserstack/mcp-server 2.0.0 → 2.2.0-beta.1

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

@@ -12,8 +12,10 @@
  * page-size parameter are published for paginated endpoints (see `project.py::_is_public`).
  * Hiding them made sense only while this module walked the pages itself.
  */
+import { invalidateToken } from "../../lib/central-oauth.js";
 import { bind } from "./bind.js";
 import { authHeaders } from "./egress.js";
+import { resolveScope, resolveTokenUrl } from "./oauth.js";
 import { InvocationError } from "./index-loader.js";
 function hasNextPage(body) {
     if (typeof body !== "object" || body === null || Array.isArray(body))
@@ -61,13 +63,32 @@ 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.`);
 }
-export async function invoke(capability, args, baseUrl, credentials, transport, auth) {
+export async function invoke(capability, args, baseUrl, credentials, transport, auth, product) {
     if (!baseUrl)
         throw new InvocationError("no base URL is configured for that product");
     assertTransportSafe(baseUrl);
     const bound = bind(capability, args);
-    const headers = authHeaders(credentials, auth);
-    const response = await transport(capability.method, `${baseUrl.replace(/\/$/, "")}${bound.path}`, headers, bound.query, bound.body);
+    // 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);
+    let response = await send();
+    /**
+     * One replay, for a minted token the product rejected.
+     *
+     * The expiry skirt covers clock skew; it does not cover a token revoked mid-life, and a
+     * cached one can outlive its welcome by up to its whole lifetime. Discarding it and
+     * retrying once turns that from a failed call into a slow one.
+     *
+     * SAFE TO REPLAY EVEN FOR A WRITE: a 401 means the request was never authorised, so
+     * nothing was changed. Once only — with genuinely bad credentials the second attempt
+     * fails identically, and a loop here would hammer the token endpoint on every wrong
+     * password.
+     */
+    if (response.status === 401 && auth?.type === "oauth2") {
+        invalidateToken(resolveTokenUrl(product ?? "this product", auth), resolveScope(auth), credentials);
+        response = await send();
+    }
     const ok = response.status >= 200 && response.status < 300;
     return {
         ok,

package/dist/tools/capability-registry/routing-token.d.ts

@@ -0,0 +1,25 @@
+/** What a routing call concluded about the user's request. */
+export interface RoutingVerdict {
+    /** `clash`: several products claim it. `blank`: no product's words at all. `settled`: one. */
+    verdict: "clash" | "blank" | "settled";
+    /** The product it settled on, for `settled`. */
+    product?: string;
+    /** The shared words, for `clash` — what the user has to be asked about. */
+    terms?: string[];
+    /** Issued-at, epoch seconds. */
+    iat: number;
+}
+/** Tokens outlive a turn, not a sitting. Long enough to answer a question, not to bank. */
+export declare const TOKEN_TTL_SECONDS: number;
+/** Sign a verdict into an opaque token the caller hands back. */
+export declare function signRouting(verdict: Omit<RoutingVerdict, "iat"> & {
+    iat?: number;
+}): string;
+/**
+ * Read a token back, or `undefined` if it was not issued here, was edited, or has expired.
+ *
+ * Every failure returns the same nothing on purpose: a caller learning WHY its token was
+ * rejected learns how to build a better one, and there is no legitimate caller that needs
+ * to know the difference.
+ */
+export declare function readRouting(token: string | undefined, now?: number): RoutingVerdict | undefined;

package/dist/tools/capability-registry/routing-token.js

@@ -0,0 +1,87 @@
+/**
+ * The routing step's verdict, signed so it can be handed back instead of remembered.
+ *
+ * The gate needs to know what the LAST routing call concluded — whether the request
+ * clashed, or settled, and on what. That is a fact about the conversation, and a tool call
+ * carries no conversation, so the server kept it: a set of unspent tokens and the listing's
+ * last verdict, both living for the life of the connection. Under stdio that is one process
+ * per client and harmless; it stops being harmless the moment one process serves several
+ * sessions, where a single shared `settledByListing` lets one client's listing satisfy
+ * another client's gate.
+ *
+ * So the verdict travels with the caller instead. It is signed with a per-process secret,
+ * which is what keeps it honest: the caller cannot mint one, cannot edit the product inside
+ * it, and cannot produce one at all without having made the routing call that issues it.
+ * Verification is recomputation — there is nothing to store, nothing to grow, and nothing
+ * to leak between sessions.
+ *
+ * WHAT THIS CANNOT DO, stated plainly: it proves a routing call happened and what it said.
+ * It cannot prove a human answered. Nothing a caller transmits can. A caller that reworded
+ * its request and ran discovery again on the new words holds a genuine token for a verdict
+ * it manufactured — closing THAT needs memory of the first question, which is the thing
+ * being removed here. `user_words`, checked against the index, remains the part that
+ * carries what the user actually said.
+ */
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+/**
+ * Per process, and deliberately not persisted.
+ *
+ * A restart invalidates every outstanding token, which is the right behaviour: a new
+ * process is a new conversation, and a verdict from the last one says nothing about this
+ * one. It also means nothing has to be configured to run the server.
+ */
+const SECRET = randomBytes(32);
+/** Tokens outlive a turn, not a sitting. Long enough to answer a question, not to bank. */
+export const TOKEN_TTL_SECONDS = 60 * 30;
+const b64 = (b) => b.toString("base64url");
+function seal(payload) {
+    return createHmac("sha256", SECRET).update(payload).digest("base64url");
+}
+/** Sign a verdict into an opaque token the caller hands back. */
+export function signRouting(verdict) {
+    const body = {
+        ...verdict,
+        iat: verdict.iat ?? Math.floor(Date.now() / 1000),
+    };
+    const payload = b64(Buffer.from(JSON.stringify(body)));
+    return `${payload}.${seal(payload)}`;
+}
+/**
+ * Read a token back, or `undefined` if it was not issued here, was edited, or has expired.
+ *
+ * Every failure returns the same nothing on purpose: a caller learning WHY its token was
+ * rejected learns how to build a better one, and there is no legitimate caller that needs
+ * to know the difference.
+ */
+export function readRouting(token, now = Math.floor(Date.now() / 1000)) {
+    if (!token)
+        return undefined;
+    const cut = token.lastIndexOf(".");
+    if (cut <= 0)
+        return undefined;
+    const payload = token.slice(0, cut);
+    const signature = token.slice(cut + 1);
+    const expected = Buffer.from(seal(payload));
+    const given = Buffer.from(signature);
+    // Length has to match before timingSafeEqual will look at the bytes, and comparing
+    // lengths first leaks only the length, which the caller already knows.
+    if (expected.length !== given.length)
+        return undefined;
+    if (!timingSafeEqual(expected, given))
+        return undefined;
+    try {
+        const body = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+        if (typeof body?.iat !== "number")
+            return undefined;
+        if (now - body.iat > TOKEN_TTL_SECONDS)
+            return undefined;
+        if (body.verdict !== "clash" &&
+            body.verdict !== "blank" &&
+            body.verdict !== "settled")
+            return undefined;
+        return body;
+    }
+    catch {
+        return undefined;
+    }
+}

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

@@ -105,12 +105,17 @@ export interface SearchResult {
     coverage: number;
     weak: boolean;
 }
-/** Which products a query could plausibly be about, when more than one could. */
 export interface ProductAmbiguity {
     /** The products that claim the query's words. Empty when the query settles itself. */
     products: string[];
     /** The shared vocabulary that caused it — what to put in front of the user. */
     terms: string[];
+    /** The one product the query's own words point at, when they point at exactly one. */
+    settled?: string;
+    /** The words that pointed there — the evidence for `settled`. */
+    because?: string[];
+    /** No word in the request belongs to ANY product: there is nothing to route on. */
+    unknown?: boolean;
 }
 /**
  * Products whose OWN vocabulary the query hits, when no word in the query settles it.
@@ -168,3 +173,25 @@ export declare function searchCapabilities(products: Record<string, ProductIndex
     limit?: number;
     offset?: number;
 }): SearchResult;
+export interface ProductAnchor {
+    /** Products the quoted words point at, through a word only that product claims. */
+    products: string[];
+    /** The words that did the anchoring, so a refusal can quote them back. */
+    terms: string[];
+}
+/**
+ * Which products the USER'S OWN WORDS name, directly or through vocabulary only one
+ * product claims.
+ *
+ * This is the other half of `ambiguousProducts`. That one asks "is the query a word both
+ * products use?"; this asks "did the user say anything that settles it?" — and it reads
+ * the user's text, not a flag the caller sets about itself. A boolean saying the user
+ * confirmed is answered by whoever wants to proceed; a quote has to come from the
+ * conversation, and the words in it are checked against the index here.
+ *
+ * Anchors are of two kinds and both are needed. A product NAME ("test management",
+ * "observability") is the explicit case. A word only one product's vocabulary claims
+ * ("quality gate", "test plan") is the implicit one, and it is the common one: users say
+ * what they want, not which product owns it.
+ */
+export declare function productAnchors(products: Record<string, ProductIndex>, text: string | undefined): ProductAnchor;

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

@@ -493,6 +493,25 @@ function score(capability, wanted, weights, aliases, hint, plural) {
 const WEAK_COVERAGE = 0.5;
 /** The heaviest field, and so the yardstick a perfect match is measured against. */
 const IDENTITY_WEIGHT = 6;
+// THE CROSS-PRODUCT FLOOR WAS HERE, and is gone with the thing that needed it.
+//
+// It reserved two slots per matching product so a small product could not be shut out by
+// a large one — tm has 173 capabilities to Load Testing's 20, and on a word both share
+// ("test", "config", "tag") tm took the whole page. "add a tag to xyz test" returned
+// tm tm LT tm tm, and an agent reading the first row went to the wrong product.
+//
+// `product` is now REQUIRED on searchCapability, so a search never spans products and the
+// floor could never fire. The bug it fixed is fixed harder: the agent chooses the product
+// deliberately against listProducts, or asks the user, instead of inferring it from which
+// row happened to rank first. Keeping the code would mean carrying a branch nothing
+// reaches and tests asserting behaviour the surface cannot produce.
+//
+// If searching across products ever returns — a "search everywhere" mode, or a caller
+// that legitimately cannot know the product — this comes back with it. It is in the
+// history at 617b4b9, and the reasoning above is why it was right.
+/** Which products a query could plausibly be about, when more than one could. */
+/** Words too common in this domain to settle a product on their own. */
+const GENERIC_ANCHORS = new Set(["test", "tests", "testing"]);
 /**
  * Products whose OWN vocabulary the query hits, when no word in the query settles it.
  *
@@ -539,17 +558,97 @@ export function ambiguousProducts(products, query) {
             }
         }
     }
+    // WORDS A PRODUCT OWNS WITHOUT MODELLING THEM. `routing_terms` is how a product claims
+    // what its users call it, as opposed to what it contains, and unlike a summary it MAY
+    // introduce a term: that is the whole point of it, since the words most in need of
+    // routing — `flaky` — are the ones no index names an entity after.
+    for (const [product, index] of Object.entries(products)) {
+        for (const word of index.routing_terms ?? []) {
+            const key = fold(String(word));
+            if (!key)
+                continue;
+            if (!owners.has(key))
+                owners.set(key, new Set());
+            owners.get(key).add(product);
+        }
+    }
+    // THE SUMMARY CAN ADD A CLAIMANT, NEVER A TERM.
+    //
+    // A product that models `view` as an entity and one that only describes views in its
+    // summary both answer questions about views, but only the first was visible here, so
+    // "delete the saved view" read as settled. Letting the summary claim a word the other
+    // product already models catches that, and refusing to mine NEW terms out of it is what
+    // keeps the prose from taking over: a summary is a paragraph of verbs and nouns written
+    // to sell the product, and every word in it would otherwise become routing vocabulary.
+    const summaries = Object.fromEntries(Object.entries(products).map(([product, index]) => [
+        product,
+        ` ${fold(index.summary ?? "")} `,
+    ]));
+    for (const [key, claimants] of owners) {
+        for (const [product, text] of Object.entries(summaries)) {
+            if (text.includes(` ${key} `))
+                claimants.add(product);
+        }
+    }
     const shared = new Map();
+    const decided = new Set();
+    const decidedBy = new Map();
     for (const [key, claimants] of owners) {
         if (!asked_.includes(` ${key} `))
             continue;
-        // A term only one product claims decides the query outright.
-        if (claimants.size < 2)
-            return none;
+        // A word this domain uses in every other sentence settles nothing and clashes over
+        // nothing: `test` is an alias on one side and appears throughout both summaries, so
+        // counting it would make almost any request look like a clash.
+        if (GENERIC_ANCHORS.has(key))
+            continue;
+        if (claimants.size < 2) {
+            // A term only one product claims POINTS somewhere; whether it decides the question
+            // depends on what else is in the sentence. It used to end the check outright, and
+            // that is what made this gate almost silent: an agent's paraphrase nearly always
+            // carries some incidental one-product word — `upload`, `saved report` — so the
+            // shared noun the user actually said stopped being examined. Worse, a sentence
+            // carrying one-product words for BOTH products read as settled, which is the case
+            // most in need of asking.
+            if (!GENERIC_ANCHORS.has(key)) {
+                const owner = [...claimants][0];
+                decided.add(owner);
+                decidedBy.set(owner, [...(decidedBy.get(owner) ?? []), key]);
+            }
+            continue;
+        }
         shared.set(key, claimants);
     }
+    // NOTHING RECOGNISED IS THE MOST AMBIGUOUS CASE, NOT THE LEAST.
+    //
+    // "Can we ship this?", "What should we fix first?", "Show me the failed tests." — no
+    // word in them is any product's, so the shared-term check finds nothing and used to
+    // report the same calm verdict it gives a request that genuinely settles itself. These
+    // are the requests with the least to go on, and answering them for a product nobody
+    // chose is exactly the guess this whole check exists to stop.
+    if (shared.size === 0 && decided.size === 0)
+        return { ...none, unknown: true };
+    // Decided, with no shared word anywhere in it — "bulk delete test cases". There is
+    // nothing to ask about, and saying WHICH product it landed on matters as much here as
+    // it does below: a caller that only hears "no clash" can still search the other one.
     if (shared.size === 0)
-        return none;
+        return decided.size === 1
+            ? {
+                ...none,
+                settled: [...decided][0],
+                because: (decidedBy.get([...decided][0]) ?? []).sort(),
+            }
+            : none;
+    // One product, and only one, is pointed at by the unshared words: the sentence answers
+    // itself and there is nothing to ask. It is still worth SAYING which one, because the
+    // caller sees only that nothing needs asking — "tell me about this project, including
+    // its settings" settles on the product that models settings, and an answer of silence
+    // let the other one be searched instead, which is the same wrong turn by a quieter route.
+    if (decided.size === 1)
+        return {
+            ...none,
+            settled: [...decided][0],
+            because: (decidedBy.get([...decided][0]) ?? []).sort(),
+        };
     const claimed = new Set();
     for (const claimants of shared.values())
         for (const product of claimants)
@@ -707,3 +806,102 @@ export function searchCapabilities(products, query, options = {}) {
         weak: wanted.length > 0 && perfect > 0 && coverage < WEAK_COVERAGE,
     };
 }
+/**
+ * Which products the USER'S OWN WORDS name, directly or through vocabulary only one
+ * product claims.
+ *
+ * This is the other half of `ambiguousProducts`. That one asks "is the query a word both
+ * products use?"; this asks "did the user say anything that settles it?" — and it reads
+ * the user's text, not a flag the caller sets about itself. A boolean saying the user
+ * confirmed is answered by whoever wants to proceed; a quote has to come from the
+ * conversation, and the words in it are checked against the index here.
+ *
+ * Anchors are of two kinds and both are needed. A product NAME ("test management",
+ * "observability") is the explicit case. A word only one product's vocabulary claims
+ * ("quality gate", "test plan") is the implicit one, and it is the common one: users say
+ * what they want, not which product owns it.
+ */
+export function productAnchors(products, text) {
+    const none = { products: [], terms: [] };
+    if (terms(text).length === 0)
+        return none;
+    const fold = (s) => terms(s).map(singular).join(" ");
+    const said = ` ${fold(text || "")} `;
+    const found = new Map();
+    const claim = (product, term) => {
+        if (!found.has(product))
+            found.set(product, new Set());
+        found.get(product).add(term);
+    };
+    // The product's own name and key, as a user would type them. `summary` is prose, not a
+    // name, so only the leading clause before ':' is used — "BrowserStack Test Management",
+    // "BrowserStack Test Reporting & Analytics (TRA, aka Test Observability)".
+    for (const [product, index] of Object.entries(products)) {
+        const names = [
+            product,
+            ...(index.summary ?? "").split(":")[0].split(/[(),]/),
+        ];
+        for (const name of names) {
+            // "aka Test Observability" is the product's other name with a connective in front
+            // of it; the user types the name, not the connective.
+            const key = fold(name.replace(/^\s*(browserstack|aka|formerly)\s+/i, ""));
+            if (key.length < 2)
+                continue;
+            if (said.includes(` ${key} `))
+                claim(product, key);
+        }
+    }
+    // Vocabulary only one product claims. Shared words settle nothing and are skipped —
+    // that is exactly what `ambiguousProducts` flagged in the first place.
+    const owners = new Map();
+    for (const [product, entries] of Object.entries(vocabularyOf(products))) {
+        for (const entry of entries) {
+            for (const word of [entry.entity, ...(entry.aliases ?? [])]) {
+                const key = fold(String(word));
+                if (!key)
+                    continue;
+                if (!owners.has(key))
+                    owners.set(key, new Set());
+                owners.get(key).add(product);
+            }
+        }
+    }
+    // The same words `ambiguousProducts` routes on, so a term that settles the question
+    // there also anchors the product here — otherwise `flaky` names a product in one half
+    // of the check and nothing at all in the other.
+    for (const [product, index] of Object.entries(products)) {
+        for (const word of index.routing_terms ?? []) {
+            const key = fold(String(word));
+            if (!key)
+                continue;
+            if (!owners.has(key))
+                owners.set(key, new Set());
+            owners.get(key).add(product);
+        }
+    }
+    const matched = [];
+    for (const [key, claimants] of owners) {
+        if (claimants.size !== 1)
+            continue;
+        if (!said.includes(` ${key} `))
+            continue;
+        matched.push({ key, product: [...claimants][0] });
+    }
+    for (const { key, product } of matched) {
+        // A word carried by nearly every request in this domain anchors nothing: tra's
+        // sp_test lists the bare word `test` as an alias, which would make "what test plans
+        // are active" read as tra on the strength of one noun that means nothing on its own.
+        if (GENERIC_ANCHORS.has(key))
+            continue;
+        // Longest match wins. "test management" and "test" both match the same sentence, and
+        // only the longer one carries the user's meaning — counting both makes a settled
+        // question look ambiguous again.
+        if (matched.some((other) => other.key !== key && ` ${other.key} `.includes(` ${key} `)))
+            continue;
+        claim(product, key);
+    }
+    return {
+        products: [...found.keys()].sort(),
+        terms: [...new Set([...found.values()].flatMap((s) => [...s]))].sort(),
+    };
+}

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

@@ -233,19 +233,58 @@ export interface PagingRule {
  * harness's `{ env: … }` value sources must NOT cross the boundary into the artifact.
  */
 export interface AuthScheme {
-    /** "apiKey" puts the rendered template in a header; "http" with scheme "basic" encodes it. */
-    type: "apiKey" | "http";
+    /**
+     * "apiKey" puts the rendered template in a header; "http" with scheme "basic" encodes it;
+     * "oauth2" exchanges the caller's credentials for a JWT and sends `Authorization: Bearer`.
+     *
+     * Each value fixes BOTH where the value comes from and how it is presented. Only `apiKey`
+     * carries `in`/`name`, because it is the only one with no convention for where it goes —
+     * RFC 6750 settles that for a bearer token, which is why OpenAPI's own `oauth2` scheme has
+     * no location fields either. `in`, `name` and `template` are REFUSED on `oauth2` rather
+     * than ignored, so an author who writes one gets an error instead of a silent 401.
+     */
+    type: "apiKey" | "http" | "oauth2";
     /** apiKey only. Header is the sole supported location — see `egress.authHeaders`. */
     in?: "header" | "cookie" | "query";
     /** apiKey only: the header name, e.g. "Api-Token". */
     name?: string;
     /** http only. */
     scheme?: string;
-    /** Defaults to `{username}:{access_key}`. */
+    /** apiKey/http only. Defaults to `{username}:{access_key}`. */
     template?: string;
+    /**
+     * oauth2 only: override the endpoint the JWT is minted at.
+     *
+     * Optional, and most products want the default. Bounded by an allowlist in `oauth.ts` —
+     * this field decides where the caller's credentials are POSTed, and an index is a data
+     * file that ships to public npm.
+     */
+    token_url?: string;
+    /**
+     * oauth2 only: override the scope set. Order is not significant; it is sorted and deduped
+     * before it reaches the grant or the token cache.
+     *
+     * There is deliberately no `flow` beside this. The server implements one grant, so a field
+     * with one legal value could distinguish nothing — and an unvalidated one would read as
+     * though it selected behaviour while selecting nothing.
+     */
+    scopes?: string[];
 }
 export interface ProductIndex {
     summary: string;
+    /**
+     * Words that route to this product but are not the name of anything in it.
+     *
+     * The entity names and their aliases are what a product CONTAINS; this is what its users
+     * CALL it when they ask for something. `flaky` is the clearest case: both indexes talk
+     * about flakiness and neither models it as an entity, so the word was invisible to
+     * routing and a question about it read as naming no product at all. The other half is
+     * the reverse — `workspace`, `team`, `setting` and `suite` belong to both products and
+     * happen to be modelled by one, which let an incidental word settle a question it had no
+     * business settling. Listing a word here is a claim about vocabulary only; it never adds
+     * a capability and never widens a search.
+     */
+    routing_terms?: string[];
     /**
      * How to authenticate to this product. Absent means the historical default: the caller's
      * credentials as `Api-Token: {username}:{access_key}`, which is what every shipped index

package/dist/tools/testmanagement.js

@@ -19,7 +19,7 @@ import { getTestPlan, GetTestPlanSchema, } from "./testmanagement-utils/get-test
 import { listSubTestPlans, ListSubTestPlansSchema, } from "./testmanagement-utils/list-sub-testplans.js";
 import { getSubTestPlan, GetSubTestPlanSchema, } from "./testmanagement-utils/get-sub-testplan.js";
 import { elicitCredentialsIfSupported } from "../lib/elicit-credentials.js";
-import { NEEDS_PROJECT_ID, NEEDS_TEST_PLAN_ID, PLAN_WRITES_VIA_AGENT, PROJECT_ID_ONLY_FOR_FOLDER, } from "./tool-handoff.js";
+import { NEEDS_PROJECT_ID, NEEDS_TEST_PLAN_ID, PLAN_WRITES_VIA_CAPABILITIES, PROJECT_ID_ONLY_FOR_FOLDER, } from "./tool-handoff.js";
 //TODO: Moving the traceMCP and catch block to the parent(server) function
 /**
  * Wrapper to call createProjectOrFolder util.
@@ -536,7 +536,7 @@ export default function addTestManagementTools(server, config) {
     }, (args, context) => createLCAStepsTool(args, context, config, server));
     tools.listTestPlans = server.tool("listTestPlans", "List test plans in a BrowserStack Test Management project. Returns each plan's identifier (TP-*), name, status, description, dates, and active/closed test-run counts. Supports pagination." +
         NEEDS_PROJECT_ID +
-        PLAN_WRITES_VIA_AGENT, ListTestPlansSchema.shape, {
+        PLAN_WRITES_VIA_CAPABILITIES, ListTestPlansSchema.shape, {
         title: "List Test Plans",
         readOnlyHint: true,
         openWorldHint: false,
@@ -546,7 +546,7 @@ export default function addTestManagementTools(server, config) {
     tools.getTestPlan = server.tool("getTestPlan", "Fetch a test plan by identifier (TP-*) from BrowserStack Test Management. Returns plan metadata, the full list of linked test runs, total test-case count across runs, and a status summary — suitable for generating test documentation or QA status reports." +
         NEEDS_PROJECT_ID +
         NEEDS_TEST_PLAN_ID +
-        PLAN_WRITES_VIA_AGENT, GetTestPlanSchema.shape, {
+        PLAN_WRITES_VIA_CAPABILITIES, GetTestPlanSchema.shape, {
         title: "Get Test Plan",
         readOnlyHint: true,
         openWorldHint: false,
@@ -556,7 +556,7 @@ export default function addTestManagementTools(server, config) {
     tools.listSubTestPlans = server.tool("listSubTestPlans", "List sub-test-plans under a parent test plan (TP-*) in a Test Management project. Supports pagination." +
         NEEDS_PROJECT_ID +
         NEEDS_TEST_PLAN_ID +
-        PLAN_WRITES_VIA_AGENT, ListSubTestPlansSchema.shape, {
+        PLAN_WRITES_VIA_CAPABILITIES, ListSubTestPlansSchema.shape, {
         title: "List Sub Test Plans",
         readOnlyHint: true,
         openWorldHint: false,
@@ -566,7 +566,7 @@ export default function addTestManagementTools(server, config) {
     tools.getSubTestPlan = server.tool("getSubTestPlan", "Fetch a sub-test-plan (STP-*) under a parent plan (TP-*). Returns metadata and linked test runs." +
         NEEDS_PROJECT_ID +
         NEEDS_TEST_PLAN_ID +
-        PLAN_WRITES_VIA_AGENT, GetSubTestPlanSchema.shape, {
+        PLAN_WRITES_VIA_CAPABILITIES, GetSubTestPlanSchema.shape, {
         title: "Get Sub Test Plan",
         readOnlyHint: true,
         openWorldHint: false,

package/dist/tools/tool-handoff.d.ts

@@ -8,7 +8,10 @@
  * where the missing identifier comes from.
  *
  * Point at a sibling tool whenever one can produce the id — it is faster and more
- * predictable than an agent. Point at `askBrowserStackAI` only when NO tool here can.
+ * predictable than anything that has to reason its way there. When no tool here can, point
+ * at the CAPABILITY FUNCTIONS: they reach the product's own API surface, so they answer the
+ * id question directly. Name them as a group, never individually — which function to call
+ * is their own business, and a name written here goes stale the moment one is renamed.
  *
  * The one that matters most: 15 of the 17 Test Management tools require a project
  * identifier and NONE of them accepts its absence, yet no tool in this server lists
@@ -35,21 +38,21 @@ export declare const NEEDS_TEST_PLAN_ID: string;
 /**
  * The ONLY capability handoff here: every other constant points at a tool that produces a
  * missing *id*, but plan WRITES have no tool at all — the surface is `listTestPlans`,
- * `getTestPlan`, `listSubTestPlans`, `getSubTestPlan` and nothing else. Atlas can do them
- * (the tm harness allows POST /api/v1/projects/{id}/test-plans plus /update, /delete,
- * /clone, /test-runs and /test-runs/unlink), so without this line the model reads the four
- * read tools, finds no create, and reports the capability as absent — which is exactly what
- * a QA eval concluded.
+ * `getTestPlan`, `listSubTestPlans`, `getSubTestPlan` and nothing else. The capability functions can do them
+ * (Test Management's own API covers creating, updating, cloning and deleting a plan, and
+ * linking or unlinking its runs), so without this line the model reads the four read tools,
+ * finds no create, and reports the capability as absent — which is exactly what a QA eval
+ * concluded.
  *
  * Deliberately narrow: it names the specific operations that are missing rather than
- * inviting the model to route plan work to the agent generally, because the tool
- * descriptions otherwise say to prefer a specific tool whenever one fits.
+ * inviting the model to route plan work elsewhere generally, because the tool descriptions
+ * otherwise say to prefer a specific tool whenever one fits.
  *
- * Caveat worth knowing: askBrowserStackAI pins every write to human approval, so this path
- * only completes on a client that can show a prompt. On one that cannot, the intended write
- * comes back in `needs_approval` instead of happening.
+ * Caveat worth knowing: a capability write is pinned to human approval, so this path only
+ * completes on a client that can show a prompt. On one that cannot, the intended write is
+ * refused rather than performed.
  */
-export declare const PLAN_WRITES_VIA_AGENT: string;
+export declare const PLAN_WRITES_VIA_CAPABILITIES: string;
 /** A build id comes from either build-lookup tool. */
 export declare const NEEDS_BUILD_ID: string;
 /**