@layr-labs/benchmaxx-arena-mcp 0.1.0

package/dist/errors.js

@@ -0,0 +1,167 @@
+/**
+ * Error types and the mapping from an API failure to one actionable message.
+ *
+ * Two failure kinds reach a tool:
+ *  - `ApiError`: a non-2xx HTTP response. It carries the status and the
+ *    server's `rpcStatus.message` (mirrors frontend/src/api/http.ts).
+ *  - `NetworkError`: the fetch itself rejected (DNS, connection refused, TLS).
+ *
+ * `toActionableMessage` turns either into a single message per issue #166 §5.4.
+ * It never includes a stack trace, a raw response body, or the bearer token.
+ */
+// credentialStore.ts owns CredentialsFileError and imports nothing from here, so
+// this dependency is one-way and introduces no cycle.
+import { CredentialsFileError } from './credentialStore.js';
+/** A failed HTTP call. `message` is the server's message; `status` is the code. */
+export class ApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.name = 'ApiError';
+        this.status = status;
+    }
+}
+/** The fetch rejected before any HTTP status was seen. */
+export class NetworkError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'NetworkError';
+    }
+}
+/**
+ * Raised when the caller cancels a login.
+ *
+ * This lives here rather than in the flow that throws it, so both the client and
+ * the loopback listener raise the one type `toActionableMessage` recognizes. A
+ * plain `Error` would fall through to the generic copy and lose the friendly
+ * message.
+ */
+export class LoginCancelled extends Error {
+    constructor() {
+        super('the login was cancelled.');
+        this.name = 'LoginCancelled';
+    }
+}
+/** Raised when the loopback listener's deadline passes before a code arrives. */
+export class LoginTimedOut extends Error {
+    constructor() {
+        super('the login timed out before the browser returned a code.');
+        this.name = 'LoginTimedOut';
+    }
+}
+/**
+ * Raised when POST /v1/auth/cli/redeem rejects the code or the verifier.
+ *
+ * A redeem 401 is NOT a revoked stored key — no stored key is involved — so it
+ * must not reach the generic 401 mapping, which would tell the user to log in
+ * again with no hint that their code is simply spent.
+ */
+export class CliRedeemFailed extends Error {
+    constructor() {
+        super('the login code was not accepted.');
+        this.name = 'CliRedeemFailed';
+    }
+}
+const CONCURRENCY_PER_USER = 'per-user concurrency cap reached — you already have the maximum number of runs in flight. Wait for a run to finish, then try again.';
+const CONCURRENCY_BENCHMARK = 'benchmark-wide concurrency cap reached — the benchmark is at its global run limit right now. Try again shortly.';
+const SPEND_CAP = 'monthly spend cap reached — your rolling 30-day spend is at its limit. Spend frees up as the window rolls forward.';
+/**
+ * Detect a caps rejection from the server message and name the cap. Returns
+ * undefined when the message is not a caps rejection.
+ *
+ * Matches only explicit spend vocabulary. An earlier version also treated the
+ * bare token `30` as spend (for "rolling 30-day"), which misfired on any message
+ * carrying an unrelated number containing 30 — a prompt-size rejection quoting a
+ * byte count, for instance, was reported as a spend cap. A digit is not
+ * evidence of a spend cap.
+ */
+function capMessage(serverMessage) {
+    const m = serverMessage.toLowerCase();
+    const mentionsCap = m.includes('cap') || m.includes('limit') || m.includes('exceed');
+    if (!mentionsCap) {
+        return undefined;
+    }
+    if (m.includes('spend') ||
+        m.includes('budget') ||
+        m.includes('rolling 30') ||
+        m.includes('30-day') ||
+        m.includes('30 day')) {
+        return SPEND_CAP;
+    }
+    if (m.includes('per-user') || m.includes('per user') || m.includes('your')) {
+        return CONCURRENCY_PER_USER;
+    }
+    if (m.includes('concurren') || m.includes('in flight') || m.includes('run')) {
+        return CONCURRENCY_BENCHMARK;
+    }
+    return undefined;
+}
+/**
+ * Detect a model-not-allowed rejection. The benchmark accepts a fixed set of
+ * models; a prompt submission with any other model is rejected.
+ */
+function modelNotAllowed(serverMessage) {
+    const m = serverMessage.toLowerCase();
+    return (m.includes('model') &&
+        (m.includes('allow') || m.includes('not permitted') || m.includes('not accepted')));
+}
+/**
+ * Map any thrown failure to one actionable message. Leaks no internals: an
+ * unknown error becomes a generic message, never a raw string or stack.
+ */
+export function toActionableMessage(error) {
+    if (error instanceof NetworkError) {
+        return `could not reach the arena — check ${'BENCHMAXX_ARENA_URL'} and try again.`;
+    }
+    // A cancelled login is not a failure to diagnose.
+    if (error instanceof LoginCancelled) {
+        return 'the login was cancelled — run the login tool again when you are ready.';
+    }
+    if (error instanceof LoginTimedOut) {
+        return 'the login timed out waiting for the browser — run the login tool again, and approve the page it opens.';
+    }
+    // The code, not a stored key, is what the server rejected.
+    if (error instanceof CliRedeemFailed) {
+        return 'that code is not valid any more — codes are single-use and expire after five minutes. Run the login tool again.';
+    }
+    // The credential file is broken or unsafe. Its message already names the file
+    // and says to fix or delete it, and it contains no secret — surfacing it is
+    // the whole point, since the user cannot act on "an unexpected error".
+    if (error instanceof CredentialsFileError) {
+        return error.message;
+    }
+    if (error instanceof ApiError) {
+        const server = error.message ?? '';
+        switch (error.status) {
+            case 401:
+                return 'key revoked or invalid — run the login tool first.';
+            case 404:
+                return 'resource not found.';
+            default: {
+                // Both heuristics read the server's prose, and a 5xx's prose is about a
+                // server fault, not the caller's input. Applying them to a 500 told the
+                // user to change their model or wait out a cap when the real cause was
+                // an arena failure they cannot act on. Gate on 4xx: only a client error
+                // is the caller's to fix.
+                if (error.status >= 400 && error.status < 500) {
+                    if (modelNotAllowed(server)) {
+                        return "that model is not on the benchmark's allowed list — call list_benchmarks or get_benchmark to see the allowed models for this variant.";
+                    }
+                    const cap = capMessage(server);
+                    if (cap) {
+                        return cap;
+                    }
+                    // A 4xx with a server message is safe to surface: it is the server's
+                    // own human-readable text, not an internal detail.
+                    if (server) {
+                        return server;
+                    }
+                }
+                return 'the request failed — try again, and if it persists the arena may be having trouble.';
+            }
+        }
+    }
+    // Unknown error kind: never surface its content.
+    return 'an unexpected error occurred.';
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * Entry point for the benchmaxx-arena MCP server.
+ *
+ * Wires the config, the credential store, the API client, and the tools, then
+ * connects the stdio transport. stdout carries the MCP protocol only; operator
+ * text (the login instructions, including the authorize URL when no browser can
+ * be opened) goes to stderr through the client's operator sink.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function buildServer(): McpServer;

package/dist/index.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+/**
+ * Entry point for the benchmaxx-arena MCP server.
+ *
+ * Wires the config, the credential store, the API client, and the tools, then
+ * connects the stdio transport. stdout carries the MCP protocol only; operator
+ * text (the login instructions, including the authorize URL when no browser can
+ * be opened) goes to stderr through the client's operator sink.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { chmod, lstat, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { ArenaClient } from './client.js';
+import { loadConfig } from './config.js';
+import { CredentialStore } from './credentialStore.js';
+import { registerTools } from './tools.js';
+const VERSION = '0.1.0';
+// The global fetch returns a Response, which structurally satisfies the
+// client's FetchResponse (ok, status, text, body). Adapt the init shape.
+const nodeFetch = (input, init) => fetch(input, init);
+export function buildServer() {
+    const config = loadConfig();
+    const store = new CredentialStore({
+        fs: { mkdir, chmod, readFile, writeFile, rename, rm, lstat },
+        homeDir: homedir(),
+        join,
+    });
+    const client = new ArenaClient({
+        origin: config.origin,
+        fetch: nodeFetch,
+        store,
+        operatorLog: (line) => process.stderr.write(`${line}\n`),
+    });
+    const server = new McpServer({ name: 'benchmaxx-arena', version: VERSION });
+    registerTools(server, client);
+    return server;
+}
+async function main() {
+    const server = buildServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    process.stderr.write(`fatal: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;GAOG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAA;AAChF,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AACvF,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,WAAW,EAAkB,MAAM,aAAa,CAAA;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE1C,MAAM,OAAO,GAAG,OAAO,CAAA;AAEvB,wEAAwE;AACxE,yEAAyE;AACzE,MAAM,SAAS,GAAc,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAC3C,KAAK,CAAC,KAAK,EAAE,IAAmB,CAAqC,CAAA;AAEvE,MAAM,UAAU,WAAW;IACzB,MAAM,MAAM,GAAG,UAAU,EAAE,CAAA;IAE3B,MAAM,KAAK,GAAG,IAAI,eAAe,CAAC;QAChC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE;QAC5D,OAAO,EAAE,OAAO,EAAE;QAClB,IAAI;KACL,CAAC,CAAA;IAEF,MAAM,MAAM,GAAG,IAAI,WAAW,CAAC;QAC7B,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,KAAK,EAAE,SAAS;QAChB,KAAK;QACL,WAAW,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC;KACzD,CAAC,CAAA;IAEF,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAA;IAC3E,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7B,OAAO,MAAM,CAAA;AACf,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,WAAW,EAAE,CAAA;IAC5B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAA;IAC5C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;AACjC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IAC1F,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;AACjB,CAAC,CAAC,CAAA"}

package/dist/loopback.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The single-shot loopback listener that receives the authorization code.
+ *
+ * The server binds 127.0.0.1 ONLY, never 0.0.0.0: the callback must be
+ * unreachable from the network. It serves the one callback request and then
+ * stops. The state nonce ties the callback to the flow that started it, and the
+ * comparison is constant-time, so a wrong state cannot be probed byte by byte.
+ *
+ * The code arrives in a query parameter, so nothing here logs the request line
+ * or the URL.
+ */
+/** How long the listener waits for the browser by default: the code's own TTL. */
+export declare const DEFAULT_LOOPBACK_TIMEOUT_MS: number;
+export interface WaitOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+export interface LoopbackListener {
+    /** The bound ephemeral port. */
+    port: number;
+    /** The full callback URL to hand to the frontend. */
+    callbackUrl: string;
+    /** Resolve with the code once a callback carrying the matching state arrives. */
+    waitForCode(state: string, options?: WaitOptions): Promise<string>;
+    /** Stop listening. Safe to call more than once. */
+    close(): Promise<void>;
+}
+/** Bind an ephemeral loopback port and return the listener handle. */
+export declare function startLoopbackListener(): Promise<LoopbackListener>;

package/dist/loopback.js

@@ -0,0 +1,120 @@
+/**
+ * The single-shot loopback listener that receives the authorization code.
+ *
+ * The server binds 127.0.0.1 ONLY, never 0.0.0.0: the callback must be
+ * unreachable from the network. It serves the one callback request and then
+ * stops. The state nonce ties the callback to the flow that started it, and the
+ * comparison is constant-time, so a wrong state cannot be probed byte by byte.
+ *
+ * The code arrives in a query parameter, so nothing here logs the request line
+ * or the URL.
+ */
+import { createServer } from 'node:http';
+import { timingSafeEqual } from 'node:crypto';
+// errors.ts imports only credentialStore.js, so this edge is one-way: the
+// listener's rejections carry the types toActionableMessage recognizes, instead
+// of plain Errors that would fall through to its generic copy.
+import { LoginCancelled, LoginTimedOut } from './errors.js';
+/** How long the listener waits for the browser by default: the code's own TTL. */
+export const DEFAULT_LOOPBACK_TIMEOUT_MS = 5 * 60 * 1000;
+const CALLBACK_PATH = '/cb';
+const SUCCESS_PAGE = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><title>Signed in</title></head>
+<body style="font-family:system-ui;padding:2rem">
+<h1>You are signed in</h1>
+<p>Close this tab and return to your terminal.</p>
+</body></html>
+`;
+/** Constant-time string compare that tolerates unequal lengths. */
+function safeEqual(a, b) {
+    const bufA = Buffer.from(a);
+    const bufB = Buffer.from(b);
+    if (bufA.length !== bufB.length) {
+        return false;
+    }
+    return timingSafeEqual(bufA, bufB);
+}
+function respond(res, status, body, contentType) {
+    res.writeHead(status, { 'Content-Type': contentType, 'Cache-Control': 'no-store' });
+    res.end(body);
+}
+/** Bind an ephemeral loopback port and return the listener handle. */
+export async function startLoopbackListener() {
+    let onCallback;
+    let onFailure;
+    let expectedState;
+    const server = createServer((req, res) => {
+        // Parse against a fixed base: req.url is a path, not an absolute URL.
+        const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+        if (url.pathname !== CALLBACK_PATH) {
+            respond(res, 404, 'not found', 'text/plain; charset=utf-8');
+            return;
+        }
+        const code = url.searchParams.get('code');
+        const state = url.searchParams.get('state');
+        if (!code || !state || !expectedState || !safeEqual(state, expectedState)) {
+            respond(res, 400, 'this callback does not match a login in progress', 'text/plain; charset=utf-8');
+            return;
+        }
+        respond(res, 200, SUCCESS_PAGE, 'text/html; charset=utf-8');
+        onCallback?.(code);
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        // 127.0.0.1 only. Binding 0.0.0.0 would expose the callback to the network.
+        server.listen(0, '127.0.0.1', () => {
+            server.removeListener('error', reject);
+            resolve();
+        });
+    });
+    const address = server.address();
+    const port = address.port;
+    let closed = false;
+    const close = async () => {
+        if (closed)
+            return;
+        closed = true;
+        await new Promise((resolve) => server.close(() => resolve()));
+        // A closed listener can never deliver a code, so an in-flight wait is
+        // failed here rather than left pending until its timeout.
+        const fail = onFailure;
+        onFailure = undefined;
+        onCallback = undefined;
+        fail?.(new Error('the login listener closed before the browser returned a code.'));
+    };
+    const waitForCode = (state, options = {}) => {
+        expectedState = state;
+        const timeoutMs = options.timeoutMs ?? DEFAULT_LOOPBACK_TIMEOUT_MS;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                cleanup();
+                reject(new LoginTimedOut());
+            }, timeoutMs);
+            const onAbort = () => {
+                cleanup();
+                reject(new LoginCancelled());
+            };
+            const cleanup = () => {
+                clearTimeout(timer);
+                options.signal?.removeEventListener('abort', onAbort);
+                onCallback = undefined;
+                onFailure = undefined;
+            };
+            if (options.signal?.aborted) {
+                onAbort();
+                return;
+            }
+            options.signal?.addEventListener('abort', onAbort, { once: true });
+            onCallback = (code) => {
+                cleanup();
+                resolve(code);
+            };
+            onFailure = (error) => {
+                cleanup();
+                reject(error);
+            };
+        });
+    };
+    return { port, callbackUrl: `http://127.0.0.1:${port}${CALLBACK_PATH}`, waitForCode, close };
+}
+//# sourceMappingURL=loopback.js.map

