@effected/mcp 0.12.0 → 0.14.0

package/McpHarness.js

@@ -1,338 +0,0 @@
-import { ToolFailure } from "./ToolFailure.js";
-import { DEFAULT_CLIENT_INFO, frame, initializeParams, isJsonRpcMessage, isResponse, isStateless, parseFrame, requestKey } from "./internal/wire.js";
-import { McpTestFailure } from "./McpTestFailure.js";
-import { Console, Deferred, Effect, Exit, Fiber, Layer, Queue, Sink, Stdio, Stream } from "effect";
-import { McpProtocol } from "effect/ai";
-import { ErrorText } from "@effected/engine";
-
-// src/McpHarness.ts
-/** The generic tag `Object.prototype.toString` answers with: a value with no string form of its own. */
-const GENERIC_STRING = /^\[object [^\]]*\]$/;
-/**
-* One captured console argument as text, as close to what the console would show as a runtime-free rendering gets,
-* and never throwing.
-*
-* @remarks
-* A harness records what the server would have printed, so the record must not lose what the console shows. Hence
-* the order: a value's own string form first (`String(error)` is `Error: boom`, where `ErrorText.describe` would keep
-* only `boom`, and it is the same for any object carrying a `message`), then JSON for an array or a plain object,
-* whose string form is `1,2` or `[object Object]`. `ErrorText.describe` is the last resort for a value whose string
-* form throws and which has no JSON: an object with no prototype has no `toString`, and `String` throws on it inside
-* the server's own console call.
-*/
-const showArg = (arg) => {
-	if (typeof arg === "string") return arg;
-	if (typeof arg !== "object" || arg === null) return ErrorText.describe(arg);
-	try {
-		if (!Array.isArray(arg)) {
-			const text = String(arg);
-			if (!GENERIC_STRING.test(text)) return text;
-		}
-	} catch {}
-	try {
-		const json = JSON.stringify(arg);
-		if (json !== void 0) return json;
-	} catch {}
-	return ErrorText.describe(arg);
-};
-/**
-* An in-process MCP client for a real server layer, over queue-backed stdio.
-*
-* @remarks
-* Builds your server with a queue-backed `Stdio.layerTest` that satisfies the
-* server's `Stdio` requirement, so tests see the exact served schemas and wire
-* results a real client would, with no child and no sockets. Pass the server
-* WITHOUT a `Stdio` of its own: a `Stdio` the server provides internally wins,
-* and talks to the real terminal. A bundled platform layer such as
-* `NodeServices.layer` (`@effect/platform-node`) brings its own `Stdio` along
-* with `FileSystem`, `Path`, `ChildProcessSpawner`, `Crypto` and `Terminal` —
-* providing it to the server loses `Stdio` the same way, and every wait
-* hangs to timeout with no error naming why. Compose the individual layers
-* the server needs instead and leave `Stdio` out; this harness supplies it.
-*
-* The server is built with a fresh layer memo map, never the ambient one, so
-* a harness made under another stdio server's `Effect.provide` still serves
-* its own. Never pass a server layer that provides a layer the test also
-* provides and then reads — `McpHarness.make(server.pipe(Layer.provide(AppLayer)))`
-* under `Effect.provide(AppLayer)` builds `AppLayer` twice, so the tools write
-* to one instance and the test reads the other. Leave the service in the
-* server layer's requirements and provide it once from the test, or build it
-* once and pass `Layer.succeed(Tag, value)`.
-*
-* - Responses are matched by id, so notifications may interleave freely.
-* - Every response wait and `awaitOutboundMethod` fails with `ServerStopped`
-*   when the server stops, and dies when `strictStdout` sees a line that is
-*   not JSON-RPC. `stop` stops the server at once; `close` ends stdin and lets
-*   in-flight requests answer first, so only `stop` releases a wait on a
-*   request that never completes.
-* - With `captureLogs`, the server's console is captured: `stderrSoFar`
-*   holds stderr writes and every log line, and `consoleLogSoFar` holds
-*   anything that went through `console.log`, which in a real server is
-*   the wire. Assert it empty.
-* - On a stateful revision (the default `2025-11-25`), send `initialize`
-*   first. `ping` is the exception: the server answers it `{}` before
-*   initialization, so it is written. Every other request before
-*   `initialize` fails with `NotInitialized` and is never written: the
-*   server would only answer an opaque refusal,
-*   `-32602 Invalid request metadata` when a stateless adapter is listed
-*   first (as in `McpStdio.protocols`), or `-32603 Internal error` when
-*   only stateful revisions are served.
-*
-* @example
-* ```ts
-* import { McpHarness } from "@effected/mcp/testing";
-* import { Effect } from "effect";
-*
-* // `ServerLayer` is the server's layer, built without its own `Stdio`.
-* const program = Effect.gen(function* () {
-* 	const harness = yield* McpHarness.make(ServerLayer);
-* 	yield* harness.initialize;
-* 	const tools = yield* harness.listTools;
-* 	return tools.map((tool) => tool.name);
-* }).pipe(Effect.scoped);
-* ```
-*
-* @public
-*/
-var McpHarness = class McpHarness {
-	/** The revision this client speaks. */
-	protocol;
-	/** `initialize` then `notifications/initialized`; `server/discover` on a stateless revision. Call it first on a stateful revision. */
-	initialize;
-	/**
-	* `initialize` asking for `protocolVersion` instead of the harness's own
-	* revision, then `notifications/initialized` only when the response
-	* carries no error. Returns the whole response: assert the negotiated
-	* `result.protocolVersion`, or the JSON-RPC `error`.
-	*
-	* @remarks
-	* It moves between stateful revisions only. A stateful server never
-	* refuses a version: it counter-offers its latest stateful revision, so
-	* asking for an unknown one, or for the stateless `2026-07-28`, comes back
-	* as `2025-11-25`. On a harness made with a stateless revision the server
-	* does not serve `initialize` at all, and the response is a JSON-RPC
-	* `-32601` "Method not found" error, with no `notifications/initialized`
-	* sent after it.
-	*/
-	initializeWith;
-	/** `server/discover`. */
-	discover;
-	/** Send a request and wait for its response. */
-	request;
-	/** Send a request now; wait for its response later. Fails with `NotInitialized`, sending nothing, on a stateful revision before `initialize` (`ping` excepted). */
-	startRequest;
-	/** Send a notification. */
-	notify;
-	/** `tools/call`, returning the whole response: a JSON-RPC error is data here. */
-	callTool;
-	/** `tools/list`'s tools; a JSON-RPC error fails with `ErrorResponse`. */
-	listTools;
-	/** `resources/list`'s resources; a JSON-RPC error fails with `ErrorResponse`. */
-	listResources;
-	/** `resources/read`, returning the whole response. */
-	readResource;
-	/** Write any value as one newline-framed line. Never gated; a raw `initialize` counts as sent. */
-	sendRaw;
-	/** The next server-initiated frame with this method, skipping and keeping others; fails with `ServerStopped` once the server stops. */
-	awaitOutboundMethod;
-	/** Every frame written to the server's stdin so far, in order, as the JSON-parsed bytes written (a snapshot the caller's later mutations cannot reach): requests, notifications and `sendRaw` values. */
-	sentSoFar;
-	/** Everything written to stderr, plus every captured log line. */
-	stderrSoFar;
-	/**
-	* Every captured `console.log`, `info` or `debug` call, its arguments joined with a space, each rendered close to
-	* what the console would show: a string as itself, a value with its own string form as that form (an `Error` as
-	* `Error: boom`, a number, a date), an array or a plain object as JSON (`{"message":"x"}`, not just `x`).
-	*
-	* @remarks
-	* Rendering never throws inside the server's own call. A value whose string form throws (an object with no
-	* prototype, a throwing `toString`) and has no JSON falls back to `ErrorText.describe` from `@effected/engine`.
-	*/
-	consoleLogSoFar;
-	/**
-	* End stdin, as a client disconnecting does. The server drains first:
-	* requests already in flight still answer, and the server stops once they
-	* have, so a wait on a request that never completes keeps waiting. Use
-	* {@link McpHarness.stop} to end the server regardless.
-	*/
-	close;
-	/**
-	* Interrupt the server without draining, as a client killing the process
-	* does: every pending response wait and `awaitOutboundMethod` fails with
-	* `ServerStopped`.
-	*/
-	stop;
-	constructor(parts) {
-		this.protocol = parts.protocol;
-		this.initialize = parts.initialize;
-		this.initializeWith = parts.initializeWith;
-		this.discover = parts.discover;
-		this.request = parts.request;
-		this.startRequest = parts.startRequest;
-		this.notify = parts.notify;
-		this.callTool = parts.callTool;
-		this.listTools = parts.listTools;
-		this.listResources = parts.listResources;
-		this.readResource = parts.readResource;
-		this.sendRaw = parts.sendRaw;
-		this.awaitOutboundMethod = parts.awaitOutboundMethod;
-		this.sentSoFar = parts.sentSoFar;
-		this.stderrSoFar = parts.stderrSoFar;
-		this.consoleLogSoFar = parts.consoleLogSoFar;
-		this.close = parts.close;
-		this.stop = parts.stop;
-	}
-	/** Build `server` over queue-backed stdio and return a client for it; fails with the layer's own error if it cannot build. */
-	static make = (server, options = {}) => Effect.gen(function* () {
-		const protocol = options.protocol ?? McpProtocol.v2025_11_25;
-		const clientInfo = options.clientInfo ?? DEFAULT_CLIENT_INFO;
-		const strictStdout = options.strictStdout ?? true;
-		const stdin = yield* Queue.unbounded();
-		const stdout = yield* Queue.unbounded();
-		const inbound = yield* Queue.unbounded();
-		const retained = [];
-		const waiters = /* @__PURE__ */ new Map();
-		const stderr = [];
-		const consoleLog = [];
-		const ready = yield* Deferred.make();
-		const stopped = yield* Deferred.make();
-		const corrupt = yield* Deferred.make();
-		const encoder = new TextEncoder();
-		const stdoutDecoder = new TextDecoder();
-		const stderrDecoder = new TextDecoder();
-		let nextId = 1;
-		const stdio = Stdio.layerTest({
-			stdin: Stream.fromQueue(stdin),
-			stdout: () => Sink.forEach((chunk) => Queue.offer(stdout, chunk)),
-			stderr: () => Sink.forEach((chunk) => Effect.sync(() => {
-				stderr.push(typeof chunk === "string" ? chunk : stderrDecoder.decode(chunk, { stream: true }));
-			}))
-		});
-		const ambient = yield* Console.Console;
-		const show = (args) => args.map(showArg).join(" ");
-		const toStdout = (...args) => {
-			consoleLog.push(show(args));
-		};
-		const toStderr = (...args) => {
-			stderr.push(`${show(args)}\n`);
-		};
-		const captured = {
-			...ambient,
-			log: toStdout,
-			info: toStdout,
-			debug: toStdout,
-			error: toStderr,
-			warn: toStderr
-		};
-		const provided = options.captureLogs === false ? server.pipe(Layer.provide(stdio)) : server.pipe(Layer.provide(stdio), Layer.provide(Layer.succeed(Console.Console, captured)));
-		const route = (line) => {
-			const parsed = parseFrame(line);
-			if (!isJsonRpcMessage(parsed)) return strictStdout ? Effect.asVoid(Deferred.die(corrupt, /* @__PURE__ */ new Error(`stdout carried a line that is not JSON-RPC: ${ToolFailure.truncate(line)}`))) : Effect.void;
-			if (isResponse(parsed)) {
-				const key = requestKey(parsed.id);
-				const waiter = waiters.get(key);
-				if (waiter !== void 0) {
-					waiters.delete(key);
-					return Effect.asVoid(Deferred.succeed(waiter, parsed));
-				}
-			}
-			return Effect.asVoid(Queue.offer(inbound, parsed));
-		};
-		const router = yield* Stream.fromQueue(stdout).pipe(Stream.map((chunk) => typeof chunk === "string" ? chunk : stdoutDecoder.decode(chunk, { stream: true })), Stream.splitLines, Stream.runForEach((line) => line.length === 0 ? Effect.void : route(line)), Effect.forkScoped);
-		const serverFiber = yield* Effect.flatMap(Effect.scope, (scope) => Layer.buildWithMemoMap(provided, Layer.makeMemoMapUnsafe(), scope)).pipe(Effect.andThen(Deferred.succeed(ready, void 0)), Effect.andThen(Effect.never), Effect.scoped, Effect.onExit((exit) => Effect.andThen(Exit.isFailure(exit) ? Deferred.failCause(ready, exit.cause) : Effect.void, Queue.end(stdout).pipe(Effect.andThen(Fiber.await(router)), Effect.andThen(Deferred.fail(stopped, new McpTestFailure({
-			reason: "ServerStopped",
-			message: "the server stopped before it responded"
-		})))))), Effect.forkScoped);
-		yield* Deferred.await(ready);
-		const stopAware = (wait) => Effect.raceAllFirst([
-			wait,
-			Deferred.await(stopped),
-			Deferred.await(corrupt)
-		]);
-		const awaitResponse = (waiter) => Effect.suspend(() => Deferred.isDoneUnsafe(waiter) ? Deferred.await(waiter) : stopAware(Deferred.await(waiter)));
-		const stateful = !isStateless(protocol);
-		let initializeSent = false;
-		const sent = [];
-		const sendRaw = (message) => Effect.suspend(() => {
-			const line = JSON.stringify(message);
-			const written = line === void 0 ? void 0 : JSON.parse(line);
-			sent.push(written);
-			if (isJsonRpcMessage(written) && written.method === "initialize") initializeSent = true;
-			return Effect.asVoid(Queue.offer(stdin, encoder.encode(`${line}\n`)));
-		});
-		const startRequest = (method, params) => Effect.gen(function* () {
-			if (stateful && !initializeSent && method !== "initialize" && method !== "ping") return yield* new McpTestFailure({
-				reason: "NotInitialized",
-				message: `${method} was not sent: call initialize first on stateful protocol ${protocol.protocolVersion}`
-			});
-			const id = nextId++;
-			const waiter = yield* Deferred.make();
-			waiters.set(requestKey(id), waiter);
-			yield* sendRaw(frame(protocol, clientInfo, method, params, id));
-			return {
-				id,
-				response: awaitResponse(waiter)
-			};
-		});
-		const request = (method, params) => Effect.flatMap(startRequest(method, params), (started) => started.response);
-		const notify = (method, params) => sendRaw(frame(protocol, clientInfo, method, params));
-		const discover = request("server/discover", {});
-		const initialize = isStateless(protocol) ? discover : Effect.gen(function* () {
-			const response = yield* request("initialize", initializeParams(protocol, clientInfo));
-			yield* notify("notifications/initialized");
-			return response;
-		});
-		const initializeWith = (protocolVersion) => Effect.gen(function* () {
-			const response = yield* request("initialize", {
-				...initializeParams(protocol, clientInfo),
-				protocolVersion
-			});
-			if (response.error === void 0) yield* notify("notifications/initialized");
-			return response;
-		});
-		const listTools = Effect.flatMap(request("tools/list"), (response) => response.error === void 0 ? Effect.succeed(response.result.tools) : Effect.fail(new McpTestFailure({
-			reason: "ErrorResponse",
-			message: `tools/list failed: ${ToolFailure.truncate(JSON.stringify(response.error))}`
-		})));
-		const listResources = Effect.flatMap(request("resources/list"), (response) => response.error === void 0 ? Effect.succeed(response.result.resources) : Effect.fail(new McpTestFailure({
-			reason: "ErrorResponse",
-			message: `resources/list failed: ${ToolFailure.truncate(JSON.stringify(response.error))}`
-		})));
-		const awaitOutboundMethod = (method) => Effect.suspend(() => {
-			const index = retained.findIndex((message) => message.method === method);
-			if (index !== -1) return Effect.succeed(retained.splice(index, 1)[0]);
-			return stopAware(Effect.gen(function* () {
-				while (true) {
-					const message = yield* Queue.take(inbound);
-					if (message.method === method) return message;
-					retained.push(message);
-				}
-			}));
-		});
-		return new McpHarness({
-			protocol,
-			initialize,
-			initializeWith,
-			discover,
-			request,
-			startRequest,
-			notify,
-			callTool: (name, args) => request("tools/call", {
-				name,
-				arguments: args ?? {}
-			}),
-			listTools,
-			listResources,
-			readResource: (uri) => request("resources/read", { uri }),
-			sendRaw,
-			awaitOutboundMethod,
-			sentSoFar: Effect.sync(() => [...sent]),
-			stderrSoFar: Effect.sync(() => stderr.join("")),
-			consoleLogSoFar: Effect.sync(() => [...consoleLog]),
-			close: Effect.asVoid(Queue.end(stdin)),
-			stop: Fiber.interrupt(serverFiber)
-		});
-	});
-};
-
-export { McpHarness };

