aztrx-cli 0.4.4 → 0.5.1

package/dist/mcp/index.js

@@ -0,0 +1,295 @@
+/**
+ * `aztrx-cli mcp` — the server an editor talks to.
+ *
+ * stdio transport, newline-delimited JSON-RPC, one message per line. That is the
+ * whole interface; everything else is in `protocol.ts` (framing and the two
+ * protocol eras), `tools.ts` (the three tools) and `install.ts` (writing the
+ * editor config).
+ *
+ * Three things here are load-bearing and easy to get wrong:
+ *
+ *  - **stdout belongs to the protocol.** One stray byte and the client's parser
+ *    dies on a line it cannot read. The orchestrator is silent under `ui: true`,
+ *    and `redirectStdoutToStderr` catches anything else that prints.
+ *  - **Boot fast, import late.** Editors time out slow servers, so nothing heavy
+ *    is imported at module load. Playwright arrives on the first scan, not on
+ *    `initialize`.
+ *  - **Exit when stdin ends.** The stdio shutdown sequence is: the client closes
+ *    our stdin, waits, then escalates to SIGTERM and SIGKILL. A server that
+ *    ignores the first step leaves an orphan holding a dev server's port and a
+ *    Chromium handle after every editor session.
+ */
+import { format } from "util";
+import { VERSION } from "../core/version.js";
+import { checkVersion, decode, encode, error, INTERNAL_ERROR, INVALID_PARAMS, isNotification, METHOD_NOT_FOUND, META_SERVER_INFO, negotiate, ProtocolError, result, serverInfo, SUPPORTED_VERSIONS, supports, } from "./protocol.js";
+import { McpRuntime, TOOLS } from "./tools.js";
+/** What a model sees when the tools are first offered to it. Short on purpose:
+ * it is prepended to every conversation that has this server attached. */
+const INSTRUCTIONS = "aztrx drives the app in a real browser and reports the runtime crashes it produced. " +
+    "Call aztrx_scan before claiming a change works — treat its clean result as the evidence " +
+    "that the app still runs. A scan that could not run says so; it never reports 'no findings' " +
+    "for an app it never reached. Findings are proven, not guessed: aztrx_repro shows the exact " +
+    "steps that reproduce one, and aztrx_fix patches it and re-verifies by replaying them.";
+/** Nothing here varies per caller or per connection, so both list results are
+ * publicly cacheable. Long enough to be worth caching, short enough that a
+ * version upgrade is picked up without a restart. */
+const TOOLS_TTL_MS = 300_000;
+const DISCOVER_TTL_MS = 3_600_000;
+/** Reroute the console's stdout-bound writers to stderr, for good.
+ *
+ * `ui: true` already silences the orchestrator, so this is the net under the net:
+ * a dependency's warning, or a `console.log` in some path nobody thought about,
+ * would otherwise land in the middle of the protocol stream. Nothing is lost by
+ * moving it — the spec sanctions stderr for *all* logging on stdio transports.
+ * `console.error` and `console.warn` already write to stderr and are left alone.
+ *
+ * Returns the undo, which the tests use to prove the guard can fail. */
+export function redirectStdoutToStderr(target) {
+    const previous = {
+        log: console.log,
+        info: console.info,
+        debug: console.debug,
+        dir: console.dir,
+    };
+    const toStderr = (...args) => {
+        target.write(format(...args) + "\n");
+    };
+    console.log = toStderr;
+    console.info = toStderr;
+    console.debug = toStderr;
+    console.dir = ((item) => toStderr(item));
+    return () => {
+        Object.assign(console, previous);
+    };
+}
+export async function startServer(opts = {}) {
+    const real = opts.io === undefined;
+    const io = opts.io ?? {
+        input: process.stdin,
+        output: process.stdout,
+        error: process.stderr,
+    };
+    const runtime = opts.runtime ?? new McpRuntime({ defaultRepoRoot: opts.repoRoot });
+    const restoreConsole = redirectStdoutToStderr(io.error);
+    // -------------------------------------------------------------------------
+    // Writing
+    // -------------------------------------------------------------------------
+    /** One message, one line, written whole.
+     *
+     * No interleaving guard is needed: `process.stdout` is a Writable, and a
+     * Writable runs its queued chunks in the order they were written, so two
+     * responses can never splice into each other. */
+    function send(message) {
+        io.output.write(encode(message));
+    }
+    // -------------------------------------------------------------------------
+    // Dispatch
+    // -------------------------------------------------------------------------
+    let stopping;
+    async function teardown() {
+        if (stopping)
+            return stopping;
+        stopping = (async () => {
+            restoreConsole();
+            // Dev servers this process booted are its children and nothing else will
+            // reap them. A browser inside an in-flight scan cannot be reached from
+            // here, but Playwright launches Chromium on a CDP pipe — this process
+            // exiting closes it, and that is what shuts the browser down.
+            await runtime.closeAll().catch(() => { });
+        })();
+        return stopping;
+    }
+    function discoverResult() {
+        return {
+            supportedVersions: [...SUPPORTED_VERSIONS],
+            capabilities: { tools: {} },
+            // Server identity lives in `_meta` under this key, not in a top-level
+            // field — the shape is the spec's, and a client that reads it from
+            // anywhere else reads nothing.
+            _meta: { [META_SERVER_INFO]: serverInfo(VERSION) },
+            instructions: INSTRUCTIONS,
+            ttlMs: DISCOVER_TTL_MS,
+            cacheScope: "public",
+        };
+    }
+    /** The legacy handshake. Answering it at all is what makes this dual-era. */
+    function initializeResult(msg) {
+        const requested = msg.params?.["protocolVersion"];
+        const agreed = negotiate(requested);
+        if (!supports(requested)) {
+            io.error.write(`aztrx mcp: client asked for protocol version ${JSON.stringify(requested)}, ` +
+                `serving ${agreed}. Legacy clients have no fall-forward, so this may end the session.\n`);
+        }
+        return {
+            protocolVersion: agreed,
+            // Exactly what we serve. Declaring `prompts`, `resources`, `logging` or
+            // `completions` would be a promise the code would break.
+            capabilities: { tools: {} },
+            serverInfo: serverInfo(VERSION),
+            instructions: INSTRUCTIONS,
+        };
+    }
+    async function toolCall(id, msg) {
+        const name = msg.params?.["name"];
+        if (typeof name !== "string" || !name) {
+            throw new ProtocolError(INVALID_PARAMS, "tools/call requires a `name`");
+        }
+        const raw = msg.params?.["arguments"];
+        if (raw !== undefined && raw !== null && (typeof raw !== "object" || Array.isArray(raw))) {
+            throw new ProtocolError(INVALID_PARAMS, "`arguments` must be an object");
+        }
+        const res = await runtime.call(name, (raw ?? {}));
+        return result(id, {
+            content: res.content,
+            structuredContent: res.structuredContent,
+            isError: res.isError === true,
+        });
+    }
+    async function route(msg) {
+        const id = msg.id ?? null;
+        switch (msg.method) {
+            case "initialize":
+                return result(id, initializeResult(msg));
+            case "server/discover":
+                return result(id, discoverResult());
+            case "tools/list":
+                // Deterministic order (the array is a literal) and cacheable. There is no
+                // pagination: three tools fit in one page, so `nextCursor` is never sent
+                // and a cursor from a client is ignored.
+                return result(id, { tools: TOOLS, ttlMs: TOOLS_TTL_MS, cacheScope: "public" });
+            case "tools/call":
+                return toolCall(id, msg);
+            // Removed by 2026-07-28, still sent by handshake-era clients as a liveness
+            // check. Answering costs nothing and a -32601 here reads to some of them as
+            // a dead server.
+            case "ping":
+                return result(id);
+            default:
+                throw new ProtocolError(METHOD_NOT_FOUND, `Method not found: ${msg.method}`);
+        }
+    }
+    async function handleRequest(msg) {
+        const id = msg.id ?? null;
+        try {
+            return await route(msg);
+        }
+        catch (e) {
+            if (e instanceof ProtocolError)
+                return error(id, e.code, e.message, e.data);
+            io.error.write(`aztrx mcp: ${e.stack ?? String(e)}\n`);
+            return error(id, INTERNAL_ERROR, `Internal error: ${e.message}`);
+        }
+    }
+    // In-flight requests, by id, with the way to mark one abandoned.
+    const inflight = new Map();
+    const abandoned = new Set();
+    const keyOf = (id) => `${typeof id}:${String(id)}`;
+    /** How a stdio client abandons a request — a cancelled scan, a user who hit
+     * stop. A notification, so it gets no reply of its own, and the request it
+     * names gets none either: a response to a request the client has moved on from
+     * is worse than silence, because it desynchronises the id sequence. */
+    function cancelInFlight(msg) {
+        const raw = msg.params?.["requestId"];
+        if (typeof raw !== "string" && typeof raw !== "number")
+            return;
+        const key = keyOf(raw);
+        const cancel = inflight.get(key);
+        if (!cancel)
+            return;
+        abandoned.add(key);
+        cancel();
+    }
+    async function handleMessage(msg) {
+        if (isNotification(msg)) {
+            if (msg.method === "notifications/cancelled")
+                cancelInFlight(msg);
+            return;
+        }
+        const versionRejected = checkVersion(msg);
+        if (versionRejected) {
+            send(versionRejected);
+            return;
+        }
+        const key = keyOf(msg.id ?? null);
+        let markAbandoned;
+        const abandonedSignal = new Promise((resolve) => {
+            markAbandoned = () => resolve(null);
+        });
+        inflight.set(key, markAbandoned);
+        try {
+            // We stop *waiting*, we cannot stop the browser mid-walk — `run()` has no
+            // abort. The abandoned scan finishes in the background, its result is
+            // discarded, and its `finally` still stops the dev server it booted, so
+            // nothing is orphaned either way.
+            const response = await Promise.race([handleRequest(msg), abandonedSignal]);
+            if (response !== null && !abandoned.has(key))
+                send(response);
+        }
+        finally {
+            inflight.delete(key);
+            abandoned.delete(key);
+        }
+    }
+    async function handleLine(line) {
+        if (!line.trim())
+            return;
+        try {
+            const decoded = decode(line.trim());
+            if (!decoded.ok) {
+                send(decoded.response);
+                return;
+            }
+            await handleMessage(decoded.msg);
+        }
+        catch (e) {
+            // Nothing above should throw, and the protocol channel must survive it if
+            // something does.
+            io.error.write(`aztrx mcp: unhandled error on a request: ${e.message}\n`);
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Reading
+    // -------------------------------------------------------------------------
+    /** Feed the reader ourselves rather than using `readline`.
+     *
+     * The framing is newline-delimited JSON, which is a five-line buffer loop and
+     * gives exact control over what counts as a message. `readline` also runs
+     * terminal handling when its input is a TTY, which a protocol channel should
+     * never be subject to. A chunk that ends mid-line is carried over — plenty of
+     * clients write a request in more than one `write()`. */
+    let buffer = "";
+    const onData = (chunk) => {
+        buffer += chunk.toString();
+        let at;
+        while ((at = buffer.indexOf("\n")) >= 0) {
+            const line = buffer.slice(0, at);
+            buffer = buffer.slice(at + 1);
+            void handleLine(line);
+        }
+    };
+    const onEnd = () => {
+        void exitNow(0);
+    };
+    io.input.on("data", onData);
+    io.input.on("end", onEnd);
+    async function exitNow(code) {
+        await teardown();
+        // Only a real process exits. A test that called `startServer` with its own
+        // streams keeps running and asserts on what it captured.
+        if (real)
+            process.exit(code);
+    }
+    if (real) {
+        process.on("SIGTERM", () => void exitNow(143));
+        process.on("SIGINT", () => void exitNow(130));
+    }
+    io.error.write(`aztrx mcp ${VERSION} — serving ${TOOLS.length} tools on stdio\n`);
+    return {
+        runtime,
+        stop: async () => {
+            io.input.off("data", onData);
+            io.input.off("end", onEnd);
+            await teardown();
+        },
+    };
+}

package/dist/mcp/install.d.ts

@@ -0,0 +1,52 @@
+/**
+ * `aztrx-cli mcp install` — write the editor config that starts this server.
+ *
+ * This mirrors the discipline of `hook install` (`src/hooks/index.ts`), with one
+ * difference that changes everything: an MCP config file is **shared with other
+ * servers**. A hook file is ours; `.mcp.json` is not. So this never writes a whole
+ * file, it edits one key inside one — read, parse, add, write back — and it
+ * refuses rather than clobbers when the file will not parse. A refused install is
+ * a message the user can act on; a clobbered config is their other three servers
+ * gone, discovered a week later.
+ */
+/** The key our server lives under. Also the marker we look for on uninstall. */
+export declare const MCP_SERVER_NAME = "aztrx";
+export interface EditorTarget {
+    id: string;
+    label: string;
+    /** Path relative to the repo root. */
+    file: string;
+    /** The key the servers live under. VS Code's differs, and conflating the two
+     * produces a file that editor reads as having no servers in it at all. */
+    key: string;
+    /** Only offered when this path exists. An editor the project does not use
+     * should be reported as skipped, not written to. */
+    marker?: string;
+}
+export declare const TARGETS: EditorTarget[];
+/** What each editor runs.
+ *
+ * Pinned to this build's version, so upgrading the CLI is upgrading the server —
+ * a config that says `aztrx-cli@latest` would silently change under the user.
+ * `npx -y` because an editor spawns this from a fresh shell with no PATH set up
+ * for the project. */
+export declare function serverEntry(version: string): Record<string, unknown>;
+export type ConfigStatus = "written" | "unchanged" | "skipped" | "refused";
+export interface ConfigOutcome {
+    target: EditorTarget;
+    status: ConfigStatus;
+    path: string;
+    message: string;
+}
+export declare function installInto(repoRoot: string, target: EditorTarget, version: string, force?: boolean): ConfigOutcome;
+export declare function uninstallFrom(repoRoot: string, target: EditorTarget): ConfigOutcome;
+export interface InstallSummary {
+    outcomes: ConfigOutcome[];
+    /** True when at least one file was written. */
+    changed: boolean;
+    /** True when every target was skipped or refused — nothing to tell the user
+     * about beyond what the individual messages already say. */
+    nothingDone: boolean;
+}
+export declare function installMcp(repoRoot: string, version: string, force?: boolean): InstallSummary;
+export declare function uninstallMcp(repoRoot: string): InstallSummary;

package/dist/mcp/install.js

@@ -0,0 +1,204 @@
+/**
+ * `aztrx-cli mcp install` — write the editor config that starts this server.
+ *
+ * This mirrors the discipline of `hook install` (`src/hooks/index.ts`), with one
+ * difference that changes everything: an MCP config file is **shared with other
+ * servers**. A hook file is ours; `.mcp.json` is not. So this never writes a whole
+ * file, it edits one key inside one — read, parse, add, write back — and it
+ * refuses rather than clobbers when the file will not parse. A refused install is
+ * a message the user can act on; a clobbered config is their other three servers
+ * gone, discovered a week later.
+ */
+import * as fs from "fs";
+import * as path from "path";
+/** The key our server lives under. Also the marker we look for on uninstall. */
+export const MCP_SERVER_NAME = "aztrx";
+export const TARGETS = [
+    // Always offered: `.mcp.json` at the repo root is the portable form, and a
+    // project that has not opened Claude Code yet can still commit one.
+    { id: "claude-code", label: "Claude Code", file: ".mcp.json", key: "mcpServers" },
+    {
+        id: "cursor",
+        label: "Cursor",
+        file: ".cursor/mcp.json",
+        key: "mcpServers",
+        marker: ".cursor",
+    },
+    { id: "vscode", label: "VS Code", file: ".vscode/mcp.json", key: "servers", marker: ".vscode" },
+];
+/** What each editor runs.
+ *
+ * Pinned to this build's version, so upgrading the CLI is upgrading the server —
+ * a config that says `aztrx-cli@latest` would silently change under the user.
+ * `npx -y` because an editor spawns this from a fresh shell with no PATH set up
+ * for the project. */
+export function serverEntry(version) {
+    return { type: "stdio", command: "npx", args: ["-y", `aztrx-cli@${version}`, "mcp"] };
+}
+function isObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function loadJson(abs) {
+    if (!fs.existsSync(abs))
+        return { ok: true, doc: {} };
+    let raw;
+    try {
+        raw = fs.readFileSync(abs, "utf-8");
+    }
+    catch (e) {
+        return { ok: false, error: `it cannot be read: ${e.message}` };
+    }
+    // An empty file is an empty config, not a syntax error — `.mcp.json` gets
+    // created by hand as often as by a tool.
+    if (!raw.trim())
+        return { ok: true, doc: {} };
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch (e) {
+        // V8's message starts with a capital and is spliced into the middle of our
+        // sentence ("… exists and Expected double-quoted property name …").
+        const msg = e.message;
+        return { ok: false, error: msg.charAt(0).toLowerCase() + msg.slice(1) };
+    }
+    if (!isObject(value))
+        return { ok: false, error: "its top level is not a JSON object" };
+    return { ok: true, doc: value };
+}
+/** Copy the file aside before an overwrite we could not parse.
+ *
+ * Best effort on purpose. The refusal above is the safety; this is the kindness —
+ * a JSON syntax error is usually one missing comma, and the user's other servers
+ * are in there. */
+function backup(abs) {
+    const dest = `${abs}.bak`;
+    try {
+        fs.copyFileSync(abs, dest);
+        return dest;
+    }
+    catch {
+        return null;
+    }
+}
+function writeJson(abs, doc) {
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, JSON.stringify(doc, null, 2) + "\n", "utf-8");
+}
+// ---------------------------------------------------------------------------
+// install / uninstall
+// ---------------------------------------------------------------------------
+export function installInto(repoRoot, target, version, force = false) {
+    const abs = path.join(repoRoot, target.file);
+    if (target.marker && !fs.existsSync(path.join(repoRoot, target.marker))) {
+        return {
+            target,
+            status: "skipped",
+            path: abs,
+            message: `no ${target.marker}/ in this project`,
+        };
+    }
+    const loaded = loadJson(abs);
+    // Unparseable and forced → start from empty rather than from the broken parse.
+    let doc = loaded.ok ? loaded.doc : {};
+    let note = "";
+    if (!loaded.ok) {
+        if (!force) {
+            return {
+                target,
+                status: "refused",
+                path: abs,
+                message: `${target.file} exists and ${loaded.error} — refusing to overwrite it, because any ` +
+                    "other MCP servers in it would go too. Fix the file, or pass --force (which saves a " +
+                    ".bak first).",
+            };
+        }
+        const saved = backup(abs);
+        note = saved ? ` (previous contents saved to ${path.basename(saved)})` : "";
+    }
+    const existing = doc[target.key];
+    if (existing !== undefined && !isObject(existing)) {
+        if (!force) {
+            return {
+                target,
+                status: "refused",
+                path: abs,
+                message: `${target.file} has a \`${target.key}\` key that is not an object — refusing to overwrite it.`,
+            };
+        }
+        const saved = backup(abs);
+        note = saved ? ` (previous contents saved to ${path.basename(saved)})` : "";
+        // Drop just the malformed key. Everything else at the top level of the file
+        // — `$schema`, an editor's other settings — is still readable and still the
+        // user's, so only the key we cannot merge into is discarded.
+        delete doc[target.key];
+    }
+    const slot = doc[target.key];
+    const servers = isObject(slot) ? slot : {};
+    const hadOurs = MCP_SERVER_NAME in servers;
+    servers[MCP_SERVER_NAME] = serverEntry(version);
+    doc[target.key] = servers;
+    const next = JSON.stringify(doc, null, 2) + "\n";
+    const current = fs.existsSync(abs) ? fs.readFileSync(abs, "utf-8") : null;
+    if (current === next) {
+        return { target, status: "unchanged", path: abs, message: `${target.file} is already up to date` };
+    }
+    writeJson(abs, doc);
+    const others = Object.keys(servers).filter((k) => k !== MCP_SERVER_NAME).length;
+    const kept = others
+        ? ` ${others} other server${others === 1 ? "" : "s"} in the file left untouched.`
+        : "";
+    return {
+        target,
+        status: "written",
+        path: abs,
+        message: `${target.file} — ${hadOurs ? "updated" : "added"}.${kept}${note}`,
+    };
+}
+export function uninstallFrom(repoRoot, target) {
+    const abs = path.join(repoRoot, target.file);
+    const rel = target.file;
+    if (!fs.existsSync(abs)) {
+        return { target, status: "skipped", path: abs, message: `no ${rel}` };
+    }
+    const loaded = loadJson(abs);
+    if (!loaded.ok) {
+        return {
+            target,
+            status: "refused",
+            path: abs,
+            message: `${rel} ${loaded.error} — leaving it alone.`,
+        };
+    }
+    const servers = loaded.doc[target.key];
+    if (!isObject(servers) || !(MCP_SERVER_NAME in servers)) {
+        return { target, status: "skipped", path: abs, message: `no aztrx entry in ${rel}` };
+    }
+    delete servers[MCP_SERVER_NAME];
+    // The file stays even when that leaves the map empty. Deleting a file we did
+    // not create, on the strength of it looking empty afterwards, is a worse
+    // failure than four bytes of leftover JSON.
+    writeJson(abs, loaded.doc);
+    return {
+        target,
+        status: "written",
+        path: abs,
+        message: `${rel} — aztrx entry removed (the file is kept: other servers may live in it).`,
+    };
+}
+export function installMcp(repoRoot, version, force = false) {
+    const outcomes = TARGETS.map((t) => installInto(repoRoot, t, version, force));
+    return {
+        outcomes,
+        changed: outcomes.some((o) => o.status === "written"),
+        nothingDone: outcomes.every((o) => o.status === "skipped" || o.status === "refused"),
+    };
+}
+export function uninstallMcp(repoRoot) {
+    const outcomes = TARGETS.map((t) => uninstallFrom(repoRoot, t));
+    return {
+        outcomes,
+        changed: outcomes.some((o) => o.status === "written"),
+        nothingDone: outcomes.every((o) => o.status === "skipped" || o.status === "refused"),
+    };
+}

package/dist/mcp/protocol.d.ts

@@ -0,0 +1,106 @@
+/**
+ * MCP wire format — framing, version negotiation, result envelopes.
+ *
+ * Hand-rolled, deliberately. Revisions `2025-11-25` and earlier open with an
+ * `initialize` handshake; `2026-07-28` removed it in favour of per-request
+ * metadata. Editors are split across the two (Cursor still opens with
+ * `initialize`), and neither official SDK speaks both: `@modelcontextprotocol/sdk`
+ * is legacy-only and pulls 17 runtime dependencies — express, hono, cors, jose,
+ * ajv — for a stdio server that needs none of them, and
+ * `@modelcontextprotocol/server` is the new revision only. A server that speaks
+ * one era is a server that is missing from somebody's editor. The spec has a name
+ * for the thing that speaks both — **dual-era** — and rules for it, which this
+ * follows rather than reinvents.
+ *
+ * This file imports nothing at all. It is loaded before the first request from
+ * an editor, and editors time out servers that boot slowly.
+ */
+/** Every revision this server can serve, oldest first. `2026-07-28` is the one
+ * that made `server/discover` mandatory and `resultType` required; the earlier
+ * four are the handshake era, and `2025-06-18` / `2025-11-25` are what the
+ * editors in the wild actually send today. */
+export declare const SUPPORTED_VERSIONS: readonly ["2024-11-05", "2025-03-26", "2025-06-18", "2025-11-25", "2026-07-28"];
+/** Newest revision implemented. Used only when we cannot serve what was asked
+ * for — never to "upgrade" a client that asked for something older. */
+export declare const LATEST_VERSION: string;
+/** `_meta` keys, per the `_meta` naming rules in the 2026-07-28 base spec. */
+export declare const META_PROTOCOL_VERSION = "io.modelcontextprotocol/protocolVersion";
+export declare const META_SERVER_INFO = "io.modelcontextprotocol/serverInfo";
+export declare const PARSE_ERROR = -32700;
+export declare const INVALID_REQUEST = -32600;
+export declare const METHOD_NOT_FOUND = -32601;
+export declare const INVALID_PARAMS = -32602;
+export declare const INTERNAL_ERROR = -32603;
+/** `UnsupportedProtocolVersionError`, per the 2026-07-28 error-code table. The
+ * number is not decorative: a modern client matches on it to tell "this server
+ * speaks my language but not this dialect — retry with one off `supported`"
+ * from "this server is old", and the two lead to opposite actions. */
+export declare const UNSUPPORTED_PROTOCOL_VERSION = -32022;
+export type RpcId = string | number | null;
+export interface RpcMessage {
+    jsonrpc?: string;
+    id?: RpcId;
+    method?: string;
+    params?: Record<string, unknown>;
+    result?: unknown;
+    error?: unknown;
+}
+/** A failure of the *request* — bad method, bad shape. Distinct from a tool that
+ * ran and reported a problem, which is a normal result with `isError: true`. */
+export declare class ProtocolError extends Error {
+    readonly code: number;
+    readonly data?: unknown | undefined;
+    constructor(code: number, message: string, data?: unknown | undefined);
+}
+/** One JSON-RPC message, one line. That is the stdio binding, and `JSON.stringify`
+ * already guarantees it — a newline inside a string is escaped, never emitted raw. */
+export declare function encode(message: unknown): string;
+export type Decoded = {
+    ok: true;
+    msg: RpcMessage;
+} | {
+    ok: false;
+    response: RpcMessage;
+};
+/** Parse one line. A line that is not JSON has an unknowable id, so the error
+ * goes out with a null one — the JSON-RPC rule for exactly this case. */
+export declare function decode(line: string): Decoded;
+/** A request expects exactly one response; a notification expects none, and
+ * answering one is a protocol violation. `id` is what separates them — a
+ * notification simply has no `id` member. */
+export declare function isNotification(msg: RpcMessage): boolean;
+export declare function supports(version: unknown): version is string;
+/** The version a *modern* request declares in `_meta`, or undefined for a legacy
+ * request (which declares nothing — its version was fixed by `initialize`). */
+export declare function declaredVersion(msg: RpcMessage): string | undefined;
+/** Which version to answer a legacy `initialize` with.
+ *
+ * The legacy spec makes this a **MUST**, not a courtesy: *"If the server supports
+ * the requested protocol version, it MUST respond with the same version.
+ * Otherwise, the server MUST respond with another protocol version it supports."*
+ * So we echo what was asked for whenever we can serve it. Answering `initialize`
+ * with our newest version when the client asked for an older one we support is a
+ * spec violation, and it is the documented way to make a modern client refuse the
+ * server outright ("Server's protocol version is not supported") — the client has
+ * no fall-forward mechanism, so a needless mismatch is fatal, not merely noisy. */
+export declare function negotiate(requested: unknown): string;
+/** Reject a request that declares a version we do not implement. Returns a
+ * ready-to-send error, or null when the request may proceed.
+ *
+ * Only modern requests declare a version; a legacy request carries none and is
+ * served under legacy semantics for the life of the process. The `data` shape is
+ * exact because it is load-bearing: the client picks a version off `supported`
+ * and retries, so an inexact copy costs it the retry it needs. */
+export declare function checkVersion(msg: RpcMessage): RpcMessage | null;
+/** A successful result.
+ *
+ * `resultType: "complete"` is required on every result from `2026-07-28` on, and
+ * older clients ignore fields they do not recognise — so it is written
+ * unconditionally rather than behind an era check. One response shape for every
+ * era is the whole reason this server can serve both. */
+export declare function result(id: RpcId, payload?: Record<string, unknown>): RpcMessage;
+export declare function error(id: RpcId, code: number, message: string, data?: unknown): RpcMessage;
+export declare function serverInfo(version: string): {
+    name: string;
+    version: string;
+};