@effected/mcp 0.1.1 → 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

@@ -51,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. */
@@ -71,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. */
@@ -80,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;
@@ -90,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;
@@ -164,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({
@@ -190,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))}`
@@ -212,6 +244,7 @@ var McpHarness = class McpHarness {
 		return new McpHarness({
 			protocol,
 			initialize,
+			initializeWith,
 			discover,
 			request,
 			startRequest,
@@ -225,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/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:
@@ -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

package/ToolOutputSchema.js

@@ -0,0 +1,66 @@
+import { Schema, SchemaAST } from "effect";
+
+//#region src/ToolOutputSchema.ts
+const MARK = "~effected/mcp/objectRooted";
+/** Always passes; contributes `type: "object"` beside whatever the node already emits. */
+const objectRoot = Schema.makeFilter(() => true, {
+	[MARK]: true,
+	toJsonSchema: () => ({ type: "object" })
+});
+const isObjectRooted = (ast) => ast.checks?.some((check) => check.annotations?.[MARK] === true) === true;
+/**
+* Shaping for a tool's `success` schema, so the `outputSchema` core serves
+* is one every client accepts.
+*
+* @remarks
+* 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.
+* `McpToolAudit`'s `objectRootedOutput` check reports it either way.
+*
+* {@link ToolOutputSchema.objectRooted} is the fix when every member of the
+* union is an object shape; never apply it to a union with a primitive or
+* array member. It works on the Effect
+* schema, not on JSON Schema — unlike `ToolInputSchema.objectRooted`, which
+* rewrites the served input document of a `Tool.dynamic`.
+*
+* @public
+*/
+var ToolOutputSchema = class {
+	constructor() {}
+	/**
+	* `schema` with `type: "object"` added beside the `anyOf` at its JSON
+	* Schema root, through a check that always passes. Decoding, encoding and
+	* the schema's type are unchanged.
+	*
+	* @remarks
+	* Order against `.annotate({ identifier })` does not matter. A check added
+	* after an identifier starts a new node that would drop the definition
+	* name, so the identifier the schema already resolves is carried onto the
+	* new check, and the served documents are equal either way (key order
+	* can differ when the schema carries a title or description). Applying it
+	* twice is a no-op.
+	*
+	* Every union member must be an object shape: the added `type: "object"`
+	* is a claim about the whole union, and nothing checks it. Do not use it
+	* on a union with a primitive or array member — the served schema would
+	* contradict the values the tool returns; give such a tool an object
+	* envelope instead.
+	*
+	* @example
+	* ```ts
+	* const Result = ToolOutputSchema.objectRooted(Schema.Union([Found, Missing])).annotate({ identifier: "Result" })
+	* Tool.make("lookup", { parameters, success: Result })
+	* ```
+	*/
+	static objectRooted = (schema) => {
+		if (isObjectRooted(schema.ast)) return schema;
+		const identifier = SchemaAST.resolveIdentifier(schema.ast);
+		const checked = schema.check(objectRoot);
+		return identifier === void 0 ? checked : checked.annotate({ identifier });
+	};
+};
+
+//#endregion
+export { ToolOutputSchema };

package/ToolRefusal.js

@@ -0,0 +1,42 @@
+import { ToolFailure } from "./ToolFailure.js";
+import { Schema } from "effect";
+
+//#region src/ToolRefusal.ts
+/**
+* A tool call refused for a reason the caller can fix: the kit's ready-made
+* declared failure, built on {@link ToolFailure.fields}.
+*
+* @remarks
+* Core scrubs every undeclared failure and every defect to one generic
+* internal-error sentence, so a refusal the agent must act on (an unknown id,
+* a missing argument, a precondition) reaches it only when the tool declares
+* it. Declare `ToolRefusal` in the tool's `failure` schema and fail with
+* {@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.
+*
+* @example
+* ```ts
+* 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" })
+* ```
+*
+* @public
+*/
+var ToolRefusal = class ToolRefusal extends Schema.TaggedError()("ToolRefusal", ToolFailure.fields) {
+	/**
+	* A refusal for `reason`, with `remediation` folded into its message by
+	* {@link ToolFailure.message}. `reason` must already truncate any
+	* caller-supplied value it echoes, with {@link ToolFailure.truncate}.
+	*/
+	static refuse = (reason, remediation) => new ToolRefusal({
+		message: ToolFailure.message(reason, remediation),
+		remediation
+	});
+};
+
+//#endregion
+export { ToolRefusal };

package/guard.d.ts

@@ -0,0 +1,157 @@
+import { Effect, Layer, Runtime } from "effect";
+//#region src/McpGuard.d.ts
+/**
+ * The slice of the host process the guard uses. Node's `process` satisfies it.
+ *
+ * @public
+ */
+interface McpGuardHost {
+  /** Register the `uncaughtException` listener. */
+  on(event: "uncaughtException", listener: (error: Error, origin: string) => void): unknown;
+  /** Register the `unhandledRejection` listener. */
+  on(event: "unhandledRejection", listener: (reason: unknown) => void): unknown;
+  /** Raise an `uncaughtException` to the registered listeners. Used only by {@link McpGuardRunOptions.injectCrash}. */
+  emit(event: "uncaughtException", error: Error, origin: "uncaughtException" | "unhandledRejection"): unknown;
+  /** Raise an `unhandledRejection` to the registered listeners. Used only by {@link McpGuardRunOptions.injectCrash}. */
+  emit(event: "unhandledRejection", reason: unknown, promise: Promise<unknown>): unknown;
+  /** Where every guard report is written. Never stdout: that is the JSON-RPC wire. */
+  readonly stderr: {
+    write(chunk: string): unknown;
+  };
+  /** End the process at once. */
+  exit(code?: number): never;
+}
+/**
+ * When a stray exception or rejection ends the process.
+ *
+ * @remarks
+ * `"exit"` exits 1 whenever it happens. `"exitBeforeConnect"` exits 1 until
+ * the server is serving, then logs and keeps serving: a server that dies
+ * mid-session deregisters every tool from the client. `"log"` never exits.
+ *
+ * @public
+ */
+interface McpGuardPolicy {
+  /** For `uncaughtException`. */
+  readonly onUncaught: "exit" | "exitBeforeConnect";
+  /** For `unhandledRejection`. Defaults to `"exit"`. */
+  readonly onRejection?: "exit" | "exitBeforeConnect" | "log" | undefined;
+}
+/**
+ * What {@link McpGuardRunOptions.load} resolves to: the server and the
+ * platform runner to launch it with.
+ *
+ * @public
+ */
+interface McpGuardedServer<ROut, E> {
+  /** The whole server layer, stdio included, with nothing left to provide. */
+  readonly layer: Layer.Layer<ROut, E, never>;
+  /** The platform's `runMain`, such as `NodeRuntime.runMain` from `@effect/platform-node`. */
+  readonly runMain: (effect: Effect.Effect<never, Error>, options: {
+    readonly teardown: Runtime.Teardown;
+  }) => void;
+  /** Formats a reported error from here on; the guard's own dependency-free formatter until then. */
+  readonly format?: ((error: unknown) => string) | undefined;
+}
+/**
+ * Options for {@link McpGuard.run}.
+ *
+ * @public
+ */
+interface McpGuardRunOptions<ROut, E> {
+  /** Prefixes every report the guard writes, as in `my-server: uncaughtException (…): …`. */
+  readonly label: string;
+  /** The process: pass `process`. */
+  readonly host: McpGuardHost;
+  /** Defaults to `{ onUncaught: "exit", onRejection: "exit" }`. */
+  readonly policy?: McpGuardPolicy | undefined;
+  /**
+   * Import and assemble the server. Everything that can throw while loading
+   * belongs here, behind a dynamic `import()`, so the guards are already
+   * listening when it runs.
+   */
+  readonly load: () => Promise<McpGuardedServer<ROut, E>>;
+  /**
+   * For a test of the guards themselves: raise one stray `kind` at `at`, so
+   * both halves of a policy can be driven end to end in a real process.
+   *
+   * @remarks
+   * - `"load"` raises it once both listeners are installed and before
+   *   `load()` is called, then waits for the guard to handle it: `load()`
+   *   is not called until the listener has run. If a test double's `exit`
+   *   throws instead of ending the process, `run` rejects with what it
+   *   threw and never calls `load()`. The pre-connect half of
+   *   the policy applies, so `"exitBeforeConnect"` exits 1 here, and only
+   *   an `onRejection` of `"log"` lets the process go on to load and serve.
+   *   The report uses the guard's own formatter, since no `format` is
+   *   loaded yet.
+   * - `"connected"` raises it on a timer right after the server is
+   *   serving, where `"exitBeforeConnect"` logs and keeps serving. A throw
+   *   from a test double's `exit` there is dropped.
+   *
+   * 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
+   * `process`, every listener registered for the event sees it, not only
+   * the guard's. It carries an `[injected]` message; a rejection is emitted
+   * with an already-handled rejected promise. `undefined`, or
+   * an `at` or `kind` outside these values, does nothing at all. Wire it to
+   * an environment variable only a test sets.
+   */
+  readonly injectCrash?: {
+    readonly at: "load" | "connected";
+    readonly kind: "uncaughtException" | "unhandledRejection";
+  } | undefined;
+}
+/**
+ * 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
+ */
+export declare class McpGuard {
+  private constructor();
+  /** 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>;
+}
+//#endregion
+export type { McpGuardHost, McpGuardPolicy, McpGuardRunOptions, McpGuardedServer };
+//# sourceMappingURL=guard.d.ts.map

package/guard.js

@@ -0,0 +1,3 @@
+import { McpGuard } from "./McpGuard.js";
+
+export { McpGuard };

package/index.d.ts

@@ -1,4 +1,4 @@
-import { Array, Effect, JsonSchema, Layer, Runtime, Schema, Stdio } from "effect";
+import { Array, Context, Effect, JsonSchema, Layer, Runtime, Schema, Stdio } from "effect";
 import { McpProtocol, McpSchema, McpServer, Tool, Toolkit } from "effect/unstable/ai";
 import { Remediation } from "@effected/engine";
 //#region src/McpStdio.d.ts
@@ -19,6 +19,26 @@ interface McpStdioOptions {
   /** Defaults to {@link McpStdio.protocols}. Read its ordering rules before overriding. */
   readonly protocols?: Array.NonEmptyReadonlyArray<McpProtocol.ProtocolAdapter> | undefined;
 }
+/**
+ * Options for {@link McpStdio.launch}.
+ *
+ * @public
+ */
+interface McpLaunchOptions {
+  /**
+   * Runs once the whole layer has built, and before the launch waits
+   * forever. By then the stdio protocol is reading stdin: the server is
+   * serving, although no client may have sent `initialize` yet.
+   *
+   * @remarks
+   * `McpGuard.run` (`@effected/mcp/guard`) uses it as its "connected"
+   * signal. A layer built after the server layer, as in
+   * `Layer.effectDiscard(ready).pipe(Layer.provide(Main))`, gives the same
+   * signal, but only if every consumer re-derives that `Layer.provide`
+   * builds its dependency first.
+   */
+  readonly onReady?: Effect.Effect<void> | undefined;
+}
 /**
  * Serve an MCP server over stdio without ever writing a log line or a failure
  * report onto stdout, which is the JSON-RPC wire.
@@ -107,8 +127,12 @@ export declare 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
@@ -129,8 +153,11 @@ export declare 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 readonly launch: <ROut, E, R>(layer: Layer.Layer<ROut, E, R>) => Effect.Effect<never, Error, R>;
+  static readonly launch: <ROut, E, R>(layer: Layer.Layer<ROut, E, R>, options?: McpLaunchOptions) => Effect.Effect<never, Error, R>;
   /**
    * Success or an interrupt-only exit maps to 0. Anything else goes to
    * `Runtime.defaultTeardown`.
@@ -239,6 +266,61 @@ interface McpToolkitOptions {
    */
   readonly unknownKeyMessage?: ((levels: ReadonlyArray<UnknownKeysLevel>) => string) | undefined;
 }
+/**
+ * A `Tool.dynamic` made by {@link McpToolkit.unionTool}: served with the
+ * strict, object-rooted JSON Schema of a `Schema.Union` of objects, and
+ * carrying that union so {@link McpToolkit.unionHandler} can decode it.
+ *
+ * @remarks
+ * `annotate` and `addDependency` keep the type, so a chained
+ * `.annotate(Tool.Title, …)` still hands `unionHandler` the union. The
+ * declared failure is `failure` together with `McpSchema.InvalidParams`.
+ *
+ * @public
+ */
+interface UnionTool<Name extends string, P extends Schema.Decoder<unknown>, S extends Schema.Constraint, F extends Schema.Constraint, R = never> extends Tool.Dynamic<Name, {
+  readonly parameters: JsonSchema.JsonSchema;
+  readonly success: S;
+  readonly failure: Schema.Union<readonly [F, typeof McpSchema.InvalidParams]>;
+  readonly failureMode: "error";
+}, R> {
+  /** The union the tool decodes its arguments with. */
+  readonly unionParameters: P;
+  /** Add an annotation, keeping the union. */
+  annotate<I, V>(tag: Context.Key<I, V>, value: V): UnionTool<Name, P, S, F, R>;
+  /** Add a request-level dependency, keeping the union. */
+  addDependency<Identifier, Service>(tag: Context.Key<Identifier, Service>): UnionTool<Name, P, S, F, Identifier | R>;
+}
+/**
+ * Options for {@link McpToolkit.unionTool}.
+ *
+ * @public
+ */
+interface UnionToolOptions<P extends Schema.Decoder<unknown>, S extends Schema.Constraint, F extends Schema.Constraint, Dependencies extends ReadonlyArray<Context.Key<unknown, unknown>>> {
+  /** What the tool does, for the agent. */
+  readonly description?: string | undefined;
+  /** A `Schema.Union` of object schemas, discriminated by an `action`, `kind`, `_tag` or `type` literal. */
+  readonly parameters: P;
+  /** The success schema. Defaults to `Schema.Void`; object-root a union whose members are all objects with `ToolOutputSchema.objectRooted`. */
+  readonly success?: S | undefined;
+  /** Declared failures besides `InvalidParams`, such as `ToolRefusal`. Defaults to `Schema.Never`. */
+  readonly failure?: F | undefined;
+  /** Services the handler needs, as with `Tool.make`. */
+  readonly dependencies?: Dependencies | undefined;
+}
+/**
+ * Options for {@link McpToolkit.unionHandler}.
+ *
+ * @public
+ */
+interface UnionHandlerOptions {
+  /**
+   * Replaces the default `ToolInputSchema.formatUnknownKeys` rendering, as
+   * {@link McpToolkitOptions.unknownKeyMessage} does for the layer. Pass the
+   * same function to both for one report on every path.
+   */
+  readonly unknownKeyMessage?: ((levels: ReadonlyArray<UnknownKeysLevel>) => string) | undefined;
+}
 /**
  * Register a toolkit exactly as core's `McpServer.toolkit` does, except that a
  * strict tool's unknown arguments are all named, at every depth, in one
@@ -271,6 +353,8 @@ interface McpToolkitOptions {
  * 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.
@@ -288,6 +372,60 @@ interface McpToolkitOptions {
  */
 export declare class McpToolkit {
   private 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 readonly unionTool: <const Name extends string, P extends Schema.Decoder<unknown>, S extends Schema.Constraint = typeof Schema.Void, F extends Schema.Constraint = typeof Schema.Never, const Dependencies extends ReadonlyArray<Context.Key<unknown, unknown>> = []>(name: Name, options: UnionToolOptions<P, S, F, Dependencies>) => UnionTool<Name, P, S, F, Context.Service.Identifier<Dependencies[number]>>;
+  /**
+   * 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 readonly unionHandler: <Name extends string, P extends Schema.Decoder<unknown>, S extends Schema.Constraint, F extends Schema.Constraint, R, A, E, RH>(tool: UnionTool<Name, P, S, F, R>, handler: (params: P["Type"]) => Effect.Effect<A, E, RH>, options?: UnionHandlerOptions) => ((payload: unknown) => Effect.Effect<A, E | McpSchema.InvalidParams, RH>);
   /**
    * `McpServer.toolkit`'s registration layer, strict by default and naming
    * every unknown argument in one `InvalidParams`.
@@ -309,7 +447,13 @@ export declare class McpToolkit {
  *
  * 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
@@ -348,5 +492,97 @@ export declare class ToolFailure {
   static readonly truncate: (value: string, limit?: number) => string;
 }
 //#endregion
-export type { FormatUnknownKeysOptions, McpStdioOptions, McpToolkitOptions, UnknownKeysLevel };
+//#region src/ToolOutputSchema.d.ts
+/**
+ * Shaping for a tool's `success` schema, so the `outputSchema` core serves
+ * is one every client accepts.
+ *
+ * @remarks
+ * 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.
+ * `McpToolAudit`'s `objectRootedOutput` check reports it either way.
+ *
+ * {@link ToolOutputSchema.objectRooted} is the fix when every member of the
+ * union is an object shape; never apply it to a union with a primitive or
+ * array member. It works on the Effect
+ * schema, not on JSON Schema — unlike `ToolInputSchema.objectRooted`, which
+ * rewrites the served input document of a `Tool.dynamic`.
+ *
+ * @public
+ */
+export declare class ToolOutputSchema {
+  private constructor();
+  /**
+   * `schema` with `type: "object"` added beside the `anyOf` at its JSON
+   * Schema root, through a check that always passes. Decoding, encoding and
+   * the schema's type are unchanged.
+   *
+   * @remarks
+   * Order against `.annotate({ identifier })` does not matter. A check added
+   * after an identifier starts a new node that would drop the definition
+   * name, so the identifier the schema already resolves is carried onto the
+   * new check, and the served documents are equal either way (key order
+   * can differ when the schema carries a title or description). Applying it
+   * twice is a no-op.
+   *
+   * Every union member must be an object shape: the added `type: "object"`
+   * is a claim about the whole union, and nothing checks it. Do not use it
+   * on a union with a primitive or array member — the served schema would
+   * contradict the values the tool returns; give such a tool an object
+   * envelope instead.
+   *
+   * @example
+   * ```ts
+   * const Result = ToolOutputSchema.objectRooted(Schema.Union([Found, Missing])).annotate({ identifier: "Result" })
+   * Tool.make("lookup", { parameters, success: Result })
+   * ```
+   */
+  static readonly objectRooted: <S extends Schema.Top>(schema: S) => S;
+}
+//#endregion
+//#region src/ToolRefusal.d.ts
+declare const ToolRefusal_base: Schema.Class<ToolRefusal, Schema.TaggedStruct<"ToolRefusal", {
+  readonly message: Schema.String;
+  readonly remediation: Schema.Struct<{
+    readonly hint: Schema.String;
+    readonly suggestedTool: Schema.optionalKey<Schema.String>;
+    readonly suggestedArgs: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
+  }>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A tool call refused for a reason the caller can fix: the kit's ready-made
+ * declared failure, built on {@link ToolFailure.fields}.
+ *
+ * @remarks
+ * Core scrubs every undeclared failure and every defect to one generic
+ * internal-error sentence, so a refusal the agent must act on (an unknown id,
+ * a missing argument, a precondition) reaches it only when the tool declares
+ * it. Declare `ToolRefusal` in the tool's `failure` schema and fail with
+ * {@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.
+ *
+ * @example
+ * ```ts
+ * 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" })
+ * ```
+ *
+ * @public
+ */
+export declare class ToolRefusal extends ToolRefusal_base {
+  /**
+   * A refusal for `reason`, with `remediation` folded into its message by
+   * {@link ToolFailure.message}. `reason` must already truncate any
+   * caller-supplied value it echoes, with {@link ToolFailure.truncate}.
+   */
+  static readonly refuse: (reason: string, remediation: Remediation) => ToolRefusal;
+}
+//#endregion
+export type { FormatUnknownKeysOptions, McpLaunchOptions, McpStdioOptions, McpToolkitOptions, UnionHandlerOptions, UnionTool, UnionToolOptions, UnknownKeysLevel };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -2,5 +2,7 @@ import { McpStdio } from "./McpStdio.js";
 import { ToolFailure } from "./ToolFailure.js";
 import { ToolInputSchema } from "./ToolInputSchema.js";
 import { McpToolkit } from "./McpToolkit.js";
+import { ToolOutputSchema } from "./ToolOutputSchema.js";
+import { ToolRefusal } from "./ToolRefusal.js";
 
-export { McpStdio, McpToolkit, ToolFailure, ToolInputSchema };
+export { McpStdio, McpToolkit, ToolFailure, ToolInputSchema, ToolOutputSchema, ToolRefusal };

package/internal/guardLaunch.js

@@ -0,0 +1,14 @@
+import { McpStdio } from "../McpStdio.js";
+import { Effect } from "effect";
+
+//#region src/internal/guardLaunch.ts
+/**
+* The server half of `McpGuard.run`, reached only through a dynamic import so
+* the guard module itself evaluates nothing but its own code.
+*
+* @internal
+*/
+const launchGuarded = (server, onReady) => server.runMain(McpStdio.launch(server.layer, { onReady: Effect.sync(onReady) }), { teardown: McpStdio.teardown });
+
+//#endregion
+export { launchGuarded };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/mcp",
-	"version": "0.1.1",
+	"version": "0.2.0",
 	"private": false,
 	"description": "The boundary layer of an effect/unstable/ai MCP server: stdio wiring that keeps stdout the wire, tool-failure shaping, strict-input walkers, and test clients",
 	"keywords": [
@@ -34,6 +34,11 @@
 			"import": "./index.js",
 			"default": "./index.js"
 		},
+		"./guard": {
+			"types": "./guard.d.ts",
+			"import": "./guard.js",
+			"default": "./guard.js"
+		},
 		"./testing": {
 			"types": "./testing.d.ts",
 			"import": "./testing.js",

package/testing.d.ts

@@ -153,6 +153,22 @@ export declare class McpHarness {
   readonly protocol: McpProtocol.ProtocolAdapter;
   /** `initialize` then `notifications/initialized`; `server/discover` on a stateless revision. Call it first on a stateful revision. */
   readonly initialize: Effect.Effect<JsonRpcMessage, McpTestFailure>;
+  /**
+   * `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.
+   */
+  readonly initializeWith: (protocolVersion: string) => Effect.Effect<JsonRpcMessage, McpTestFailure>;
   /** `server/discover`. */
   readonly discover: Effect.Effect<JsonRpcMessage, McpTestFailure>;
   /** Send a request and wait for its response. */
