@specific.dev/spectest 0.54.1 → 0.56.0

package/src/mcp.ts

@@ -0,0 +1,1435 @@
+// `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, type StepBlock } from "./recorder.js";
+import { wrap, type Wrapped } from "./inspect.js";
+import {
+  McpHttpError,
+  McpRpcError,
+  McpTransport,
+  PROTOCOL_VERSION,
+  type HttpExchange,
+  type JsonRpcNotification,
+  type JsonRpcRequest,
+  type McpChallenge,
+} from "./mcp-transport.js";
+import {
+  authorize as beginAuthorization,
+  refreshIdentity,
+  type AuthorizationServerInfo,
+  type AuthorizeOptions,
+  type McpIdentity,
+} from "./mcp-auth.js";
+
+export { McpHttpError, McpRpcError, type McpChallenge } from "./mcp-transport.js";
+export {
+  McpAuthDeniedError,
+  type AuthorizeOptions,
+  type AuthorizationServerInfo,
+  type McpIdentity,
+} from "./mcp-auth.js";
+
+/** One part of a tool result or a resource read. The open member keeps a
+ *  content type this SDK predates from being dropped. */
+export type McpContent =
+  | { type: "text"; text: string }
+  | { type: "image"; data: string; mimeType: string }
+  | { type: "audio"; data: string; mimeType: string }
+  | { type: "resource"; resource: McpResourceContents }
+  | { type: "resource_link"; uri: string; name?: string; mimeType?: string }
+  | { type: string; [key: string]: unknown };
+
+export interface McpResourceContents {
+  uri: string;
+  mimeType?: string;
+  /** Text resources carry `text`; binary ones carry base64 `blob`. */
+  text?: string;
+  blob?: string;
+}
+
+export interface McpToolInfo {
+  name: string;
+  title?: string;
+  description?: string;
+  inputSchema?: unknown;
+  outputSchema?: unknown;
+}
+
+export interface McpResourceInfo {
+  uri: string;
+  name?: string;
+  title?: string;
+  description?: string;
+  mimeType?: string;
+}
+
+export interface McpPromptInfo {
+  name: string;
+  title?: string;
+  description?: string;
+  arguments?: { name: string; description?: string; required?: boolean }[];
+}
+
+export interface McpPromptResult {
+  description?: string;
+  messages: { role: string; content: McpContent }[];
+}
+
+/**
+ * What a tool call returned.
+ *
+ * Every field is provenance-wrapped, like a `ctx.fetch` response, so an
+ * assertion on it nests under the call in the timeline. That also means a
+ * field is a HANDLE, not the value: `expect(res.isError).toBe(true)` is
+ * the way to check it, and code that must branch calls
+ * `res.isError.unwrap()`. A bare `if (res.isError)` is always true,
+ * because a handle is an object — the same rule `res.ok` follows on a
+ * wrapped `fetch` response.
+ */
+export interface McpToolResult<T = unknown> {
+  /** True when the TOOL failed — an error the model is meant to read. A
+   *  protocol or transport failure throws instead. */
+  isError: Wrapped<boolean>;
+  /** Every content part, in order. */
+  content: Wrapped<McpContent[]>;
+  /** The text parts, joined with a newline. The usual thing to assert on. */
+  text: Wrapped<string>;
+  /** `structuredContent`, when the tool declares an output schema. */
+  structured?: Wrapped<T>;
+  /** `structuredContent` if the tool returned it, else the text parsed as
+   *  JSON. Throws when the text is not JSON. */
+  json<U = T>(): Wrapped<U>;
+  /** The whole result, with no provenance wrappers. */
+  unwrap(): { isError: boolean; content: McpContent[]; structuredContent?: T };
+}
+
+/** A notification the server sent, with the moment it arrived. */
+export interface McpNotification {
+  method: string;
+  params?: unknown;
+  /** Milliseconds since this client was created. */
+  atMs: number;
+}
+
+/** A server-to-client sampling request (`sampling/createMessage`): the
+ *  server is asking the client's model to generate something. */
+export interface McpSamplingRequest {
+  messages: { role: string; content: McpContent }[];
+  systemPrompt?: string;
+  maxTokens?: number;
+  [key: string]: unknown;
+}
+
+/** What a test answers a sampling request with. Return a string for the
+ *  common "the model said this" case. */
+export type McpSamplingResult =
+  | string
+  | { text?: string; content?: McpContent; model?: string; stopReason?: string; role?: string };
+
+export interface McpOptions {
+  /** A static bearer token. For a server that issues API keys rather than
+   *  running an OAuth flow. */
+  bearer?: string;
+  /** Extra headers on every request (an API key, a tenant id). */
+  headers?: Record<string, string>;
+  /** Per-request budget. Default 30 s. */
+  timeoutMs?: number;
+  /**
+   * Prefix for this client's step titles. Display only — it keys nothing.
+   * Worth setting when one test drives two clients; otherwise leave it
+   * out and the steps read as the tool names they are.
+   */
+  label?: string;
+  /** What this client calls itself in the `initialize` handshake. */
+  clientInfo?: { name: string; version: string };
+  /** Roots to advertise, as URIs or `{ uri, name }`. */
+  roots?: (string | { uri: string; name?: string })[];
+  /** Answer `sampling/createMessage`. Declaring it advertises the
+   *  capability, so a server that asks gets a deterministic reply instead
+   *  of a "method not found". */
+  sampling?: (req: McpSamplingRequest) => McpSamplingResult | Promise<McpSamplingResult>;
+}
+
+/** The in-progress authorization a test drives with its own browser. */
+export interface McpAuthorization {
+  /**
+   * Send the browser here.
+   *
+   * This and the other inputs below are raw strings, not wrapped handles:
+   * they are arguments to `page.goto(...)` and to your own code, and a
+   * handle would break at the call. What the flow FOUND — {@link server},
+   * and the {@link McpIdentity} that {@link complete} returns — is wrapped
+   * and is what a test asserts on.
+   */
+  readonly url: string;
+  readonly redirectUri: string;
+  readonly state: string;
+  readonly clientId: string;
+  /** What discovery found, wrapped against the `authorize` step. */
+  readonly server: Wrapped<AuthorizationServerInfo>;
+  readonly scopes: string[];
+  readonly resource?: string;
+  /**
+   * Wait for the redirect, exchange the code, and connect the client.
+   *
+   * Nothing to pass with the default loopback redirect. Pass `url` when
+   * the flow used a custom `redirectUri` that this daemon does not serve:
+   * hand back where the browser landed (`page.url()`).
+   */
+  complete(opts?: { url?: string; timeoutMs?: number }): Promise<Wrapped<McpIdentity>>;
+  /** Give up and release the loopback port. */
+  cancel(): void;
+}
+
+/** How a server names itself in the handshake. */
+export interface McpServerInfo {
+  name: string;
+  version: string;
+  title?: string;
+}
+
+export interface Mcp {
+  readonly url: string;
+  /** `serverInfo` from the handshake. Absent until the client connects.
+   *  Wrapped against the handshake step, so an assertion on it nests
+   *  there. */
+  readonly serverInfo?: Wrapped<McpServerInfo>;
+  /** What the server said it can do. */
+  readonly capabilities?: Wrapped<Record<string, unknown>>;
+  /** The negotiated protocol revision. */
+  readonly protocolVersion?: Wrapped<string>;
+  /** The server's `Mcp-Session-Id`, when it issues one. */
+  readonly sessionId?: Wrapped<string>;
+  /** True once a handshake has succeeded. A plain boolean: this is the
+   *  client's own state, not something a server op produced. */
+  readonly connected: boolean;
+  /** The last `401` challenge this client saw, parsed. Wrapped against
+   *  the step that was refused. */
+  readonly challenge?: Wrapped<McpChallenge>;
+  /** The grant, once an authorization completed. */
+  readonly identity?: Wrapped<McpIdentity>;
+  /** Instructions the server offers a client, when it does. */
+  readonly instructions?: Wrapped<string>;
+
+  /** Begin an OAuth flow. Does discovery, registration and PKCE, and
+   *  returns the URL to send a browser to. */
+  authorize(opts?: AuthorizeOptions): Promise<McpAuthorization>;
+
+  tools(): Promise<Wrapped<McpToolInfo[]>>;
+  call<T = unknown>(
+    name: string,
+    args?: Record<string, unknown>,
+    opts?: { timeoutMs?: number },
+  ): Promise<McpToolResult<T>>;
+  resources(): Promise<Wrapped<McpResourceInfo[]>>;
+  read(uri: string): Promise<Wrapped<McpResourceContents[]>>;
+  prompts(): Promise<Wrapped<McpPromptInfo[]>>;
+  prompt(name: string, args?: Record<string, string>): Promise<Wrapped<McpPromptResult>>;
+
+  /**
+   * Everything the server has pushed so far, oldest first.
+   *
+   * Each one is wrapped against its own step, so an assertion on a
+   * notification's params nests under the notification that carried them.
+   * The array itself is plain, so `.length` is a number.
+   */
+  notifications(filter?: string | RegExp): Wrapped<McpNotification>[];
+  /** End the session (`DELETE`). Tests do not need to call this. */
+  close(): Promise<void>;
+}
+
+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: string, opts: McpOptions = {}): Promise<Mcp> {
+  const client = new McpClient(url, opts);
+  await client.connectQuietly();
+  return client;
+}
+
+class McpClient implements Mcp {
+  readonly url: string;
+  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.
+  private _serverInfo?: McpServerInfo;
+  private _capabilities?: Record<string, unknown>;
+  private _protocolVersion?: string;
+  private _instructions?: string;
+  private _challenge?: McpChallenge;
+  private _identity?: McpIdentity;
+  /** Seq of the handshake step, the refused step, and the step that
+   *  completed an authorization. */
+  private connectSeq?: number;
+  private challengeSeq?: number;
+  private identitySeq?: number;
+  /** Seq of the step this client recorded last. */
+  private lastStepSeq?: number;
+  /**
+   * 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.
+   */
+  private refusedToken?: string | null;
+  /**
+   * 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.
+   */
+  private pauseDepth = 0;
+
+  private readonly opts: McpOptions;
+  private readonly transport: McpTransport;
+  private readonly createdAt = Date.now();
+  /** Notifications, each with the seq of the step it was recorded as. */
+  private readonly received: (McpNotification & { seq?: number })[] = [];
+  /** The step a server-to-client request should nest under: the tool call
+   *  that provoked it. */
+  private activeSeq?: number;
+  private token?: string;
+  private clientSecret?: string;
+  private lastExchange?: HttpExchange;
+
+  constructor(url: string, opts: McpOptions) {
+    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(): Wrapped<McpServerInfo> | undefined {
+    return wrapped(this._serverInfo, this.connectSeq);
+  }
+
+  get capabilities(): Wrapped<Record<string, unknown>> | undefined {
+    return wrapped(this._capabilities, this.connectSeq);
+  }
+
+  get protocolVersion(): Wrapped<string> | undefined {
+    return wrapped(this._protocolVersion, this.connectSeq);
+  }
+
+  get instructions(): Wrapped<string> | undefined {
+    return wrapped(this._instructions, this.connectSeq);
+  }
+
+  get sessionId(): Wrapped<string> | undefined {
+    return wrapped(this.transport.sessionId, this.connectSeq);
+  }
+
+  get challenge(): Wrapped<McpChallenge> | undefined {
+    return wrapped(this._challenge, this.challengeSeq);
+  }
+
+  get identity(): Wrapped<McpIdentity> | undefined {
+    return wrapped(this._identity, this.identitySeq);
+  }
+
+  /** Handshake, but treat a `401` as information rather than as failure. */
+  async connectQuietly(): Promise<void> {
+    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;
+    }
+  }
+
+  private async handshake(): Promise<void> {
+    const result = await this.transport.request<{
+      protocolVersion?: string;
+      capabilities?: Record<string, unknown>;
+      serverInfo?: { name: string; version: string; title?: string };
+      instructions?: string;
+    }>("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");
+  }
+
+  private clientCapabilities(): Record<string, unknown> {
+    const capabilities: Record<string, unknown> = {};
+    if (this.opts.sampling) capabilities["sampling"] = {};
+    if (this.opts.roots) capabilities["roots"] = { listChanged: false };
+    return capabilities;
+  }
+
+  async authorize(opts: AuthorizeOptions = {}): Promise<McpAuthorization> {
+    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): Promise<Wrapped<McpIdentity>> {
+        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(): Promise<Wrapped<McpToolInfo[]>> {
+    return this.stepWrapped(
+      "list tools",
+      async () => {
+        const result = await this.send<{ tools?: McpToolInfo[] }>("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<T = unknown>(
+    name: string,
+    args: Record<string, unknown> = {},
+    opts?: { timeoutMs?: number },
+  ): Promise<McpToolResult<T>> {
+    const resv = reserveEvent();
+    const started = Date.now();
+    this.pause();
+    let raw: RawToolResult<T> | undefined;
+    let failure: unknown;
+    try {
+      this.activeSeq = resv?.seq;
+      raw = await this.send<RawToolResult<T>>("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<T>(raw, content, text, isError, seq);
+  }
+
+  async resources(): Promise<Wrapped<McpResourceInfo[]>> {
+    return this.stepWrapped(
+      "list resources",
+      async () => {
+        const result = await this.send<{ resources?: McpResourceInfo[] }>("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: string): Promise<Wrapped<McpResourceContents[]>> {
+    return this.stepWrapped(
+      `read ${uri}`,
+      async () => {
+        const result = await this.send<{ contents?: McpResourceContents[] }>("resources/read", { uri });
+        return result.contents ?? [];
+      },
+      {
+        summary: (contents) => contents.flatMap((c) => resourceBlocks(c)),
+      },
+    );
+  }
+
+  async prompts(): Promise<Wrapped<McpPromptInfo[]>> {
+    return this.stepWrapped(
+      "list prompts",
+      async () => {
+        const result = await this.send<{ prompts?: McpPromptInfo[] }>("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: string, args?: Record<string, string>): Promise<Wrapped<McpPromptResult>> {
+    return this.stepWrapped(
+      `prompt ${name}`,
+      () => this.send<McpPromptResult>("prompts/get", { name, arguments: args ?? {} }),
+      {
+        summary: (result) => [
+          ...(result.description ? [{ type: "text" as const, text: result.description }] : []),
+          {
+            type: "chat",
+            messages: (result.messages ?? []).map((m) => ({
+              side: m.role === "assistant" ? ("other" as const) : ("self" as const),
+              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?: string | RegExp): Wrapped<McpNotification>[] {
+    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) as Wrapped<McpNotification>);
+  }
+
+  async close(): Promise<void> {
+    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.
+   */
+  private async send<T>(
+    method: string,
+    params?: unknown,
+    opts?: { timeoutMs?: number },
+  ): Promise<T> {
+    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<T>(method, params, opts);
+    } catch (err) {
+      if (await this.repair(err)) return this.transport.request<T>(method, params, opts);
+      throw err;
+    }
+  }
+
+  /** Try to make one failure survivable. Returns true when the caller
+   *  should retry exactly once. */
+  private async repair(err: unknown): Promise<boolean> {
+    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;
+  }
+
+  private async reconnect(): Promise<boolean> {
+    this.transport.sessionId = undefined;
+    this.connected = false;
+    try {
+      await this.handshake();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  private async refresh(): Promise<boolean> {
+    if (!this._identity) return false;
+    if (!this._identity.tokenEndpoint) return false;
+    const started = Date.now();
+    let refreshed: McpIdentity | undefined;
+    let failure: unknown;
+    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;
+  }
+
+  private onNotification(n: JsonRpcNotification): void {
+    // 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.
+   */
+  private async onServerRequest(request: JsonRpcRequest): Promise<unknown> {
+    const parentSeq = this.activeSeq;
+    const started = Date.now();
+    const params = (request.params ?? {}) as Record<string, unknown>;
+
+    const finish = (title: string, blocks: StepBlock[], error?: string): void => {
+      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 as unknown as McpSamplingRequest;
+      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") as "self" | "other",
+                text: contentText(m.content),
+              })),
+              { side: "other" as const, 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. */
+  private async step<T>(
+    title: string,
+    run: () => Promise<T>,
+    opts?: StepOpts<T>,
+  ): Promise<T> {
+    return (await this.runStep(title, run, opts)).value;
+  }
+
+  /** The same, with the result provenance-wrapped so an assertion on it
+   *  nests under this step. */
+  private async stepWrapped<T>(
+    title: string,
+    run: () => Promise<T>,
+    opts?: StepOpts<T>,
+  ): Promise<Wrapped<T>> {
+    const { value, seq } = await this.runStep(title, run, opts);
+    return wrap(value, seq) as Wrapped<T>;
+  }
+
+  private async runStep<T>(
+    title: string,
+    run: () => Promise<T>,
+    opts?: StepOpts<T>,
+  ): Promise<{ value: T; seq: number | undefined }> {
+    const resv = reserveEvent();
+    const started = Date.now();
+    this.pause();
+    let value: T;
+    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.
+   */
+  private noteChallenge(err: unknown, seq: number | undefined): void {
+    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. */
+  private pause(): void {
+    this.pauseDepth += 1;
+    pauseRecording();
+  }
+
+  private resume(): void {
+    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. */
+  private recording<T>(fn: () => T): T {
+    if (this.pauseDepth === 0) return fn();
+    this.resume();
+    try {
+      return fn();
+    } finally {
+      this.pause();
+    }
+  }
+
+  private title(op: string): string {
+    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.
+   */
+  private connectionBlock(): StepBlock[] {
+    const rows: [string, string | undefined][] = [["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?: string): StepBlock[] {
+    const blocks: StepBlock[] = [
+      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" as const, 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" as const, value: this._capabilities, label: "Capabilities" }]
+        : []),
+    ];
+    return fold ? [{ type: "details", summary: fold, blocks }] : blocks;
+  }
+
+  private failureBlocks(err: unknown): StepBlock[] {
+    const blocks: StepBlock[] = [];
+    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;
+  }
+}
+
+/** How one recorded step is built. */
+interface StepOpts<T> {
+  /** Blocks describing what the step did, from its result. */
+  summary?: (value: T) => StepBlock[];
+  /** Append the folded "Connection" disclosure. Off for the steps where
+   *  the connection is itself the subject (the handshake, the grant). */
+  connection?: boolean;
+}
+
+/**
+ * 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: Record<string, unknown>): StepBlock[] {
+  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) })),
+    },
+  ];
+}
+
+interface RawToolResult<T> {
+  content?: McpContent[];
+  structuredContent?: T;
+  isError?: boolean;
+}
+
+function makeToolResult<T>(
+  raw: RawToolResult<T>,
+  content: McpContent[],
+  text: string,
+  isError: boolean,
+  seq: number | undefined,
+): McpToolResult<T> {
+  return {
+    isError: wrap(isError, seq, ["isError"]) as unknown as Wrapped<boolean>,
+    content: wrap(content, seq, ["content"]) as unknown as Wrapped<McpContent[]>,
+    text: wrap(text, seq, ["text"]) as unknown as Wrapped<string>,
+    structured:
+      raw.structuredContent === undefined
+        ? undefined
+        : (wrap(raw.structuredContent, seq, ["structured"]) as unknown as Wrapped<T>),
+    json<U = T>(): Wrapped<U> {
+      if (raw.structuredContent !== undefined) {
+        return wrap(raw.structuredContent, seq, ["json()"]) as unknown as Wrapped<U>;
+      }
+      let parsed: unknown;
+      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()"]) as Wrapped<U>;
+    },
+    unwrap: () => ({ isError, content, structuredContent: raw.structuredContent }),
+  };
+}
+
+/** Join the text parts. The usual thing a test asserts on. */
+function textOf(content: McpContent[]): string {
+  return content
+    .filter((c) => c.type === "text")
+    .map((c) => (c as { text?: string }).text ?? "")
+    .join("\n");
+}
+
+function contentText(content: McpContent | undefined): string {
+  if (!content) return "";
+  if (content.type === "text") return (content as { text?: string }).text ?? "";
+  if (content.type === "image" || content.type === "audio") {
+    return `[${content.type} ${(content as { mimeType?: string }).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: McpContent[],
+  structured: unknown,
+  shownAsError?: string,
+): StepBlock[] {
+  const blocks: StepBlock[] = [];
+  // 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: StepBlock[] = [];
+  if (structured !== undefined) blocks.push({ type: "json", value: structured, label: "Result" });
+
+  const textCount = content.filter((c) => c.type === "text").length;
+  const label = (index: number): string => (textCount > 1 ? `Text ${index + 1}` : "Result");
+
+  let textIndex = 0;
+  for (const part of content) {
+    if (part.type === "text") {
+      const text = (part as { text?: string }).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: StepBlock =
+        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 as { mimeType?: string; data?: string };
+      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 as { resource: McpResourceContents }).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: string, value: unknown): StepBlock[] {
+  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: unknown, b: unknown): boolean {
+  try {
+    return JSON.stringify(a) === JSON.stringify(b);
+  } catch {
+    return false;
+  }
+}
+
+function resourceBlocks(contents: McpResourceContents): StepBlock[] {
+  const blocks: StepBlock[] = [
+    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: McpSamplingResult): {
+  role: string;
+  content: McpContent;
+  model: string;
+  stopReason?: string;
+} {
+  if (typeof answer === "string") {
+    return { role: "assistant", content: { type: "text", text: answer }, model: "spectest" };
+  }
+  const content: McpContent = answer.content ?? { type: "text", text: answer.text ?? "" };
+  return {
+    role: answer.role ?? "assistant",
+    content,
+    model: answer.model ?? "spectest",
+    stopReason: answer.stopReason,
+  };
+}
+
+function isConnectionError(err: unknown): boolean {
+  const message = (err as Error)?.message ?? String(err);
+  return /ECONNRESET|ECONNREFUSED|EPIPE|socket|fetch failed|Unable to connect|closed/i.test(message);
+}
+
+function errorMessage(err: unknown): string | undefined {
+  if (err === undefined || err === null) return undefined;
+  return (err as Error)?.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: string): string {
+  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<T>(value: T | undefined, seq: number | undefined): Wrapped<T> | undefined {
+  return value === undefined ? undefined : (wrap(value, seq) as unknown as Wrapped<T>);
+}
+
+function kv(rows: [string, string | undefined][], label?: string): StepBlock {
+  return {
+    type: "kv",
+    label,
+    rows: rows.filter(([, value]) => value !== undefined).map(([label, value]) => ({ label, value })),
+  };
+}
+
+function tryParse(text: string): unknown {
+  const trimmed = text.trim();
+  if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) return undefined;
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return undefined;
+  }
+}
+
+function langOf(mimeType?: string): string | undefined {
+  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?: string): string {
+  if (!base64) return "0 bytes";
+  const bytes = Math.floor((base64.length * 3) / 4);
+  return bytes < 1024 ? `${bytes} bytes` : `${(bytes / 1024).toFixed(1)} kB`;
+}