@effected/mcp 0.4.0 → 0.5.0

package/McpGuard.js

@@ -1,26 +1,19 @@
+import { ProcessGuard } from "@effected/engine/guard";
+
 //#region src/McpGuard.ts
-const isInjectedKind = (kind) => kind === "uncaughtException" || kind === "unhandledRejection";
-/** Emit one injected crash through the host, to the listeners the guard installed there. */
-const emitInjected = (host, kind) => {
-	const error = /* @__PURE__ */ new Error(`[injected] ${kind}`);
-	if (kind === "uncaughtException") {
-		host.emit("uncaughtException", error, "uncaughtException");
-		return;
-	}
-	const promise = Promise.reject(error);
-	promise.catch(() => void 0);
-	host.emit("unhandledRejection", error, promise);
-};
-const fallbackFormat = (error) => error instanceof Error ? error.stack ?? error.message : String(error);
 /**
 * Crash guards for an MCP server process, installed before the server's
 * module graph is loaded. Imported from `@effected/mcp/guard`.
 *
 * @remarks
-* {@link McpGuard.run} registers `uncaughtException` and `unhandledRejection`
-* listeners on `host`, then awaits `load()`, then launches the server with
-* `McpStdio.launch` and `McpStdio.teardown` under the `runMain` it returned.
-* This entrypoint has no static runtime import: it loads `effect` and the
+* {@link McpGuard.run} is `ProcessGuard.run` from `@effected/engine/guard`
+* with an MCP launch in its `load`: it registers `uncaughtException` and
+* `unhandledRejection` listeners on `host`, then awaits `load()`, then
+* launches the server with `McpStdio.launch` and `McpStdio.teardown` under
+* the `runMain` it returned. A server on another transport (an LSP over
+* `vscode-languageserver`, say) uses `ProcessGuard.run` directly and calls
+* its `markConnected` itself. This entrypoint statically imports only
+* `@effected/engine/guard`, which imports nothing: it loads `effect` and the
 * stdio wiring only after the guards are listening, so a throw while any of
 * it evaluates is still reported on stderr.
 *
@@ -58,63 +51,31 @@ const fallbackFormat = (error) => error instanceof Error ? error.stack ?? error.
 */
 var McpGuard = class {
 	constructor() {}
+	/**
+	* Parse a test-only crash-injection setting into {@link McpGuardRunOptions.injectCrash}: `<at>:<kind>`, where `at`
+	* is `"load"` or `"connected"` and `kind` is `"uncaughtException"` or `"unhandledRejection"`. Anything else, or no
+	* value, is `undefined`. The same grammar as `ProcessGuard.parseInjectCrash` from `@effected/engine/guard`, which
+	* this is, so an MCP launcher need not import the engine guard for it.
+	*
+	* @example
+	* ```ts
+	* McpGuard.parseInjectCrash("load:uncaughtException"); // => { at: "load", kind: "uncaughtException" }
+	* ```
+	*/
+	static parseInjectCrash = ProcessGuard.parseInjectCrash;
 	/** Install the guards, load the server, and launch it. Resolves once the server is launched. */
-	static run = async (options) => {
-		const { host, label } = options;
-		const onUncaught = options.policy?.onUncaught ?? "exit";
-		const onRejection = options.policy?.onRejection ?? "exit";
-		let connected = false;
-		let format = fallbackFormat;
-		const describe = (error) => {
-			try {
-				return format(error);
-			} catch {
-				try {
-					return fallbackFormat(error);
-				} catch {
-					return "<unformattable error value>";
-				}
-			}
-		};
-		const exits = (mode) => mode === "exit" || mode === "exitBeforeConnect" && !connected;
-		host.on("uncaughtException", (error, origin) => {
-			host.stderr.write(`${label}: uncaughtException (${origin}): ${describe(error)}\n`);
-			if (exits(onUncaught)) host.exit(1);
-		});
-		host.on("unhandledRejection", (reason) => {
-			host.stderr.write(`${label}: unhandledRejection: ${describe(reason)}\n`);
-			if (exits(onRejection)) host.exit(1);
-		});
-		const inject = options.injectCrash;
-		const injectKind = isInjectedKind(inject?.kind) ? inject.kind : void 0;
-		if (inject?.at === "load" && injectKind !== void 0) await new Promise((resolve, reject) => {
-			setTimeout(() => {
-				try {
-					emitInjected(host, injectKind);
-					resolve();
-				} catch (error) {
-					reject(error);
-				}
-			}, 0);
-		});
-		const onReady = () => {
-			connected = true;
-			if (inject?.at === "connected" && injectKind !== void 0) setTimeout(() => {
-				try {
-					emitInjected(host, injectKind);
-				} catch {}
-			}, 0);
-		};
-		try {
+	static run = (options) => ProcessGuard.run({
+		label: options.label,
+		host: options.host,
+		policy: options.policy,
+		injectCrash: options.injectCrash,
+		load: async (guard) => {
 			const server = await options.load();
-			if (server.format !== void 0) format = server.format;
+			if (server.format !== void 0) guard.useFormat(server.format);
 			const { launchGuarded } = await import("./internal/guardLaunch.js");
-			launchGuarded(server, onReady);
-		} catch (error) {
-			host.stderr.write(`${label}: startup failed: ${describe(error)}\n`);
-			host.exit(1);
+			launchGuarded(server, guard.markConnected);
 		}
-	};
+	});
 };
 
 //#endregion

package/McpHarness.js

@@ -1,7 +1,7 @@
 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, Layer, Queue, Sink, Stdio, Stream } from "effect";
