@effected/mcp 0.1.1 → 0.3.0

package/McpToolkit.js

@@ -1,42 +1,144 @@
+import { ToolFailure } from "./ToolFailure.js";
 import { ToolInputSchema } from "./ToolInputSchema.js";
-import { Context, Effect, Layer } from "effect";
-import { McpSchema, McpServer, Tool, Toolkit } from "effect/unstable/ai";
+import { Context, Effect, Layer, Schema } from "effect";
+import { McpSchema, McpServer, Tool, Toolkit } from "effect/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}` });
+const MAX_ACCEPTED_LINES = 20;
+/**
+* `path` as core renders an issue path, `["a"][0]["b"]`: a segment indexing
+* an array in `payload` is bare, any other is a JSON string. Truncated, since
+* the segments are the caller's keys.
+*/
+const issuePath = (payload, path) => {
+	let node = payload;
+	let out = "";
+	for (const segment of path) {
+		out += Array.isArray(node) ? `[${segment}]` : `[${JSON.stringify(segment)}]`;
+		node = typeof node === "object" && node !== null ? node[segment] : void 0;
+	}
+	return ToolFailure.truncate(out);
+};
+/**
+* One line per level of `payload` that carries a key the served
+* `inputSchema` does not accept: `Accepted params at <path>: a, b.`, with
+* `keys matching <pattern>` for a level that also accepts keys by
+* `patternProperties`, and `This tool accepts no params.` for a
+* zero-parameter root. At most 20 lines; empty when no level has an
+* unknown key.
+*/
+const acceptedParamsLines = (payload, inputSchema) => ToolInputSchema.unknownKeys(payload, inputSchema).slice(0, MAX_ACCEPTED_LINES).map((level) => {
+	const patterns = level.acceptedPatterns ?? [];
+	if (level.path.length === 0 && level.accepted.length === 0 && patterns.length === 0) return "This tool accepts no params.";
+	const parts = [...level.accepted.length > 0 ? [level.accepted.join(", ")] : [], ...patterns.length > 0 ? [`keys matching ${patterns.join(", ")}`] : []];
+	return `Accepted params at ${level.path.length === 0 ? "the root" : issuePath(payload, level.path)}: ${parts.length > 0 ? parts.join("; ") : "(none)"}.`;
+});
+/**
+* `error` with {@link acceptedParamsLines} appended to its message, one per
+* line after core's own report; `error` itself when there is nothing to add.
+* Core stays the decoder: this only annotates the report it produced.
+*/
+const withAcceptedParams = (error, payload, inputSchema) => {
+	const lines = acceptedParamsLines(payload, inputSchema);
+	return lines.length === 0 ? error : new McpSchema.InvalidParams({
+		message: [error.message, ...lines].join("\n"),
+		...error.data !== void 0 ? { data: error.data } : {}
+	});
+};
+/**
+* The one decode a union tool's payload gets, shared by the `McpToolkit.layer`
+* decorator and {@link McpToolkit.unionHandler}: the union's strict decode
+* with the options core decodes a strict `Tool.make` tool with
+* (`onExcessProperty: "error"`, `errors: "all"`), so every excess, missing and
+* invalid field of the matched member is reported together, worded as core
+* words a `Tool.make` failure, with the accepted params appended as the layer
+* appends them to core's own report.
+*/
+const decodeUnionPayload = (name, union, inputSchema) => {
+	const decode = Schema.decodeUnknownEffect(union);
+	return (payload) => {
+		const raw = payload ?? {};
+		return decode(raw, {
+			onExcessProperty: "error",
+			errors: "all"
+		}).pipe(Effect.mapError((error) => withAcceptedParams(invalidParameters(name, error.message), raw, inputSchema)));
+	};
+};
+/**
+* The registration `McpToolkit.layer` hands core in place of `registration`:
+* a union tool gets its payload decoded first, with the wrapped handler built
+* only after the decode passes, so a rejected payload never reaches it.
+* Anything else is decoded by core as before, and core's parameter failure,
+* the only `InvalidParams` its `handle` fails with, gets the accepted params
+* appended.
+*
+* @internal
+*/
+const guardRegistration = (registration) => {
+	const union = Context.get(registration.annotations, UnionParameters);
+	if (union === void 0) return {
+		...registration,
+		handle: (payload) => registration.handle(payload).pipe(Effect.catchTag("InvalidParams", (error) => Effect.fail(withAcceptedParams(error, payload ?? {}, registration.tool.inputSchema))))
+	};
+	const check = decodeUnionPayload(registration.tool.name, union, registration.tool.inputSchema);
+	return {
+		...registration,
+		handle: (payload) => check(payload).pipe(Effect.flatMap(() => registration.handle(payload)))
+	};
+};
 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)));
 /**
-* 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
-* response.
+* Register a toolkit exactly as core's `McpServer.toolkit` does, except that
+* every tool is strict by default and a {@link McpToolkit.unionTool} gets its
+* union decoded.
 *
 * @remarks
-* Rejection itself is core's: a tool annotated `Tool.Strict` is served with
-* `additionalProperties: false` on every object node and decoded with
-* `onExcessProperty: "error"`. But core reports only the FIRST excess key
-* (`Expected no excess property at ["extra"]`), so an agent fixes one typo
-* per round trip and never learns about a nested one until the next call.
-* This layer is the better report, not the rejecter: it runs core's
+* Rejection and reporting are core's: a tool annotated `Tool.Strict` is
+* served with `additionalProperties: false` on every object node and decoded
+* with `onExcessProperty: "error"` and `errors: "all"`, so one
+* `InvalidParams` names every excess key at every depth together with every
+* missing or invalid field. The layer appends to that report, never in place
+* of it: for every object level of the payload that carries a key the served
+* input schema does not accept, one line naming what that level does accept,
+* `Accepted params at the root: query, filter.` or
+* `Accepted params at ["filter"]: kind, tag.` (the path as core writes it),
+* with `keys matching <pattern>` for keys a `patternProperties` level
+* accepts, and `This tool accepts no params.` for a zero-parameter tool. An
+* agent can fix the call from the reply alone. A failure with no unknown key
+* (a missing or mistyped field only) is core's report unchanged. The lines
+* are appended to core's `InvalidParams` as it leaves the tool's registered
+* handler, the one failure that handler has for bad parameters.
+*
+* On top of that is the policy: under
+* `strict: "all"` (the default) it annotates every tool that carries no
+* `Tool.Strict` annotation of its own as strict, skipping `Tool.dynamic`
+* tools (core dies at registration on a strict dynamic tool). It runs core's
 * `registerToolkit` unchanged under a registration-scoped `McpServer` whose
-* `addTool` puts a `ToolInputSchema.unknownKeys` pre-check in front of each
-* handler. The pre-check walks the input schema the tool actually serves
-* (after core's own top-level `$ref` inlining), follows `$ref`, `allOf` and
-* discriminated `oneOf`/`anyOf` members, and fails with one
-* `McpSchema.InvalidParams` naming every unknown key path plus the accepted
-* params, before core decodes. Core's strict decode stays behind it as the
-* backstop. The pre-check is gated on the same predicate core uses to choose
-* strict decoding — the registered tool's `Tool.Strict` annotation is
-* `true` — so a lenient tool (explicit `Tool.Strict` false, a
-* `Tool.dynamic` tool, or any unannotated tool under `"annotated"`) is
-* never rejected here, even when its raw JSON Schema carries
-* `additionalProperties: false`. The pre-check runs under `Effect.suspend`,
-* so a throwing `unknownKeyMessage` dies inside the call's effect. No core
-* internals are patched, so this survives an rc bump without re-diffing.
+* `addTool` puts the union decode in front of a union tool's handler and
+* passes every other registration through untouched. It patches no core
+* internals: it uses only `McpServer.registerToolkit` and `addTool`.
 *
 * Registration goes through core's module-level `McpServer.McpServer.layer`,
 * 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 +157,86 @@ const strictened = (toolkit, mode) => mode === "annotated" ? toolkit : Toolkit.m
 var McpToolkit = class {
 	constructor() {}
 	/**
-	* `McpServer.toolkit`'s registration layer, strict by default and naming
-	* every unknown argument in one `InvalidParams`.
+	* 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: a strict decode with
+	* `errors: "all"` before the handler runs, reporting every excess, missing
+	* and invalid field of the matched member in one `InvalidParams`, with the
+	* same `Accepted params at <path>: …` lines appended, 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}: decodes the raw payload
+	* exactly as {@link McpToolkit.layer} does, and passes the decoded member
+	* to `handler`.
+	*
+	* @remarks
+	* A payload that does not decode strictly fails with one
+	* `McpSchema.InvalidParams`, worded as core words a `Tool.make` decode
+	* failure, naming every excess key at every depth together with every
+	* missing or invalid field of the matched member, then one
+	* `Accepted params at <path>: …` line per level with an unknown key. 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.
+	* `options.unknownKeyMessage` is deprecated and ignored.
+	*/
+	static unionHandler = (tool, handler, _options = {}) => {
+		const check = decodeUnionPayload(tool.name, tool.unionParameters, tool.jsonSchema);
+		return (payload) => check(payload).pipe(Effect.flatMap(handler));
+	};
+	/**
+	* `McpServer.toolkit`'s registration layer, strict by default.
+	* `options.unknownKeyMessage` is deprecated and ignored.
 	*/
 	static layer = (toolkit, options = {}) => Layer.effectDiscard(Effect.gen(function* () {
 		const registry = yield* McpServer.McpServer;
-		const format = options.unknownKeyMessage ?? ((levels) => ToolInputSchema.formatUnknownKeys(levels));
 		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))
 		});
 		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