package/dist/loopback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loopback.js","sourceRoot":"","sources":["../src/loopback.ts"],"names":[],"mappings":"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"}

package/dist/pkce.d.ts

@@ -0,0 +1,24 @@
+/**
+ * PKCE (RFC 7636) values for the loopback login.
+ *
+ * The verifier never leaves this process until redemption. The challenge is the
+ * unpadded base64url SHA-256 of the verifier, and it travels through the
+ * browser in a query parameter. A code observed in browser history is therefore
+ * useless to anything that does not hold the verifier.
+ */
+/** A verifier and its S256 challenge. */
+export interface PkcePair {
+    verifier: string;
+    challenge: string;
+}
+/**
+ * Create a verifier and its challenge. 32 random bytes encode to 43 base64url
+ * characters, which is the RFC's minimum verifier length and the exact length of
+ * an S256 challenge.
+ */
+export declare function createPkcePair(): PkcePair;
+/**
+ * Create the state nonce that ties a callback to the flow that started it. The
+ * listener refuses a callback whose state does not match.
+ */
+export declare function createStateNonce(): string;

package/dist/pkce.js

@@ -0,0 +1,27 @@
+/**
+ * PKCE (RFC 7636) values for the loopback login.
+ *
+ * The verifier never leaves this process until redemption. The challenge is the
+ * unpadded base64url SHA-256 of the verifier, and it travels through the
+ * browser in a query parameter. A code observed in browser history is therefore
+ * useless to anything that does not hold the verifier.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+/**
+ * Create a verifier and its challenge. 32 random bytes encode to 43 base64url
+ * characters, which is the RFC's minimum verifier length and the exact length of
+ * an S256 challenge.
+ */
+export function createPkcePair() {
+    const verifier = randomBytes(32).toString('base64url');
+    const challenge = createHash('sha256').update(verifier).digest('base64url');
+    return { verifier, challenge };
+}
+/**
+ * Create the state nonce that ties a callback to the flow that started it. The
+ * listener refuses a callback whose state does not match.
+ */
+export function createStateNonce() {
+    return randomBytes(16).toString('hex');
+}
+//# sourceMappingURL=pkce.js.map