+import { Console, Deferred, Effect, Exit, Fiber, Layer, Queue, Sink, Stdio, Stream } from "effect";
 import { McpProtocol } from "effect/ai";
 
 //#region src/McpHarness.ts
@@ -30,9 +30,11 @@ import { McpProtocol } from "effect/ai";
 * once and pass `Layer.succeed(Tag, value)`.
 *
 * - Responses are matched by id, so notifications may interleave freely.
-* - No wait can hang: every response wait and `awaitOutboundMethod` fails
-*   with `ServerStopped` when the server stops (stdin closing does that),
-*   and dies when `strictStdout` sees a line that is not JSON-RPC.
+* - 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
@@ -109,8 +111,19 @@ var McpHarness = class McpHarness {
 	stderrSoFar;
 	/** Every captured `console.log`, `info` or `debug` call. */
 	consoleLogSoFar;
-	/** End stdin, as a client disconnecting does. */
+	/**
+	* 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;
@@ -129,6 +142,7 @@ var McpHarness = class McpHarness {
 		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* () {
@@ -186,11 +200,11 @@ var McpHarness = class McpHarness {
 			}
 			return Effect.asVoid(Queue.offer(inbound, parsed));
 		};
-		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);
-		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, Deferred.fail(stopped, new McpTestFailure({
+		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);
+		})))))), Effect.forkScoped);
 		yield* Deferred.await(ready);
 		const stopAware = (wait) => Effect.raceAllFirst([
 			wait,
@@ -277,7 +291,8 @@ var McpHarness = class McpHarness {
 			sentSoFar: Effect.sync(() => [...sent]),
 			stderrSoFar: Effect.sync(() => stderr.join("")),
 			consoleLogSoFar: Effect.sync(() => [...consoleLog]),
-			close: Effect.asVoid(Queue.end(stdin))
+			close: Effect.asVoid(Queue.end(stdin)),
+			stop: Fiber.interrupt(serverFiber)
 		});
 	});
 };

package/McpProbe.js

@@ -12,8 +12,9 @@ import { McpProtocol } from "effect/ai";
 *
 * @remarks
 * Stdin stays open until the id-1 response has arrived. Closing it right
-* after writing makes an Effect server drop the in-flight response and exit 0, so a slow boot reads as a pass with
-* no response. The caller asserts `response.error === undefined`, `stderr` is
+* 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.

package/McpProcess.js

@@ -1,7 +1,7 @@
 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, Effect, Queue, Ref, Stream } from "effect";
+import { Deferred, Duration, Effect, Option, Queue, Ref, Stream, SubscriptionRef } from "effect";
 import { McpProtocol } from "effect/ai";
 import { ChildProcessSpawner } from "effect/process";
 
@@ -22,8 +22,9 @@ import { ChildProcessSpawner } from "effect/process";
 *   `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 is dropped by an Effect server:
-*   read its response first.
+* - 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
@@ -77,6 +78,22 @@ var McpProcess = class McpProcess {
 	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) {
@@ -88,6 +105,7 @@ var McpProcess = class McpProcess {
 		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. */
@@ -99,9 +117,35 @@ var McpProcess = class McpProcess {
 		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* Ref.make("");
+		const stderr = yield* SubscriptionRef.make({
+			text: "",
+			done: false
+		});
 		const stderrDone = yield* Deferred.make();
-		yield* Stream.decodeText(handle.stderr).pipe(Stream.runForEach((text) => Ref.update(stderr, (sofar) => sofar + text)), Effect.ensuring(Deferred.succeed(stderrDone, void 0)), Effect.forkScoped);
+		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)}`}`
@@ -142,8 +186,9 @@ var McpProcess = class McpProcess {
 			handshake,
 			closeStdin: Effect.asVoid(Queue.end(stdin)),
 			exitCode: Effect.map(handle.exitCode, (code) => Number(code)),
-			stderrSoFar: Ref.get(stderr),
-			stderrFinal: Effect.andThen(Deferred.await(stderrDone), Ref.get(stderr))
+			stderrSoFar: stderrText,
+			stderrUntil,
+			stderrFinal: Effect.andThen(Deferred.await(stderrDone), stderrText)
 		});
 	});
 };

