@browserstack/mcp-server 1.4.0-beta.2 → 1.5.0-beta.1

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

@@ -1,116 +0,0 @@
-/**
- * CONTRACT v2 (A1) — read the ask off the response, send the decision separately.
- *
- * WHY THIS REPLACES THE CALLBACK. `callback.ts` binds `127.0.0.1:<ephemeral>` and hands
- * Atlas the URL. That works only when Atlas is on the same loopback. For a real user it
- * cannot work at all: this server runs on their machine, and a laptop behind NAT is not
- * addressable from a pod in BrowserStack's cluster. There is no route, and no
- * configuration creates one. Every successful relay run to date used a locally-run
- * Atlas — the shape the v1 contract was written for, and not the shape a user is in.
- *
- * A1 inverts it. Both connections are outbound from here:
- *
- *   1. `POST /agent` — the response is an SSE stream carrying `run`, then any
- *      `permission` asks, then exactly one `result`.
- *   2. `POST /agent/{run_id}/permission` — a fresh short request per decision.
- *
- * So NAT, firewalls and loopback stop mattering, because nothing ever dials in.
- *
- * WHAT THIS FILE DELIBERATELY DOES NOT DO: decide anything. Whether a human approved,
- * how an elicitation outcome maps to allow/deny, what the result looks like — all of
- * that stays in `relay.ts`, untouched, and is shared with the callback transport. This
- * is a pipe. Keeping the judgement out of the transport is why swapping A2 for A1 does
- * not risk the fail-closed behaviour.
- */
-import type { AgentRequest, PermissionAsk } from "./types.js";
-/** One SSE frame, already parsed. `data` is whatever JSON the frame carried. */
-export interface StreamEvent {
-    event: string;
-    data: unknown;
-    /**
-     * The HTTP status, carried ONLY on a `result` synthesised from a non-stream reply.
-     *
-     * Load-bearing, and it was a bug to omit it. `relay.ts` reads the status to tell a
-     * rejected credential (401) from an account without the feature (403) from an
-     * ordinary failure, and those produce three different sentences for the user. A
-     * result event that dropped the status made every one of them read as a generic
-     * error. On a real SSE stream the status is 200 by definition, so this is absent.
-     */
-    status?: number;
-}
-/**
- * CONTRACT v2 §4 — the whole-run guard, so a runaway run cannot hold a tool call open
- * forever. Deliberately generous: it is a backstop against a hung server, not a budget
- * for a human's attention, and the thing that actually bounds one approval is Atlas's
- * 300s gate.
- */
-export declare const WHOLE_RUN_TIMEOUT_MS = 1800000;
-export declare const EVENT_RUN = "run";
-export declare const EVENT_PERMISSION = "permission";
-export declare const EVENT_RESULT = "result";
-/** Atlas's `f"perm-{uuid.uuid4().hex}"`, and nothing else. */
-export declare const PERM_ID_PATTERN: RegExp;
-/**
- * Read an ask out of a `permission` frame's data, or return null.
- *
- * Came over from the transport this one replaced, and the reasons it existed did not
- * change with the transport — only the direction the ask arrives from did. It is not a
- * trust check on Atlas: it is what keeps a malformed frame from turning into a prompt
- * that cannot be honoured.
- *
- * A blank description is rejected rather than relayed: the description IS the whole of
- * what the human is shown, so an empty one is a prompt asking a person to approve
- * nothing. A `perm_id` off Atlas's shape is rejected because it is the only thing that
- * routes the answer back — the decision endpoint matches on it, so an id we could not
- * have received is an answer that can never be delivered.
- *
- * Only the four fields of CONTRACT §2 are carried forward. `op_key`, `method`, `path`
- * and `host` are Atlas-private (v1.1 §A) and it does not send them; if a future one
- * ever did, they would stop here rather than reach an elicitation prompt or a result.
- */
-export declare function parseAsk(data: unknown): PermissionAsk | null;
-/**
- * The transport seam: the shape `AgentTransport` had before A2 was removed, except that it
- * yields many events instead of returning one body. Injectable for the same reason that one
- * was: the tests must be able to drive a whole approval round trip without a socket.
- */
-export type AgentStreamTransport = (url: string, headers: Record<string, string>, body: AgentRequest) => AsyncIterable<StreamEvent>;
-/** Posts one decision. Separate seam because it is a separate connection. */
-export type DecisionTransport = (url: string, headers: Record<string, string>, body: {
-    perm_id: string;
-    decision: string;
-    reason: string;
-}) => Promise<number>;
-/**
- * Split a buffer into complete SSE frames, returning the leftover.
- *
- * Exported for its own tests because chunk boundaries are where SSE parsers break: a
- * frame can arrive split across two reads, two frames can arrive in one read, and a
- * `data:` line can contain anything except a newline. Getting this wrong shows up as an
- * ask that is silently dropped — a write that never gets approved and never explains
- * why — so it is tested directly rather than only through the happy path.
- */
-export declare function splitFrames(buffer: string): {
-    frames: string[];
-    rest: string;
-};
-/**
- * Parse one frame. Returns null for anything that is not an event we can use —
- * including the heartbeat, which is a bare `:` comment and is SUPPOSED to be ignored
- * here: its only job is to be a read on the socket so the ingress does not time the
- * connection out while a human is thinking.
- */
-export declare function parseFrame(frame: string): StreamEvent | null;
-/**
- * A fetch-based streaming transport.
- *
- * `timeoutMs` bounds the WHOLE run, not one request — CONTRACT v2 §4 replaced the old
- * 330s outer rung because under A1 the stream lives for the run and may contain several
- * 300s approvals in series. The per-ask rung (270s elicitation inside Atlas's 300s gate)
- * is unchanged and still enforced where it belongs.
- */
-export declare function fetchAgentStreamTransport(timeoutMs?: number): AgentStreamTransport;
-/** The decision POST. 30s, because it is an ordinary short request. */
-export declare function fetchDecisionTransport(timeoutMs?: number): DecisionTransport;
-/** `POST /agent/{run_id}/permission`, built from the base URL the tool already resolved. */
-export declare function decisionUrl(agentUrl: string, runId: string): string;

