@effected/mcp 0.1.0 → 0.2.0

package/McpGuard.js

@@ -0,0 +1,121 @@
+//#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
+* stdio wiring only after the guards are listening, so a throw while any of
+* it evaluates is still reported on stderr.
+*
+* - "Connected" means the whole server layer has built, so stdin is being
+*   read. That is before any client sends `initialize`.
+* - `injectCrash` drives either half of the policy from a test, before
+*   `load()` or once connected; unset, it does nothing.
+* - A `load()` that rejects is reported as `startup failed` and exits 1
+*   whatever the policy. Left to a log-only rejection listener, it would
+*   let the event loop drain and exit 0 with no server.
+* - Installing an `unhandledRejection` listener switches off Node's default
+*   of throwing on one, so `"log"` really does keep the process running.
+* - An exit from a guard skips Effect's finalizers and the teardown.
+* - Keeping on serving after a crash works because the platform `runMain`
+*   holds the process open while the server fiber lives.
+* - A layer that fails to build is still reported by `McpStdio.launch`.
+*
+* @example
+* ```ts
+* import { McpGuard } from "@effected/mcp/guard";
+*
+* await McpGuard.run({
+*   label: "my-server",
+*   host: process,
+*   policy: { onUncaught: "exitBeforeConnect", onRejection: "log" },
+*   load: async () => {
+*     const { NodeRuntime } = await import("@effect/platform-node");
+*     const { Main } = await import("./server.js");
+*     return { layer: Main, runMain: NodeRuntime.runMain };
+*   },
+* });
+* ```
+*
+* @public
+*/
+var McpGuard = class {
+	constructor() {}
+	/** 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 {
+			const server = await options.load();
+			if (server.format !== void 0) format = 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);
+		}
+	};
+};
+
+//#endregion
+export { McpGuard };

package/McpHarness.js

@@ -39,8 +39,10 @@ import { McpProtocol } from "effect/unstable/ai";
 *   the wire. Assert it empty.
 * - On a stateful revision (the default `2025-11-25`), send `initialize`
 *   first. Every other request before it fails with `NotInitialized` and
-*   is never written: the server would only answer an opaque
-*   `Invalid request metadata`, `ping` included.
+*   is never written, `ping` included: 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.
 *
 * @public
 */
@@ -49,6 +51,22 @@ var McpHarness = class McpHarness {
 	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. */
@@ -69,6 +87,8 @@ var McpHarness = class McpHarness {
 	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. */
@@ -78,6 +98,7 @@ var McpHarness = class McpHarness {
 	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;
@@ -88,6 +109,7 @@ var McpHarness = class McpHarness {
 		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;
@@ -162,9 +184,13 @@ var McpHarness = class McpHarness {
 		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(() => {
-			if (isJsonRpcMessage(message) && message.method === "initialize") initializeSent = true;
-			return Effect.asVoid(Queue.offer(stdin, encoder.encode(`${JSON.stringify(message)}\n`)));
+			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") return yield* new McpTestFailure({
@@ -188,6 +214,14 @@ var McpHarness = class McpHarness {
 			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))}`
@@ -210,6 +244,7 @@ var McpHarness = class McpHarness {
 		return new McpHarness({
 			protocol,
 			initialize,
+			initializeWith,
 			discover,
 			request,
 			startRequest,
@@ -223,6 +258,7 @@ var McpHarness = class McpHarness {
 			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))

package/McpStdio.js

@@ -96,8 +96,12 @@ var McpStdio = class McpStdio {
 	* one graph does that, and so does building or providing the second
 	* anywhere under the first one's `Effect.provide`: nested `Layer.build`
 	* and `Effect.provide` fork the ambient memo map rather than starting a
-	* new one. Isolate each server with its own `ManagedRuntime`,
-	* `Effect.provide(layer, { local: true })` or its own process.
+	* new one. The tool registry is shared the same way. Isolate each server
+	* by wrapping its whole bundle (its toolkit layers together with this
+	* layer) in `Layer.fresh`, or with its own `ManagedRuntime`,
+	* `Effect.provide(layer, { local: true })` or its own process. Never put
+	* the `Layer.fresh` boundary between a toolkit and this layer: the server
+	* would serve an empty registry.
 	*
 	* Code after a completed `Effect.provide` of a stdio server never runs:
 	* core's stdio protocol interrupts the fiber that built it when its stdin
@@ -124,8 +128,11 @@ var McpStdio = class McpStdio {
 	* `Effect.provideService` reaches, and Effect's default logger writes
 	* through `console.log` unless `LogToStderr` is set. For an MCP server
 	* that is stdout, which is the wire.
+	*
+	* `options.onReady` runs after the layer has built and before the launch
+	* waits forever, as {@link McpLaunchOptions.onReady} describes.
 	*/
-	static launch = (layer) => Layer.launch(layer).pipe(Effect.catchCause((cause) => Cause.hasInterruptsOnly(cause) ? Effect.failCause(cause) : Effect.logError(cause).pipe(Effect.andThen(Effect.fail(new LaunchFailed(Runtime.getErrorExitCode(Cause.squash(cause))))))), Effect.provideService(References.LogToStderr, true));
+	static launch = (layer, options = {}) => (options.onReady === void 0 ? Layer.launch(layer) : Effect.scoped(Layer.build(layer).pipe(Effect.andThen(options.onReady), Effect.andThen(Effect.never)))).pipe(Effect.catchCause((cause) => Cause.hasInterruptsOnly(cause) ? Effect.failCause(cause) : Effect.logError(cause).pipe(Effect.andThen(Effect.fail(new LaunchFailed(Runtime.getErrorExitCode(Cause.squash(cause))))))), Effect.provideService(References.LogToStderr, true));
 	/**
 	* Success or an interrupt-only exit maps to 0. Anything else goes to
 	* `Runtime.defaultTeardown`.

package/McpTestFailure.js

@@ -20,8 +20,9 @@ import { Schema } from "effect";
 *   because stdin closed while the request was in flight.
 * - `NotInitialized` (`McpHarness`): a request other than `initialize` was
 *   made on a stateful revision before `initialize` was sent. The request
-*   is never written; the server would only have refused it with an opaque
-*   `Invalid request metadata`.
+*   is never written; the server would only have refused it opaquely:
+*   `-32602 Invalid request metadata` when a stateless adapter is listed
+*   first, `-32603 Internal error` when only stateful revisions are served.
 * - `ErrorResponse` (`McpHarness.listTools`): the server answered with a
 *   JSON-RPC error where a result was required. Every other request method
 *   returns the whole response, error included, as data.

package/McpToolAudit.js

@@ -88,8 +88,11 @@ var McpToolAudit = class {
 			}
 			const title = tool.title ?? tool.annotations?.title;
 			if (policy.requireTitle === true && (typeof title !== "string" || title === "")) report("no title");
-			if (policy.requireOutputSchema === true && tool.outputSchema === void 0) report("no outputSchema");
-			if ((policy.objectRootedOutput ?? true) && tool.outputSchema !== void 0 && tool.outputSchema.type !== "object") report(`outputSchema is not object-rooted (root type: ${String(tool.outputSchema.type ?? "none")})`);
+			if (policy.requireOutputSchema === true && tool.outputSchema === void 0) report("no outputSchema (a union success schema is dropped on stateful revisions; see ToolOutputSchema.objectRooted)");
+			if ((policy.objectRootedOutput ?? true) && tool.outputSchema !== void 0 && tool.outputSchema.type !== "object") {
+				const union = Array.isArray(tool.outputSchema.anyOf) || Array.isArray(tool.outputSchema.oneOf);
+				report(`outputSchema is not object-rooted (root type: ${String(tool.outputSchema.type ?? "none")})${union ? "; if every union member is an object, wrap the union success schema in ToolOutputSchema.objectRooted" : ""}`);
+			}
 			const length = (tool.description ?? "").length;
 			if (policy.maxDescription !== void 0 && length > policy.maxDescription) report(`description is ${length} characters, over the ${policy.maxDescription} limit`);
 			if (policy.requireHints === true) {

package/McpToolkit.js

@@ -1,8 +1,66 @@
 import { ToolInputSchema } from "./ToolInputSchema.js";
-import { Context, Effect, Layer } from "effect";
+import { Context, Effect, Layer, Schema } from "effect";
 import { McpSchema, McpServer, Tool, Toolkit } from "effect/unstable/ai";
 
 //#region src/McpToolkit.ts
+/** The union a {@link McpToolkit.unionTool} decodes with; read by the `McpToolkit.layer` decorator. */
+const UnionParameters = Context.Reference("@effected/mcp/UnionParameters", { defaultValue: () => void 0 });
+/**
+* Effect's strict JSON Schema document for `parameters`, definitions attached
+* as `$defs`, then object-rooted: the served input schema of a union tool.
+*/
+const unionInputJsonSchema = (parameters) => {
+	const document = Schema.toJsonSchemaDocument(parameters, { onExcessProperty: "error" });
+	return ToolInputSchema.objectRooted(Object.keys(document.definitions).length === 0 ? document.schema : {
+		...document.schema,
+		$defs: document.definitions
+	});
+};
+const invalidParameters = (name, message) => new McpSchema.InvalidParams({ message: `Invalid parameters for tool '${name}': ${message}` });
+/** The rendering both union paths use when the caller names none: `ToolInputSchema.formatUnknownKeys`. */
+const defaultUnknownKeyMessage = (levels) => ToolInputSchema.formatUnknownKeys(levels);
+/**
+* The one decode a union tool's payload gets, shared by the `McpToolkit.layer`
+* decorator and {@link McpToolkit.unionHandler}: every unknown key at every
+* depth named in one `InvalidParams` (walked over the served `inputSchema`),
+* then the union's strict decode, whose failure is worded as core words a
+* `Tool.make` one. Suspended, so a throwing `format` dies inside the call.
+*/
+const decodeUnionPayload = (name, union, inputSchema, format) => {
+	const decode = Schema.decodeUnknownEffect(union);
+	return (payload) => Effect.suspend(() => {
+		const raw = payload ?? {};
+		const levels = ToolInputSchema.unknownKeys(raw, inputSchema);
+		if (levels.length > 0) return Effect.fail(new McpSchema.InvalidParams({ message: format(levels) }));
+		return decode(raw, { onExcessProperty: "error" }).pipe(Effect.mapError((error) => invalidParameters(name, error.message)));
+	});
+};
+/**
+* The registration `McpToolkit.layer` hands core in place of `registration`:
+* a union tool gets its payload decoded first, a strict tool its unknown keys
+* refused first, and anything else passes through untouched. The wrapped
+* handler is built only after the check passes, so a rejected payload never
+* reaches it.
+*
+* @internal
+*/
+const guardRegistration = (registration, format) => {
+	const union = Context.get(registration.annotations, UnionParameters);
+	if (union !== void 0) {
+		const check = decodeUnionPayload(registration.tool.name, union, registration.tool.inputSchema, format);
+		return {
+			...registration,
+			handle: (payload) => check(payload).pipe(Effect.flatMap(() => registration.handle(payload)))
+		};
+	}
+	return Context.get(registration.annotations, Tool.Strict) === true ? {
+		...registration,
+		handle: (payload) => Effect.suspend(() => {
+			const levels = ToolInputSchema.unknownKeys(payload ?? {}, registration.tool.inputSchema);
+			return levels.length > 0 ? Effect.fail(new McpSchema.InvalidParams({ message: format(levels) })) : registration.handle(payload);
+		})
+	} : registration;
+};
 const DEFAULT_STRICT = "all";
 const strictened = (toolkit, mode) => mode === "annotated" ? toolkit : Toolkit.make(...Object.values(toolkit.tools).map((tool) => Tool.isDynamic(tool) || Tool.getStrictMode(tool) !== void 0 ? tool : tool.annotate(Tool.Strict, true)));
 /**
@@ -37,6 +95,8 @@ const strictened = (toolkit, mode) => mode === "annotated" ? toolkit : Toolkit.m
 * shared by reference with `McpStdio.layer`'s own copy — provide both into
 * the same graph, as with `McpServer.toolkit`. Never wrap that layer in
 * `Layer.fresh`: tools would register into a second registry nobody serves.
+* To give two servers separate registries, wrap each whole bundle (this
+* layer together with `McpStdio.layer`) in `Layer.fresh` instead.
 *
 * Each call mints a fresh layer; bind the result to a `const` or the
 * registration runs twice.
@@ -55,25 +115,84 @@ const strictened = (toolkit, mode) => mode === "annotated" ? toolkit : Toolkit.m
 var McpToolkit = class {
 	constructor() {}
 	/**
+	* A tool whose parameters are a `Schema.Union` of objects, which
+	* `Tool.make` cannot take: core dies at registration on a non-object
+	* `parameters` root.
+	*
+	* @remarks
+	* The tool is a `Tool.dynamic` served with Effect's strict JSON Schema
+	* document for `parameters` (`additionalProperties: false` on every
+	* object node, definitions as `$defs`), rewritten by
+	* `ToolInputSchema.objectRooted` to an object root carrying `type`,
+	* `oneOf` and `x-discriminator`. Write its handler with
+	* {@link McpToolkit.unionHandler}, which receives the decoded member.
+	*
+	* Registered through {@link McpToolkit.layer}, a union tool gets the same
+	* treatment as a strict `Tool.make` tool: every unknown key named in one
+	* `InvalidParams`, then a strict decode, both before the handler runs, so
+	* bad arguments answer JSON-RPC `-32602` on `2025-06-18` and an `isError`
+	* result on the later revisions, exactly as a `Tool.make` decode failure
+	* does. Registered through core's `McpServer.toolkit` it still decodes
+	* strictly, in the handler, but the `InvalidParams` is then a declared
+	* failure: an `isError` result on every revision.
+	*
+	* Never annotate it `Tool.Strict` true: core dies at registration on a
+	* strict tool with a raw JSON Schema.
+	*
+	* @example
+	* ```ts
+	* const Note = McpToolkit.unionTool("note", {
+	*   parameters: Schema.Union([AddNote, ListNotes]),
+	*   success: ToolOutputSchema.objectRooted(Schema.Union([Added, Listed])),
+	*   failure: ToolRefusal,
+	* }).annotate(Tool.Title, "Note")
+	* const handlers = Kit.toLayer({ note: McpToolkit.unionHandler(Note, (params) => handleNote(params)) })
+	* ```
+	*/
+	static unionTool = (name, options) => {
+		const tool = Tool.dynamic(name, {
+			description: options.description,
+			parameters: unionInputJsonSchema(options.parameters),
+			success: options.success ?? Schema.Void,
+			failure: Schema.Union([options.failure ?? Schema.Never, McpSchema.InvalidParams])
+		}).annotate(UnionParameters, options.parameters);
+		return Object.assign(tool, { unionParameters: options.parameters });
+	};
+	/**
+	* The handler for a {@link McpToolkit.unionTool}: checks and decodes the
+	* raw payload exactly as {@link McpToolkit.layer} does, and passes the
+	* decoded member to `handler`.
+	*
+	* @remarks
+	* A payload carrying unknown keys fails with one `McpSchema.InvalidParams`
+	* naming every one of them, at every depth, in the
+	* `ToolInputSchema.formatUnknownKeys` report (or `options.unknownKeyMessage`'s),
+	* walked over the tool's served input schema. A payload that then does
+	* not decode fails `InvalidParams` worded as core words a `Tool.make`
+	* decode failure. It is the same implementation the layer runs, so a
+	* handler called directly (a test helper, or a toolkit registered through
+	* core's `McpServer.toolkit`) reports what a client of the layer sees.
+	* Under {@link McpToolkit.layer} the layer has already rejected a bad
+	* call before the handler runs, and its own `unknownKeyMessage` wins.
+	*/
+	static unionHandler = (tool, handler, options = {}) => {
+		const check = decodeUnionPayload(tool.name, tool.unionParameters, tool.jsonSchema, options.unknownKeyMessage ?? defaultUnknownKeyMessage);
+		return (payload) => check(payload).pipe(Effect.flatMap(handler));
+	};
+	/**
 	* `McpServer.toolkit`'s registration layer, strict by default and naming
 	* every unknown argument in one `InvalidParams`.
 	*/
 	static layer = (toolkit, options = {}) => Layer.effectDiscard(Effect.gen(function* () {
 		const registry = yield* McpServer.McpServer;
-		const format = options.unknownKeyMessage ?? ((levels) => ToolInputSchema.formatUnknownKeys(levels));
+		const format = options.unknownKeyMessage ?? defaultUnknownKeyMessage;
 		const decorated = McpServer.McpServer.of({
 			...registry,
-			addTool: (registration) => Context.get(registration.annotations, Tool.Strict) === true ? registry.addTool({
-				...registration,
-				handle: (payload) => Effect.suspend(() => {
-					const levels = ToolInputSchema.unknownKeys(payload ?? {}, registration.tool.inputSchema);
-					return levels.length > 0 ? Effect.fail(new McpSchema.InvalidParams({ message: format(levels) })) : registration.handle(payload);
-				})
-			}) : registry.addTool(registration)
+			addTool: (registration) => registry.addTool(guardRegistration(registration, format))
 		});
 		yield* McpServer.registerToolkit(strictened(toolkit, options.strict ?? DEFAULT_STRICT)).pipe(Effect.provideService(McpServer.McpServer, decorated));
 	})).pipe(Layer.provide(McpServer.McpServer.layer));
 };
 
 //#endregion
-export { McpToolkit };
+export { McpToolkit, guardRegistration };

package/README.md

@@ -87,6 +87,31 @@ console.log(ToolFailure.truncate(enginePath, ToolFailure.ENGINE_ECHO_LIMIT) ===
 
 `ToolFailure` is a static-namespace class with a private constructor — it is never instantiated.
 
+### ToolRefusal
+
+For a refusal with no fields of its own, `ToolRefusal` is that shape ready-made: a `Schema.TaggedError` on `ToolFailure.fields`, built with `ToolRefusal.refuse(reason, remediation)`, which folds the remediation into `message`. Declare it in the tool's `failure` schema:
+
+```ts
+import { ToolFailure, ToolRefusal } from "@effected/mcp";
+import { Effect, Schema } from "effect";
+import { Tool } from "effect/unstable/ai";
+
+const GetRun = Tool.make("get_run", {
+  parameters: Schema.Struct({ id: Schema.String }),
+  success: Schema.Struct({ status: Schema.String }),
+  failure: ToolRefusal,
+});
+
+const refusal = ToolRefusal.refuse(`No run "${ToolFailure.truncate("r9")}".`, {
+  hint: "List the runs first.",
+  suggestedTool: "list_runs",
+});
+console.log(refusal.message);
+// => No run "r9". List the runs first. Try list_runs.
+```
+
+**Audit every throw path when you port a tool.** Core scrubs an undeclared failure, and every defect, to `Tool execution failed due to an internal server error.` The message you wrote never reaches the agent, and nothing warns you. Any failure the agent should act on must be declared in the tool's `failure` schema, as a `ToolRefusal` or your own `ToolFailure`-shaped error.
+
 ## Putting it together
 
 A stdio server's `main.ts` is one line, plus the layer that wires it:
@@ -156,8 +181,8 @@ below.
 `McpStdio.layer` is core's `McpServer.layerStdio` with every log line sent to
 stderr, and with stdin read through a guard. Core's own stdio decoder throws on
 a line that is not JSON without ever trimming it from its buffer, so one bad
-line wedges the server: every later request goes unanswered while stdin EOF
-still exits 0. The guard frames stdin exactly as core does — one streaming
+line wedges the server: every later request goes unanswered, yet the process
+still ends at stdin EOF exactly as a healthy session does. The guard frames stdin exactly as core does — one streaming
 UTF-8 decoder, a byte-order mark stripped only at the start of the stream,
 lines split on `\n` — and answers each line core would choke on itself, on
 stdout:
@@ -188,9 +213,51 @@ first one's memo map shares its protocol: only the first server reads stdin,
 and the second never answers. Merging both into one graph does that, and so
 does building or providing the second anywhere under the first one's
 `Effect.provide` — a nested `Layer.build` or `Effect.provide` forks the
-ambient memo map rather than starting a new one. Isolate each server with its
-own `ManagedRuntime`, `Effect.provide(layer, { local: true })`, or its own
-process.
+ambient memo map rather than starting a new one. The tool registry is shared
+the same way. Isolate each server by wrapping its whole bundle (its toolkit
+layers together with `McpStdio.layer`) in `Layer.fresh`, or give it its own
+`ManagedRuntime`, `Effect.provide(layer, { local: true })`, or its own
+process. Never put the `Layer.fresh` boundary between a toolkit and
+`McpStdio.layer`: the server would serve an empty registry.
+
+## Crash guards
+
+A stray `uncaughtException` or `unhandledRejection` in a stdio server either kills it silently or, worse, happens while its modules are still loading, before anything is listening. `@effected/mcp/guard` installs the listeners first. The entrypoint has no static runtime import, so the guards are in place before `effect` or your server graph is evaluated:
+
+```ts
+import { McpGuard } from "@effected/mcp/guard";
+
+await McpGuard.run({
+  label: "my-server",
+  host: process,
+  policy: { onUncaught: "exitBeforeConnect", onRejection: "log" },
+  load: async () => {
+    const NodeRuntime = await import("@effect/platform-node/NodeRuntime");
+    const { Main } = await import("./server.js");
+    return { layer: Main, runMain: NodeRuntime.runMain };
+  },
+});
+```
+
+`McpGuard.run` registers both listeners on `host`, awaits `load()`, and launches the returned layer with `McpStdio.launch` and `McpStdio.teardown` under the returned `runMain`. Keep every import that could throw inside `load`, behind a dynamic `import()`.
+
+The policy decides when a stray exception or rejection ends the process. `"exit"` exits 1 whenever it happens. `"exitBeforeConnect"` exits 1 until the server is serving, then logs and keeps serving, because a server that dies mid-session takes every tool away from the client. `"log"` (rejections only) never exits. Both default to `"exit"`.
+
+Some behaviour worth knowing:
+
+- "Connected" means the whole server layer has built, so stdin is being read. That comes before any client sends `initialize`. `McpStdio.launch`'s `onReady` option is where the guard gets that signal.
+- A `load()` that rejects is reported as `startup failed` and exits 1, whatever the policy. Left to a log-only rejection listener it would let the event loop drain and exit 0 with no server running.
+- An `unhandledRejection` listener switches off Node's default of throwing on one, so `"log"` really does keep the process running.
+- A guard's exit skips Effect's finalizers and the teardown.
+- Carrying on after a crash works because the platform `runMain` holds the process open while the server fiber lives.
+- A layer that fails to build is still reported by `McpStdio.launch`, on stderr.
+
+To test the guards themselves, pass `injectCrash: { at, kind }`, with `kind` either `"uncaughtException"` or `"unhandledRejection"`. Wire it to an environment variable only your test sets; unset, it does nothing. The crash is raised through `host.emit` on a `setTimeout(0)` tick, so the guard's own listeners handle it identically under the real `process` and under a test double for `McpGuardHost` (which therefore needs `on`, `emit`, `stderr` and `exit`). If a double's `exit` throws at `"load"`, `run` rejects with what it threw instead of waiting.
+
+- `at: "load"` raises it once both listeners are installed and before `load()` is called, and `load()` waits until the guard has handled it. The pre-connect half of the policy applies: `"exitBeforeConnect"` and `"exit"` both exit 1 here, and only `onRejection: "log"` lets the process go on to load and serve. The report uses the guard's own formatter, because no `format` is loaded yet.
+- `at: "connected"` raises it on a timer just after the server is serving, where `"exitBeforeConnect"` logs and keeps serving.
+
+Together they drive both halves of `"exitBeforeConnect"` in a real child process.
 
 ## Strict input
 
@@ -289,6 +356,59 @@ edit({ action: "rename", to: "b", extra: 1, options: { force: true, bogus: 2 } }
 => Unrecognized parameter(s): extra. Accepted params: action, to, options. Unrecognized parameter(s): options.bogus. Accepted params: force.
 ```
 
+## Union-parameter tools
+
+A tool whose parameters are a `Schema.Union` of objects cannot be a `Tool.make` tool: core dies at registration on a non-object `parameters` root. `McpToolkit.unionTool` makes it a `Tool.dynamic` served with Effect's strict JSON Schema document for the union (`additionalProperties: false` on every object node), object-rooted by `ToolInputSchema.objectRooted`. `McpToolkit.unionHandler` wraps a handler that receives the decoded member:
+
+```ts
+import { McpToolkit, ToolOutputSchema, ToolRefusal } from "@effected/mcp";
+import { Effect, Schema } from "effect";
+import { Tool, Toolkit } from "effect/unstable/ai";
+
+const AddNote = Schema.Struct({ action: Schema.Literal("add"), text: Schema.String });
+const ListNotes = Schema.Struct({ action: Schema.Literal("list"), limit: Schema.optionalKey(Schema.Number) });
+
+const Note = McpToolkit.unionTool("note", {
+  description: "Add or list notes.",
+  parameters: Schema.Union([AddNote, ListNotes]),
+  success: ToolOutputSchema.objectRooted(
+    Schema.Union([
+      Schema.Struct({ kind: Schema.Literal("added") }),
+      Schema.Struct({ kind: Schema.Literal("listed"), count: Schema.Number }),
+    ]),
+  ),
+  failure: ToolRefusal,
+}).annotate(Tool.Title, "Note");
+
+const Kit = Toolkit.make(Note);
+const Handlers = Kit.toLayer({
+  // `params` is AddNote | ListNotes, already decoded.
+  note: McpToolkit.unionHandler(Note, (params) =>
+    Effect.succeed(params.action === "add" ? { kind: "added" as const } : { kind: "listed" as const, count: 0 }),
+  ),
+});
+```
+
+`annotate` and `addDependency` keep the union on the tool, so a chained `.annotate(Tool.Title, …)` still hands `unionHandler` the decoded type.
+
+Registered through `McpToolkit.layer`, a union tool is checked like a strict `Tool.make` tool: every unknown key at every depth is named in one `InvalidParams`, then the union is decoded strictly, both before the handler runs. Bad arguments therefore answer as a `Tool.make` decode failure does: a JSON-RPC `-32602` on `2025-06-18`, an `isError` result on the later revisions. Registered through core's `McpServer.toolkit` instead, or called directly (a test helper, say), `unionHandler` runs the same check itself, so the message is identical: every unknown key named per level in the `ToolInputSchema.formatUnknownKeys` report, then core's `Tool.make` wording for a bad value. Under `McpServer.toolkit` that `InvalidParams` is a declared failure, an `isError` result on every revision. A custom rendering goes in `unionHandler`'s third argument, `{ unknownKeyMessage }`, as it does in `McpToolkit.layer`'s options: pass the same function to both. Never annotate a union tool `Tool.Strict` true: core dies at registration on a strict tool with a raw JSON Schema.
+
+## Union success schemas
+
+MCP requires a tool's `outputSchema` to be rooted in an object, and a top-level `Schema.Union` emits a bare `anyOf`. Core drops such an `outputSchema` from `tools/list` on the stateful revisions, and serves it verbatim on the stateless one, where strict clients reject it. When every member of the union is an object shape, `ToolOutputSchema.objectRooted` adds `type: "object"` beside the `anyOf` through a check that always passes, so decoding and the schema's type stay the same:
+
+```ts
+import { ToolOutputSchema } from "@effected/mcp";
+import { Schema } from "effect";
+
+const Found = Schema.Struct({ kind: Schema.Literal("found"), id: Schema.String });
+const Missing = Schema.Struct({ kind: Schema.Literal("missing"), reason: Schema.String });
+
+const Result = ToolOutputSchema.objectRooted(Schema.Union([Found, Missing])).annotate({ identifier: "Result" });
+```
+
+It can go before or after `.annotate({ identifier })`: the identifier the schema already carries moves onto the new check, so the served documents are equal either way. Every union member must be an object shape: do not use it on a union with a primitive or array member, because the added `type: "object"` is a claim about the whole union that nothing checks, and the served schema would then contradict what the tool returns — give that tool an object envelope instead. `McpToolAudit`'s `objectRootedOutput` check names this helper when it finds a union root.
+
 ## Testing
 
 `@effected/mcp/testing` is a separate entrypoint — importing it never pulls
@@ -314,7 +434,7 @@ const test = Effect.gen(function* () {
 On a stateful revision (the default is `2025-11-25`), `initialize` comes
 first: any other request sent before it fails fast with `McpTestFailure`
 reason `NotInitialized` instead of the server's opaque `Invalid request
-metadata`.
+metadata`. `client.initializeWith("2025-06-18")` asks for a different stateful revision than the harness speaks and returns the whole response, so a test can assert the negotiated `protocolVersion`. A stateful server never refuses a version: an unknown one, or the stateless `2026-07-28`, is counter-offered `2025-11-25`. On a harness made with the stateless revision, `initialize` itself is not served, and the response is a JSON-RPC `-32601` error with no `notifications/initialized` sent after it. `client.sentSoFar` holds every frame the harness has written, in order.
 
 `McpHarness.make` runs the server in-process over queue-backed `Stdio`, so
 a test sees the exact served schemas and wire results a real client would,

package/ToolFailure.js

@@ -16,7 +16,13 @@ const isHighSurrogate = (code) => code >= 55296 && code <= 56319;
 *
 * Spread {@link ToolFailure.fields} into your tool's `Schema.TaggedError`, build
 * `message` with {@link ToolFailure.message}, and pass every caller-supplied
-* value through {@link ToolFailure.truncate} before echoing it.
+* value through {@link ToolFailure.truncate} before echoing it. For a plain
+* refusal with no fields of its own, `ToolRefusal` is this shape ready-made.
+*
+* Only a declared failure keeps its message: core scrubs an undeclared
+* failure or a defect to "Tool execution failed due to an internal server
+* error.", so audit every throw path a tool can take and declare each one the
+* agent should read.
 *
 * @example
 * ```ts