@@ -1,6 +1,6 @@
 # @effected/mcp
 
-The boundary layer of an `effect/unstable/ai` MCP server: stdio wiring that keeps stdout the JSON-RPC wire, tool-failure shaping, and strict-input walkers, plus a `./testing` subpath for driving a built server from a test.
+The boundary layer of an `effect/ai` MCP server: stdio wiring that keeps stdout the JSON-RPC wire, tool-failure shaping, and strict-input walkers, plus a `./testing` subpath for driving a built server from a test.
 
 [![npm](https://img.shields.io/npm/v/@effected%2Fmcp?label=npm&color=cb3837)](https://www.npmjs.com/package/@effected/mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
@@ -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/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:
@@ -95,7 +120,7 @@ A stdio server's `main.ts` is one line, plus the layer that wires it:
 import { McpStdio, McpToolkit, ToolFailure } from "@effected/mcp";
 import { NodeRuntime, NodeStdio } from "@effect/platform-node";
 import { Effect, Layer, Schema } from "effect";
-import { Tool, Toolkit } from "effect/unstable/ai";
+import { Tool, Toolkit } from "effect/ai";
 
 class NotFound extends Schema.TaggedError<NotFound>()("NotFound", {
   ...ToolFailure.fields,
@@ -147,20 +172,20 @@ its own queue-backed `Stdio`.
 
 `McpToolkit.layer` re-annotates every tool without its own `Tool.Strict`
 annotation to strict by default, so `get_thing({ id: "known", extra: 1 })`
-is rejected with one `Unrecognized parameter(s): extra. Accepted params:
-id.` before the handler ever runs — see [Strict input](#strict-input)
-below.
+is rejected by core's strict decode, which names every excess, missing and
+invalid field in one `InvalidParams`, before the handler ever runs, and the
+layer adds `Accepted params at the root: id.` — see
+[Strict input](#strict-input) below.
 
 ## The stdio boundary
 
 `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, 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:
+stderr, and with stdin read through a guard. Core's own stdio decoder skips a
+line it cannot use and keeps serving, but it sends no reply, where JSON-RPC 2.0
+requires one: the client is left waiting on a request it will never hear about.
+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 such line itself, on stdout:
 
 - a line that is not JSON gets a JSON-RPC parse error,
   `{"jsonrpc":"2.0","id":null,"error":{"code":-32700,"message":"Parse error"}}`,
@@ -171,11 +196,16 @@ stdout:
 - a line that is JSON but no JSON-RPC message gets an Invalid Request,
   `{"jsonrpc":"2.0","id":null,"error":{"code":-32600,"message":"Invalid Request"}}`,
   and the server keeps serving. That covers a value that is neither an object
-  nor an array (core throws on a bare `null`, dropping every other frame that
-  arrived in the same chunk, and ignores a number, string or boolean without a
-  reply), an object whose `method` is not a string and whose `id` is absent or
-  `null` (core throws on that too), and an object with neither `method` nor
-  `id`, which is neither a request nor a response;
+  nor an array, an object whose `method` is not a string and whose `id` is
+  absent or `null`, and an object with neither `method` nor `id`, which is
+  neither a request nor a response;
+- a line whose `method` starts with `@effect/rpc/` never reaches core, which
+  would read one without an `id` as its own RPC control message:
+  `{"jsonrpc":"2.0","method":"@effect/rpc/Eof"}` alone silently stops an
+  unguarded server ([Effect-TS/effect#8499](https://github.com/Effect-TS/effect/issues/8499),
+  open upstream). Such a notification is
+  dropped; such a request is answered `-32601` Method not found, echoing its
+  `id`;
 - a line of JSON whitespace (space, tab, carriage return) is ignored.
 
 Every other line goes to core. That includes an array, which core answers with
@@ -188,9 +218,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
 
@@ -208,35 +280,73 @@ scopes:
 - **`McpToolkit.layer(toolkit, options?)`** — the registration-scoped
   decorator, and the recommended default: every tool without its own
   `Tool.Strict` annotation is served and decoded strict
-  (`options.strict` defaults to `"all"`), and a rejected call names every
-  unknown key at every depth in one response, not just the first. An
-  explicit `Tool.Strict` annotation always wins, and a `Tool.dynamic` tool
-  is never re-annotated. Pass `{ strict: "annotated" }` to leave
+  (`options.strict` defaults to `"all"`). Rejection and the report are
+  core's: a strict tool is decoded with `errors: "all"`, so one
+  `InvalidParams` names every excess key at every depth together with every
+  missing or invalid field. The layer appends to that report, never in
+  place of it: one `Accepted params at <path>: …` line for each object level
+  of the payload that carries an unknown key, so an agent can fix the call
+  from the reply alone (example below). An explicit `Tool.Strict`
+  annotation always wins, and a `Tool.dynamic` tool is never re-annotated.
+  `options.unknownKeyMessage` is deprecated and ignored. Pass `{ strict: "annotated" }` to leave
   unannotated tools lenient, or annotate an individual tool
   `Tool.Strict` false to opt it out under the default.
 
 ```ts
 import { McpToolkit } from "@effected/mcp";
 import { Layer } from "effect";
-import type { Tool, Toolkit } from "effect/unstable/ai";
+import type { Tool, Toolkit } from "effect/ai";
 
 // The toolkit and its handlers, as built in "Putting it together".
 declare const MyTools: Toolkit.Toolkit<Record<string, Tool.Any>>;
 declare const MyHandlers: Layer.Layer<never>;
 
-// Default: every tool is strict, and every rejection names every unknown key.
+// Default: every tool is strict; core's rejection names every bad field at once.
 const ToolsLayer = McpToolkit.layer(MyTools).pipe(Layer.provide(MyHandlers));
 
 // Only tools explicitly annotated Tool.Strict are decoded strict.
 const LenientByDefault = McpToolkit.layer(MyTools, { strict: "annotated" }).pipe(Layer.provide(MyHandlers));
 ```
 
+A strict `search` tool taking `query` and an optional `filter` union, called
+with an unknown key at the root and one inside the selected `filter` member,
+and without its required `query`:
+
+```text
+search({ extra: 1, filter: { kind: "tag", tag: "t", text: "sneaky" } })
+=> Invalid parameters for tool 'search': Expected no excess property
+     at ["extra"]
+   Missing key
+     at ["query"]
+   Expected no excess property
+     at ["filter"]["text"]
+   Accepted params at the root: query, filter.
+   Accepted params at ["filter"]: kind, tag.
+```
+
+The first six lines are core's. The layer adds the last two: one per object
+level that carries an unknown key, naming its accepted keys, plus
+`keys matching <pattern>` where the level accepts keys by `patternProperties`.
+A zero-parameter tool gets `This tool accepts no params.` instead. A failure
+with no unknown key, only missing or mistyped fields, is core's report
+unchanged.
+
+A pattern-keyed `Schema.Record` is served closed, with `patternProperties`,
+only when its key pattern's RegExp carries the Unicode flag:
+`Schema.isPattern(/^x-/u)`. Without `u`, Effect treats the exported pattern as
+approximate and serves the record open (`additionalProperties` set to the value
+schema), so the served schema, and `ToolInputSchema.unknownKeys` walking it,
+accept any key; the strict decode still enforces the pattern. `McpToolAudit`'s `input: "closed"` check reports such
+a record open and suggests the flag. Where a closed level accepts keys by
+pattern, `formatUnknownKeys` names the patterns (`Accepted keys matching: ^x-.`)
+rather than claiming it accepts none.
+
 The dynamic-tool recipe, with the handler reporting every unknown key:
 
 ```ts
 import { McpToolkit, ToolInputSchema } from "@effected/mcp";
 import { Effect, Layer, Schema } from "effect";
-import { Tool, Toolkit } from "effect/unstable/ai";
+import { Tool, Toolkit } from "effect/ai";
 
 // A top-level union, written as raw JSON Schema and rewritten to an object root.
 const EditInput = ToolInputSchema.objectRooted({
@@ -289,6 +399,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/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 decoded like a strict `Tool.make` tool, before the handler runs: strictly, with `errors: "all"`, so one `InvalidParams` in core's `Tool.make` wording names every excess key at every depth together with every missing or invalid field of the matched member, followed by the same `Accepted params at <path>: …` lines. 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 decode itself, so the message is identical. Under `McpServer.toolkit` that `InvalidParams` is a declared failure, an `isError` result on every revision. `unionHandler`'s third argument, `{ unknownKeyMessage }`, is deprecated and ignored. 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
@@ -297,7 +460,7 @@ test machinery into a server's runtime import graph.
 ```ts
 import { McpHarness } from "@effected/mcp/testing";
 import { Effect, type Layer, type Stdio } from "effect";
-import type { McpServer } from "effect/unstable/ai";
+import type { McpServer } from "effect/ai";
 
 // The server layer from "Putting it together" — still requiring Stdio.
 declare const ServerLayer: Layer.Layer<McpServer.McpServer, never, Stdio.Stdio>;
@@ -314,7 +477,8 @@ 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`. `ping` is the exception: the server answers it `{}` before
+initialization, so the harness sends it. `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,
@@ -357,7 +521,7 @@ import { join } from "node:path";
 import { NodeServices } from "@effect/platform-node";
 import { McpProcess } from "@effected/mcp/testing";
 import { Effect } from "effect";
-import { ChildProcess } from "effect/unstable/process";
+import { ChildProcess } from "effect/process";
 
 // A minimal server, written to disk so it can be spawned as a real process.
 const serverFile = join(import.meta.dirname, "mcp-guard-demo-server.mjs");
@@ -367,7 +531,7 @@ writeFileSync(
 import { McpStdio, McpToolkit } from "@effected/mcp";
 import { NodeRuntime, NodeStdio } from "@effect/platform-node";
 import { Effect, Layer } from "effect";
-import { Tool, Toolkit } from "effect/unstable/ai";
+import { Tool, Toolkit } from "effect/ai";
 
 const Ping = Tool.make("ping", { description: "Liveness check.", parameters: Tool.EmptyParams });
 const Tools = Toolkit.make(Ping);

package/ToolFailure.js

@@ -9,14 +9,20 @@ const isHighSurrogate = (code) => code >= 55296 && code <= 56319;
 * @remarks
 * Core sends a declared failure that is an `Error` instance — every
 * `Schema.TaggedError` is — as `isError: true` with `error.message` as the only
-* text and no `structuredContent` (effect `unstable/ai/McpServer.ts`,
+* text and no `structuredContent` (effect `ai/McpServer.ts`,
 * `declaredFailureResult`). So the remediation must be folded into `message`
 * when the error is constructed: whatever is not in the message never reaches
 * the agent.
 *
 * 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