package/dist/tools/ask-browserstack/stream.js

@@ -1,237 +0,0 @@
-/**
- * CONTRACT v2 (A1) — read the ask off the response, send the decision separately.
- *
- * WHY THIS REPLACES THE CALLBACK. `callback.ts` binds `127.0.0.1:<ephemeral>` and hands
- * Atlas the URL. That works only when Atlas is on the same loopback. For a real user it
- * cannot work at all: this server runs on their machine, and a laptop behind NAT is not
- * addressable from a pod in BrowserStack's cluster. There is no route, and no
- * configuration creates one. Every successful relay run to date used a locally-run
- * Atlas — the shape the v1 contract was written for, and not the shape a user is in.
- *
- * A1 inverts it. Both connections are outbound from here:
- *
- *   1. `POST /agent` — the response is an SSE stream carrying `run`, then any
- *      `permission` asks, then exactly one `result`.
- *   2. `POST /agent/{run_id}/permission` — a fresh short request per decision.
- *
- * So NAT, firewalls and loopback stop mattering, because nothing ever dials in.
- *
- * WHAT THIS FILE DELIBERATELY DOES NOT DO: decide anything. Whether a human approved,
- * how an elicitation outcome maps to allow/deny, what the result looks like — all of
- * that stays in `relay.ts`, untouched, and is shared with the callback transport. This
- * is a pipe. Keeping the judgement out of the transport is why swapping A2 for A1 does
- * not risk the fail-closed behaviour.
- */
-import logger from "../../logger.js";
-import { AskError } from "./config.js";
-/**
- * CONTRACT v2 §4 — the whole-run guard, so a runaway run cannot hold a tool call open
- * forever. Deliberately generous: it is a backstop against a hung server, not a budget
- * for a human's attention, and the thing that actually bounds one approval is Atlas's
- * 300s gate.
- */
-export const WHOLE_RUN_TIMEOUT_MS = 1_800_000;
-export const EVENT_RUN = "run";
-export const EVENT_PERMISSION = "permission";
-export const EVENT_RESULT = "result";
-/** Atlas's `f"perm-{uuid.uuid4().hex}"`, and nothing else. */
-export const PERM_ID_PATTERN = /^perm-[0-9a-f]{32}$/;
-/**
- * Read an ask out of a `permission` frame's data, or return null.
- *
- * Came over from the transport this one replaced, and the reasons it existed did not
- * change with the transport — only the direction the ask arrives from did. It is not a
- * trust check on Atlas: it is what keeps a malformed frame from turning into a prompt
- * that cannot be honoured.
- *
- * A blank description is rejected rather than relayed: the description IS the whole of
- * what the human is shown, so an empty one is a prompt asking a person to approve
- * nothing. A `perm_id` off Atlas's shape is rejected because it is the only thing that
- * routes the answer back — the decision endpoint matches on it, so an id we could not
- * have received is an answer that can never be delivered.
- *
- * Only the four fields of CONTRACT §2 are carried forward. `op_key`, `method`, `path`
- * and `host` are Atlas-private (v1.1 §A) and it does not send them; if a future one
- * ever did, they would stop here rather than reach an elicitation prompt or a result.
- */
-export function parseAsk(data) {
-    if (typeof data !== "object" || data === null || Array.isArray(data))
-        return null;
-    const record = data;
-    const permId = record.perm_id;
-    const description = record.description;
-    if (typeof permId !== "string" || !PERM_ID_PATTERN.test(permId))
-        return null;
-    if (typeof description !== "string" || !description.trim())
-        return null;
-    return {
-        perm_id: permId,
-        product: typeof record.product === "string" ? record.product : "",
-        mode: typeof record.mode === "string" ? record.mode : "",
-        description,
-    };
-}
-/**
- * Split a buffer into complete SSE frames, returning the leftover.
- *
- * Exported for its own tests because chunk boundaries are where SSE parsers break: a
- * frame can arrive split across two reads, two frames can arrive in one read, and a
- * `data:` line can contain anything except a newline. Getting this wrong shows up as an
- * ask that is silently dropped — a write that never gets approved and never explains
- * why — so it is tested directly rather than only through the happy path.
- */
-export function splitFrames(buffer) {
-    const frames = [];
-    let rest = buffer;
-    for (;;) {
-        const idx = rest.indexOf("\n\n");
-        if (idx === -1)
-            break;
-        frames.push(rest.slice(0, idx));
-        rest = rest.slice(idx + 2);
-    }
-    return { frames, rest };
-}
-/**
- * Parse one frame. Returns null for anything that is not an event we can use —
- * including the heartbeat, which is a bare `:` comment and is SUPPOSED to be ignored
- * here: its only job is to be a read on the socket so the ingress does not time the
- * connection out while a human is thinking.
- */
-export function parseFrame(frame) {
-    let event = "";
-    const dataLines = [];
-    for (const line of frame.split("\n")) {
-        if (line.startsWith(":"))
-            continue; // comment / heartbeat
-        if (line.startsWith("event:"))
-            event = line.slice(6).trim();
-        else if (line.startsWith("data:"))
-            dataLines.push(line.slice(5).trim());
-    }
-    if (!event)
-        return null;
-    if (dataLines.length === 0)
-        return { event, data: null };
-    try {
-        return { event, data: JSON.parse(dataLines.join("\n")) };
-    }
-    catch {
-        // A frame we cannot read is not a frame we may guess at. Dropping it is safe
-        // because the only consequence is that an ask goes unanswered and the gate denies
-        // on its own expiry — never that something is approved.
-        logger.warn("askBrowserStackAI: unparseable stream frame, ignoring");
-        return null;
-    }
-}
-/**
- * A fetch-based streaming transport.
- *
- * `timeoutMs` bounds the WHOLE run, not one request — CONTRACT v2 §4 replaced the old
- * 330s outer rung because under A1 the stream lives for the run and may contain several
- * 300s approvals in series. The per-ask rung (270s elicitation inside Atlas's 300s gate)
- * is unchanged and still enforced where it belongs.
- */
-export function fetchAgentStreamTransport(timeoutMs = WHOLE_RUN_TIMEOUT_MS) {
-    return function stream(url, headers, body) {
-        return {
-            async *[Symbol.asyncIterator]() {
-                const controller = new AbortController();
-                const timer = setTimeout(() => controller.abort(), timeoutMs);
-                try {
-                    let response;
-                    try {
-                        response = await fetch(url, {
-                            method: "POST",
-                            headers: { ...headers, Accept: "text/event-stream" },
-                            body: JSON.stringify(body),
-                            // A redirect from an authenticated API is usually a login bounce, and
-                            // following it turns a clear 401 into a 200 carrying an HTML page.
-                            redirect: "manual",
-                            signal: controller.signal,
-                        });
-                    }
-                    catch {
-                        // The same sentence the request/response transport gives, and for the same
-                        // reason: the upstream detail ("connection reset", "fetch failed") names our
-                        // plumbing rather than anything the reader can act on, and letting it through
-                        // once already produced a result that read like the user had done something
-                        // wrong. What they need to know is that BrowserStack was not reachable.
-                        throw new AskError("BrowserStack AI could not be reached");
-                    }
-                    const contentType = response.headers.get("content-type") || "";
-                    // GRACEFUL DEGRADE, and the reason A1 is safe to ship before Atlas has it
-                    // everywhere: an Atlas that does not know `mode: "stream"` answers with an
-                    // ordinary JSON body (a read-only run, `permission_relay.reason: "disabled"`).
-                    // Yielding it as a single `result` means the caller needs no version
-                    // negotiation and no flag — it gets a correct read-only answer instead of a
-                    // parse failure against a body that was never SSE.
-                    if (contentType.includes("json")) {
-                        const parsed = await response.json().catch(() => null);
-                        yield {
-                            event: EVENT_RESULT,
-                            data: parsed,
-                            status: response.status,
-                        };
-                        return;
-                    }
-                    if (!response.ok || !response.body) {
-                        // Neither a stream nor a JSON result. Surface it as a first-class failure
-                        // rather than an empty iteration, which the caller could not tell apart
-                        // from "the run finished and said nothing".
-                        throw new AskError(`BrowserStack AI refused the stream (HTTP ${response.status}).`);
-                    }
-                    const decoder = new TextDecoder();
-                    let buffer = "";
-                    for await (const chunk of response.body) {
-                        buffer += decoder.decode(chunk, { stream: true });
-                        const { frames, rest } = splitFrames(buffer);
-                        buffer = rest;
-                        for (const frame of frames) {
-                            const parsed = parseFrame(frame);
-                            if (parsed)
-                                yield parsed;
-                        }
-                    }
-                    // A trailing frame with no terminating blank line still counts.
-                    const tail = parseFrame(buffer);
-                    if (tail)
-                        yield tail;
-                }
-                finally {
-                    clearTimeout(timer);
-                }
-            },
-        };
-    };
-}
-/** The decision POST. 30s, because it is an ordinary short request. */
-export function fetchDecisionTransport(timeoutMs = 30_000) {
-    return async (url, headers, body) => {
-        const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), timeoutMs);
-        try {
-            const response = await fetch(url, {
-                method: "POST",
-                headers,
-                body: JSON.stringify(body),
-                redirect: "manual",
-                signal: controller.signal,
-            });
-            return response.status;
-        }
-        catch {
-            // The gate on the far side is still waiting and will deny on its own expiry, so
-            // a lost decision is safe — it is never an approval. 0 says "never delivered" so
-            // the caller can say that rather than implying a human refused.
-            return 0;
-        }
-        finally {
-            clearTimeout(timer);
-        }
-    };
-}
-/** `POST /agent/{run_id}/permission`, built from the base URL the tool already resolved. */
-export function decisionUrl(agentUrl, runId) {
-    return `${agentUrl.replace(/\/+$/, "")}/${encodeURIComponent(runId)}/permission`;
-}

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

