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

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

@@ -1,416 +0,0 @@
-/**
- * `askBrowserStackAI` — one tool call in, one tool result out, with a human's approval
- * relayed through the middle of it.
- *
- * The shape, and why:
- *
- *   1. NEGOTIATE FIRST. `relayMode()` is consulted BEFORE Atlas is called, so Atlas learns
- *      whether a human is reachable before it starts rather than discovering it at the gate.
- *      Anything other than "offered" means `permission_relay` is omitted entirely and Atlas
- *      runs read-only — today's exact behaviour, and the path opencode and goose stay on.
- *      That also covers the hosted `REMOTE_MCP` deployment, where the relay cannot work at
- *      all; see `relayMode` for why. Nothing here depends on `sampling`, which Claude Code
- *      does not declare.
- *   2. LISTEN ON LOOPBACK. Transport is A2, so Atlas calls US back; because it initiates,
- *      the decision returns on the same connection to the same pod and PLAN.md's affinity
- *      problem never arises for this stdio deployment.
- *   3. ELICIT, ONCE. Atlas's `description` is the message, nothing is requested in the form,
- *      and the ACTION is mapped by CONTRACT §7 with no second chances.
- *   4. RETURN THE TRAIL. `approvals` and `applied_before_stop` are what let a caller tell
- *      "nothing happened" from "some steps applied, then stopped".
- *
- * FAIL CLOSED THROUGHOUT. A decline, a cancel, a timeout, a bad token, a body we cannot
- * parse, a handler that throws — every one of them denies. An unattended run cannot approve
- * itself because a headless client returns `cancel`, which is a deny.
- */
-import { ErrorCode, McpError, } from "@modelcontextprotocol/sdk/types.js";
-import { z } from "zod";
-import appConfig from "../../config.js";
-import { trackMCP } from "../../lib/instrumentation.js";
-import logger from "../../logger.js";
-import { AskError, ELICITATION_TIMEOUT_MS, agentUrl, allowRemoteRelay, authTokenUrl, isEnabled, } from "./config.js";
-import { fetchTokenTransport, mintCentralToken } from "./central-oauth.js";
-import { agentHeaders } from "./egress.js";
-import { EVENT_PERMISSION, EVENT_RESULT, EVENT_RUN, decisionUrl, fetchAgentStreamTransport, fetchDecisionTransport, parseAsk, } from "./stream.js";
-import { buildResult, decide, elicitationMessage, elicitationShape, errorResult, } from "./relay.js";
-import { PRODUCTS, } from "./types.js";
-/**
- * THE FALLBACK POSITIONING IN THE FIRST SENTENCE IS LOAD-BEARING.
- *
- * This server registers 45 tools, most of them hand-written for one endpoint each. Those are
- * faster, cheaper and more predictable than handing a task to an agent that has to work out
- * its own API calls, so they should win whenever one of them actually fits. What this tool
- * covers is the gap: a task nothing here has a tool for, or one where the specific tools were
- * tried and did not get there.
- *
- * A description is the ONLY thing steering that choice — the client picks a tool from these
- * words alone, before any call is made — so the ordering is deliberate: when to reach for it
- * first, what it does second, and the consent behaviour last.
- */
-const DESCRIPTION = 
-// Alpha status leads, deliberately. The model reads this before deciding to call, and a
-// tool that is not enabled for the account cannot do the job at all — so "there is a
-// per-account gate, fall back to the individual tools" is the most useful thing to say
-// first. Parenthesised so it reads as a status note, not as the tool's purpose.
-"(Alpha, limited availability. Enabled per account and per product; if it is not enabled " +
-    "the call returns an entitlement error, nothing runs, and you should complete the task " +
-    "with the individual tools instead. To request access, the user should contact their " +
-    "BrowserStack account owner.) " +
-    "Use this when no other BrowserStack tool here fits the task, or when the ones you tried " +
-    "did not get you there. Prefer a specific tool whenever one fits: it is faster and more " +
-    "predictable than handing the job to an agent. " +
-    "Otherwise, describe what you want in plain language and BrowserStack's agent decides " +
-    "which calls to make, then returns its answer plus the steps it took. Anything that would " +
-    "change data pauses and asks you to confirm it first, in your own client; deletes are " +
-    "refused outright. If your client cannot show you a prompt, the run is read-only and " +
-    "everything it wanted to change comes back in `needs_approval` instead. One task per call.";
-/**
- * `isError` marks a call that FAILED, not one that was refused.
- *
- * A `blocked` run is the feature working: the agent asked, a human said no, and the trail
- * says so. Flagging that as a tool error makes a client render a correct refusal in red and
- * — worse — invites it to retry, which is exactly the "retry forever" loop the distinct
- * `permission_relay` reasons exist to prevent. `ok` still means `status === "ok"`.
- */
-function toResult(payload) {
-    const failed = payload.status === "error" || payload.status === "rate_limited";
-    return {
-        content: [{ type: "text", text: JSON.stringify(payload) }],
-        ...(failed ? { isError: true } : {}),
-    };
-}
-function isTimeout(error) {
-    return error instanceof McpError && error.code === ErrorCode.RequestTimeout;
-}
-/**
- * Relay one ask to the human and record what they said.
- *
- * The elicitation is NEVER retried. A client that timed out or errored has told us it
- * cannot get an answer, and asking again only produces a second prompt for the same action.
- */
-async function relayOneAsk(server, ask, approvals, relatedRequestId) {
-    let answer;
-    try {
-        // `relatedRequestId` IS LOAD-BEARING OVER HTTP, and its absence fails silently.
-        // Streamable HTTP routes a server->client message onto the stream of the request it
-        // relates to (`_requestToStreamMapping`). With no id the SDK falls back to the
-        // standalone SSE stream, and a host that answers GET /mcp with 405 has none — so the
-        // SDK drops the message with "Stream is disconnected", the tool waits out its 270s,
-        // and Atlas's gate expires into `reason: "timeout"`. The human is told they did not
-        // answer a question they were never shown.
-        //
-        // Measured exactly that way against the hosted server before this was threaded
-        // through. On stdio it is irrelevant — one pipe, nothing to route — which is why no
-        // local test could have caught it.
-        answer = await server.server.elicitInput({
-            mode: "form",
-            // Framed with the PRODUCT and nothing else (v1.1 §G): a bare sentence with no
-            // attribution is a worse prompt than a framed one, and `product` is all the
-            // ask carries — the route, method, path and op_key never reach this side by design,
-            // and that is the whole privacy boundary (the ask is four named fields). The
-            // description goes through VERBATIM: paraphrasing it would mean the human approves
-            // something other than what the model actually said. Atlas no longer rewrites it
-            // either — it used to replace a route-shaped one with a placeholder, which asked a
-            // person to approve a sentence they could not read; CONTRACT v2 §3 was amended and
-            // that guard removed. An older Atlas can still send the placeholder, which is why
-            // the framing is tested against it.
-            message: elicitationMessage(ask.product, ask.description),
-            requestedSchema: {
-                // NOTHING IS REQUESTED. The action IS the answer: `accept` already means the human
-                // approved, and `decline` already gives them an unambiguous refusal in the same
-                // dialog. A `confirm` boolean used to live here and produced a FALSE DENIAL — a
-                // user approved on preprod and was told they had refused, because a client renders
-                // a form field and submits its unset value. We cannot distinguish that from a
-                // deliberate untick, so the field is gone rather than guessed at.
-                //
-                // Fail-closed is untouched by this and never rested on the boolean: a headless
-                // client with nobody at the terminal returns `cancel` (measured, HANDOFF.md), and
-                // `cancel` is a deny. That is what stops an unattended run self-approving.
-                type: "object",
-                properties: {},
-            },
-        }, 
-        // The inner rung of CONTRACT §4's ladder, strictly shorter than Atlas's 300s gate.
-        { timeout: ELICITATION_TIMEOUT_MS, relatedRequestId });
-    }
-    catch (error) {
-        if (isTimeout(error)) {
-            approvals.push({
-                description: ask.description,
-                decision: "deny",
-                reason: "timeout",
-            });
-            return { perm_id: ask.perm_id, decision: "deny", reason: "timeout" };
-        }
-        // An unexpected failure has no honest `reason` in CONTRACT §2's vocabulary, so it is
-        // not given one on the wire: the throw says "this side broke" without claiming a human
-        // decided anything. `runStreamed` catches it and sends the explicit deny the throw
-        // implies — see the comment there for why A1 cannot let it escape.
-        approvals.push({
-            description: ask.description,
-            decision: "deny",
-            reason: "error",
-        });
-        throw error;
-    }
-    // The SHAPE of the answer only — a fixed action enum and a boolean, never the description
-    // or anything a user typed. Logged so that what a client actually submits can be read next
-    // time rather than inferred from a compiled binary.
-    logger.info("askBrowserStackAI: elicitation answered %s", elicitationShape(answer));
-    const { decision, reason } = decide(answer);
-    approvals.push({ description: ask.description, decision, reason });
-    return { perm_id: ask.perm_id, decision, reason };
-}
-/**
- * Decide whether to offer the approval channel at all.
- *
- * STDIO ALWAYS. HOSTED ONLY WHEN ITS OPERATOR OPTS IN — and the reason is a property of
- * the HOST, not of this tool.
- *
- * Elicitation is a SERVER-INITIATED message whose answer arrives on a SEPARATE POST. A
- * stateless host builds a fresh `McpServer` per POST, so that answer reaches an instance
- * which never asked anything, while the one actually suspended on `await` waits out its
- * timeout. Nothing in this package can fix that; what it holds is a live Promise resolver
- * and a paused function in the host's heap, and a paused call cannot be moved.
- *
- * This is why `841c6358` was right to remove sessions from the hosted server on the
- * grounds that "we use neither server-initiated messages nor subscriptions/sampling" —
- * this feature is the exception that commit did not have to consider.
- *
- * MEASURED, not assumed: with the host keeping one server per session
- * (browserstack/remote-mcp-server#96), a tool call and its elicitation answer were served
- * by the same instance over hosted Streamable HTTP, and the relay completed. So the
- * refusal below is now conditional rather than absolute.
- *
- * It stays OFF by default because it depends on a deployment property this package cannot
- * observe. A hosted operator turns it on only once their host keeps sessions AND pins a
- * session to a pod — sessions are per-process, so without affinity the answer POST can
- * land on a replica that has never seen it. That failure is intermittent and reads like a
- * client bug, which is exactly why it must not be the default.
- *
- * When refused, Atlas runs read-only — a supported path that already works — and
- * `permission_relay.reason` says `remote_mode` so nobody mistakes it for a human's no.
- */
-/**
- * CONTRACT v2 (A1) — drive one run over the stream.
- *
- * The loop is the whole orchestration: read events, elicit on each `permission`, POST
- * the decision, hand the `result` to `buildResult`. It decides nothing itself —
- * `relayOneAsk` owns the elicitation and the allow/deny mapping, unchanged from the
- * transport it replaced. That is deliberate: the transport changed, the judgement did
- * not, and the judgement is the part that is dangerous to get wrong.
- *
- * Reading pauses while a human is being prompted, which is correct rather than merely
- * tolerable: Atlas is blocked on that decision and will emit nothing but heartbeats
- * until it arrives, and heartbeats are dropped by the parser.
- *
- * A run that ends with no `result` is an error, not an empty success. A stream that
- * simply stops is indistinguishable from a network drop, and reporting it as a finished
- * run with no answer would be the transport quietly speaking for the agent.
- */
-async function runStreamed(server, streamTransport, decisionTransport, url, headers, body, approvals, mode, product, relatedRequestId) {
-    let runId = "";
-    let result;
-    let sawResult = false;
-    // 200 unless the reply was not a stream at all, in which case the transport carries
-    // the real status — `relay.ts` needs it to tell 401 from 403 from a plain failure.
-    let resultStatus = 200;
-    for await (const event of streamTransport(url, headers, body)) {
-        if (event.event === EVENT_RUN) {
-            runId = String(event.data?.run_id || "");
-            continue;
-        }
-        if (event.event === EVENT_RESULT) {
-            result = event.data;
-            sawResult = true;
-            if (typeof event.status === "number")
-                resultStatus = event.status;
-            continue;
-        }
-        if (event.event !== EVENT_PERMISSION)
-            continue;
-        // Validated, not cast: a frame missing a usable `perm_id` or carrying a blank
-        // description cannot produce an answerable prompt, so it must not produce a prompt.
-        const ask = parseAsk(event.data);
-        if (!ask) {
-            logger.error("askBrowserStackAI: unusable permission ask on the stream; ignoring");
-            continue;
-        }
-        if (!runId) {
-            // Atlas emits `run` before any ask precisely so this cannot happen. If it does,
-            // there is nowhere to send a decision — so do not prompt a human for an answer
-            // that could never be delivered.
-            logger.error("askBrowserStackAI: permission ask arrived before run_id; cannot answer");
-            continue;
-        }
-        // `relayOneAsk` RETHROWS on an unexpected elicitation failure. Under A2 that was
-        // load-bearing: the throw made the inbound callback answer 500, which Atlas's
-        // fail-closed rule read as a deny. Under A1 there is no inbound request to fail, so
-        // letting it escape would abandon the run and leave Atlas waiting out its full 300s
-        // gate — turning a client hiccup into a five-minute stall. So it is caught here and
-        // converted into the explicit deny the throw used to imply. `relayOneAsk` has
-        // already recorded the approvals entry, so only the wire decision is missing.
-        let decision;
-        try {
-            decision = await relayOneAsk(server, ask, approvals, relatedRequestId);
-        }
-        catch (error) {
-            logger.warn("askBrowserStackAI: elicitation failed, denying explicitly: %s", error instanceof Error ? error.message : String(error));
-            decision = { perm_id: ask.perm_id, decision: "deny", reason: "error" };
-        }
-        const status = await decisionTransport(decisionUrl(url, runId), headers, {
-            perm_id: decision.perm_id,
-            decision: decision.decision,
-            reason: decision.reason || "",
-        });
-        if (status !== 204) {
-            // Never fatal, and never re-sent. Atlas's gate is still waiting and denies on its
-            // own expiry, so a lost decision is safe — it can only cost an approval, never
-            // grant one. Retrying risks the opposite: a duplicate that 409s, or worse, an
-            // approval applied to a step the run has already moved past.
-            logger.warn("askBrowserStackAI: decision for %s was not accepted (HTTP %s)", decision.perm_id, status);
-        }
-    }
-    if (!sawResult) {
-        return errorResult("BrowserStack AI ended the run without a result. Nothing was changed " +
-            "beyond any step you already approved.", approvals);
-    }
-    // Shaped as an `AgentResponse` so `buildResult` — written for the transport A1 replaced
-    // and unchanged — sees exactly what it always saw.
-    return buildResult({ status: resultStatus, body: result }, approvals, mode, product);
-}
-export function relayMode(server) {
-    // The hosted deployment refuses UNLESS its operator has opted in, because whether an
-    // elicitation can be answered there depends on the host keeping one server alive per
-    // session — see `allowRemoteRelay`. Verified working against the hosted Streamable
-    // HTTP server once it does (browserstack/remote-mcp-server#96).
-    if (appConfig.REMOTE_MCP && !allowRemoteRelay())
-        return "remote_mode";
-    // The real gate either way: can THIS client be asked? A client that never declared
-    // `elicitation` gets a read-only run whatever the deployment.
-    return server.server.getClientCapabilities()?.elicitation
-        ? "offered"
-        : "no_human";
-}
-export function addAskBrowserStackAITool(server, deps, config) {
-    // A1 (CONTRACT v2) is the only path; A2 is gone. No version flag is needed to talk to
-    // an Atlas that predates the stream: such a server answers `POST /agent` with ordinary
-    // JSON, the parser sees no `text/event-stream`, and the run degrades to a read-only
-    // answer carrying that response's own status.
-    const streamTransport = deps.streamTransport || fetchAgentStreamTransport();
-    const decisionTransport = deps.decisionTransport || fetchDecisionTransport();
-    const tools = {};
-    /** Instrumentation in the house style, and never fatal to the call it wraps. */
-    const track = (name) => {
-        try {
-            trackMCP(name, server.server.getClientVersion(), undefined, config);
-        }
-        catch {
-            // Telemetry must not decide whether a tool call succeeds.
-        }
-    };
-    tools.askBrowserStackAI = server.tool("askBrowserStackAI", DESCRIPTION, {
-        product: z
-            .enum(PRODUCTS)
-            .describe("Which product to work in: tm (Test Management), " +
-            "tra (Test Reporting & Analytics)."),
-        query: z
-            .string()
-            .describe("What you want, in plain language. One thing per call."),
-    }, {
-        // It can write now, which is the whole point of the relay. Destructive operations
-        // stay refused, so `destructiveHint` is false for the same reason invokeEndpoint
-        // sets it false: consent is not a licence to delete.
-        readOnlyHint: false,
-        destructiveHint: false,
-        // openWorldHint: the agent fans out to product APIs chosen at runtime, so the set of
-        // effects is not knowable from this schema. idempotentHint false because a repeated
-        // call can create a second record — the relay asks again, it does not dedupe.
-        openWorldHint: true,
-        idempotentHint: false,
-        title: "Ask BrowserStack AI (Alpha)",
-    }, async ({ product, query }, extra) => {
-        track("askBrowserStackAI");
-        const approvals = [];
-        // Negotiated before anything else so the failure paths below report the mode they
-        // would have run in.
-        const mode = relayMode(server);
-        try {
-            const url = deps.agentUrl();
-            // Signed in BEFORE the listener is opened and before the run starts. Minting
-            // lazily mid-call would put a token round-trip inside the window where a human is
-            // being prompted, and a mint that failed there would strand an open port.
-            const headers = agentHeaders(await deps.mintToken());
-            const body = { task: query, product };
-            // Attribution, and now belt-and-braces rather than the source of truth: the minted
-            // JWT is user-attested, so Atlas sets `principal_verified=True` and takes the acting
-            // user from signed claims instead of this field. It is still sent because it is part
-            // of the frozen wire format (CONTRACT v1.2 §3) and dropping it would be a one-sided
-            // change — but nothing should trust it, and Atlas no longer does.
-            // Omitted ENTIRELY when unset, never sent as "".
-            const username = (deps.credentialsFor().username || "").trim();
-            if (username)
-                body.user_id = username;
-            // A1: asking for a stream costs nothing to set up — no port, no listener, no
-            // per-run bearer, because nothing dials in. Which is the whole point: the
-            // callback this replaces could never reach a laptop behind NAT, so the feature
-            // was read-only for every real user regardless of what was configured.
-            if (mode === "offered") {
-                body.permission_relay = { mode: "stream" };
-            }
-            else {
-                // Omitted ENTIRELY, not sent empty: its absence is what selects Atlas's
-                // read-only HeadlessGate.
-                logger.info("askBrowserStackAI: no permission relay (%s); running read-only", mode);
-            }
-            // `product` reaches the result so an entitlement refusal can name it: the flags
-            // are per product, and a bare "not enabled" sends the user to their admin
-            // asking about the wrong thing.
-            return toResult(await runStreamed(server, streamTransport, decisionTransport, url, headers, body, approvals, mode, product, 
-            // The tool call's own id, so each elicitation is routed onto THIS request's
-            // stream. Over Streamable HTTP there is nowhere else for it to go.
-            extra?.requestId));
-        }
-        catch (error) {
-            const message = error instanceof AskError || error instanceof Error
-                ? error.message
-                : String(error);
-            logger.error("askBrowserStackAI failed: %s", message);
-            // Error telemetry, in the same never-fatal shape as the success-path `track()`:
-            // a failing tool call must not be made worse by a failing analytics call.
-            try {
-                trackMCP("askBrowserStackAI", server.server.getClientVersion(), error, config);
-            }
-            catch {
-                /* ignore */
-            }
-            // No `canElicit` argument: the request never left this process, so whether the
-            // client could have been prompted is not what the reader needs to know.
-            return toResult(errorResult(message, approvals));
-        }
-        // No teardown: A1 opens no port and binds nothing, so there is nothing that can
-        // leak across calls or survive an error. The stream is closed by its own
-        // iteration ending, and Atlas drops the run when the response completes.
-    });
-    return tools;
-}
-/** The tool-adder the server factory calls. */
-export function addAskBrowserStackAIToolFromConfig(server, config) {
-    if (!isEnabled()) {
-        logger.info("askBrowserStackAI disabled by ASK_BROWSERSTACK_DISABLED");
-        return {};
-    }
-    const credentials = () => ({
-        username: config["browserstack-username"],
-        accessKey: config["browserstack-access-key"],
-    });
-    const tokenTransport = fetchTokenTransport();
-    return addAskBrowserStackAITool(server, {
-        // Both resolved per call. An unconfigured host surfaces as a named error from the
-        // tool rather than as a missing tool, so the cause is visible to whoever hits it.
-        agentUrl,
-        mintToken: () => mintCentralToken(authTokenUrl(), credentials(), tokenTransport),
-        credentialsFor: credentials,
-    }, config);
-}
-export default addAskBrowserStackAIToolFromConfig;

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

