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

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;
 /**

package/dist/tools/tool-handoff.js

@@ -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
@@ -21,8 +24,8 @@
  */
 /** No tool lists projects, so this genuinely has to go to the agent. */
 export const NEEDS_PROJECT_ID = " Requires a project identifier (PR-*). No tool here lists projects, so if you do not " +
-    'have one, call askBrowserStackAI with product "tm" and ask which projects exist, then ' +
-    "retry this tool with the identifier it returns.";
+    "have one, use the capability functions to list the Test Management projects, then " +
+    "retry this tool with the identifier they return.";
 /** A sibling tool can produce the id — prefer it over the agent. */
 export function needsIdFrom(idLabel, sourceTool) {
     return ` Requires ${idLabel}. Call ${sourceTool} first if you do not have it.`;
@@ -34,30 +37,30 @@ export function needsIdFrom(idLabel, sourceTool) {
  * "create me a project" through the agent before letting the tool run.
  */
 export const PROJECT_ID_ONLY_FOR_FOLDER = " Creating a project needs no identifier. Creating a folder inside an EXISTING project " +
-    "needs that project's identifier (PR-*); no tool here lists projects, so ask " +
-    'askBrowserStackAI with product "tm" for it.';
+    "needs that project's identifier (PR-*); no tool here lists projects, so use the " +
+    "capability functions to look it up.";
 /** A test plan id (TP-*) comes from listTestPlans. */
 export const NEEDS_TEST_PLAN_ID = needsIdFrom("a test plan identifier (TP-*)", "listTestPlans");
 /**
  * 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 const PLAN_WRITES_VIA_AGENT = " Creating a test plan or sub-plan, and linking or unlinking test runs on one, are not " +
-    'available as tools here: call askBrowserStackAI with product "tm" and describe what you ' +
-    "want. It asks you to confirm before changing anything.";
+export const PLAN_WRITES_VIA_CAPABILITIES = " Creating a test plan or sub-plan, and linking or unlinking test runs on one, are not " +
+    "available as tools here: use the capability functions, which reach Test Management's " +
+    "own API for these operations. They ask you to confirm before changing anything.";
 /** A build id comes from either build-lookup tool. */
 export const NEEDS_BUILD_ID = needsIdFrom("a BrowserStack build id", "getBuildId or listBuildId");
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserstack/mcp-server",
-  "version": "2.1.0",
+  "version": "2.2.0-beta.1",
   "description": "BrowserStack's Official MCP Server",
   "mcpName": "io.github.browserstack/mcp-server",
   "main": "dist/index.js",
@@ -19,6 +19,7 @@
     "check:contract": "python3 scripts/check-contract.py capability/tm.capability-index.json --baseline scripts/contract-baseline/tm.json --quiet",
     "eval:index": "tsx scripts/eval-index.mts",
     "seed:live": "tsx scripts/seed-live.mts",
+    "seed:live:tra": "tsx scripts/seed-live-tra.mts",
     "plan:tests": "tsx scripts/plan-capability-tests.mts",
     "replay:live": "tsx scripts/replay-live.mts"
   },

package/dist/tools/ask-browserstack/deferred.d.ts

@@ -1,74 +0,0 @@
-/**
- * The two-call shape: ask now, decide later, with nothing held open in between.
- *
- * WHY IT EXISTS. Elicitation is what makes this process stateful — a suspended
- * `elicitation/create` pins an McpServer in one pod's heap until the answer arrives, so
- * the hosted deployment needs sessions, ingress affinity keyed on the caller's
- * credentials, and a cap on how many sessions may be alive. Deferred removes the
- * suspension rather than routing around it: Atlas returns at its first ask, we hand that
- * ask back, and the caller returns with the decision in a SECOND call. Between the two
- * this process holds nothing, so any pod can serve either.
- *
- * WHAT IT COSTS, stated plainly because it is not free:
- *   - Approval rides the CLIENT's own permission prompt on the second call, not an
- *     elicitation. A client configured not to prompt (`--permission-mode auto`) approves
- *     with no human. Elicitation fails closed by construction; this fails closed only if
- *     the client asks. That is the trade, and it is why stdio keeps elicitation.
- *   - One extra round trip per APPROVAL, not per task. Atlas's gate is serial, so a task
- *     with five writes is five approvals and six calls.
- *
- * The run itself is parked on Atlas's side for the gate's own 300s, kept alive exactly as
- * a dropped reader leaves it (CONTRACT v2 §4.2). Nothing here has to manage that.
- */
-import { DeferredTransport } from "./stream.js";
-import { AgentRequest, AskResult, RelayMode } from "./types.js";
-/** What a parked run needs the caller to send back. */
-export interface ParkedAsk {
-    perm_id: string;
-    description: string;
-    product: string;
-    mode: string;
-}
-/**
- * Atlas's `needs_approval` payload → our result, or `null` when it is not one.
- *
- * Null rather than a throw: a deferred request whose run never needed approval comes
- * back as an ORDINARY result, and that is a success to pass straight through — not an
- * unexpected shape. A read-only task must cost one call, not two.
- */
-export declare function parkedResult(body: unknown, product: string): {
-    runId: string;
-    ask: ParkedAsk;
-} | null;
-/** CONTRACT §5's shape, for a run that is parked rather than finished. */
-export declare function needsApprovalResult(runId: string, ask: ParkedAsk, product: string): AskResult;
-/** The FIRST call: run until the first ask, then answer. Nothing is held open. */
-export declare function runDeferred(url: string, headers: Record<string, string>, body: AgentRequest, transport: DeferredTransport, mode: RelayMode, product: string): Promise<AskResult>;
-/**
- * The SECOND call: deliver the decision, then pick the run back up.
- *
- * Two requests, in this order, and the order is the safety property: the decision is
- * posted FIRST so that a reattach which then fails cannot leave the gate waiting on an
- * answer we already have. A lost reattach costs the caller the answer; a lost decision
- * would cost them the run.
- */
-export declare function runResumed(agentUrl: string, headers: Record<string, string>, runId: string, permId: string, decision: "allow" | "deny", transport: DeferredTransport, mode: RelayMode, product: string): Promise<AskResult>;
-/** A resume that did not happen. Every field says "nothing changed", because in each
- *  case nothing did — and a caller that cannot tell a failed resume from a refusal
- *  either retries a write that landed or abandons one that never did. */
-export declare function resumeFailed(error: string): AskResult;
-/** A decision that went out and whose reply never came back.
- *
- *  Deliberately NOT `resumeFailed`: every field there says "nothing changed", and that
- *  is a claim this case cannot make. The decision request carries the continuation now,
- *  so a lost reply covers everything from "it never arrived" to "the write landed and
- *  the answer was lost" — and telling a model nothing happened is what gets the change
- *  made twice.
- *
- *  `applied_before_stop: null` for the same reason: null is "not measured", which is
- *  true, where false would be a measurement nobody took. */
-export declare function decisionUnknown(): AskResult;
-/** Starting a run with no task. Only reachable now that `query` is optional, which it
- *  has to be so a model can follow `next_step` — which omits it — literally. */
-export declare function missingQuery(): AskResult;
-export declare function incompleteResume(): AskResult;