@@ -1,196 +0,0 @@
-/**
- * CONTRACT v1, expressed as types.
- *
- * Everything in this file is one half of a wire format whose other half is being written
- * against `~/.claude/orchestration/shared/CONTRACT.md` by a different session, in a
- * different repo, at the same time. A field renamed here to read better is a field the
- * other half will never send. Nothing here changes without changing that document first.
- */
-export declare const PRODUCTS: readonly ["tm", "a11y", "tra"];
-export type Product = (typeof PRODUCTS)[number];
-/** CONTRACT §2 — what Atlas emits on the run's stream when its gate needs a human. */
-export interface PermissionAsk {
-    /**
-     * Atlas's own `perm-<32 hex>` uuid4, carried, never re-minted.
-     *
-     * Commit 737f6f57 replaced a per-Bridge sequential scheme with this one after ids
-     * collided across pods and left a turn blocked until its 300s timeout. A second id
-     * scheme on this side would reintroduce that bug on a new axis, so we echo theirs.
-     */
-    perm_id: string;
-    product: string;
-    /** "ask-always" | "ask-once" — Atlas's vocabulary, not re-interpreted here. */
-    mode: string;
-    /**
-     * The model's `thought`: product language, route-free.
-     *
-     * The privacy boundary is that `op_key`, `method`, `path` and `host` stay inside Atlas's
-     * private record. This field is the whole of what a human is shown.
-     */
-    description: string;
-}
-export type Decision = "allow" | "deny";
-/**
- * CONTRACT §2/§7. Advisory ONLY — `decision` alone decides whether the action proceeds.
- * It exists so a result can distinguish "a human said no" from "no human was there".
- */
-export type DecisionReason = "" | "declined" | "cancelled" | "no_human" | "timeout" | "error";
-/** CONTRACT §2 — the body we POST to `/agent/{run_id}/permission` to answer one ask. */
-export interface PermissionDecision {
-    perm_id: string;
-    decision: Decision;
-    reason: DecisionReason;
-}
-/** CONTRACT §1 — the one new optional field on `POST /agent`. */
-/**
- * The `permission_relay` block — one shape, because there is one transport.
- *
- * `{ mode: "stream" }` is A1 / CONTRACT v2: nothing to address and nothing to
- * authenticate inbound, because nothing dials in. A2's `{ callback_url, token }` was
- * removed on both halves (v2 §7.4) — it could only ever reach a co-located caller, and
- * an Atlas that still sees that shape now reports the relay as `disabled` rather than
- * trying it.
- *
- * `mode` stays optional rather than required so this stays a superset of the block an
- * older Atlas will simply ignore: the field's ABSENCE is what selects the read-only
- * gate, and that has to remain expressible.
- */
-export interface PermissionRelay {
-    mode?: string;
-}
-/**
- * CONTRACT §1 — the `POST /agent` body.
- *
- * `permission_relay` is OMITTED ENTIRELY, not sent empty or null, when the client cannot
- * elicit: its absence is what selects Atlas's read-only `HeadlessGate`, which is today's
- * byte-identical behaviour and the opencode/goose path.
- */
-export interface AgentRequest {
-    task: string;
-    product: string;
-    /**
-     * Who the run is for (CONTRACT v1.2 §3).
-     *
-     * The shared delegation token authenticates the caller but not the principal
-     * (`principal_verified=false`), so Atlas reads the acting user from here. Omitted entirely
-     * when no username is configured — never sent as `""`.
-     *
-     * Note the asymmetry and do not try to close it: on this path a caller can CLAIM any
-     * `user_id`. That is Atlas's documented design for the shared-token route; a signed
-     * principal requires the central-JWT path, which is out of scope.
-     */
-    user_id?: string;
-    permission_relay?: PermissionRelay;
-}
-/** CONTRACT §5 — one entry in an approval trail, in the order the asks arrived. */
-export interface ApprovalRecord {
-    description: string;
-    decision: Decision;
-    reason: string;
-    /**
-     * Did this approved step's request actually land? (Atlas task 3 §1.)
-     *
-     * `true` only when the entry was `allow` AND its request then returned 2xx. Everything
-     * else — a dead port, a 4xx, a 5xx, an async-dispatch refusal — resolves to `false`:
-     * unknown fails toward not-applied, never the other way.
-     *
-     * ONLY ATLAS CAN KNOW THIS. The gate returns before any request is sent, which was the
-     * whole of D2; the fact is written by the tool layer into the same record object the gate
-     * keeps by reference, so it correlates by object identity rather than by position.
-     *
-     * ABSENT means not reported (an Atlas that predates this, or our own elicitation trail,
-     * which has no way to know). Never render an absent value as a measured `false`.
-     */
-    applied?: boolean;
-    /**
-     * A human-readable phrase for this entry.
-     *
-     * Exists because `allow` + `applied: false` — approved, then the request failed — is a
-     * genuinely different thing to tell a person than a refusal, and the two must not read
-     * alike. Derived, never sent by anyone.
-     */
-    outcome?: string;
-}
-/**
- * Whether the approval channel was offered to Atlas at all, and if not, why not.
- *
- * Three different facts about this deployment and this client, each needing a different
- * thing from whoever reads the result — so they are three values rather than one boolean.
- */
-export type RelayMode = 
-/** `permission_relay` was sent and the run's stream carried the asks. */
-"offered"
-/** The client declares no `elicitation` capability, so nobody could be prompted. */
- | "no_human"
-/** This process is the hosted multi-tenant server, which cannot prompt a human. */
- | "remote_mode";
-export declare const ASK_STATUSES: readonly ["ok", "blocked", "error", "rate_limited"];
-export type AskStatus = (typeof ASK_STATUSES)[number];
-/** CONTRACT §5 — the single tool result. */
-export interface AskResult {
-    ok: boolean;
-    status: AskStatus;
-    answer: unknown;
-    /**
-     * THE AUTHORITATIVE approval trail: Atlas's whenever it supplied one, ours otherwise.
-     *
-     * Atlas's wins because it is the only side that can populate `applied`, and because it
-     * records what happened to the STEP — an ask answered without a prompt appearing (a
-     * 401'd probe, a shape rejection) is a denial there and nothing at all here.
-     */
-    approvals: ApprovalRecord[];
-    /** Which side produced `approvals`, so a reader never has to infer it. */
-    approvals_source: "atlas" | "mcp";
-    /**
-     * OUR trail: one entry per prompt this server actually put in front of a human.
-     *
-     * Kept beside `approvals` rather than folded into it, because where the two disagree the
-     * disagreement is the signal. An entry Atlas records as a denial with nothing here means a
-     * ask was answered without any prompt appearing — which is what an attacker probing
-     * the loopback port looks like.
-     */
-    elicitations: ApprovalRecord[];
-    needs_approval: unknown[];
-    /**
-     * Atlas's own verdict: this run stopped on a refusal AND something had already changed.
-     *
-     * READ, NEVER DERIVED. Atlas computes it because only Atlas knows `applied`, and it sends
-     * the field whenever a relay gate ran — including `false`, including with an empty trail.
-     *
-     * `null` means NOT REPORTED, which is not the same as `false`: either no gate ran (so
-     * Atlas has nothing to say about applications) or this Atlas predates the field. Treating
-     * it as `false` would assert something nobody measured.
-     */
-    applied_before_stop: boolean | null;
-    /**
-     * Why a write may have been refused.
-     *
-     * `reason` is ATLAS'S OWN when it reported one (CONTRACT v1.1 §D: `"" | disabled |
-     * host_not_allowed | malformed`), and ours — `no_human` (§7's last row) — when the client
-     * could not be prompted at all, which Atlas never learns about because we omit the block.
-     * Typed as a plain string rather than a union because an Atlas newer than this build may
-     * name a reason this one has never heard of, and an unrecognised reason must degrade to a
-     * sentence, not throw.
-     */
-    permission_relay: {
-        used: boolean;
-        reason: string;
-        detail: string;
-    };
-    /**
-     * Atlas's public payload, verbatim.
-     *
-     * The mapped fields above are the contract; this is the belt to their braces. The two
-     * halves are being built in parallel, so a field named slightly differently on the other
-     * side would otherwise silently become `null` here rather than reaching the caller.
-     */
-    atlas_response: unknown;
-    /**
-     * Why the call failed, when it did.
-     *
-     * Ours when egress never completed; otherwise Atlas's own `error` string, which its
-     * `public()` includes ONLY when non-empty (v1.1 §B). Lifted out of `atlas_response` so a
-     * caller reading the top level is told why rather than having to go looking.
-     */
-    error?: string;
-}

