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

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

@@ -13,6 +13,7 @@
  * enforced HERE rather than on a client-side hint — which is the one thing a separate
  * read/write tool pair was buying.
  */
+import { signRouting, readRouting } from "./routing-token.js";
 import { z } from "zod";
 import logger from "../../logger.js";
 import { trackMCP } from "../../lib/instrumentation.js";
@@ -21,7 +22,7 @@ import { redact } from "./redact.js";
 import { fetchTransport } from "./egress.js";
 import { CapabilityRegistry, InvocationError, resolveResponses, } from "./index-loader.js";
 import { invoke } from "./resolve.js";
-import { ambiguousProducts, isBrowseQuery, searchCapabilities, singular, terms, vocabularyOf, } from "./search.js";
+import { ambiguousProducts, productAnchors, isBrowseQuery, searchCapabilities, singular, terms, vocabularyOf, } from "./search.js";
 export const PERMISSION_VALUES = ["not_asked", "granted", "denied"];
 /**
  * The search-side twin of `user_permission`: did a human choose the product, or did you?
@@ -155,6 +156,10 @@ export function addCapabilityRegistryTools(server, deps, config) {
         // likeliest refusal of all, and it was landing in the generic bucket.
         if (message.startsWith("capability_disabled:"))
             return "capability_disabled";
+        // Auth failed before the product was ever called, so it is not the product's 401 and
+        // must not be counted as one. oauth.ts prefixes every one of these.
+        if (message.startsWith("token_mint_failed:"))
+            return "token_mint_failed";
         if (message.startsWith("missing required parameter"))
             return "missing_parameter";
         if (/is not a usable path value/.test(message))
@@ -187,15 +192,122 @@ export function addCapabilityRegistryTools(server, deps, config) {
     tools.listProducts = server.tool("listProducts", "List the BrowserStack products this surface can reach: what each one does, the " +
         "entities it models, and a line saying what each entity is. START HERE — " +
         "searchCapability needs a product, and this is what tells you which one. If two " +
-        "products could both fit the task, ask the user rather than choosing for them.", {}, {
+        "products could both fit the task, ask the user rather than choosing for them. " +
+        "ALWAYS pass the user's request, in their own words, as `query`: the answer then " +
+        "says outright whether the products clash over the words in it. WHEN IT REPORTS A " +
+        "CLASH — two products claiming the same word for different things — ASK THE USER " +
+        "WHICH PRODUCT THEY MEAN AND WAIT FOR THEIR ANSWER BEFORE SEARCHING OR INVOKING " +
+        "ANYTHING. The response carries the question to put to them and what the shared " +
+        "word means in each product. Choosing for them, or searching each product in turn " +
+        "and merging the results, is the failure this call exists to prevent.", {
+        query: z
+            .string()
+            .optional()
+            .describe("The user's request, in their own words. With it the response carries a " +
+            "`routing` block saying whether the products share the vocabulary this " +
+            "request uses — and, when they do, the question to put to the user before " +
+            "searching either product."),
+    }, {
         title: "List Capability Products",
         readOnlyHint: true,
         destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false,
-    }, async () => {
+    }, async ({ query }) => {
         track("listProducts");
+        // THE CLASH, STATED RATHER THAN LEFT TO BE NOTICED. The entity lists below carry
+        // the evidence — `report` under two products — but reading two lists and spotting
+        // the overlap is work an agent skips when it already has a product in mind. So the
+        // overlap is computed here and put at the top, with the question already written:
+        // the cheap failure is picking one silently, and this is the call that precedes it.
+        const ambiguity = query
+            ? ambiguousProducts(registry.index.products, query)
+            : { products: [], terms: [] };
+        // A CLASH ANNOUNCED HERE BINDS THE NEXT SEARCH. Reporting it and then letting the
+        // very next call through was the gap the measured runs walked through: the agent
+        // read the clash, searched one product and then the other, and asked only
+        // afterwards. The gate downstream judges the caller's paraphrase when no user words
+        // are quoted, and a paraphrase carries none of the shared words that caused this —
+        // so the refusal never fired. Opening a token here makes the question outlive the
+        // call that raised it, and `user_words` is what closes it.
+        // THE VERDICT TRAVELS WITH THE CALLER. Signed here, read back by the search — which
+        // is how the search can know what this call concluded about the whole request
+        // without the server keeping a note between the two.
+        const listingToken = query
+            ? signRouting(ambiguity.products.length > 1
+                ? { verdict: "clash", terms: ambiguity.terms }
+                : ambiguity.unknown
+                    ? { verdict: "blank" }
+                    : { verdict: "settled", product: ambiguity.settled })
+            : undefined;
+        const routing = ambiguity.products.length > 1
+            ? {
+                verdict: "products_clash",
+                note: `These products clash over ${ambiguity.terms.map((t) => `'${t}'`).join(", ")} — ` +
+                    `the same word means something different in ${ambiguity.products.join(" and ")}. ` +
+                    "ASK THE USER which they mean before searching or invoking anything; do not " +
+                    "search each product in turn and merge the results. Searching before you " +
+                    "ask will be refused: send the user's answer in `user_words` with this " +
+                    "`routing_token`.",
+                routing_token: listingToken,
+                shared_terms: ambiguity.terms,
+                products: ambiguity.products,
+                question: `Which product do you mean — ${ambiguity.products.join(" or ")}?`,
+                senses: ambiguity.products.map((name) => ({
+                    product: name,
+                    means: ambiguity.terms
+                        .map((term) => {
+                        const entities = registry.index.products[name]?.entities ?? {};
+                        const key = Object.keys(entities).find((candidate) => [
+                            candidate,
+                            ...(entities[candidate].aliases ?? []),
+                        ].some((word) => terms(word).map(singular).join(" ") === term));
+                        return key
+                            ? {
+                                term,
+                                entity: key,
+                                description: entities[key].description,
+                            }
+                            : undefined;
+                    })
+                        .filter(Boolean),
+                })),
+            }
+            : query && ambiguity.unknown
+                ? {
+                    verdict: "no_vocabulary",
+                    note: "Nothing in this request names a product, or any word that belongs to " +
+                        "one — so there is no evidence here about which product is meant. This " +
+                        "is the LEAST settled a request can be, not the most. ASK THE USER " +
+                        "which product they mean before searching or invoking anything. " +
+                        "Searching before you ask will be refused: send their answer in " +
+                        "`user_words` with this `routing_token`.",
+                    routing_token: listingToken,
+                    question: `Which product do you mean — ${registry
+                        .productNames()
+                        .join(" or ")}?`,
+                }
+                : query
+                    ? {
+                        verdict: "no_clash",
+                        note: ambiguity.settled
+                            ? `This request names words only ${ambiguity.settled} claims` +
+                                (ambiguity.because?.length
+                                    ? ` (${ambiguity.because.map((t) => `'${t}'`).join(", ")})`
+                                    : "") +
+                                `, so it settles on ${ambiguity.settled} without asking. SEARCH ` +
+                                `${ambiguity.settled}; the other products do not answer this request.`
+                            : "No word in this request is claimed by more than one product, so the " +
+                                "entity lists below settle it without asking.",
+                        routing_token: listingToken,
+                        ...(ambiguity.settled ? { product: ambiguity.settled } : {}),
+                        ...(ambiguity.because?.length
+                            ? { deciding_terms: ambiguity.because }
+                            : {}),
+                    }
+                    : undefined;
         return ok({
+            ...(routing ? { routing } : {}),
             products: registry.productNames().map((name) => ({
                 name,
                 summary: registry.index.products[name].summary,
@@ -260,10 +372,11 @@ export function addCapabilityRegistryTools(server, deps, config) {
         return ok({ product, entity, ...doc });
     });
     tools.searchCapability = server.tool("searchCapability", "Find endpoints this surface can call, by plain language, within ONE product. " +
-        `You must say which: ${productList}. If the task does not name it unambiguously, ` +
-        "call listProducts first — it returns what each product does, the entities each " +
-        "models, and what every entity means, which is what settles the choice. Where two " +
-        "products use the same word for different things, ask the user rather than picking. " +
+        "CALL listProducts FIRST, passing the user's request as its `query`: it names the " +
+        "products, says whether they clash over the words in that request, and gives you " +
+        "the question to ask when they do. You need it anyway — `product` here takes a name " +
+        "exactly as listProducts spells it. Where two products use the same word for " +
+        "different things, ask the USER and wait for an answer rather than picking. " +
         "Search matches the product's OWN words, not synonyms. When your words are not the " +
         "product's, the response says so: `weak_match: true` with a `suggested_vocabulary` " +
         "map of the product's entities and their aliases. Results are still returned, but " +
@@ -306,19 +419,44 @@ export function addCapabilityRegistryTools(server, deps, config) {
         // not (run, project, report, result, folder, workspace, execution, history), where
         // the old behaviour was to silently pick whichever product ranked higher. A wasted
         // round trip against a silent wrong-product answer is not a close trade.
-        product: productArg().describe(`Which product to search: ${productList}. Call listProducts if the task does ` +
-            `not make it obvious, and ask the user when two products could both fit.`),
-        // REQUIRED, and self-reported, exactly like `user_permission` on a write. The
-        // server cannot see whether you asked anyone; what it can do is refuse to answer a
-        // question only the user can settle, and make claiming otherwise an explicit act
-        // rather than an omission.
-        product_choice: z
-            .enum(PRODUCT_CHOICE_VALUES)
-            .describe("'user_confirmed' only when the user named the product, or the task names it " +
-            "unmistakably. 'not_asked' otherwise — then a query that could mean either " +
-            "product is refused and told what to ask, instead of being answered for the " +
-            "wrong one. Never search each product in turn and merge the results: that is " +
-            "the guess this argument exists to prevent."),
+        // A FREE STRING, NOT AN ENUM, AND DELIBERATELY SO — this is the only argument on
+        // this surface that is. An enum publishes the product names in the schema, which
+        // every client shows the model before it calls anything, so a model that has never
+        // called listProducts already knows `tm` and `tra` exist and picks one. Measured:
+        // on the requests that still routed silently, listProducts was never called at all
+        // — there was nothing left to learn from it. Withholding the names makes the
+        // discovery call the only way to obtain one, and discovery is where the clash gets
+        // reported. The cost is losing client-side validation of a typo; an unknown name is
+        // refused here instead, by a message that names listProducts.
+        product: z
+            .string()
+            .describe("Which product to search, named exactly as listProducts spells it. Call " +
+            "listProducts with the user's request to get the name — and to find out " +
+            "whether the products clash over it, in which case ask the user first."),
+        // `product_choice` USED TO LIVE HERE, AND WAS ITS OWN DEFEAT.
+        //
+        // A required enum of 'user_confirmed' | 'not_asked' publishes, in the schema every
+        // client shows the model before it calls anything, the exact string that opens the
+        // gate. Measured on the prompts that still routed silently: the caller wrote
+        // `user_confirmed` on every single one, with no user input behind any of them. A
+        // flag the caller fills in about itself can always be filled in; there is no wording
+        // of it that makes it true. What replaced it is a token this server mints and the
+        // caller cannot guess, plus `user_words`, which is a claim the index can test.
+        routing_token: z
+            .string()
+            .optional()
+            .describe("The `routing_token` from the last listProducts call or product_ambiguous " +
+            "refusal — it carries what that step concluded about the user's request, " +
+            "signed. Always pass the most recent one. When it reports a clash, send the " +
+            "user's answer in `user_words` alongside it; neither works alone."),
+        user_words: z
+            .string()
+            .optional()
+            .describe("The USER'S OWN words, verbatim, that settle which product this is — either " +
+            "the product's name or a term only one product uses ('quality gate', 'test " +
+            "plan'). Quote them; do not paraphrase, and do not write words the user did " +
+            "not say. When a query could mean either product this is what lifts the " +
+            "refusal, because it is checked against the index rather than taken on trust."),
         mode: z
             .enum(["read", "write", "destructive"])
             .optional()
@@ -335,7 +473,7 @@ export function addCapabilityRegistryTools(server, deps, config) {
         destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false,
-    }, async ({ query, entity, product, product_choice, mode, limit, offset }) => {
+    }, async ({ query, entity, product, routing_token, user_words, mode, limit, offset, }) => {
         // THE GATE. Nothing here can tell whether a human was asked — same as the write
         // gate, which also takes the caller's word. What it can do is refuse to answer a
         // question that is genuinely the user's, so that answering it anyway takes a
@@ -349,18 +487,106 @@ export function addCapabilityRegistryTools(server, deps, config) {
         // contains no word to be ambiguous about — `*` names nothing — so there is nothing
         // to ask, and asking anyway would block the one query whose whole purpose is to
         // show what a product contains.
-        if (product_choice !== "user_confirmed" &&
-            !entity &&
-            !isBrowseQuery(query)) {
-            const ambiguity = ambiguousProducts(registry.index.products, query);
-            if (ambiguity.products.length > 1) {
-                // EVERYTHING NEEDED TO ASK, IN THE REFUSAL. Telling the agent to go and call
+        // `product_choice` is the caller describing itself, and a caller that wants to
+        // proceed says user_confirmed — measured at 103 of 183 ambiguous prompts with no
+        // user input behind it, which skipped this gate entirely. So under the flag the
+        // ambiguity check runs whatever the flag says, and what lifts it is `user_words`:
+        // the user's own text, checked here against the index. Quoting the conversation is
+        // a claim the server can test; a boolean is not.
+        // `entity` USED TO BYPASS THIS TOO, and had no business doing so. An entity narrows
+        // WITHIN a product; it says nothing about WHICH product, and the four names both
+        // products carry — project, report, test_run, comment — are precisely the ones the
+        // clash is about. `entity: "report"` alongside a guessed product is the silent pick
+        // this gate exists to stop, stated more confidently, so it skipped the check at the
+        // exact moment the check mattered.
+        // `product` is a free string now, so an unknown name reaches the handler. Refuse it
+        // where the caller can act on it: naming listProducts, which is where the real names
+        // come from, rather than returning an empty search that reads as "nothing matched".
+        if (!registry.index.products[product]) {
+            return refuse("searchCapability", "unknown_product", `No product named '${product}'. Call listProducts — passing the user's request ` +
+                "as `query` — for the names, and for whether the products clash over it.", {}, { product });
+        }
+        if (!isBrowseQuery(query)) {
+            // JUDGE THE USER'S WORDS, NOT THE AGENT'S REWRITE.
+            //
+            // `query` is the caller's paraphrase into product vocabulary, so the caller
+            // decides, through its own phrasing, whether this check fires: "what did the last
+            // report say?" became "list saved reports", and `saved report` is tra-only, so the
+            // shared word the user actually said stopped being examined. It is also the escape
+            // from a refusal — reword and try again, which is what the measured runs did. The
+            // user's text is the one input the caller cannot rewrite without quoting something
+            // different, and `productAnchors` checks what it quotes against this index.
+            const subject = user_words?.trim() ? user_words : query;
+            const ambiguity = ambiguousProducts(registry.index.products, subject);
+            // ALWAYS, NOT ONLY UNDER THE FLAG. With the self-reported flag gone, quoting the
+            // user is the only way past a clash, so the check that reads the quote has to run
+            // on both paths — otherwise the default path refuses with no way out at all. The
+            // flag now governs the stricter refusals (a blank request, a clash still open),
+            // not whether the user's own words count.
+            const anchor = productAnchors(registry.index.products, user_words);
+            // WHAT THE ROUTING STEP CONCLUDED, READ BACK OFF THE CALLER. The token is signed
+            // here and verified by recomputation, so the server keeps no note between the two
+            // calls — and the caller cannot write one, edit the product inside it, or hold one
+            // without having made the routing call that issues it.
+            const routed = readRouting(routing_token);
+            // A clash the routing step already reported is only cleared by the user's own
+            // words: the token shows the question was put, `user_words` says what came back.
+            // Neither works alone — a token on its own is just proof of having been refused.
+            const answered = routed?.verdict !== "settled" &&
+                anchor.products.length === 1 &&
+                anchor.products[0] === product;
+            // One product anchored, and it is the one being searched: the user settled it.
+            // A routing step that already settled on this product counts the same way — it
+            // read the user's whole request, which is more than the fragment quoted here.
+            const settled = (anchor.products.length === 1 && anchor.products[0] === product) ||
+                (routed?.verdict === "settled" && routed.product === product);
+            // NOTHING TO ASK WHEN THERE IS NOTHING TO CHOOSE BETWEEN. A registry serving one
+            // product cannot route a request to the wrong one, so every refusal below is a
+            // question with a single possible answer — pure obstruction.
+            const routable = registry.productNames().length > 1;
+            // A CLASH THE CALLER IS CARRYING IS STILL OPEN UNTIL IT IS ANSWERED, whatever this
+            // call's wording looks like. It has to outlive a REWORDING of the request — the
+            // escape it exists to close — while leaving a genuinely different request alone:
+            // "bulk delete test cases" names a thing only one product has, and blocking it
+            // because something earlier was ambiguous is obstruction, not routing.
+            const reopened = routable &&
+                !settled &&
+                !answered &&
+                ambiguity.settled !== product &&
+                (routed?.verdict === "clash" || routed?.verdict === "blank");
+            // THE WORDS POINT SOMEWHERE ELSE, WHICH IS EVIDENCE, NOT NOISE. A request whose
+            // own vocabulary settles on one product, sent as a search of the OTHER one, is the
+            // silent wrong pick this gate exists to catch — and it used to pass, because the
+            // checks above only ask whether the request settles, never whether it settles on
+            // what is being asked for. `product` is the caller's conclusion; the words are the
+            // evidence, and when they disagree the evidence is the thing to go on. The refusal
+            // already had the sentence for it ("the words you quoted point at X, not Y") and
+            // nothing could reach it.
+            const mismatch = routable && !!ambiguity.settled && ambiguity.settled !== product;
+            // NOTHING RECOGNISED IS NOT PERMISSION TO PICK. A request carrying no product's
+            // vocabulary is the least settled kind there is, and it used to pass this gate
+            // untouched because there was no shared word in it to object to.
+            const blank = routable && ambiguity.unknown && !settled;
+            if (routable &&
+                (ambiguity.products.length > 1 || reopened || blank || mismatch) &&
+                !settled &&
+                !answered) {
+                const token = signRouting(ambiguity.products.length > 1
+                    ? { verdict: "clash", terms: ambiguity.terms }
+                    : mismatch
+                        ? { verdict: "settled", product: ambiguity.settled }
+                        : { verdict: "blank" });
+                // WHAT TO ASK, NOT JUST THAT ASKING IS NEEDED. Sending the caller back to
                 // listProducts costs a round trip and still leaves it composing a question out
                 // of nothing — so it tends to guess instead, which is the behaviour being
-                // stopped. What makes the choice answerable is what each product calls the
-                // shared word and what it means THERE: tm's project owns folders and test
-                // cases, Load Testing's does not.
-                const options = ambiguity.products.map((name) => {
+                // stopped. What makes the choice answerable is what each product CALLS the
+                // shared word and what it means there.
+                const choices = ambiguity.products.length
+                    ? ambiguity.products
+                    : mismatch
+                        ? [ambiguity.settled, product]
+                        : registry.productNames();
+                const options = choices.map((name) => {
                     const entities = registry.index.products[name]?.entities ?? {};
                     const senses = ambiguity.terms
                         .map((term) => {
@@ -380,19 +606,41 @@ export function addCapabilityRegistryTools(server, deps, config) {
                         ...(senses.length ? { shared_terms: senses } : {}),
                     };
                 });
-                return refuse("searchCapability", "product_ambiguous", `'${query}' could mean ${ambiguity.products.join(" or ")} — ` +
-                    `${ambiguity.terms.map((t) => `'${t}'`).join(", ")} ` +
-                    `${ambiguity.terms.length === 1 ? "belongs" : "belong"} to both. ` +
-                    "Put the choice in `clarify` to the USER in their own terms, wait for an " +
-                    "answer, then resend with product_choice='user_confirmed'. Do NOT search " +
-                    "each product in turn and merge the results — that answers the question " +
-                    "instead of asking it.", {
+                const named = anchor.products.length > 0;
+                return refuse("searchCapability", "product_ambiguous", (blank
+                    ? `Nothing in '${subject}' names a product, or any word that belongs to ` +
+                        "one, so there is no evidence here about which one is meant — that is " +
+                        "the least settled a request can be, not the most. "
+                    : mismatch
+                        ? `'${subject}' names words only ${ambiguity.settled} claims` +
+                            (ambiguity.because?.length
+                                ? ` (${ambiguity.because.map((t) => `'${t}'`).join(", ")})`
+                                : "") +
+                            `, so the request points at ${ambiguity.settled}, not ${product}. ` +
+                            "Search the product the words name, or — if the user meant " +
+                            `${product} — get them to say so and quote them. `
+                        : `'${subject}' could mean ${ambiguity.products.join(" or ")} — ` +
+                            `${ambiguity.terms.map((t) => `'${t}'`).join(", ")} ` +
+                            `${ambiguity.terms.length === 1 ? "belongs" : "belong"} to both. `) +
+                    (named
+                        ? `The words you quoted (${anchor.terms.map((t) => `'${t}'`).join(", ")}) ` +
+                            `point at ${anchor.products.join(" and ")}, not ${product}. `
+                        : user_words
+                            ? "Nothing in the words you quoted names a product or a term only one " +
+                                "product uses. "
+                            : "Send `user_words` — the user's OWN words naming the product, or a " +
+                                "term only one product uses — or ask them. ") +
+                    "Put the choice to the USER in their own terms, wait for an answer, then " +
+                    "resend with their words in `user_words` AND `routing_token` set to the " +
+                    "token below. Rewording this query will not get past here. Do NOT search " +
+                    "each product in turn and merge the results.", {
+                    routing_token: token,
                     clarify: {
-                        question: `Which product do you mean — ${ambiguity.products.join(" or ")}?`,
+                        question: `Which product do you mean — ${choices.join(" or ")}?`,
                         shared: ambiguity.terms,
                         options,
                     },
-                }, { product: ambiguity.products.join("+") });
+                }, { product: ambiguity.products.join("+") || "none" });
             }
         }
         const { hits, weak, top_matched, ...rest } = searchCapabilities(registry.index.products, query, {
@@ -684,7 +932,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);
+            const result = await invoke(capability, args, await deps.baseUrlFor(product), 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.

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

@@ -35,4 +35,4 @@ export interface InvokeResult {
         error?: string;
     };
 }
-export declare function invoke(capability: Capability, args: GroupedArguments, baseUrl: string, credentials: Credentials, transport: Transport, auth?: AuthScheme): Promise<InvokeResult>;
+export declare function invoke(capability: Capability, args: GroupedArguments, baseUrl: string, credentials: Credentials, transport: Transport, auth?: AuthScheme, product?: string): Promise<InvokeResult>;

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;