@effected/mcp 0.2.0 → 0.3.0

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)
@@ -94,7 +94,7 @@ For a refusal with no fields of its own, `ToolRefusal` is that shape ready-made:
 ```ts
 import { ToolFailure, ToolRefusal } from "@effected/mcp";
 import { Effect, Schema } from "effect";
-import { Tool } from "effect/unstable/ai";
+import { Tool } from "effect/ai";
 
 const GetRun = Tool.make("get_run", {
   parameters: Schema.Struct({ id: Schema.String }),
@@ -120,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,
@@ -172,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"}}`,
@@ -196,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
@@ -275,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({
@@ -363,7 +406,7 @@ A tool whose parameters are a `Schema.Union` of objects cannot be a `Tool.make`
 ```ts
 import { McpToolkit, ToolOutputSchema, ToolRefusal } from "@effected/mcp";
 import { Effect, Schema } from "effect";
-import { Tool, Toolkit } from "effect/unstable/ai";
+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) });
@@ -391,7 +434,7 @@ const Handlers = Kit.toLayer({
 
 `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.
+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
 
@@ -417,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>;
@@ -434,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`. `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.
+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,
@@ -477,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");
@@ -487,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,7 +9,7 @@ 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.

package/ToolInputSchema.js

@@ -77,11 +77,15 @@ const collect = (payload, root) => {
 			if (match === void 0) extra.push(key);
 			else patterned.push([key, match[1]]);
 		}
-		if (extra.length > 0 && isClosed) out.push({
-			path,
-			unknown: extra,
-			accepted
-		});
+		if (extra.length > 0 && isClosed) {
+			const acceptedPatterns = patterns.map(([pattern]) => pattern);
+			out.push({
+				path,
+				unknown: extra,
+				accepted,
+				...acceptedPatterns.length > 0 ? { acceptedPatterns } : {}
+			});
+		}
 		for (const key of accepted) if (Object.hasOwn(value, key)) walk(value[key], properties[key], [...path, key], depth + 1);
 		for (const [key, schema] of patterned) walk(value[key], schema, [...path, key], depth + 1);
 		if (additional !== void 0) for (const key of extra) walk(value[key], additional, [...path, key], depth + 1);
@@ -94,10 +98,12 @@ const collect = (payload, root) => {
 * depth, a message naming them all, and an object-rooted form of a union.
 *
 * @remarks
-* Core's `Tool.Strict` rejects unknown keys but reports only the first
-* (effect `unstable/ai/McpServer.ts` decodes without `errors: "all"`), so an
-* agent fixes one typo per round trip. These walkers run over the schema core
-* actually serves, so what they accept matches what the tool advertises:
+* For a `Tool.make` tool, core's strict decode already names every unknown
+* key, with every missing or invalid field, in one response. Core never
+* validates a `Tool.dynamic` tool's raw JSON Schema, so these walkers are
+* for that case: a handler runs them against the schema it registered.
+* They run over the schema as served, so what they accept matches what the
+* tool advertises:
 *
 * - Only `additionalProperties: false` closes a node, as in JSON Schema; core
 *   emits it on every object node of a strict tool and `true` otherwise.
@@ -108,6 +114,9 @@ const collect = (payload, root) => {
 * - `items`, `prefixItems`, `$ref` into `$defs` (JSON Pointer escapes
 *   honoured), and `patternProperties` are followed; a key matched by a
 *   pattern is accepted and walked with the first matching pattern's schema.
+*   Effect serves a pattern-keyed `Schema.Record` with `patternProperties`
+*   only when the key pattern's RegExp has the `u` flag; without it the
+*   record is served open, and every key is accepted.
 * - The payload is untrusted: the walk stops descending at depth 256 rather
 *   than overflowing the stack, so a deeper unknown key goes unreported and
 *   is left for decoding. Every hop counts toward that cap: each property or
@@ -121,17 +130,22 @@ var ToolInputSchema = class {
 	/** Every level of `payload` that carries a key `schema` does not accept. */
 	static unknownKeys = (payload, schema) => collect(payload, schema);
 	/**
-	* `Unrecognized parameter(s): a, b.c. Accepted params: x, y.` per level. Each
-	* echoed key is truncated, and at most 20 keys and 20 levels are named; a
-	* trailing `(and N more levels).` counts the levels left out.
+	* `Unrecognized parameter(s): a, b.c. Accepted params: x, y.` per level,
+	* followed by `Accepted keys matching: ^x-.` when the level also accepts
+	* keys by pattern. A level that accepts keys only by pattern names its
+	* patterns alone, never `Accepted params: (none).` Each echoed key and
+	* pattern is truncated, and at most 20 keys, 20 patterns and 20 levels are
+	* named; a trailing `(and N more levels).` counts the levels left out.
 	*/
 	static formatUnknownKeys = (levels, options = {}) => {
 		const limit = options.echoLimit ?? ToolFailure.ECHO_LIMIT;
 		const sentences = levels.slice(0, MAX_ECHOED).map((level) => {
 			const shown = level.unknown.slice(0, MAX_ECHOED).map((key) => ToolFailure.truncate([...level.path, key].join("."), limit));
 			const more = level.unknown.length > MAX_ECHOED ? ` (and ${level.unknown.length - MAX_ECHOED} more)` : "";
-			const accepted = level.accepted.length === 0 ? "(none)" : level.accepted.join(", ");
-			return `Unrecognized parameter(s): ${shown.join(", ")}${more}. Accepted params: ${accepted}.`;
+			const patterns = (level.acceptedPatterns ?? []).slice(0, MAX_ECHOED).map((pattern) => ToolFailure.truncate(pattern, limit));
+			const params = level.accepted.length > 0 ? ` Accepted params: ${level.accepted.join(", ")}.` : patterns.length === 0 ? " Accepted params: (none)." : "";
+			const matching = patterns.length > 0 ? ` Accepted keys matching: ${patterns.join(", ")}.` : "";
+			return `Unrecognized parameter(s): ${shown.join(", ")}${more}.${params}${matching}`;
 		});
 		const hidden = levels.length > MAX_ECHOED ? ` (and ${levels.length - MAX_ECHOED} more levels).` : "";
 		return `${sentences.join(" ")}${hidden}`;

package/index.d.ts

@@ -1,5 +1,5 @@
 import { Array, Context, Effect, JsonSchema, Layer, Runtime, Schema, Stdio } from "effect";
-import { McpProtocol, McpSchema, McpServer, Tool, Toolkit } from "effect/unstable/ai";
+import { McpProtocol, McpSchema, McpServer, Tool, Toolkit } from "effect/ai";
 import { Remediation } from "@effected/engine";
 //#region src/McpStdio.d.ts
 /**
@@ -99,26 +99,35 @@ export declare class McpStdio {
    *
    * The server reads stdin through a guard that frames it exactly as core's
    * decoder does: one streaming UTF-8 decoder, a byte-order mark stripped
-   * only at the start of the stream, lines split on `\n`. A line that is
-   * not JSON is answered on stdout with a JSON-RPC parse error, code
-   * `-32700` and `id: null`, and never reaches core's decoder, which would
-   * otherwise throw on that line again for every later chunk and stop
-   * answering. So is a line longer than core's cap of 16 Mi UTF-16 code
-   * units: it is answered once, as soon as it passes the cap, and the rest
-   * of it is discarded up to its newline. A line of JSON whitespace (space,
-   * tab, carriage return) is ignored.
+   * only at the start of the stream, lines split on `\n`. Core itself skips
+   * a line it cannot use and keeps serving, but sends no reply, where
+   * JSON-RPC 2.0 requires one; the guard supplies it. A line that is not
+   * JSON is answered on stdout with a parse error, code `-32700` and
+   * `id: null`, and never reaches core. So is a line longer than core's cap
+   * of 16 Mi UTF-16 code units: it is answered once, as soon as it passes
+   * the cap, and the rest of it is discarded up to its newline (core would
+   * log it on stderr and drop it). A line of JSON whitespace (space, tab,
+   * carriage return) is ignored.
    *
    * A line that is JSON but no JSON-RPC message core can handle is answered
    * with an Invalid Request, code `-32600` and `id: null`, and never reaches
-   * core: a value that is neither an object nor an array (core throws on
-   * `null`, dropping every other frame in its 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 it too), and
-   * an object with neither `method` nor `id`, which is neither a request nor
-   * a response. Everything else goes to core: an array, which core answers
-   * `-32600` itself because it serves no batches; an object with an `id`
-   * and no `method`, which is a response and gets no reply; and a request
-   * with an `id`, which core answers even when its `method` is malformed.
+   * core: a value that is neither an object 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,
+   * whose JSON-RPC decoder would read one without an `id` as its own RPC
+   * control message: `@effect/rpc/Eof` alone silently stops the server
+   * (Effect-TS/effect#8499, open upstream). Such a request is answered
+   * `-32601` Method not found, echoing its `id`; such a notification is
+   * dropped. The guard stops doing this once core no longer treats a
+   * client's `@effect/rpc/` frame as a control message.
+   *
+   * Everything else goes to core: an array, which core answers `-32600`
+   * itself because it serves no batches; an object with an `id` and no
+   * `method`, which is a response and gets no reply; and a request with an
+   * `id`, which core answers even when its `method` is malformed.
    *
    * Give each server a fresh layer memo map. Core's stdio protocol layer
    * is a shared constant, so a second `McpStdio.layer` server whose build
@@ -184,6 +193,11 @@ interface UnknownKeysLevel {
   readonly unknown: ReadonlyArray<string>;
   /** Keys this level declares, in schema order. */
   readonly accepted: ReadonlyArray<string>;
+  /**
+   * The `patternProperties` patterns this level also accepts keys by, in
+   * schema order. Present only when the level has at least one.
+   */
+  readonly acceptedPatterns?: ReadonlyArray<string>;
 }
 /**
  * Options for {@link ToolInputSchema.formatUnknownKeys}.
@@ -199,10 +213,12 @@ interface FormatUnknownKeysOptions {
  * depth, a message naming them all, and an object-rooted form of a union.
  *
  * @remarks
- * Core's `Tool.Strict` rejects unknown keys but reports only the first
- * (effect `unstable/ai/McpServer.ts` decodes without `errors: "all"`), so an
- * agent fixes one typo per round trip. These walkers run over the schema core
- * actually serves, so what they accept matches what the tool advertises:
+ * For a `Tool.make` tool, core's strict decode already names every unknown
+ * key, with every missing or invalid field, in one response. Core never
+ * validates a `Tool.dynamic` tool's raw JSON Schema, so these walkers are
+ * for that case: a handler runs them against the schema it registered.
+ * They run over the schema as served, so what they accept matches what the
+ * tool advertises:
  *
  * - Only `additionalProperties: false` closes a node, as in JSON Schema; core
  *   emits it on every object node of a strict tool and `true` otherwise.
@@ -213,6 +229,9 @@ interface FormatUnknownKeysOptions {
  * - `items`, `prefixItems`, `$ref` into `$defs` (JSON Pointer escapes
  *   honoured), and `patternProperties` are followed; a key matched by a
  *   pattern is accepted and walked with the first matching pattern's schema.
+ *   Effect serves a pattern-keyed `Schema.Record` with `patternProperties`
+ *   only when the key pattern's RegExp has the `u` flag; without it the
+ *   record is served open, and every key is accepted.
  * - The payload is untrusted: the walk stops descending at depth 256 rather
  *   than overflowing the stack, so a deeper unknown key goes unreported and
  *   is left for decoding. Every hop counts toward that cap: each property or
@@ -226,9 +245,12 @@ export declare class ToolInputSchema {
   /** Every level of `payload` that carries a key `schema` does not accept. */
   static readonly unknownKeys: (payload: unknown, schema: JsonSchema.JsonSchema) => ReadonlyArray<UnknownKeysLevel>;
   /**
-   * `Unrecognized parameter(s): a, b.c. Accepted params: x, y.` per level. Each
-   * echoed key is truncated, and at most 20 keys and 20 levels are named; a
-   * trailing `(and N more levels).` counts the levels left out.
+   * `Unrecognized parameter(s): a, b.c. Accepted params: x, y.` per level,
+   * followed by `Accepted keys matching: ^x-.` when the level also accepts
+   * keys by pattern. A level that accepts keys only by pattern names its
+   * patterns alone, never `Accepted params: (none).` Each echoed key and
+   * pattern is truncated, and at most 20 keys, 20 patterns and 20 levels are
+   * named; a trailing `(and N more levels).` counts the levels left out.
    */
   static readonly formatUnknownKeys: (levels: ReadonlyArray<UnknownKeysLevel>, options?: FormatUnknownKeysOptions) => string;
   /**
@@ -253,16 +275,16 @@ interface McpToolkitOptions {
    * annotation is served and decoded strict. `"annotated"`: only tools
    * annotated `Tool.Strict` true are. In both modes an explicit annotation,
    * true or false, always wins, and a `Tool.dynamic` tool is never
-   * re-annotated (core dies at registration on a strict dynamic tool). Only
-   * a tool that ends up strict gets the unknown-key pre-check; a lenient
-   * one is passed through untouched even if its raw schema is closed.
+   * re-annotated (core dies at registration on a strict dynamic tool).
    */
   readonly strict?: "all" | "annotated" | undefined;
   /**
-   * Replaces the default `ToolInputSchema.formatUnknownKeys` rendering. It
-   * runs per rejected call inside the handler's effect, so a throw becomes
-   * a defect of that call alone — the client receives a JSON-RPC internal
-   * error (-32603) — never a crash of the server.
+   * Ignored. Core's strict decode reports every excess key at every depth,
+   * together with every missing or invalid field, in one `InvalidParams`,
+   * and the layer appends a fixed `Accepted params at <path>: …` line per
+   * level that carries an unknown key; this option changes neither.
+   *
+   * @deprecated A no-op, scheduled for removal in a later minor.
    */
   readonly unknownKeyMessage?: ((levels: ReadonlyArray<UnknownKeysLevel>) => string) | undefined;
 }
@@ -315,39 +337,45 @@ interface UnionToolOptions<P extends Schema.Decoder<unknown>, S extends Schema.C
  */
 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.
+   * Ignored. The union decode reports every excess, missing and invalid
+   * field in one `InvalidParams`, followed by the same fixed
+   * `Accepted params at <path>: …` lines {@link McpToolkit.layer} appends;
+   * this option changes neither.
+   *
+   * @deprecated A no-op, scheduled for removal in a later minor.
    */
   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
- * 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
@@ -386,9 +414,11 @@ export declare class McpToolkit {
    * {@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`
+   * 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
@@ -409,26 +439,27 @@ export declare class McpToolkit {
    */
   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`.
+   * 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 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.
+   * 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 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>);
+  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`.
+   * `McpServer.toolkit`'s registration layer, strict by default.
+   * `options.unknownKeyMessage` is deprecated and ignored.
    */
   static readonly layer: <Tools extends Record<string, Tool.Any>>(toolkit: Toolkit.Toolkit<Tools>, options?: McpToolkitOptions) => Layer.Layer<never, never, Tool.HandlersFor<Tools> | Exclude<Tool.HandlerServices<Tools>, McpSchema.McpRequestContext>>;
 }
@@ -440,7 +471,7 @@ export declare class McpToolkit {
  * @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.