package/dist/tools/ask-browserstack/types.js

@@ -1,10 +0,0 @@
-/**
- * CONTRACT v1, expressed as types.
- *
- * Everything in this file is one half of a wire format whose other half is being written
- * against `~/.claude/orchestration/shared/CONTRACT.md` by a different session, in a
- * different repo, at the same time. A field renamed here to read better is a field the
- * other half will never send. Nothing here changes without changing that document first.
- */
-export const PRODUCTS = ["tm", "a11y", "tra"];
-export const ASK_STATUSES = ["ok", "blocked", "error", "rate_limited"];

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

@@ -1,37 +0,0 @@
-/**
- * Precondition sentences appended to a tool's description.
- *
- * WHY THESE EXIST. Nothing routes an MCP call: the client's model picks a tool from the
- * descriptions alone. A tool that needs an identifier the caller does not have is a dead
- * end — the model either asks the user for something they also do not know, or gives up.
- * These sentences turn that dead end into a HANDOFF by naming, in the description itself,
- * 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.
- *
- * 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
- * projects. "List my projects" is the first step of nearly every Test Management journey
- * and it was unserved, which is exactly why that request did not reach any tool unless a
- * user named one explicitly.
- *
- * Keep these as shared constants, not per-tool prose: the wording is a routing signal, and
- * twenty hand-written variants drift into twenty different signals.
- */
-/** No tool lists projects, so this genuinely has to go to the agent. */
-export declare const NEEDS_PROJECT_ID: string;
-/** A sibling tool can produce the id — prefer it over the agent. */
-export declare function needsIdFrom(idLabel: string, sourceTool: string): string;
-/** A test plan id (TP-*) comes from listTestPlans. */
-export declare const NEEDS_TEST_PLAN_ID: string;
-/** A build id comes from either build-lookup tool. */
-export declare const NEEDS_BUILD_ID: string;
-/** Session ids are not listable by any tool here. */
-export declare const NEEDS_SESSION_ID: string;
-/** A completed scan's ids come from startAccessibilityScan, or from the agent. */
-export declare const NEEDS_A11Y_SCAN_ID: string;
-/** Auth-config ids are not listable by any tool here. */
-export declare const NEEDS_A11Y_CONFIG_ID: string;
-/** Test ids come from listTestIds, which itself needs a build id. */
-export declare const NEEDS_TEST_IDS: string;

