@effected/mcp 0.1.1 → 0.3.0

package/index.d.ts

@@ -1,5 +1,5 @@
-import { Array, Effect, JsonSchema, Layer, Runtime, Schema, Stdio } from "effect";
-import { McpProtocol, McpSchema, McpServer, Tool, Toolkit } from "effect/unstable/ai";
+import { Array, Context, Effect, JsonSchema, Layer, Runtime, Schema, Stdio } from "effect";
+import { McpProtocol, McpSchema, McpServer, Tool, Toolkit } from "effect/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.
@@ -79,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
@@ -107,8 +136,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 +162,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`.
@@ -157,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}.
@@ -172,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.
@@ -186,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
@@ -199,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;
   /**
@@ -226,51 +275,114 @@ 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;
 }
 /**
- * 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.
+ * 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
- * 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
+ * `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 {
+  /**
+   * 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
+ * every tool is strict by default and a {@link McpToolkit.unionTool} gets its
+ * union decoded.
+ *
+ * @remarks
+ * 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.
@@ -289,8 +401,65 @@ interface McpToolkitOptions {
 export declare class McpToolkit {
   private 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 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}: 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 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.
+   * `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>>;
 }
@@ -302,14 +471,20 @@ 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.
  *
  * 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 +523,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 };