@@ -176,6 +192,8 @@ export declare class McpHarness {
   readonly sendRaw: (message: unknown) => Effect.Effect<void>;
   /** The next server-initiated frame with this method, skipping and keeping others; fails with `ServerStopped` once the server stops. */
   readonly awaitOutboundMethod: (method: string) => Effect.Effect<JsonRpcMessage, McpTestFailure>;
+  /** 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. */
+  readonly sentSoFar: Effect.Effect<ReadonlyArray<unknown>>;
   /** Everything written to stderr, plus every captured log line. */
   readonly stderrSoFar: Effect.Effect<string>;
   /** Every captured `console.log`, `info` or `debug` call. */
@@ -321,9 +339,21 @@ interface McpToolAuditPolicy {
   readonly input: "open" | "closed" | "any";
   /** Every tool must carry a non-empty `title`, top-level or in `annotations.title`. */
   readonly requireTitle?: boolean | undefined;
-  /** Every tool must serve an `outputSchema`. The stateful revisions drop a non-object one, so check the revision you serve. */
+  /**
+   * Every tool must serve an `outputSchema`. The stateful revisions drop a
+   * non-object one, so check the revision you serve; the violation names
+   * the likely cause, a union success schema, and `ToolOutputSchema.objectRooted`.
+   */
   readonly requireOutputSchema?: boolean | undefined;
-  /** A served `outputSchema` must be rooted at `type: "object"`. Defaults to `true` (D10). */
+  /**
+   * A served `outputSchema` must be rooted at `type: "object"`. Defaults to
+   * `true` (D10). 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
+   * instead). On a stateful revision the
+   * same schema is dropped, and `requireOutputSchema` reports it instead.
+   */
   readonly objectRootedOutput?: boolean | undefined;
   /** The longest `description` allowed, in UTF-16 code units; a missing description counts as 0. */
   readonly maxDescription?: number | undefined;