package/McpStdio.js

@@ -64,6 +64,16 @@ var McpStdio = class McpStdio {
 	* `Layer.provideMerge(McpStdio.layer(...))`. A sibling merged beside it
 	* with `Layer.mergeAll` is not provided by it, so its build logs still
 	* go through `console.log`, onto the wire.
+	
+	*
+	* `LogToStderr` only reaches a logger that reads it: Effect's default
+	* logger and `Logger.consolePretty`. `Logger.consoleJson`,
+	* `Logger.consoleLogFmt` and `Logger.consoleStructured` are built with
+	* `Logger.withConsoleLog`, which writes through `console.log` whatever
+	* `LogToStderr` says, so a server that installs one puts every log line on
+	* the wire. Never install them under this layer; wrap the formatter in
+	* `Logger.withConsoleError` instead, as in
+	* `Logger.layer([Logger.withConsoleError(Logger.formatJson)])`.
 	*
 	* The server reads stdin through a guard that frames it exactly as core's
 	* decoder does: one streaming UTF-8 decoder, a byte-order mark stripped

package/McpTestFailure.js

@@ -10,7 +10,10 @@ import { Schema } from "effect";
 *
 * - `StreamEnded` (`McpProcess`, `McpProbe`): the spawned child's stdout
 *   ended first, because the child exited. `McpProbe` folds the exit code
-*   and stderr into the message.
+*   and stderr into the message. `McpProcess.stderrUntil` raises it when
+*   stderr ends before its predicate holds.
+* - `TimedOut` (`McpProcess.stderrUntil`): the predicate did not hold
+*   within the given timeout. The message carries the stderr seen so far.
 * - `NotJsonRpc` (`McpProcess.readUntilResponse`, `McpProbe`): a spawned
 *   child's stdout line was not a JSON-RPC frame. `McpHarness` never raises
 *   it: under `strictStdout` a non-JSON-RPC line DIES the pending wait as a
@@ -36,7 +39,8 @@ var McpTestFailure = class extends Schema.TaggedError()("McpTestFailure", {
 		"ServerStopped",
 		"NotJsonRpc",
 		"NotInitialized",
-		"ErrorResponse"
+		"ErrorResponse",
+		"TimedOut"
 	]),
 	/** A human-readable description of what went wrong. */
 	message: Schema.String

package/ToolRefusal.js

@@ -17,6 +17,19 @@ import { Schema } from "effect";
 * Audit every throw path of a tool: any failure left undeclared loses its
 * message on the wire, however carefully it was worded.
 *
+* **Structured data on a refusal is deliberately unreachable: put it in the
+* message.** Core's `McpServer.registerToolkit` builds every failed call's
+* result with `structuredContent` unset and no `_meta`, on every protocol
+* revision. Under the default `failureMode: "error"` a declared `Error`
+* failure sends `message` as the only text; under `failureMode: "return"`
+* it sends the whole encoded failure JSON-stringified into the text, still
+* with no `structuredContent`, which buries the human message in JSON a
+* client must parse. So `refuse` takes no data argument: a list of valid
+* names, the root that was searched, the id that was not found all belong
+* in `reason`, truncated with {@link ToolFailure.truncate}. When an agent
+* must branch on the data itself, return it on the success channel as an
+* `ok: false` envelope, where `structuredContent` does reach the client.
+*
 * @example
 * ```ts
 * import { ToolFailure, ToolRefusal } from "@effected/mcp";

package/guard.d.ts

@@ -89,6 +89,13 @@ interface McpGuardRunOptions<ROut, E> {
    *   serving, where `"exitBeforeConnect"` logs and keeps serving. A throw
    *   from a test double's `exit` there is dropped.
    *
+   * **The `"connected"` report is asynchronous.** It is raised on a later
+   * tick, a `setTimeout(0)` after the server starts serving, so it can land
+   * after the first responses a test reads: reading stderr once, right
+   * after the `initialize` or `tools/list` response, can see an empty
+   * buffer. Wait for it with `McpProcess.stderrUntil` from
+   * `@effected/mcp/testing` rather than reading it once.
+   *
    * Either is raised only through `host.emit`, on a `setTimeout(0)` tick,
    * never as a real throw or rejection, so the guard's listeners handle it
    * the same way under the real `process` and under a test double. Under
@@ -108,10 +115,14 @@ interface McpGuardRunOptions<ROut, E> {
  * module graph is loaded. Imported from `@effected/mcp/guard`.
  *
  * @remarks
- * {@link McpGuard.run} registers `uncaughtException` and `unhandledRejection`
- * listeners on `host`, then awaits `load()`, then launches the server with
- * `McpStdio.launch` and `McpStdio.teardown` under the `runMain` it returned.
- * This entrypoint has no static runtime import: it loads `effect` and the
+ * {@link McpGuard.run} is `ProcessGuard.run` from `@effected/engine/guard`
+ * with an MCP launch in its `load`: it registers `uncaughtException` and
+ * `unhandledRejection` listeners on `host`, then awaits `load()`, then
+ * launches the server with `McpStdio.launch` and `McpStdio.teardown` under
+ * the `runMain` it returned. A server on another transport (an LSP over
+ * `vscode-languageserver`, say) uses `ProcessGuard.run` directly and calls
+ * its `markConnected` itself. This entrypoint statically imports only
+ * `@effected/engine/guard`, which imports nothing: it loads `effect` and the
  * stdio wiring only after the guards are listening, so a throw while any of
  * it evaluates is still reported on stderr.
  *
@@ -149,6 +160,18 @@ interface McpGuardRunOptions<ROut, E> {
  */
 export declare class McpGuard {
   private constructor();
+  /**
+   * Parse a test-only crash-injection setting into {@link McpGuardRunOptions.injectCrash}: `<at>:<kind>`, where `at`
+   * is `"load"` or `"connected"` and `kind` is `"uncaughtException"` or `"unhandledRejection"`. Anything else, or no
+   * value, is `undefined`. The same grammar as `ProcessGuard.parseInjectCrash` from `@effected/engine/guard`, which
+   * this is, so an MCP launcher need not import the engine guard for it.
+   *
+   * @example
+   * ```ts
+   * McpGuard.parseInjectCrash("load:uncaughtException"); // => { at: "load", kind: "uncaughtException" }
+   * ```
+   */
+  static readonly parseInjectCrash: (value: string | undefined) => McpGuardRunOptions<unknown, unknown>["injectCrash"];
   /** Install the guards, load the server, and launch it. Resolves once the server is launched. */
   static readonly run: <ROut, E>(options: McpGuardRunOptions<ROut, E>) => Promise<void>;
 }

package/index.d.ts

@@ -96,6 +96,15 @@ export declare class McpStdio {
    * with `Layer.mergeAll` is not provided by it, so its build logs still
    * go through `console.log`, onto the wire.
    *
+   * `LogToStderr` only reaches a logger that reads it: Effect's default
+   * logger and `Logger.consolePretty`. `Logger.consoleJson`,
+   * `Logger.consoleLogFmt` and `Logger.consoleStructured` are built with
+   * `Logger.withConsoleLog`, which writes through `console.log` whatever
+   * `LogToStderr` says, so a server that installs one puts every log line on
+   * the wire. Never install them under this layer; wrap the formatter in
+   * `Logger.withConsoleError` instead, as in
+   * `Logger.layer([Logger.withConsoleError(Logger.formatJson)])`.
+   *
    * The server reads stdin through a guard that frames it exactly as core's
    * decoder does: one streaming UTF-8 decoder, a byte-order mark stripped
    * only at the start of the stream, lines split on `\n`. Core itself skips
@@ -604,6 +613,19 @@ declare const ToolRefusal_base: Schema.Class<ToolRefusal, Schema.TaggedStruct<"T
  * Audit every throw path of a tool: any failure left undeclared loses its
  * message on the wire, however carefully it was worded.
  *
+ * **Structured data on a refusal is deliberately unreachable: put it in the
+ * message.** Core's `McpServer.registerToolkit` builds every failed call's
+ * result with `structuredContent` unset and no `_meta`, on every protocol
+ * revision. Under the default `failureMode: "error"` a declared `Error`
+ * failure sends `message` as the only text; under `failureMode: "return"`
+ * it sends the whole encoded failure JSON-stringified into the text, still
+ * with no `structuredContent`, which buries the human message in JSON a
+ * client must parse. So `refuse` takes no data argument: a list of valid
+ * names, the root that was searched, the id that was not found all belong
+ * in `reason`, truncated with {@link ToolFailure.truncate}. When an agent
+ * must branch on the data itself, return it on the success channel as an
+ * `ok: false` envelope, where `structuredContent` does reach the client.
+ *
  * @example
  * ```ts
  * import { ToolFailure, ToolRefusal } from "@effected/mcp";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/mcp",
-	"version": "0.4.0",
+	"version": "0.5.0",
 	"private": false,
 	"description": "The boundary layer of an effect/ai MCP server: stdio wiring that keeps stdout the wire, tool-failure shaping, strict-input walkers, and test clients",
 	"keywords": [
@@ -47,7 +47,7 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"@effected/engine": "^0.3.0",
+		"@effected/engine": "^0.4.0",
 		"effect": "^4.0.0"
 	},
 	"engines": {

package/testing.d.ts

@@ -1,10 +1,10 @@
-import { Effect, JsonSchema, Layer, PlatformError, Schema, Scope, Stdio } from "effect";
+import { Duration, Effect, JsonSchema, Layer, PlatformError, Schema, Scope, Stdio } from "effect";
 import { McpProtocol } from "effect/ai";
 import { ChildProcess, ChildProcessSpawner } from "effect/process";
 //#region src/McpTestFailure.d.ts
 declare const McpTestFailure_base: Schema.Class<McpTestFailure, Schema.TaggedStruct<"McpTestFailure", {
   /** Which failure occurred; see the list above for which client raises which. */
-  readonly reason: Schema.Literals<readonly ["StreamEnded", "ServerStopped", "NotJsonRpc", "NotInitialized", "ErrorResponse"]>;
+  readonly reason: Schema.Literals<readonly ["StreamEnded", "ServerStopped", "NotJsonRpc", "NotInitialized", "ErrorResponse", "TimedOut"]>;
   /** A human-readable description of what went wrong. */
   readonly message: Schema.String;
 }>, import("effect/Cause").YieldableError>;
@@ -17,7 +17,10 @@ declare const McpTestFailure_base: Schema.Class<McpTestFailure, Schema.TaggedStr
  *
  * - `StreamEnded` (`McpProcess`, `McpProbe`): the spawned child's stdout
  *   ended first, because the child exited. `McpProbe` folds the exit code
- *   and stderr into the message.
+ *   and stderr into the message. `McpProcess.stderrUntil` raises it when
+ *   stderr ends before its predicate holds.
+ * - `TimedOut` (`McpProcess.stderrUntil`): the predicate did not hold
+ *   within the given timeout. The message carries the stderr seen so far.
  * - `NotJsonRpc` (`McpProcess.readUntilResponse`, `McpProbe`): a spawned
  *   child's stdout line was not a JSON-RPC frame. `McpHarness` never raises
  *   it: under `strictStdout` a non-JSON-RPC line DIES the pending wait as a
@@ -134,9 +137,11 @@ interface McpHarnessOptions {
  * once and pass `Layer.succeed(Tag, value)`.
  *
  * - Responses are matched by id, so notifications may interleave freely.
- * - No wait can hang: every response wait and `awaitOutboundMethod` fails
- *   with `ServerStopped` when the server stops (stdin closing does that),
- *   and dies when `strictStdout` sees a line that is not JSON-RPC.
+ * - 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
@@ -216,8 +221,19 @@ export declare class McpHarness {
   readonly stderrSoFar: Effect.Effect<string>;
   /** Every captured `console.log`, `info` or `debug` call. */
   readonly consoleLogSoFar: Effect.Effect<ReadonlyArray<string>>;
-  /** End stdin, as a client disconnecting does. */
+  /**
+   * 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.
+   */
   readonly close: Effect.Effect<void>;
+  /**
+   * Interrupt the server without draining, as a client killing the process
+   * does: every pending response wait and `awaitOutboundMethod` fails with
+   * `ServerStopped`.
+   */
+  readonly stop: Effect.Effect<void>;
   private constructor();
   /** Build `server` over queue-backed stdio and return a client for it; fails with the layer's own error if it cannot build. */
   static readonly make: <ROut, E, R>(server: Layer.Layer<ROut, E, R>, options?: McpHarnessOptions) => Effect.Effect<McpHarness, E, Scope.Scope | Exclude<R, Stdio.Stdio>>;
@@ -254,8 +270,9 @@ interface McpProbeResult {
  *
  * @remarks
  * Stdin stays open until the id-1 response has arrived. Closing it right
- * after writing makes an Effect server drop the in-flight response and exit 0, so a slow boot reads as a pass with
- * no response. The caller asserts `response.error === undefined`, `stderr` is
+ * 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.
@@ -295,6 +312,20 @@ export declare class McpProbe {
 }
 //#endregion
 //#region src/McpProcess.d.ts
+/**
+ * Options for {@link McpProcess.stderrUntil}.
+ *
+ * @public
+ */
+interface McpProcessStderrUntilOptions {
+  /**
+   * How long to wait for the predicate to hold before failing with
+   * `TimedOut`. Real time: under `it.effect`'s `TestClock` it never fires,
+   * so a test that waits on stderr runs under `it.live`. Keep it below the
+   * test runner's own timeout, or the runner kills the test first.
+   */
+  readonly timeout: Duration.Input;
+}
 /**
  * A spawned MCP server bin a test writes to while it runs.
  *
@@ -311,8 +342,9 @@ export declare class McpProbe {
  *   `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 is dropped by an Effect server:
- *   read its response first.
+ * - 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
@@ -369,6 +401,22 @@ export declare class McpProcess {
   readonly exitCode: Effect.Effect<number, PlatformError.PlatformError>;
   /** Everything written to stderr so far. */
   readonly stderrSoFar: Effect.Effect<string>;
+  /**
+   * 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`.
+   */
+  readonly stderrUntil: (predicate: (stderr: string) => boolean, options: McpProcessStderrUntilOptions) => Effect.Effect<string, McpTestFailure>;
   /** Everything written to stderr, once stderr has ended. Waits for the child to exit. */
   readonly stderrFinal: Effect.Effect<string>;
   private constructor();
@@ -442,5 +490,5 @@ export declare class McpToolAudit {
   static readonly check: (tools: ReadonlyArray<ServedTool>, policy: McpToolAuditPolicy) => ReadonlyArray<string>;
 }
 //#endregion
-export type { JsonRpcMessage, McpHarnessOptions, McpProbeOptions, McpProbeResult, McpToolAuditPolicy, ServedResource, ServedTool };
+export type { JsonRpcMessage, McpHarnessOptions, McpProbeOptions, McpProbeResult, McpProcessStderrUntilOptions, McpToolAuditPolicy, ServedResource, ServedTool };
 //# sourceMappingURL=testing.d.ts.map