package/McpProbe.js

@@ -1,94 +0,0 @@
-import { ToolFailure } from "./ToolFailure.js";
-import { DEFAULT_CLIENT_INFO, STDERR_HINT, frame, initializeParams, isJsonRpcMessage, isResponse, isStateless, parseFrame } from "./internal/wire.js";
-import { McpTestFailure } from "./McpTestFailure.js";
-import { McpProcess } from "./McpProcess.js";
-import { Effect } from "effect";
-import { McpProtocol } from "effect/ai";
-
-// src/McpProbe.ts
-/**
-* The smallest proof that an installed MCP bin boots: one initialize, a clean
-* close, and exit 0.
-*
-* @remarks
-* Stdin stays open until the id-1 response has arrived. Closing it right
-* after writing proves nothing against a server that stops at stdin EOF
-* without answering what is in flight: it replies nothing and exits 0, so a
-* slow boot reads as a pass with no response. The caller asserts `response.error === undefined`, `stderr` is
-* empty and `exitCode` is 0; this is the MCP half of a packed-install proof.
-* Checking stderr and the exit code alone passes a server that answers
-* the handshake with a JSON-RPC error, exits 0 and writes nothing.
-*
-* - Any stdout line that is not JSON-RPC fails with `NotJsonRpc`, naming the
-*   line: a server that logs to stdout corrupts the wire, so the probe fails
-*   rather than skipping the line.
-* - A child that exits before responding fails with `StreamEnded`, and the
-*   message carries its exit code and stderr.
-* - A child that ignores stdin EOF never exits, and the probe waits for it.
-*   Wrap the probe in `Effect.timeout`.
-*
-* @example
-* ```ts
-* import { McpProbe } from "@effected/mcp/testing";
-* import { Effect } from "effect";
-* import { ChildProcess } from "effect/process";
-*
-* const program = Effect.gen(function* () {
-* 	const probe = yield* McpProbe.initialize(ChildProcess.make(process.execPath, ["./bin/server.js"]));
-* 	// A clean boot: no JSON-RPC error, empty stderr, exit code 0.
-* 	return probe.response.error === undefined && probe.stderr === "" && probe.exitCode === 0;
-* });
-* // Requires a `ChildProcessSpawner` from the platform layer.
-* ```
-*
-* @public
-*/
-var McpProbe = class {
-	constructor() {}
-	/**
-	* Spawn `command`, send one `initialize` (or `server/discover` on a
-	* stateless revision) as id 1, wait for its response, close stdin, and
-	* collect stdout, stderr and the exit code.
-	*/
-	static initialize = (command, options = {}) => Effect.scoped(Effect.gen(function* () {
-		const child = yield* McpProcess.spawn(command);
-		const protocol = options.protocol ?? McpProtocol.v2025_11_25;
-		const stateless = isStateless(protocol);
-		yield* child.send(frame(protocol, DEFAULT_CLIENT_INFO, stateless ? "server/discover" : "initialize", stateless ? {} : initializeParams(protocol, DEFAULT_CLIENT_INFO), 1));
-		const stdout = [];
-		const read = Effect.gen(function* () {
-			const line = yield* child.nextLine;
-			stdout.push(line);
-			const message = parseFrame(line);
-			if (!isJsonRpcMessage(message)) return yield* new McpTestFailure({
-				reason: "NotJsonRpc",
-				message: `stdout carried a line that is not JSON-RPC: ${ToolFailure.truncate(line)}`
-			});
-			return message;
-		});
-		const diagnose = (failure) => failure.reason !== "StreamEnded" ? Effect.fail(failure) : Effect.gen(function* () {
-			const code = yield* child.exitCode;
-			const stderr = yield* child.stderrFinal;
-			return yield* new McpTestFailure({
-				reason: "StreamEnded",
-				message: `${failure.message.replace(STDERR_HINT, "")}; the child exited with code ${code}; stderr: ${stderr === "" ? "(empty)" : ToolFailure.truncate(stderr)}`
-			});
-		});
-		let response;
-		while (response === void 0) {
-			const message = yield* Effect.catch(read, diagnose);
-			if (isResponse(message) && message.id === 1) response = message;
-		}
-		yield* child.closeStdin;
-		const exitCode = yield* child.exitCode;
-		while (true) if (!(yield* Effect.catch(Effect.map(read, () => true), (failure) => failure.reason === "StreamEnded" ? Effect.succeed(false) : Effect.fail(failure)))) break;
-		return {
-			response,
-			stdout,
-			stderr: yield* child.stderrFinal,
-			exitCode
-		};
-	}));
-};
-
-export { McpProbe };