@@ -1,201 +0,0 @@
-/**
- * The decision mapping and the result assembly — the two places where being wrong is
- * expensive, kept pure so they can be tested without a server, a socket or a client.
- */
-import { ElicitResult } from "@modelcontextprotocol/sdk/types.js";
-import { AgentResponse } from "./egress.js";
-import { ApprovalRecord, AskResult, AskStatus, Decision, DecisionReason, RelayMode } from "./types.js";
-export declare const RELAY_ON_DETAIL: string;
-/**
- * Used when the channel worked and every ask came back with nobody behind it.
- *
- * `RELAY_ON_DETAIL` cannot be used here and saying it was a bug, observed live: it claims
- * "BrowserStack asked before each change and the answers are in `approvals`" while the
- * trail says `refused: nobody was there to be asked`. Both sentences were in the same
- * result, contradicting each other — the same class of confusion as `disabled` vs a human
- * saying no, and it is the reader who pays for it. The channel being usable and a person
- * actually answering are different facts, and only the second one licenses the word
- * "answers".
- */
-export declare const RELAY_ON_NO_ANSWER_DETAIL: string;
-/**
- * One sentence per way the relay can fail to run, because they call for different things
- * from the person reading them, and a caller who cannot tell them apart retries forever.
- *
- * `no_human` is ours (CONTRACT §7's last row); the rest are Atlas's (v1.1 §D).
- */
-export declare const RELAY_OFF_DETAILS: Record<string, string>;
-/** Kept for anything still importing the old single constant. */
-export declare const RELAY_OFF_DETAIL: string;
-/** The sentence that goes with a `{used, reason}` pair, whoever produced it. */
-export declare function relayDetail(used: boolean, reason: string): string;
-/**
- * Did this request die before the agent ever started?
- *
- * Atlas omits its `permission_relay` verdict on refusals that never reach the delegation
- * layer — 401 unauthorized, 400 bad body, 503 delegation-not-enabled all answer with a bare
- * `{"detail": …}` — and a transport failure has no body at all. Read naively, "no verdict"
- * looks identical to "an Atlas older than v1.1", and the optimistic fallback for THAT case
- * then claims the channel was used and answers were collected when zero prompts appeared.
- *
- * Which is the same confusion the `disabled` sentence exists to prevent, one layer earlier:
- * a caller who cannot tell "nobody was asked" from "somebody said no" retries forever.
- */
-export declare function looksLikeDelegationResult(body: unknown): boolean;
-/**
- * Is this Atlas saying the ACCOUNT is not enabled for the product's agent?
- *
- * Atlas gained an entitlement gate on `POST /agent` (`flags.is_agent_enabled`, AIC-386) that
- * the WebSocket path already had. The flags are PER PRODUCT — `aiHarnessAgent` for tm,
- * `aiHarnessAgentTRA`, `aiHarnessAgentA11y` — so an account can be entitled for one product
- * and not another. It is also FAIL-OPEN on Atlas's side: Redis down, a flag never seeded, or
- * an unknown product all allow the request. So a 403 here is a real, deliberate "this account
- * is not enabled", never an outage.
- *
- * KEYED STRUCTURALLY, NEVER ON THE PROSE. Matching the sentence would break silently the
- * first time someone rewords it, falling through to a generic error.
- *
- * TODO(atlas/9.md): Atlas is deciding whether to add a `code` field to this body. When it
- * lands, prefer it over the status — add the check as the first rung here and leave the
- * status as the fallback for an older Atlas. Until then the status IS the structural signal.
- */
-export declare function isNotEntitled(response: AgentResponse): boolean;
-/**
- * The sentence the user asked for, with the product named.
- *
- * Entitlement is per product, so a bare "not enabled" sends someone to their admin asking
- * about the wrong thing. The disambiguation from a 401 is deliberate and load-bearing:
- * without it, a working access key gets rotated in response to a permissions problem.
- */
-export declare const NOT_ENTITLED_DETAIL: (product: string) => string;
-export declare function neverReachedAgent(response: AgentResponse): boolean;
-/**
- * Atlas's own verdict on the relay (v1.1 §D), when it gave one.
- *
- * Present ONLY when we supplied a `permission_relay` block, so its absence is either "we
- * never offered one" or "this Atlas predates v1.1" — neither of which is an error. A block
- * we cannot read is treated as no block at all rather than half-trusted.
- */
-export declare function atlasRelayVerdict(payload: Record<string, unknown>): {
-    used: boolean;
-    reason: string;
-} | null;
-/**
- * Product-language framing for the prompt (v1.1 §G, approved).
- *
- * `product` is the ONLY thing added — it is all §2 carries, and the route, method and path
- * never reach this side by design. The description itself is passed through untouched:
- * paraphrasing or truncating it would mean the human approves something other than what the
- * model actually said. Atlas sends it as the model wrote it (its route guard was removed —
- * CONTRACT v2 §3, amended), so this prefix is the only thing in front of the model's own
- * sentence. A placeholder can still arrive from an older Atlas and reads fine after it.
- */
-export declare const PRODUCT_LABELS: Record<string, string>;
-export declare function elicitationMessage(product: string, description: string): string;
-/**
- * CONTRACT §7. THE ACTION IS THE WHOLE ANSWER.
- *
- * | accept  | allow | ""        |
- * | decline | deny  | declined  |
- * | cancel  | deny  | cancelled |
- *
- * Nothing is requested in the form any more, so nothing can contradict the action. There used
- * to be a `confirm` boolean, and it had to go: with an `accept` action that ALREADY means the
- * human approved, `accept` + `confirm: false` is genuinely ambiguous between "I approved, and
- * a checkbox I never saw defaulted to false" and "I unticked it deliberately". The first is a
- * FALSE DENIAL — indistinguishable in the result from a human refusing, which is the exact
- * confusion D3 and N1 existed to remove — and a user hit it live. We cannot tell the two
- * apart, and guessing either way is wrong for the other. `decline` already gives an
- * unambiguous refusal in the same dialog, so the boolean bought nothing.
- *
- * FAIL-CLOSED IS UNCHANGED, and the boolean was never what provided it. A headless client with
- * no human at a terminal returns `cancel` — measured, not assumed (HANDOFF.md) — and `cancel`
- * is a deny. That is why an unattended run still cannot self-approve. It is also why an
- * elicitation is never retried: a second ask cannot conjure a human, only wear one down.
- */
-export declare function decide(result: ElicitResult): {
-    decision: Decision;
-    reason: DecisionReason;
-};
-/**
- * A one-line description of the SHAPE of what a client answered with — never its content.
- *
- * Which client sends what is currently guesswork: the elicitation bug in task 9 had to be
- * fixed without being able to confirm what Claude Code actually submits, because its binary
- * is compiled and its strings too fragmented to read. This line means the next person can
- * look it up instead of inferring it.
- *
- * `action` and `confirm` are a fixed enum and a boolean; neither can carry a description, a
- * credential or anything else a user typed.
- */
-export declare function elicitationShape(result: ElicitResult): string;
-/**
- * Read Atlas's `applied_before_stop`. NEVER DERIVE IT.
- *
- * This side used to compute it as CONTRACT §5's literal "any allow preceded a deny", which
- * could only ever be a guess: an approval whose request then failed counted as applied, so
- * the field lied in the exact direction it exists to prevent (D2). Atlas now computes it
- * from `applied`, which only Atlas can know, and sends it whenever a gate ran — including
- * `false`, including with an empty trail.
- *
- * So a MISSING field is never "false". It is "nobody measured this": either no gate ran, or
- * this Atlas predates the field. `null` says that out loud instead of asserting a fact.
- */
-export declare function readAppliedBeforeStop(payload: Record<string, unknown>): boolean | null;
-/**
- * Atlas's approval trail, when it sent one.
- *
- * Returns `null` — not `[]` — when the key is absent, because an empty trail Atlas DID send
- * ("the relay ran and nothing was asked") is a different fact from no trail at all, and only
- * the second is a reason to fall back to ours.
- *
- * Every entry is rebuilt rather than trusted: a `decision` that is not exactly `"allow"`
- * becomes `"deny"`, so a garbled trail fails closed in the reporting the same way the wire
- * does, and `applied` is carried only when it is genuinely a boolean.
- */
-export declare function parseAtlasApprovals(payload: Record<string, unknown>): ApprovalRecord[] | null;
-/**
- * One phrase per entry, because "approved, then it failed" and "refused" must not read
- * alike — conflating them is the whole reason D2 mattered.
- *
- * An `allow` with no `applied` key is NOT rendered as a failure: nobody measured it, and
- * saying otherwise would invent the very fact this is meant to report.
- */
-/**
- * Every ask was refused because no person was there — not because one said no.
- *
- * `cancelled` is what a client with nobody at the terminal returns (measured), and
- * `no_human` is our own word for the same thing. An EMPTY trail is not this case: nothing
- * was asked at all, which the existing sentences already describe correctly.
- */
-export declare function nobodyAnswered(trail: ApprovalRecord[]): boolean;
-export declare function approvalOutcome(entry: ApprovalRecord): string;
-/**
- * Atlas's own status wins when it declares one; otherwise it is derived from what we can
- * see. Deriving is a last resort, not an interpretation of the answer.
- */
-export declare function deriveStatus(response: AgentResponse, approvals: ApprovalRecord[], needsApproval: unknown[]): AskStatus;
-/** Assemble CONTRACT §5's result. Atlas's payload is carried, never rewritten. */
-export declare function buildResult(response: AgentResponse, approvals: ApprovalRecord[], mode: RelayMode, 
-/** Named in the not-entitled sentence, because entitlement is per product. */
-product?: string): AskResult;
-/**
- * A rejected credential and a refused action are unrelated problems, and a result that lets
- * them read alike sends someone hunting for a human who said no when the real answer is that
- * this server never got through the door.
- *
- * Atlas answers a bad `Authorization` with `401 {"detail": "unauthorized"}` — no `error`
- * string of its own — so without this the caller would see a bare "error" and nothing else.
- * A denial, by contrast, is `status: "blocked"` with a populated `approvals` trail.
- *
- * The token itself is NOT named here, only the variable that should hold it.
- */
-export declare const UNAUTHENTICATED_DETAIL: string;
-/**
- * A result for a call that never reached, or never got past, Atlas.
- *
- * It keeps §5's shape — including the approval trail — because a failure AFTER an approval
- * was granted is exactly the case where a caller most needs to know something may already
- * have been applied.
- */
-export declare function errorResult(message: string, approvals: ApprovalRecord[]): AskResult;