package/dist/pkce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkce.js","sourceRoot":"","sources":["../src/pkce.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAQrD;;;;GAIG;AACH,MAAM,UAAU,cAAc;IAC5B,MAAM,QAAQ,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAA;IACtD,MAAM,SAAS,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAA;IAC3E,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAA;AAChC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;AACxC,CAAC"}

package/dist/tools.d.ts

@@ -0,0 +1,28 @@
+/**
+ * MCP tool registration.
+ *
+ * Each tool validates its input with a Zod schema (the SDK builds the advertised
+ * JSON Schema from it and rejects bad input before the handler runs), calls the
+ * client, and returns pretty-printed JSON text plus `structuredContent`. A
+ * failure returns `isError: true` with one actionable message from
+ * `toActionableMessage`. No tool prints to stdout, which carries the MCP
+ * protocol only: login instructions — the authorize URL on the no-browser path,
+ * and liveness while a human approves — go to stderr through the client's
+ * operator sink and to the host as an MCP progress notification.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ArenaClient } from './client.js';
+import type { LeaderboardResponse } from './apiTypes.js';
+/**
+ * Human explanation for an empty leaderboard, using the epoch and baseline
+ * signals to distinguish the causes of zero rows.
+ *
+ * The baseline test must be `== null`, not `=== undefined`. `baseline` is a
+ * message field and the gateway sets `EmitUnpopulated: true`, so an unset
+ * baseline arrives as an explicit `null` and an `=== undefined` test never
+ * fires. (The field it replaced, the scalar `baselinePass`, arrived as `0` when
+ * unset for the same reason, so that test never fired either.) `== null`
+ * catches both null and a genuinely absent key.
+ */
+export declare function explainEmptyLeaderboard(board: LeaderboardResponse): string;
+export declare function registerTools(server: McpServer, client: ArenaClient): void;