package/McpProcess.js

@@ -1,196 +0,0 @@
-import { ToolFailure } from "./ToolFailure.js";
-import { DEFAULT_CLIENT_INFO, STDERR_HINT, frame, initializeParams, isJsonRpcMessage, isResponse, isStateless, parseFrame } from "./internal/wire.js";
-import { McpTestFailure } from "./McpTestFailure.js";
-import { Deferred, Duration, Effect, Option, Queue, Ref, Stream, SubscriptionRef } from "effect";
-import { McpProtocol } from "effect/ai";
-import { ChildProcessSpawner } from "effect/process";
-
-// src/McpProcess.ts
-/**
-* A spawned MCP server bin a test writes to while it runs.
-*
-* @remarks
-* Build the command in the test file with `execPath` and an explicit `env`:
-* `ChildProcess.make(process.execPath, [bin], { env })`.
-*
-* - `nextLine` fails with `StreamEnded` when stdout ends, so a child that
-*   exits early fails the test instead of hanging it.
-* - `send` writes one JSON-encoded line; `sendRaw` writes a string or bytes
-*   exactly as given, for a malformed frame or one frame split across
-*   writes, even mid-character.
-* - `readUntilResponse` reads past interleaved notifications, such as
-*   `list_changed`, to the matching id and returns what it saw.
-* - `closeStdin` is `Queue.end`, never `Queue.shutdown`, so every frame
-*   already sent is delivered before stdin closes.
-* - A request in flight when stdin closes still answers from an Effect
-*   server, which drains before it exits; a server that does not drain
-*   drops it, so a portable client reads the response first.
-*
-* @example
-* ```ts
-* import { McpProcess } from "@effected/mcp/testing";
-* import { Effect } from "effect";
-* import { ChildProcess } from "effect/process";
-*
-* const program = Effect.gen(function* () {
-* 	const child = yield* McpProcess.spawn(ChildProcess.make(process.execPath, ["./bin/server.js"]));
-* 	yield* child.handshake();
-* 	yield* child.send({ jsonrpc: "2.0", id: 2, method: "tools/list" });
-* 	const { response } = yield* child.readUntilResponse(2);
-* 	yield* child.closeStdin;
-* 	return response;
-* }).pipe(Effect.scoped);
-* // Requires a `ChildProcessSpawner` from the platform layer.
-* ```
-*
-* @public
-*/
-var McpProcess = class McpProcess {
-	/**
-	* Write one JSON-encoded, newline-framed message to the child's stdin.
-	*
-	* @remarks
-	* Never fails. A frame sent after `closeStdin` is dropped, and a write the
-	* child can no longer receive fails the stdin pump instead; the next
-	* `StreamEnded` message names that failure.
-	*/
-	send;
-	/**
-	* Write `text` to the child's stdin exactly as given: a string as UTF-8,
-	* bytes unchanged, with no JSON encoding and no newline added.
-	*
-	* @remarks
-	* For frames `send` cannot produce: a line that is not JSON, a blank line,
-	* or one frame split across several writes, including mid-character by
-	* passing bytes. Include the `\n` yourself.
-	* Never fails, on the same terms as `send`.
-	*/
-	sendRaw;
-	/** The next non-empty stdout line; fails with `StreamEnded` once stdout ends. */
-	nextLine;
-	/** Read JSON-RPC lines up to and including the response with this id. */
-	readUntilResponse;
-	/** `initialize` (id 1) then `notifications/initialized`, or `server/discover` (id 1) on a stateless revision. Use ids of 2 or more for your own requests. */
-	handshake;
-	/** End stdin after every frame already sent. */
-	closeStdin;
-	/** Wait for the child to exit. */
-	exitCode;
-	/** Everything written to stderr so far. */
-	stderrSoFar;
-	/**
-	* Wait until everything written to stderr so far satisfies `predicate`,
-	* and return that text.
-	*
-	* @remarks
-	* Event-driven: the predicate is checked against the current text at once,
-	* then again on every chunk the child writes, never on a polling timer.
-	* Fails with `StreamEnded` when stderr ends (the child exited) without the
-	* predicate holding, and with `TimedOut` once `options.timeout` passes;
-	* both messages carry the stderr seen so far. Reach for it whenever a
-	* report lands on a later tick than the responses a test reads, such as
-	* `McpGuard`'s `injectCrash: { at: "connected" }` report, instead of
-	* reading `stderrSoFar` once. `options.timeout` is real time: run the test
-	* under `it.live`.
-	*/
-	stderrUntil;
-	/** Everything written to stderr, once stderr has ended. Waits for the child to exit. */
-	stderrFinal;
-	constructor(parts) {
-		this.send = parts.send;
-		this.sendRaw = parts.sendRaw;
-		this.nextLine = parts.nextLine;
-		this.readUntilResponse = parts.readUntilResponse;
-		this.handshake = parts.handshake;
-		this.closeStdin = parts.closeStdin;
-		this.exitCode = parts.exitCode;
-		this.stderrSoFar = parts.stderrSoFar;
-		this.stderrUntil = parts.stderrUntil;
-		this.stderrFinal = parts.stderrFinal;
-	}
-	/** Spawn `command` for the life of the current scope. */
-	static spawn = (command) => Effect.gen(function* () {
-		const handle = yield* (yield* ChildProcessSpawner.ChildProcessSpawner).spawn(command);
-		const encoder = new TextEncoder();
-		const stdin = yield* Queue.unbounded();
-		const stdinFailure = yield* Ref.make(void 0);
-		yield* Stream.run(Stream.fromQueue(stdin), handle.stdin).pipe(Effect.catch((error) => Ref.set(stdinFailure, error.message)), Effect.forkScoped);
-		const lines = yield* Queue.unbounded();
-		yield* Stream.splitLines(Stream.decodeText(handle.stdout)).pipe(Stream.runForEach((line) => line.length === 0 ? Effect.void : Effect.asVoid(Queue.offer(lines, line))), Effect.ensuring(Queue.end(lines)), Effect.forkScoped);
-		const stderr = yield* SubscriptionRef.make({
-			text: "",
-			done: false
-		});
-		const stderrDone = yield* Deferred.make();
-		yield* Stream.decodeText(handle.stderr).pipe(Stream.runForEach((text) => SubscriptionRef.update(stderr, (sofar) => ({
-			text: sofar.text + text,
-			done: false
-		}))), Effect.ensuring(Effect.andThen(SubscriptionRef.update(stderr, (sofar) => ({
-			text: sofar.text,
-			done: true
-		})), Deferred.succeed(stderrDone, void 0))), Effect.forkScoped);
-		const stderrText = Effect.map(SubscriptionRef.get(stderr), (state) => state.text);
-		const stderrUntil = (predicate, options) => SubscriptionRef.changes(stderr).pipe(Stream.filter((state) => state.done || predicate(state.text)), Stream.runHead, Effect.flatMap((found) => {
-			const state = Option.getOrElse(found, () => ({
-				text: "",
-				done: true
-			}));
-			return predicate(state.text) ? Effect.succeed(state.text) : Effect.fail(new McpTestFailure({
-				reason: "StreamEnded",
-				message: `the server's stderr ended before it matched; stderr: ${ToolFailure.truncate(state.text, ToolFailure.ENGINE_ECHO_LIMIT)}`
-			}));
-		}), Effect.timeoutOrElse({
-			duration: options.timeout,
-			orElse: () => Effect.flatMap(stderrText, (text) => Effect.fail(new McpTestFailure({
-				reason: "TimedOut",
-				message: `the server's stderr did not match within ${Duration.format(Duration.fromInputUnsafe(options.timeout))}; stderr so far: ${ToolFailure.truncate(text, ToolFailure.ENGINE_ECHO_LIMIT)}`
-			})))
-		}));
-		const nextLine = Queue.take(lines).pipe(Effect.catch(() => Effect.flatMap(Ref.get(stdinFailure), (pump) => Effect.fail(new McpTestFailure({
-			reason: "StreamEnded",
-			message: `the server's stdout ended before the expected line${STDERR_HINT}${pump === void 0 ? "" : `; stdin pump failed: ${ToolFailure.truncate(pump)}`}`
-		})))));
-		const readUntilResponse = (id) => Effect.gen(function* () {
-			const seen = [];
-			while (true) {
-				const line = yield* nextLine;
-				const message = parseFrame(line);
-				if (!isJsonRpcMessage(message)) return yield* new McpTestFailure({
-					reason: "NotJsonRpc",
-					message: `stdout carried a line that is not JSON-RPC: ${ToolFailure.truncate(line)}`
-				});
-				seen.push(message);
-				if (isResponse(message) && message.id === id) return {
-					response: message,
-					seen
-				};
-			}
-		});
-		const sendRaw = (text) => Effect.asVoid(Queue.offer(stdin, typeof text === "string" ? encoder.encode(text) : text));
-		const send = (message) => sendRaw(`${JSON.stringify(message)}\n`);
-		const handshake = (protocol = McpProtocol.v2025_11_25) => Effect.gen(function* () {
-			if (isStateless(protocol)) {
-				yield* send(frame(protocol, DEFAULT_CLIENT_INFO, "server/discover", {}, 1));
-				return (yield* readUntilResponse(1)).response;
-			}
-			yield* send(frame(protocol, DEFAULT_CLIENT_INFO, "initialize", initializeParams(protocol, DEFAULT_CLIENT_INFO), 1));
-			const { response } = yield* readUntilResponse(1);
-			yield* send(frame(protocol, DEFAULT_CLIENT_INFO, "notifications/initialized", void 0));
-			return response;
-		});
-		return new McpProcess({
-			send,
-			sendRaw,
-			nextLine,
-			readUntilResponse,
-			handshake,
-			closeStdin: Effect.asVoid(Queue.end(stdin)),
-			exitCode: Effect.map(handle.exitCode, (code) => Number(code)),
-			stderrSoFar: stderrText,
-			stderrUntil,
-			stderrFinal: Effect.andThen(Deferred.await(stderrDone), stderrText)
-		});
-	});
-};
-
-export { McpProcess };