package/dist/tools/tool-handoff.js

@@ -1,47 +0,0 @@
-/**
- * Precondition sentences appended to a tool's description.
- *
- * WHY THESE EXIST. Nothing routes an MCP call: the client's model picks a tool from the
- * descriptions alone. A tool that needs an identifier the caller does not have is a dead
- * end — the model either asks the user for something they also do not know, or gives up.
- * These sentences turn that dead end into a HANDOFF by naming, in the description itself,
- * 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.
- *
- * 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
- * projects. "List my projects" is the first step of nearly every Test Management journey
- * and it was unserved, which is exactly why that request did not reach any tool unless a
- * user named one explicitly.
- *
- * Keep these as shared constants, not per-tool prose: the wording is a routing signal, and
- * twenty hand-written variants drift into twenty different signals.
- */
-/** 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.";
-/** 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.`;
-}
-/** A test plan id (TP-*) comes from listTestPlans. */
-export const NEEDS_TEST_PLAN_ID = needsIdFrom("a test plan identifier (TP-*)", "listTestPlans");
-/** A build id comes from either build-lookup tool. */
-export const NEEDS_BUILD_ID = needsIdFrom("a BrowserStack build id", "getBuildId or listBuildId");
-/** Session ids are not listable by any tool here. */
-export const NEEDS_SESSION_ID = " Requires a session id, which no tool here lists. If you only know the build, call " +
-    "getBuildId or listBuildId; if you have neither, call askBrowserStackAI with product " +
-    '"tra" and describe the run you mean.';
-/** A completed scan's ids come from startAccessibilityScan, or from the agent. */
-export const NEEDS_A11Y_SCAN_ID = " Requires the ids of a completed scan. They are returned by startAccessibilityScan; " +
-    'for a scan run earlier, call askBrowserStackAI with product "a11y" to locate it, since ' +
-    "no tool here lists past scans.";
-/** Auth-config ids are not listable by any tool here. */
-export const NEEDS_A11Y_CONFIG_ID = " Requires the numeric id returned by createAccessibilityAuthConfig. No tool here lists " +
-    "existing configurations, so if you do not have the id, call askBrowserStackAI with " +
-    'product "a11y".';
-/** Test ids come from listTestIds, which itself needs a build id. */
-export const NEEDS_TEST_IDS = needsIdFrom("test ids", "listTestIds");