@specific.dev/spectest 0.55.0 → 0.56.0

package/dist/mcp.js

@@ -0,0 +1,1060 @@
+// `ctx.mcp(url)` — drive a Model Context Protocol server from a test.
+//
+// An MCP server is the interface an application exposes to an AI client:
+// tools it can call, resources it can read, prompts it can fill in. This
+// module is the client half. A test connects to the server under test,
+// calls its tools like a real client would, and asserts on what comes
+// back — and every call renders on the timeline as its own step, with the
+// arguments and the result, instead of as raw HTTP.
+//
+// ## No session registry, and no names
+//
+// `ctx.mcp(url)` connects and returns a NEW client every time. There is no
+// per-name registry like `ctx.browser("alice")` has. A client that has
+// authenticated is passed to the tests that need it, as the test's return
+// value:
+//
+//     export const signedIn = env.test("sign in", async (ctx) => {
+//       const mcp = await ctx.mcp(URL);
+//       …authorize…
+//       return mcp;                       // ctx.parent, for every child
+//     });
+//
+//     env.test("call a tool", { dependsOn: signedIn }, async (ctx) => {
+//       await ctx.parent.call("create_invoice", { amount: 250 });
+//     });
+//
+// That works because a test's return value crosses the fork in daemon
+// memory, live connections included. Two identities are two calls to
+// `ctx.mcp`, with no naming concept at all.
+//
+// ## The client does not police the server
+//
+// `call()` sends the request with whatever credentials it holds, including
+// none. A protected server answers `401` and that is what the test sees —
+// an {@link McpHttpError} carrying the parsed challenge. The client never
+// refuses to try, because "the server rejects an unauthenticated call" is
+// a thing tests must be able to prove.
+//
+// ## Authentication
+//
+// The SDK owns the protocol (discovery, registration, PKCE, the RFC 8707
+// `resource` binding, the token exchange, refresh — all in `mcp-auth.ts`).
+// The test owns the human: it drives the login and the consent screen in
+// its own browser. Nothing here guesses at a button.
+//
+//     const auth = await mcp.authorize();
+//     await page.goto(auth.url);
+//     …sign in, click Allow…
+//     await auth.complete();
+//
+// ## Recording
+//
+// Each operation records one `mcp` step in the dashboard's generic
+// presentation vocabulary (`crates/control-plane/src/web/blocks.rs`), so
+// no server change was needed to render any of this. HTTP is done with
+// recording PAUSED — otherwise every JSON-RPC round trip would also land
+// as an `http` row and bury the step it belongs to. Tokens are redacted
+// before an event exists.
+import { pauseRecording, recordStep, reserveEvent, resumeRecording } from "./recorder.js";
+import { wrap } from "./inspect.js";
+import { McpHttpError, McpRpcError, McpTransport, PROTOCOL_VERSION, } from "./mcp-transport.js";
+import { authorize as beginAuthorization, refreshIdentity, } from "./mcp-auth.js";
+export { McpHttpError, McpRpcError } from "./mcp-transport.js";
+export { McpAuthDeniedError, } from "./mcp-auth.js";
+const DEFAULT_CLIENT_INFO = { name: "spectest", version: "1.0.0" };
+/**
+ * Connect to an MCP server over streamable HTTP.
+ *
+ * Does not throw when the server answers the handshake with `401`: that
+ * response is the documented start of the OAuth flow, and it is kept on
+ * the client as {@link Mcp.challenge}. Any other failure throws.
+ */
+export async function openMcp(url, opts = {}) {
+    const client = new McpClient(url, opts);
+    await client.connectQuietly();
+    return client;
+}
+class McpClient {
+    url;
+    connected = false;
+    // Raw state. Everything a test READS comes back through the getters
+    // below, wrapped against the step that produced it — so an assertion on
+    // `mcp.serverInfo.name` nests under the handshake, and one on
+    // `mcp.challenge` nests under the call that was refused. Internal code
+    // uses these fields, never the getters: a wrapped value handed to
+    // `fetch` or to a header would be an object, not a string.
+    _serverInfo;
+    _capabilities;
+    _protocolVersion;
+    _instructions;
+    _challenge;
+    _identity;
+    /** Seq of the handshake step, the refused step, and the step that
+     *  completed an authorization. */
+    connectSeq;
+    challengeSeq;
+    identitySeq;
+    /** Seq of the step this client recorded last. */
+    lastStepSeq;
+    /**
+     * The credential the server last refused the handshake for.
+     *
+     * Without this, an unauthenticated `call()` recorded TWO identical
+     * failed steps: one for the handshake it retried, one for the call. The
+     * handshake cannot succeed with a credential that was just refused, so
+     * the call goes straight out and the server refuses the thing the test
+     * actually asked for.
+     */
+    refusedToken;
+    /**
+     * How many times THIS client has paused the recorder.
+     *
+     * Recording is paused for the length of an operation so its HTTP does
+     * not also land as `http` rows. Two things record from inside that
+     * region — the answer to a server-to-client request, and a token
+     * refresh — and they must lift the pause to do it. `resumeRecording`
+     * clamps at zero, so lifting a pause that is no longer held would leave
+     * the recorder paused for the rest of the test after the matching
+     * `pauseRecording`. The answer runs on a detached task, so that
+     * ordering is reachable. This counter is how we know.
+     */
+    pauseDepth = 0;
+    opts;
+    transport;
+    createdAt = Date.now();
+    /** Notifications, each with the seq of the step it was recorded as. */
+    received = [];
+    /** The step a server-to-client request should nest under: the tool call
+     *  that provoked it. */
+    activeSeq;
+    token;
+    clientSecret;
+    lastExchange;
+    constructor(url, opts) {
+        this.url = url;
+        this.opts = opts;
+        this.token = opts.bearer;
+        this.transport = new McpTransport({
+            url,
+            headers: opts.headers,
+            token: () => this.token,
+            timeoutMs: opts.timeoutMs,
+            onNotification: (n) => this.onNotification(n),
+            onRequest: (r) => this.onServerRequest(r),
+            onExchange: (x) => {
+                this.lastExchange = x;
+            },
+        });
+    }
+    get serverInfo() {
+        return wrapped(this._serverInfo, this.connectSeq);
+    }
+    get capabilities() {
+        return wrapped(this._capabilities, this.connectSeq);
+    }
+    get protocolVersion() {
+        return wrapped(this._protocolVersion, this.connectSeq);
+    }
+    get instructions() {
+        return wrapped(this._instructions, this.connectSeq);
+    }
+    get sessionId() {
+        return wrapped(this.transport.sessionId, this.connectSeq);
+    }
+    get challenge() {
+        return wrapped(this._challenge, this.challengeSeq);
+    }
+    get identity() {
+        return wrapped(this._identity, this.identitySeq);
+    }
+    /** Handshake, but treat a `401` as information rather than as failure. */
+    async connectQuietly() {
+        try {
+            const { seq } = await this.runStep("connect", () => this.handshake(), {
+                summary: () => this.handshakeBlocks(),
+                connection: false,
+            });
+            this.connectSeq = seq;
+        }
+        catch (err) {
+            // A refused handshake is the documented start of the OAuth flow,
+            // not a failure to report. The challenge it carried is kept, and
+            // `authorize()` starts from it.
+            if (err instanceof McpHttpError && err.status === 401) {
+                this._challenge = err.challenge;
+                this.refusedToken = this.token ?? null;
+                return;
+            }
+            throw err;
+        }
+    }
+    async handshake() {
+        const result = await this.transport.request("initialize", {
+            protocolVersion: PROTOCOL_VERSION,
+            capabilities: this.clientCapabilities(),
+            clientInfo: this.opts.clientInfo ?? DEFAULT_CLIENT_INFO,
+        });
+        this.refusedToken = undefined;
+        this._protocolVersion = result.protocolVersion ?? PROTOCOL_VERSION;
+        this.transport.protocolVersion = this._protocolVersion;
+        this._capabilities = result.capabilities;
+        this._serverInfo = result.serverInfo;
+        this._instructions = result.instructions;
+        this.connected = true;
+        this._challenge = undefined;
+        await this.transport.notify("notifications/initialized");
+    }
+    clientCapabilities() {
+        const capabilities = {};
+        if (this.opts.sampling)
+            capabilities["sampling"] = {};
+        if (this.opts.roots)
+            capabilities["roots"] = { listChanged: false };
+        return capabilities;
+    }
+    async authorize(opts = {}) {
+        const { value: flow, seq: authorizeSeq } = await this.runStep("authorize", () => beginAuthorization(this.url, this._challenge?.resourceMetadataUrl, opts), {
+            connection: false,
+            summary: (auth) => [
+                kv([
+                    ["Issuer", auth.server.issuer],
+                    ["Client", auth.clientId],
+                    [
+                        "Registered",
+                        auth.server.dynamicallyRegistered ? "dynamically, for this flow" : "already known",
+                    ],
+                    ["Redirect", auth.redirectUri],
+                    ["Scopes", auth.scopes.length > 0 ? auth.scopes.join(" ") : "none requested"],
+                ]),
+                {
+                    type: "text",
+                    text: "Waiting for a browser to sign in and consent.",
+                },
+                {
+                    type: "details",
+                    summary: "Discovery",
+                    blocks: [
+                        kv([
+                            ["Authorization", auth.server.authorizationEndpoint],
+                            ["Token", auth.server.tokenEndpoint],
+                            ["Registration", auth.server.registrationEndpoint],
+                            ["Resource", auth.resource],
+                            ["PKCE", "S256"],
+                        ]),
+                        { type: "code", code: auth.url, label: "Authorization URL" },
+                    ],
+                },
+            ],
+        });
+        this.clientSecret = opts.clientSecret;
+        const client = this;
+        return {
+            url: flow.url,
+            redirectUri: flow.redirectUri,
+            state: flow.state,
+            clientId: flow.clientId,
+            server: wrapped(flow.server, authorizeSeq),
+            scopes: flow.scopes,
+            resource: flow.resource,
+            cancel: () => flow.cancel(),
+            async complete(completeOpts) {
+                const { value: identity, seq } = await client.runStep("complete authorization", async () => {
+                    const identity = await flow.complete(completeOpts);
+                    client._identity = identity;
+                    client.token = identity.accessToken;
+                    // A session opened before the token was issued was refused,
+                    // so start a clean one rather than reusing its id.
+                    client.transport.sessionId = undefined;
+                    await client.handshake();
+                    return identity;
+                }, {
+                    connection: false,
+                    // Every field of the identity is readable — and therefore
+                    // assertable — so every field is shown. An assertion on
+                    // `identity.redirectUri` that names a row nobody can see is
+                    // worse than no assertion at all.
+                    summary: (identity) => [
+                        kv([
+                            ["Granted scopes", identity.scopes.join(" ") || "none"],
+                            ["Token", redactToken(identity.accessToken)],
+                            ["Token type", identity.tokenType],
+                            ["Refresh token", identity.refreshToken ? "issued" : "none"],
+                            [
+                                "Expires",
+                                identity.expiresAt
+                                    ? new Date(identity.expiresAt).toISOString().replace("T", " ").slice(0, 19)
+                                    : "not stated",
+                            ],
+                            ["Resource", identity.resource],
+                            ["Client", identity.clientId],
+                            ["Issuer", identity.issuer],
+                            ["Redirect URI", identity.redirectUri],
+                            ["Token endpoint", identity.tokenEndpoint],
+                        ]),
+                        // This step ran the handshake, so the server's own identity
+                        // was read here too — and `mcp.serverInfo` assertions point
+                        // at this step.
+                        ...client.handshakeBlocks("Server"),
+                    ],
+                });
+                // Both the grant and the handshake it ran belong to this step, so
+                // `mcp.identity` and `mcp.serverInfo` assert against it.
+                client.identitySeq = seq;
+                client.connectSeq = seq;
+                return wrapped(identity, seq);
+            },
+        };
+    }
+    async tools() {
+        return this.stepWrapped("list tools", async () => {
+            const result = await this.send("tools/list", {});
+            return result.tools ?? [];
+        }, {
+            summary: (tools) => [
+                {
+                    type: "table",
+                    columns: ["Tool", "Title", "Description"],
+                    rows: tools.map((t) => [t.name, t.title ?? "", t.description ?? ""]),
+                },
+                // The table carries three columns; a tool also has its input and
+                // output schemas, and a test may assert on either.
+                ...rawBlock("Full catalogue", tools),
+            ],
+        });
+    }
+    async call(name, args = {}, opts) {
+        const resv = reserveEvent();
+        const started = Date.now();
+        this.pause();
+        let raw;
+        let failure;
+        try {
+            this.activeSeq = resv?.seq;
+            raw = await this.send("tools/call", { name, arguments: args }, opts);
+        }
+        catch (err) {
+            failure = err;
+        }
+        finally {
+            this.activeSeq = undefined;
+            this.resume();
+        }
+        const durationMs = Date.now() - started;
+        if (failure || !raw) {
+            const seq = recordStep({
+                kind: "mcp",
+                title: this.title(name),
+                status: "failed",
+                durationMs,
+                error: errorMessage(failure),
+                blocks: [
+                    ...argumentBlocks(args),
+                    ...this.failureBlocks(failure),
+                    ...this.connectionBlock(),
+                ],
+            }, resv);
+            this.noteChallenge(failure, seq);
+            throw failure;
+        }
+        const content = raw.content ?? [];
+        const text = textOf(content);
+        const isError = raw.isError === true;
+        const seq = recordStep({
+            kind: "mcp",
+            title: this.title(name),
+            status: isError ? "failed" : "passed",
+            durationMs,
+            error: isError ? text || "the tool reported an error" : undefined,
+            blocks: [
+                ...argumentBlocks(args),
+                // `res.isError` is assertable, so it is shown rather than left
+                // to be inferred from the step's pass/fail chip. It needs its
+                // own label: two kv blocks in a row read as one list, and
+                // without a heading this looked like a third argument.
+                {
+                    type: "kv",
+                    label: "Outcome",
+                    rows: [{ label: "isError", value: String(isError), error: isError }],
+                },
+                // A failed tool's message IS its text content, and the step
+                // already leads with it as the error. Printing it twice reads
+                // as two different things having gone wrong.
+                ...resultBlocks(content, raw.structuredContent, isError ? text : undefined),
+                ...this.connectionBlock(),
+            ],
+        }, resv);
+        return makeToolResult(raw, content, text, isError, seq);
+    }
+    async resources() {
+        return this.stepWrapped("list resources", async () => {
+            const result = await this.send("resources/list", {});
+            return result.resources ?? [];
+        }, {
+            summary: (resources) => [
+                {
+                    type: "table",
+                    columns: ["URI", "Name", "Type"],
+                    rows: resources.map((r) => [r.uri, r.name ?? r.title ?? "", r.mimeType ?? ""]),
+                },
+                ...rawBlock("Full listing", resources),
+            ],
+        });
+    }
+    async read(uri) {
+        return this.stepWrapped(`read ${uri}`, async () => {
+            const result = await this.send("resources/read", { uri });
+            return result.contents ?? [];
+        }, {
+            summary: (contents) => contents.flatMap((c) => resourceBlocks(c)),
+        });
+    }
+    async prompts() {
+        return this.stepWrapped("list prompts", async () => {
+            const result = await this.send("prompts/list", {});
+            return result.prompts ?? [];
+        }, {
+            summary: (prompts) => [
+                {
+                    type: "table",
+                    columns: ["Prompt", "Description"],
+                    rows: prompts.map((p) => [p.name, p.description ?? ""]),
+                },
+                ...rawBlock("Full listing", prompts),
+            ],
+        });
+    }
+    async prompt(name, args) {
+        return this.stepWrapped(`prompt ${name}`, () => this.send("prompts/get", { name, arguments: args ?? {} }), {
+            summary: (result) => [
+                ...(result.description ? [{ type: "text", text: result.description }] : []),
+                {
+                    type: "chat",
+                    messages: (result.messages ?? []).map((m) => ({
+                        side: m.role === "assistant" ? "other" : "self",
+                        text: contentText(m.content),
+                    })),
+                },
+                // Bubbles carry the text of each turn. The role names and any
+                // non-text content are only in the message objects themselves.
+                ...rawBlock("Messages", result.messages ?? []),
+            ],
+        });
+    }
+    notifications(filter) {
+        const matches = filter === undefined
+            ? this.received
+            : this.received.filter((n) => typeof filter === "string" ? n.method === filter : filter.test(n.method));
+        // Wrapped per element, not per array: each notification came from a
+        // different step, and a whole-array tag would point every assertion at
+        // whichever one happened to be last.
+        return matches.map(({ seq, ...n }) => wrapped(n, seq));
+    }
+    async close() {
+        await this.step("close", async () => {
+            await this.transport.close();
+            this.connected = false;
+        });
+    }
+    /**
+     * Send one request, repairing the two failures a test environment
+     * produces by itself.
+     *
+     * A client is normally handed down from the test that authenticated it,
+     * so by the time it is used it lives in a RESTORED fork: the connection
+     * it holds was opened before the snapshot and the peer may have reset
+     * it. And an access token expires. Both are repaired once, silently,
+     * because neither is something a test should have to write.
+     */
+    async send(method, params, opts) {
+        if (!this.connected && this.refusedToken !== (this.token ?? null)) {
+            // No session yet — the handshake was refused, or the server dropped
+            // it. Open one now and let a `401` propagate: a rejection is the
+            // server's answer to this call, not something to hide behind a
+            // client-side gate.
+            try {
+                await this.handshake();
+            }
+            catch (err) {
+                if (err instanceof McpHttpError && err.status === 401) {
+                    this._challenge = err.challenge;
+                    this.refusedToken = this.token ?? null;
+                }
+                throw err;
+            }
+        }
+        try {
+            return await this.transport.request(method, params, opts);
+        }
+        catch (err) {
+            if (await this.repair(err))
+                return this.transport.request(method, params, opts);
+            throw err;
+        }
+    }
+    /** Try to make one failure survivable. Returns true when the caller
+     *  should retry exactly once. */
+    async repair(err) {
+        if (err instanceof McpHttpError) {
+            if (err.status === 401) {
+                this._challenge = err.challenge;
+                // An expired token, and a refresh token to spend on it.
+                if (this._identity?.refreshToken) {
+                    const refreshed = await this.refresh();
+                    if (refreshed)
+                        return true;
+                }
+                return false;
+            }
+            // The server forgot this session — it restarted, or the session id
+            // came from before the fork. A fresh handshake is the whole repair.
+            if (err.status === 404 || err.status === 400) {
+                return this.reconnect();
+            }
+            return false;
+        }
+        // A connection the peer reset. Common in a restored fork: the flow was
+        // established before the snapshot.
+        if (isConnectionError(err))
+            return this.reconnect();
+        return false;
+    }
+    async reconnect() {
+        this.transport.sessionId = undefined;
+        this.connected = false;
+        try {
+            await this.handshake();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async refresh() {
+        if (!this._identity)
+            return false;
+        if (!this._identity.tokenEndpoint)
+            return false;
+        const started = Date.now();
+        let refreshed;
+        let failure;
+        try {
+            refreshed = await refreshIdentity(this._identity, this.clientSecret);
+        }
+        catch (err) {
+            failure = err;
+        }
+        if (refreshed) {
+            this._identity = refreshed;
+            this.token = refreshed.accessToken;
+        }
+        // The caller paused the recorder for the length of its own step; lift
+        // that just long enough to put this repair on the timeline.
+        this.recording(() => recordStep({
+            kind: "mcp",
+            title: this.title("refresh token"),
+            status: refreshed ? "passed" : "failed",
+            durationMs: Date.now() - started,
+            error: refreshed
+                ? undefined
+                : (errorMessage(failure) ?? "the server issued no refresh token"),
+            blocks: refreshed
+                ? [
+                    kv([
+                        ["Token", redactToken(refreshed.accessToken)],
+                        [
+                            "Expires",
+                            refreshed.expiresAt ? new Date(refreshed.expiresAt).toISOString() : "not stated",
+                        ],
+                    ]),
+                ]
+                : [],
+        }));
+        return refreshed !== undefined;
+    }
+    onNotification(n) {
+        // A notification the server pushed is something that HAPPENED, and
+        // `mcp.notifications()` can be asserted on, so it gets a step of its
+        // own — nested under the call it arrived during, when there is one.
+        const seq = this.recording(() => recordStep({
+            kind: "mcp",
+            title: this.title(`notification ${n.method}`),
+            status: "passed",
+            parentSeq: this.activeSeq,
+            blocks: n.params === undefined ? [] : [{ type: "json", value: n.params, label: "Params" }],
+        }));
+        this.received.push({
+            method: n.method,
+            params: n.params,
+            atMs: Date.now() - this.createdAt,
+            seq,
+        });
+    }
+    /**
+     * Answer a server-to-client request.
+     *
+     * Recorded as a child of the call that provoked it (`parentSeq`), so a
+     * tool that asks the user something renders inside that tool's step
+     * rather than as a stray event somewhere below it.
+     */
+    async onServerRequest(request) {
+        const parentSeq = this.activeSeq;
+        const started = Date.now();
+        const params = (request.params ?? {});
+        const finish = (title, blocks, error) => {
+            this.recording(() => recordStep({
+                kind: "mcp",
+                title: this.title(title),
+                status: error ? "failed" : "passed",
+                durationMs: Date.now() - started,
+                error,
+                parentSeq,
+                blocks,
+            }));
+        };
+        if (request.method === "sampling/createMessage" && this.opts.sampling) {
+            const req = params;
+            try {
+                const answer = await this.opts.sampling(req);
+                const result = samplingResult(answer);
+                finish("sampling", [
+                    {
+                        type: "chat",
+                        messages: [
+                            ...(req.messages ?? []).map((m) => ({
+                                side: (m.role === "assistant" ? "other" : "self"),
+                                text: contentText(m.content),
+                            })),
+                            { side: "other", text: contentText(result.content), new: true },
+                        ],
+                    },
+                ]);
+                return result;
+            }
+            catch (err) {
+                finish("sampling", [], errorMessage(err));
+                throw err;
+            }
+        }
+        if (request.method === "roots/list") {
+            const roots = (this.opts.roots ?? []).map((r) => typeof r === "string" ? { uri: r } : { uri: r.uri, name: r.name });
+            finish("list roots", [{ type: "json", value: roots, label: "Roots" }]);
+            return { roots };
+        }
+        if (request.method === "ping")
+            return {};
+        throw new Error(`the server asked for "${request.method}", which this client did not advertise. ` +
+            "Declare it on ctx.mcp(url, { … }) to answer it.");
+    }
+    /** Run one operation as a recorded step, with HTTP paused inside it. */
+    async step(title, run, opts) {
+        return (await this.runStep(title, run, opts)).value;
+    }
+    /** The same, with the result provenance-wrapped so an assertion on it
+     *  nests under this step. */
+    async stepWrapped(title, run, opts) {
+        const { value, seq } = await this.runStep(title, run, opts);
+        return wrap(value, seq);
+    }
+    async runStep(title, run, opts) {
+        const resv = reserveEvent();
+        const started = Date.now();
+        this.pause();
+        let value;
+        try {
+            value = await run();
+        }
+        catch (err) {
+            this.resume();
+            const seq = recordStep({
+                kind: "mcp",
+                title: this.title(title),
+                status: "failed",
+                durationMs: Date.now() - started,
+                error: errorMessage(err),
+                blocks: [...this.failureBlocks(err), ...this.connectionBlock()],
+            }, resv);
+            this.noteChallenge(err, seq);
+            throw err;
+        }
+        this.resume();
+        const seq = recordStep({
+            kind: "mcp",
+            title: this.title(title),
+            status: "passed",
+            durationMs: Date.now() - started,
+            blocks: [
+                ...(opts?.summary?.(value) ?? []),
+                ...(opts?.connection === false ? [] : this.connectionBlock()),
+            ],
+        }, resv);
+        return { value, seq };
+    }
+    /**
+     * Keep the `401` challenge a refused step carried, tagged with that
+     * step.
+     *
+     * This is what lets a test assert that a server really is protected —
+     * `expect(mcp.challenge?.status).toBe(401)` — with the assertion nested
+     * under the call that was refused. The thrown error carries the same
+     * information, but a caught error has no provenance to assert through.
+     */
+    noteChallenge(err, seq) {
+        if (!(err instanceof McpHttpError) || err.status !== 401 || !err.challenge)
+            return;
+        this._challenge = err.challenge;
+        this.challengeSeq = seq;
+    }
+    /** Pause the recorder for the length of one operation's HTTP. */
+    pause() {
+        this.pauseDepth += 1;
+        pauseRecording();
+    }
+    resume() {
+        if (this.pauseDepth === 0)
+            return;
+        this.pauseDepth -= 1;
+        resumeRecording();
+    }
+    /** Run `fn` with this client's own pause lifted, then put it back. A
+     *  no-op wrapper when we hold no pause. */
+    recording(fn) {
+        if (this.pauseDepth === 0)
+            return fn();
+        this.resume();
+        try {
+            return fn();
+        }
+        finally {
+            this.pause();
+        }
+    }
+    title(op) {
+        return this.opts.label ? `${this.opts.label}: ${op}` : op;
+    }
+    /**
+     * Which connection this step ran on — folded away.
+     *
+     * It is the same six rows on every step of a session, and none of them
+     * is why anyone opened the step. Above the content they buried it (the
+     * arguments of a tool call started below the fold); in a disclosure at
+     * the bottom they are one click away when a session id or a token
+     * actually is the question.
+     */
+    connectionBlock() {
+        const rows = [["Server", this.url]];
+        if (this._serverInfo) {
+            rows.push(["Implementation", `${this._serverInfo.name} ${this._serverInfo.version}`]);
+        }
+        if (this._protocolVersion)
+            rows.push(["Protocol", this._protocolVersion]);
+        if (this.transport.sessionId)
+            rows.push(["Session", this.transport.sessionId]);
+        if (this._identity) {
+            rows.push(["Token", redactToken(this._identity.accessToken)]);
+            if (this._identity.scopes.length > 0)
+                rows.push(["Scopes", this._identity.scopes.join(" ")]);
+        }
+        return [{ type: "details", summary: "Connection", blocks: [kv(rows)] }];
+    }
+    /**
+     * What the handshake established.
+     *
+     * Shown on the two steps that perform one — the plain `connect`, and
+     * the `complete authorization` that re-runs it with the token — because
+     * `mcp.serverInfo` / `capabilities` / `protocolVersion` / `sessionId`
+     * are all wrapped against whichever of those ran, and a value a test can
+     * assert on has to be a value the reader can see.
+     *
+     * `fold` puts it in a disclosure, for the step whose own subject is
+     * something else.
+     */
+    handshakeBlocks(fold) {
+        const blocks = [
+            kv([
+                ["Server", this.url],
+                ["Name", this._serverInfo?.name],
+                ["Version", this._serverInfo?.version],
+                ["Title", this._serverInfo?.title],
+                ["Protocol", this._protocolVersion],
+                ["Session", this.transport.sessionId],
+                ["Capabilities", Object.keys(this._capabilities ?? {}).join(", ") || "none"],
+            ]),
+            ...(this._instructions
+                ? [{ type: "text", text: this._instructions }]
+                : []),
+            // The capability map is nested, so a row cannot carry it — and a
+            // test may assert on any leaf of it.
+            ...(this._capabilities && Object.keys(this._capabilities).length > 0
+                ? [{ type: "json", value: this._capabilities, label: "Capabilities" }]
+                : []),
+        ];
+        return fold ? [{ type: "details", summary: fold, blocks }] : blocks;
+    }
+    failureBlocks(err) {
+        const blocks = [];
+        if (err instanceof McpHttpError) {
+            blocks.push(kv([
+                ["HTTP status", String(err.status)],
+                ["Scheme", err.challenge?.scheme],
+                ["Error", err.challenge?.error],
+                ["Scope", err.challenge?.scope],
+                ["Resource metadata", err.challenge?.resourceMetadataUrl],
+                ["WWW-Authenticate", err.challenge?.raw],
+            ]));
+            if (err.body) {
+                const body = err.body.slice(0, 4000);
+                const json = tryParse(body);
+                blocks.push(json === undefined
+                    ? { type: "code", code: body, label: "Response" }
+                    : { type: "json", value: json, label: "Response" });
+            }
+        }
+        else if (err instanceof McpRpcError) {
+            blocks.push(kv([["JSON-RPC error", String(err.code)]]));
+            if (err.data !== undefined)
+                blocks.push({ type: "json", value: err.data, label: "Error data" });
+        }
+        else if (this.lastExchange) {
+            blocks.push(kv([["Last HTTP status", String(this.lastExchange.status)]]));
+        }
+        return blocks;
+    }
+}
+/**
+ * A tool call's arguments.
+ *
+ * A flat object — which is what most tool calls take — reads far better as
+ * a definition list than as a JSON blob, and it lines up with the rest of
+ * the panel. Anything nested keeps its JSON, where the shape matters.
+ */
+function argumentBlocks(args) {
+    const entries = Object.entries(args);
+    if (entries.length === 0)
+        return [];
+    const flat = entries.every(([, v]) => v === null || typeof v !== "object");
+    if (!flat)
+        return [{ type: "json", value: args, label: "Arguments" }];
+    return [
+        {
+            type: "kv",
+            label: "Arguments",
+            rows: entries.map(([label, value]) => ({ label, value: String(value) })),
+        },
+    ];
+}
+function makeToolResult(raw, content, text, isError, seq) {
+    return {
+        isError: wrap(isError, seq, ["isError"]),
+        content: wrap(content, seq, ["content"]),
+        text: wrap(text, seq, ["text"]),
+        structured: raw.structuredContent === undefined
+            ? undefined
+            : wrap(raw.structuredContent, seq, ["structured"]),
+        json() {
+            if (raw.structuredContent !== undefined) {
+                return wrap(raw.structuredContent, seq, ["json()"]);
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                throw new Error("the tool returned no structuredContent and its text is not JSON. " +
+                    "Assert on res.text, or read res.content.");
+            }
+            return wrap(parsed, seq, ["json()"]);
+        },
+        unwrap: () => ({ isError, content, structuredContent: raw.structuredContent }),
+    };
+}
+/** Join the text parts. The usual thing a test asserts on. */
+function textOf(content) {
+    return content
+        .filter((c) => c.type === "text")
+        .map((c) => c.text ?? "")
+        .join("\n");
+}
+function contentText(content) {
+    if (!content)
+        return "";
+    if (content.type === "text")
+        return content.text ?? "";
+    if (content.type === "image" || content.type === "audio") {
+        return `[${content.type} ${content.mimeType ?? ""}]`;
+    }
+    return JSON.stringify(content);
+}
+/**
+ * Render a tool result.
+ *
+ * A tool that declares an output schema usually returns the SAME value
+ * twice — once as `structuredContent` and once as a JSON text part, since
+ * a client that does not read structured output still has to see
+ * something. Rendering both is noise, so a text part that parses to the
+ * structured value is dropped.
+ *
+ * An image renders as a line of metadata rather than a picture:
+ * `blocks.rs` has no image block yet. When one is added, this is the only
+ * place that changes.
+ */
+function resultBlocks(content, structured, shownAsError) {
+    const blocks = [];
+    // Text parts a reader does not need when `structuredContent` already
+    // answers the question. Folded, not dropped: what the model would have
+    // read is still one click away.
+    const folded = [];
+    if (structured !== undefined)
+        blocks.push({ type: "json", value: structured, label: "Result" });
+    const textCount = content.filter((c) => c.type === "text").length;
+    const label = (index) => (textCount > 1 ? `Text ${index + 1}` : "Result");
+    let textIndex = 0;
+    for (const part of content) {
+        if (part.type === "text") {
+            const text = part.text ?? "";
+            const json = tryParse(text);
+            const index = textIndex++;
+            // The same value twice — a tool with an output schema usually
+            // returns both forms. Once is enough.
+            if (json !== undefined && structured !== undefined && sameJson(json, structured))
+                continue;
+            // Already the step's error line.
+            if (shownAsError !== undefined && text === shownAsError)
+                continue;
+            const block = json === undefined
+                ? { type: "code", code: text, label: label(index) }
+                : { type: "json", value: json, label: label(index) };
+            (structured === undefined ? blocks : folded).push(block);
+            continue;
+        }
+        if (part.type === "image" || part.type === "audio") {
+            const p = part;
+            blocks.push({
+                type: "kv",
+                rows: [{ label: part.type, value: `${p.mimeType ?? "unknown type"}, ${byteSize(p.data)}` }],
+            });
+            continue;
+        }
+        if (part.type === "resource") {
+            blocks.push(...resourceBlocks(part.resource));
+            continue;
+        }
+        blocks.push({ type: "json", value: part, label: part.type });
+    }
+    if (folded.length > 0) {
+        blocks.push({ type: "details", summary: "Text content", blocks: folded });
+    }
+    return blocks;
+}
+/**
+ * A folded block carrying a value in full.
+ *
+ * The rule this serves: a test can assert on any field of what a call
+ * returned, so every field has to be somewhere a reader can reach. A
+ * table or a set of bubbles shows what matters; this keeps the rest one
+ * click away instead of nowhere.
+ */
+function rawBlock(summary, value) {
+    if (Array.isArray(value) && value.length === 0)
+        return [];
+    return [{ type: "details", summary, blocks: [{ type: "json", value }] }];
+}
+/** Structural equality, for the duplicate-result check above. */
+function sameJson(a, b) {
+    try {
+        return JSON.stringify(a) === JSON.stringify(b);
+    }
+    catch {
+        return false;
+    }
+}
+function resourceBlocks(contents) {
+    const blocks = [
+        kv([
+            ["URI", contents.uri],
+            ["Type", contents.mimeType],
+        ]),
+    ];
+    if (contents.text !== undefined) {
+        const json = tryParse(contents.text);
+        blocks.push(json === undefined
+            ? { type: "code", code: contents.text, lang: langOf(contents.mimeType), label: "Contents" }
+            : { type: "json", value: json, label: "Contents" });
+    }
+    else if (contents.blob !== undefined) {
+        blocks.push({ type: "text", text: `binary contents, ${byteSize(contents.blob)}` });
+    }
+    return blocks;
+}
+function samplingResult(answer) {
+    if (typeof answer === "string") {
+        return { role: "assistant", content: { type: "text", text: answer }, model: "spectest" };
+    }
+    const content = answer.content ?? { type: "text", text: answer.text ?? "" };
+    return {
+        role: answer.role ?? "assistant",
+        content,
+        model: answer.model ?? "spectest",
+        stopReason: answer.stopReason,
+    };
+}
+function isConnectionError(err) {
+    const message = err?.message ?? String(err);
+    return /ECONNRESET|ECONNREFUSED|EPIPE|socket|fetch failed|Unable to connect|closed/i.test(message);
+}
+function errorMessage(err) {
+    if (err === undefined || err === null)
+        return undefined;
+    return err?.message ?? String(err);
+}
+/** Show that a token exists and let two tokens be told apart, without
+ *  putting a credential in a run that is stored forever. */
+function redactToken(token) {
+    return token.length <= 8 ? "••••" : `••••${token.slice(-4)}`;
+}
+/**
+ * A wrapped view of a value this client read, tagged with the step that
+ * produced it. `wrap` is typed as the identity function (it returns a
+ * proxy that behaves like the value), so the wrapped TYPE is asserted
+ * here — in one place, rather than at every getter.
+ */
+function wrapped(value, seq) {
+    return value === undefined ? undefined : wrap(value, seq);
+}
+function kv(rows, label) {
+    return {
+        type: "kv",
+        label,
+        rows: rows.filter(([, value]) => value !== undefined).map(([label, value]) => ({ label, value })),
+    };
+}
+function tryParse(text) {
+    const trimmed = text.trim();
+    if (!trimmed.startsWith("{") && !trimmed.startsWith("["))
+        return undefined;
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        return undefined;
+    }
+}
+function langOf(mimeType) {
+    if (!mimeType)
+        return undefined;
+    if (mimeType.includes("json"))
+        return "json";
+    if (mimeType.includes("html"))
+        return "html";
+    if (mimeType.includes("markdown"))
+        return "markdown";
+    if (mimeType.includes("yaml"))
+        return "yaml";
+    return undefined;
+}
+function byteSize(base64) {
+    if (!base64)
+        return "0 bytes";
+    const bytes = Math.floor((base64.length * 3) / 4);
+    return bytes < 1024 ? `${bytes} bytes` : `${(bytes / 1024).toFixed(1)} kB`;
+}