@effected/mcp 0.3.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
@@ -46,6 +48,20 @@ import { McpProtocol } from "effect/ai";
 *   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 {
@@ -95,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;
@@ -115,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* () {
@@ -172,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,
@@ -263,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,9 +12,9 @@ import { McpProtocol } from "effect/ai";
 *
 * @remarks
 * Stdin stays open until the id-1 response has arrived. Closing it right
-* after writing, as every hand-rolled smoke test did, 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.
@@ -27,6 +27,20 @@ import { McpProtocol } from "effect/ai";
 * - 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 {

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,26 @@ 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
+* 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
 */
@@ -60,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) {
@@ -71,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. */
@@ -82,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)}`}`
@@ -125,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

@@ -39,10 +39,9 @@ var McpStdio = class McpStdio {
 	* first, then the two newest stateful ones.
 	*
 	* @remarks
-	* Real clients open with either handshake: Claude Code 2.1.281 was
-	* measured opening a stdio server with the stateless `server/discover`,
-	* while most other shipping clients still send `initialize`. The order
-	* is load-bearing:
+	* Real clients open with either handshake: some (Claude Code, for one)
+	* open a stdio server with the stateless `server/discover`, while others
+	* still send `initialize`. The order is load-bearing:
 	*
 	* - Stateless first: a request with no session and no `_meta` falls to
 	*   `protocols[0]`.
@@ -65,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
@@ -30,13 +33,16 @@ import { Schema } from "effect";
 * @public
 */
 var McpTestFailure = class extends Schema.TaggedError()("McpTestFailure", {
+	/** Which failure occurred; see the list above for which client raises which. */
 	reason: Schema.Literals([
 		"StreamEnded",
 		"ServerStopped",
 		"NotJsonRpc",
 		"NotInitialized",
-		"ErrorResponse"
+		"ErrorResponse",
+		"TimedOut"
 	]),
+	/** A human-readable description of what went wrong. */
 	message: Schema.String
 }) {};
 

package/McpToolkit.js

@@ -185,6 +185,11 @@ var McpToolkit = class {
 	*
 	* @example
 	* ```ts
+	* import { McpToolkit, ToolOutputSchema, ToolRefusal } from "@effected/mcp";
+	* import { Schema } from "effect";
+	* import { Tool } from "effect/ai";
+	*
+	* // `AddNote`, `ListNotes`, `Added`, `Listed` are object schemas; `Kit` is a Toolkit that includes `Note`.
 	* const Note = McpToolkit.unionTool("note", {
 	*   parameters: Schema.Union([AddNote, ListNotes]),
 	*   success: ToolOutputSchema.objectRooted(Schema.Union([Added, Listed])),

package/README.md

@@ -7,10 +7,10 @@ The boundary layer of an `effect/ai` MCP server: stdio wiring that keeps stdout
 [![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
 [![TypeScript 7.0](https://img.shields.io/badge/TypeScript-7.0-3178c6.svg)](https://www.typescriptlang.org/)
 
-> **Pre-release.** This package is part of the `@effected/*` kit, in pre-`1.0.0`
-> development against a single pinned Effect v4 prerelease. Packages graduate to
-> `1.0.0` once Effect `4.0.0` ships. To hold your own `effect` versions at
-> exactly the ones the kit is built and tested against, install
+> **Pre-`1.0.0`.** This package is part of the `@effected/*` kit, built on stable
+> Effect v4 (`effect` `^4.0.0`) and still in `0.x` development. Stable Effect
+> makes a kit `1.0.0` possible, not automatic. To keep your `effect` and
+> `@effect/*` versions on the line the kit is built and tested against, install
 > [`@effected/pnpm-plugin-effect`](https://www.npmjs.com/package/@effected/pnpm-plugin-effect).
 >
 > **Stability: unstable.** This package's API surface is not yet considered

package/ToolFailure.js

@@ -26,6 +26,9 @@ const isHighSurrogate = (code) => code >= 55296 && code <= 56319;
 *
 * @example
 * ```ts
+* import { ToolFailure } from "@effected/mcp";
+* import { Schema } from "effect";
+*
 * class NotFound extends Schema.TaggedError<NotFound>()("NotFound", { ...ToolFailure.fields, id: Schema.String }) {}
 * const remediation = { hint: "List the ids first.", suggestedTool: "list_things" }
 * new NotFound({ id, remediation, message: ToolFailure.message(`No thing "${ToolFailure.truncate(id)}".`, remediation) })

package/ToolRefusal.js

@@ -14,11 +14,27 @@ import { Schema } from "effect";
 * {@link ToolRefusal.refuse}; its message already carries the remediation,
 * because a declared `Error` failure sends `message` and nothing else.
 *
-* Audit every throw path when porting a tool: any failure left undeclared
-* loses its message on the wire, however carefully it was worded.
+* 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";
+* import { Tool } from "effect/ai";
+*
 * const Lookup = Tool.make("lookup", { parameters, success, failure: ToolRefusal })
 * // in the handler:
 * return yield* ToolRefusal.refuse(`No run "${ToolFailure.truncate(id)}".`, { hint: "List runs first.", suggestedTool: "list_runs" })

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

@@ -74,10 +74,9 @@ export declare class McpStdio {
    * first, then the two newest stateful ones.
    *
    * @remarks
-   * Real clients open with either handshake: Claude Code 2.1.281 was
-   * measured opening a stdio server with the stateless `server/discover`,
-   * while most other shipping clients still send `initialize`. The order
-   * is load-bearing:
+   * Real clients open with either handshake: some (Claude Code, for one)
+   * open a stdio server with the stateless `server/discover`, while others
+   * still send `initialize`. The order is load-bearing:
    *
    * - Stateless first: a request with no session and no `_meta` falls to
    *   `protocols[0]`.
@@ -97,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
@@ -429,6 +437,11 @@ export declare class McpToolkit {
    *
    * @example
    * ```ts
+   * import { McpToolkit, ToolOutputSchema, ToolRefusal } from "@effected/mcp";
+   * import { Schema } from "effect";
+   * import { Tool } from "effect/ai";
+   *
+   * // `AddNote`, `ListNotes`, `Added`, `Listed` are object schemas; `Kit` is a Toolkit that includes `Note`.
    * const Note = McpToolkit.unionTool("note", {
    *   parameters: Schema.Union([AddNote, ListNotes]),
    *   success: ToolOutputSchema.objectRooted(Schema.Union([Added, Listed])),
@@ -488,6 +501,9 @@ export declare class McpToolkit {
  *
  * @example
  * ```ts
+ * import { ToolFailure } from "@effected/mcp";
+ * import { Schema } from "effect";
+ *
  * class NotFound extends Schema.TaggedError<NotFound>()("NotFound", { ...ToolFailure.fields, id: Schema.String }) {}
  * const remediation = { hint: "List the ids first.", suggestedTool: "list_things" }
  * new NotFound({ id, remediation, message: ToolFailure.message(`No thing "${ToolFailure.truncate(id)}".`, remediation) })
@@ -594,11 +610,27 @@ declare const ToolRefusal_base: Schema.Class<ToolRefusal, Schema.TaggedStruct<"T
  * {@link ToolRefusal.refuse}; its message already carries the remediation,
  * because a declared `Error` failure sends `message` and nothing else.
  *
- * Audit every throw path when porting a tool: any failure left undeclared
- * loses its message on the wire, however carefully it was worded.
+ * 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";
+ * import { Tool } from "effect/ai";
+ *
  * const Lookup = Tool.make("lookup", { parameters, success, failure: ToolRefusal })
  * // in the handler:
  * return yield* ToolRefusal.refuse(`No run "${ToolFailure.truncate(id)}".`, { hint: "List runs first.", suggestedTool: "list_runs" })

package/internal/LaunchFailed.js

@@ -7,15 +7,27 @@ import { Runtime } from "effect";
 * second time — through a logger that writes to stdout — and the original exit
 * code rides along for the teardown.
 *
+* @remarks
+* Both runtime markers are prototype getters rather than own fields, so a JSON
+* or logger dump of the error does not carry them; the code lives in a private
+* field.
+*
 * @internal
 */
 var LaunchFailed = class extends Error {
-	[Runtime.errorReported] = false;
-	[Runtime.errorExitCode];
+	#code;
 	constructor(code) {
 		super(`the MCP server failed to launch (exit ${code})`);
 		this.name = "LaunchFailed";
-		this[Runtime.errorExitCode] = code;
+		this.#code = code;
+	}
+	/** Already reported on stderr: `runMain` must not report it again. */
+	get [Runtime.errorReported]() {
+		return false;
+	}
+	/** The exit code the launch failed with. */
+	get [Runtime.errorExitCode]() {
+		return this.#code;
 	}
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/mcp",
-	"version": "0.3.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,8 +47,8 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"@effected/engine": "^0.2.0",
-		"effect": "4.0.0-rc.118"
+		"@effected/engine": "^0.4.0",
+		"effect": "^4.0.0"
 	},
 	"engines": {
 		"node": ">=24.11.0"

package/testing.d.ts

@@ -1,9 +1,11 @@
-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", {
-  readonly reason: Schema.Literals<readonly ["StreamEnded", "ServerStopped", "NotJsonRpc", "NotInitialized", "ErrorResponse"]>;
+  /** Which failure occurred; see the list above for which client raises which. */
+  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>;
 /**
@@ -15,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
@@ -132,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
@@ -148,6 +155,20 @@ interface McpHarnessOptions {
  *   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
  */
 export declare class McpHarness {
@@ -200,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>>;
@@ -238,9 +270,9 @@ interface McpProbeResult {
  *
  * @remarks
  * Stdin stays open until the id-1 response has arrived. Closing it right
- * after writing, as every hand-rolled smoke test did, 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.
@@ -253,6 +285,20 @@ interface McpProbeResult {
  * - 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
  */
 export declare class McpProbe {
@@ -266,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.
  *
@@ -282,8 +342,26 @@ 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
+ * 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
  */
@@ -323,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();
@@ -349,7 +443,7 @@ interface McpToolAuditPolicy {
   readonly requireOutputSchema?: boolean | undefined;
   /**
    * A served `outputSchema` must be rooted at `type: "object"`. Defaults to
-   * `true` (D10). Only the stateless revision serves a non-object root, so
+   * `true`. Only the stateless revision serves a non-object root, so
    * only there does this fire; a union root (`anyOf` or `oneOf`) names
    * `ToolOutputSchema.objectRooted` as the fix for a union whose members are
    * all objects (a union with a primitive member needs an object envelope
@@ -396,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