@effected/mcp-kit 0.0.0-stage → 0.14.0

package/index.d.ts

@@ -0,0 +1,1048 @@
+import { Array, Cause, Context, Effect, JsonSchema, Layer, Option, Runtime, Schema, Scope, Stdio, Struct } from "effect";
+import { McpProtocol, McpSchema, McpServer, Tool, Toolkit } from "effect/ai";
+import { Remediation } from "@effected/kit";
+import { KeyValueStore } from "effect/persistence";
+/**
+ * Options for {@link McpStdio.layer}.
+ *
+ * @public
+ */
+interface McpStdioOptions<RA = never, RE = never, RR = never> {
+  /** The server name reported to the client. */
+  readonly name: string;
+  /** The server version reported to the client. */
+  readonly version: string;
+  /** Surfaced in `initialize` and `server/discover`; tell the agent how to use the tools. */
+  readonly instructions?: string | undefined;
+  /** A one-line description of the server, reported to the client. */
+  readonly description?: string | undefined;
+  /** The server's website, reported in `server/discover` and `initialize`. */
+  readonly websiteUrl?: string | undefined;
+  /** Icons for the server, reported to the client. */
+  readonly icons?: ReadonlyArray<McpSchema.Icon> | undefined;
+  /** Capability extensions the server advertises, keyed `vendor/name`. */
+  readonly extensions?: (typeof McpSchema.ServerCapabilities)["Type"]["extensions"] | undefined;
+  /**
+   * How long a client may treat each list result as fresh, per result kind.
+   *
+   * @remarks
+   * Core's `cacheHints`, forwarded unchanged. Only the stateless `2026-07-28` revision carries them; earlier
+   * revisions ignore the option. Omitted kinds keep a zero `ttl`. A positive `ttl` lets a client keep showing a list
+   * after registrations change, until it expires: raise it only for a list that is fixed for the server's lifetime.
+   */
+  readonly cacheHints?: McpServer.CacheHints | undefined;
+  /** Defaults to {@link McpStdio.protocols}. Read its ordering rules before overriding. */
+  readonly protocols?: Array.NonEmptyReadonlyArray<McpProtocol.ProtocolAdapter> | undefined;
+  /**
+   * The server's registration layers (toolkits, resources, prompts), built
+   * before the server reads its first request and under `LogToStderr`.
+   *
+   * @remarks
+   * Core's `registrations` option of `McpServer.layerStdio`. The transport
+   * discharges each `McpServer.McpRequest<"Requires", Scope>` marker; any
+   * other request-level marker stays in the layer's requirements, to be met
+   * by MCP middleware. A registration that needs `Stdio` when it is built
+   * gets the guarded one this layer serves over.
+   */
+  readonly registrations?: Layer.Layer<RA, RE, RR> | undefined;
+}
+/**
+ * The services a registration layer needs that {@link McpStdio.layer} does
+ * not supply: everything but `McpServer` and `Stdio` (which the layer
+ * requires itself), with each request-level marker but
+ * `McpServer.McpRequest<"Requires", Scope>`, which the transport discharges.
+ *
+ * @public
+ */
+type McpStdioRegistrationServices<RR> = Exclude<McpServer.McpRequest.Without<RR>, McpServer.McpServer> | McpServer.McpRequest.From<"Requires", Exclude<McpServer.McpRequest.Only<"Requires", RR>, Scope.Scope>>;
+/**
+ * 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-kit/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.
+ *
+ * @remarks
+ * The one-line `main.ts`:
+ *
+ * ```ts
+ * NodeRuntime.runMain(McpStdio.launch(Main), { teardown: McpStdio.teardown })
+ * ```
+ *
+ * - {@link McpStdio.layer} is `McpServer.layerStdio` with `LogToStderr`
+ *   provided and merged into its output, and a bad `protocols` list
+ *   turned into a defect. It answers a
+ *   stdin line that is not JSON with a JSON-RPC `-32700` parse error, and
+ *   JSON that is not a JSON-RPC message with `-32600`, and keeps serving.
+ * - {@link McpStdio.launch} reports a launch failure itself, on stderr, and
+ *   hides it from `runMain`, whose own report is written outside anything
+ *   the program can provide.
+ * - {@link McpStdio.teardown} maps stdin EOF, the normal end of every
+ *   session, to exit 0 instead of 130.
+ *
+ * Never `NodeRuntime.runMain(Layer.launch(Main).pipe(Effect.provideService(References.LogToStderr, true)))`:
+ * it typechecks and serves, but a launch failure is still reported by
+ * `runMain` through `console.log`, straight onto the wire, where the client
+ * reads it as a malformed frame instead of an error.
+ *
+ * @public
+ */
+export declare class McpStdio {
+  private constructor();
+  /**
+   * `[v2026_07_28, v2025_11_25, v2025_06_18]` — the stateless revision
+   * first, then the two newest stateful ones.
+   *
+   * @remarks
+   * Real clients open with either handshake: some (Claude Code, for one)
+   * open a stdio server with the stateless `server/discover`, while others
+   * still send `initialize`. The order is load-bearing:
+   *
+   * - Stateless first: a request with no session and no `_meta` falls to
+   *   `protocols[0]`.
+   * - Never a single entry: `initialize` only matches stateful adapters, so
+   *   a stateless-only list refuses every client that opens with it.
+   * - At most one stateless adapter; a second fails the layer.
+   */
+  static readonly protocols: Array.NonEmptyReadonlyArray<McpProtocol.ProtocolAdapter>;
+  /**
+   * `McpServer.layerStdio` with `LogToStderr` provided and merged into the
+   * output, so every layer it provides logs to stderr too. A bad
+   * `protocols` list dies: it is the implementer's defect. So does a
+   * registration that fails with `Cause.IllegalArgumentError`, which core
+   * reports for the same class of mistake; any other registration error
+   * stays in the error channel.
+   *
+   * @remarks
+   * Pass the server's registration layers as `options.registrations`: they
+   * are built before the server reads its first request, under
+   * `LogToStderr`. Providing this layer to them, as
+   * `Registrations.pipe(Layer.provideMerge(McpStdio.layer(...)))`, also
+   * serves them, and they inherit `LogToStderr` the same way. A sibling
+   * merged beside it with `Layer.mergeAll` is neither: its build logs still
+   * go through `console.log`, onto the wire.
+   *
+   * The output is `McpServer` and the `McpServer.McpRequest<"Requires", Scope>`
+   * marker the transport discharges. `McpServerClient` is not in it: the
+   * stateless `v2026_07_28` revision has no client session, so a handler
+   * reads the client's details from `McpSchema.McpRequestContext` instead.
+   *
+   * `LogToStderr` only reaches a logger that reads it: Effect's default
+   * logger and `Logger.consolePretty`. `Logger.consoleJson`,
+   * `Logger.consoleLogFmt` and `Logger.consoleStructured` are built with
+   * `Logger.withConsoleLog`, which writes through `console.log` whatever
+   * `LogToStderr` says, so a server that installs one puts every log line on
+   * the wire. Never install them under this layer; wrap the formatter in
+   * `Logger.withConsoleError` instead, as in
+   * `Logger.layer([Logger.withConsoleError(Logger.formatJson)])`.
+   *
+   * 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`. 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, 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.
+   *
+   * 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
+   * sees the 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`: nested `Layer.build`
+   * and `Effect.provide` fork the 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 (this layer with its `registrations`, or 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
+   * loop ends, which closing the provide's scope does. In a test, serve the
+   * layer through `McpHarness` from `@effected/mcp-kit/testing` instead.
+   *
+   * Each call mints a fresh layer; bind the result to a `const` or the
+   * server builds twice.
+   */
+  static readonly layer: <RA = never, RE = never, RR = never>(options: McpStdioOptions<RA, RE, RR>) => Layer.Layer<McpServer.McpServer | McpServer.McpRequest<"Requires", Scope.Scope>, Exclude<RE, Cause.IllegalArgumentError>, Stdio.Stdio | McpStdioRegistrationServices<RR>>;
+  /**
+   * `Layer.launch`, with any failure other than an interrupt logged on
+   * stderr here and re-raised marked as already reported, keeping its exit
+   * code.
+   *
+   * @remarks
+   * `runMain` logs an unhandled failure from outside the program, where no
+   * `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>, options?: McpLaunchOptions) => Effect.Effect<never, Error, R>;
+  /**
+   * Success or an interrupt-only exit maps to 0. Anything else goes to
+   * `Runtime.defaultTeardown`.
+   *
+   * @remarks
+   * Stdin EOF, the normal end of every session, ends in an interrupt-only
+   * exit, and so do SIGINT and SIGTERM: `runMain` interrupts the program on
+   * either signal. All three exit 0 here, not the 130 a default teardown
+   * reports for an interrupt.
+   */
+  static readonly teardown: Runtime.Teardown;
+}
+/**
+ * The unknown keys found at one object level of a tool-call payload.
+ *
+ * @public
+ */
+interface UnknownKeysLevel {
+  /** Keys from the payload root to this object; empty at the root. Array positions are decimal strings. */
+  readonly path: ReadonlyArray<string>;
+  /** Keys the payload carries that this level does not accept, in payload order. */
+  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}.
+ *
+ * @public
+ */
+interface FormatUnknownKeysOptions {
+  /** The cap on each echoed key path, in UTF-16 code units. Defaults to `ToolFailure.ECHO_LIMIT`. */
+  readonly echoLimit?: number | undefined;
+}
+/**
+ * Pure walkers over a tool's served JSON Schema: every unknown key at every
+ * depth, a message naming them all, and an object-rooted form of a union.
+ *
+ * @remarks
+ * 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.
+ * - `allOf` members' properties merge; `oneOf`/`anyOf` members are chosen by an
+ *   `action`, `kind`, `_tag` or `type` literal (tried in that order), or by
+ *   being the only object member. A payload whose discriminant matches no
+ *   member, or is missing, is skipped and left for decoding.
+ * - `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
+ *   array position, and also each union member selection, which adds a hop
+ *   without adding a path segment.
+ *
+ * @public
+ */
+export declare class ToolInputSchema {
+  private constructor();
+  /** 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,
+   * 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;
+  /**
+   * `schema` with a root `$ref` inlined and a top-level union of objects
+   * sharing an `action`, `kind`, `_tag` or `type` literal rewritten to an
+   * object root carrying `type: "object"`, `oneOf` and `"x-discriminator"` —
+   * MCP requires an object root, and core dies at boot on a union root.
+   * Returned as the same value when nothing changes.
+   */
+  static readonly objectRooted: (schema: JsonSchema.JsonSchema) => JsonSchema.JsonSchema;
+}
+/**
+ * Options for {@link McpToolkit.layer}.
+ *
+ * @public
+ */
+interface McpToolkitOptions {
+  /**
+   * `"all"` (the default): every tool without its own `Tool.Strict`
+   * 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).
+   */
+  readonly strict?: "all" | "annotated" | undefined;
+  /**
+   * 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;
+}
+/**
+ * A `Tool.dynamic` made by {@link McpToolkit.unionTool}: served with the
+ * strict, object-rooted JSON Schema of a `Schema.Union` of objects, and
+ * carrying that union so {@link McpToolkit.unionHandler} can decode it.
+ *
+ * @remarks
+ * `annotate` and `addDependency` keep the type, so a chained
+ * `.annotate(Tool.Title, …)` still hands `unionHandler` the union. The
+ * declared failure is `failure` together with `McpSchema.InvalidParams`.
+ *
+ * @public
+ */
+interface UnionTool<Name extends string, P extends Schema.Decoder<unknown>, S extends Schema.Constraint, F extends Schema.Constraint, R = never> extends Tool.Dynamic<Name, {
+  readonly parameters: JsonSchema.JsonSchema;
+  readonly success: S;
+  readonly failure: Schema.Union<readonly [F, typeof McpSchema.InvalidParams]>;
+  readonly failureMode: "error";
+}, R> {
+  /** The union the tool decodes its arguments with. */
+  readonly unionParameters: P;
+  /** Add an annotation, keeping the union. */
+  annotate<I, V>(tag: Context.Key<I, V>, value: V): UnionTool<Name, P, S, F, R>;
+  /** Add a request-level dependency, keeping the union. */
+  addDependency<Identifier, Service>(tag: Context.Key<Identifier, Service>): UnionTool<Name, P, S, F, Identifier | R>;
+}
+/**
+ * Options for {@link McpToolkit.unionTool}.
+ *
+ * @public
+ */
+interface UnionToolOptions<P extends Schema.Decoder<unknown>, S extends Schema.Constraint, F extends Schema.Constraint, Dependencies extends ReadonlyArray<Context.Key<unknown, unknown>>> {
+  /** What the tool does, for the agent. */
+  readonly description?: string | undefined;
+  /** A `Schema.Union` of object schemas, discriminated by an `action`, `kind`, `_tag` or `type` literal. */
+  readonly parameters: P;
+  /** The success schema. Defaults to `Schema.Void`; object-root a union whose members are all objects with `ToolOutputSchema.objectRooted`. */
+  readonly success?: S | undefined;
+  /** Declared failures besides `InvalidParams`, such as `ToolRefusal`. Defaults to `Schema.Never`. */
+  readonly failure?: F | undefined;
+  /** Services the handler needs, as with `Tool.make`. */
+  readonly dependencies?: Dependencies | undefined;
+}
+/**
+ * Options for {@link McpToolkit.unionHandler}.
+ *
+ * @public
+ */
+interface UnionHandlerOptions {
+  /**
+   * 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 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.
+ *
+ * @example
+ * ```ts
+ * import { Layer } from "effect";
+ * import { McpStdio, McpToolkit } from "@effected/mcp-kit";
+ *
+ * const ToolsLayer = McpToolkit.layer(MyToolkit).pipe(Layer.provide(MyHandlers));
+ * const ServerLayer = ToolsLayer.pipe(Layer.provideMerge(McpStdio.layer({ name: "my-server", version: "1.0.0" })));
+ * ```
+ *
+ * @public
+ */
+export declare class McpToolkit {
+  private constructor();
+  /**
+   * A tool whose parameters are a `Schema.Union` of objects, which
+   * `Tool.make` cannot take: core dies at registration on a non-object
+   * `parameters` root.
+   *
+   * @remarks
+   * The tool is a `Tool.dynamic` served with Effect's strict JSON Schema
+   * document for `parameters` (`additionalProperties: false` on every
+   * object node, definitions as `$defs`), rewritten by
+   * `ToolInputSchema.objectRooted` to an object root carrying `type`,
+   * `oneOf` and `x-discriminator`. Write its handler with
+   * {@link McpToolkit.unionHandler}, which receives the decoded member.
+   *
+   * Registered through {@link McpToolkit.layer}, a union tool gets the same
+   * treatment as a strict `Tool.make` tool: 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
+   * import { McpToolkit, ToolOutputSchema, ToolRefusal } from "@effected/mcp-kit";
+   * import { Schema } from "effect";
+   * import { Tool } from "effect/ai";
+   *
+   * // `AddNote`, `ListNotes`, `Added`, `Listed` are object schemas; `Kit` is a Toolkit that includes `Note`.
+   * 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.
+   *
+   * @remarks
+   * Its requirements are core's `McpServer.ToolkitRequirements` less
+   * `McpServer`, which the layer provides itself: the handlers, any service
+   * a parameter or success schema needs, and each service a tool declares
+   * with `dependencies` or `addDependency` as an
+   * `McpServer.McpRequest<"Requires", S>` marker. A marker is met per
+   * request by MCP middleware (`McpServer.middleware`, its `layer` provided
+   * to this one), never by providing `S`. A service the handlers only need
+   * when they are built is captured by the effect form of
+   * `Toolkit.toLayer` instead, and declared nowhere.
+   */
+  static readonly layer: <Tools extends Record<string, Tool.Any>>(toolkit: Toolkit.Toolkit<Tools>, options?: McpToolkitOptions) => Layer.Layer<never, never, Exclude<McpServer.ToolkitRequirements<Tools>, McpServer.McpServer>>;
+  /**
+   * Meet the request-level dependencies a tool declares with `dependencies`
+   * or `addDependency` from a layer built once for the server's lifetime.
+   * Provide the result to {@link McpToolkit.layer}.
+   *
+   * @remarks
+   * The layer builds with the server's graph, so a failure fails the server
+   * build rather than a request, and its finalizers run at server shutdown.
+   * It builds in that graph's memo map: a layer the graph also builds is
+   * shared, and two servers each wrapped whole in `Layer.fresh` build their
+   * own.
+   *
+   * It captures what the layer outputs and nothing else, so a key the build
+   * merely ran under (a span, a request-level reference) never shadows the
+   * request's own, which capturing `Effect.context` in hand-written
+   * middleware does. The outputs are taken as given: a layer that outputs
+   * `Effect.context()` wholesale, through `Layer.effectContext`, still leaks
+   * everything it read.
+   *
+   * A service that varies per request still needs its own
+   * `McpServer.middleware`. A service only the handlers' construction needs
+   * is captured by the effect form of `Toolkit.toLayer` and declared nowhere.
+   *
+   * Each call mints a fresh layer; bind the result to a `const` or the
+   * middleware builds again.
+   *
+   * @example
+   * ```ts
+   * import { McpToolkit } from "@effected/mcp-kit";
+   * import { Layer } from "effect";
+   *
+   * // `Kit` declares `dependencies: [Inspector]`; `InspectorLive` builds it once.
+   * const Lifetime = McpToolkit.provideLifetime(InspectorLive);
+   * const ToolsLayer = McpToolkit.layer(Kit).pipe(Layer.provide(Lifetime), Layer.provide(KitHandlers));
+   * ```
+   */
+  static readonly provideLifetime: <S, E, R>(layer: Layer.Layer<S, E, R>) => Layer.Layer<McpServer.McpRequest.From<"Requires", S>, E, R>;
+}
+/**
+ * How a tool's declared failure should read on the wire.
+ *
+ * @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 `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. 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
+ * import { ToolFailure } from "@effected/mcp-kit";
+ * import { Schema } from "effect";
+ *
+ * class NotFound extends Schema.TaggedError<NotFound>()("NotFound", { ...ToolFailure.fields, id: Schema.String }) {}
+ * const remediation = { hint: "List the ids first.", suggestedTool: "list_things" }
+ * new NotFound({ id, remediation, message: ToolFailure.message(`No thing "${ToolFailure.truncate(id)}".`, remediation) })
+ * ```
+ *
+ * @public
+ */
+export declare class ToolFailure {
+  private constructor();
+  /** The cap, in UTF-16 code units, on a caller-supplied value echoed into a message. */
+  static readonly ECHO_LIMIT: number;
+  /** The larger cap for a value the engine produced (a path, a diagnostic), not one a caller typed. */
+  static readonly ENGINE_ECHO_LIMIT: number;
+  /**
+   * The `message` and `remediation` fields to spread into a consumer's
+   * `Schema.TaggedError`, each carrying a default `description` that a served
+   * JSON Schema (a tool's `outputSchema`) shows the agent.
+   */
+  static readonly fields: {
+    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>>;
+    }>;
+  };
+  /**
+   * `"<raw> <hint> Try <suggestedTool>."`, dropping any empty part, so a
+   * missing tool or an empty hint never leaves a double space.
+   */
+  static readonly message: (raw: string, remediation: Remediation) => string;
+  /**
+   * `value` cut to `limit` code units with a trailing ellipsis, backing off one
+   * unit rather than splitting a surrogate pair. A hostile multi-megabyte
+   * argument is otherwise echoed into the agent's context whole.
+   */
+  static readonly truncate: (value: string, limit?: number) => string;
+}
+/**
+ * What a {@link ToolOutcome.catchAsEnvelope} case returns for one caught error:
+ * the same `message` and `remediation` a {@link ToolRefusal} carries, plus any
+ * structured fields the agent branches on.
+ *
+ * @remarks
+ * `message` is the plain sentence. The hint stays in `remediation`, where it
+ * reaches the agent as data; unlike a refusal's message, nothing is folded in.
+ *
+ * @public
+ */
+interface ToolOutcomeErrorInput {
+  readonly message: string;
+  readonly remediation: Remediation;
+  readonly [field: string]: unknown;
+}
+/**
+ * The `ok: false` member of an envelope: `{ ok: false, error: { _tag, message, remediation, ...fields } }`.
+ *
+ * @public
+ */
+interface ToolOutcomeFailure<Tag extends string, I extends ToolOutcomeErrorInput> {
+  readonly ok: false;
+  readonly error: {
+    readonly _tag: Tag;
+  } & I;
+}
+/**
+ * The failure values {@link ToolOutcome.catchAsEnvelope} produces for a set of
+ * cases: one {@link ToolOutcomeFailure} per handled tag.
+ *
+ * @public
+ */
+type ToolOutcomeFailures<Cases> = { [K in keyof Cases]: Cases[K] extends ((...args: ReadonlyArray<never>) => infer I) ? I extends ToolOutcomeErrorInput ? ToolOutcomeFailure<K & string, I> : never : never; }[keyof Cases];
+/**
+ * {@link ToolOutcome.envelope}'s options: annotations for the `ok: false`
+ * member, so a served `outputSchema` can name and describe it.
+ *
+ * @public
+ */
+interface ToolOutcomeEnvelopeOptions {
+  /**
+   * The failure member's schema identifier. Core's JSON Schema output then
+   * emits it once under `$defs` by this name and refers to it with `$ref`.
+   */
+  readonly identifier?: string;
+  /**
+   * The failure member's description, replacing the default one (which says
+   * that `ok: false` carries an expected error to branch on).
+   */
+  readonly description?: string;
+}
+/**
+ * The `ok: false` structured-outcome envelope: an expected error an agent
+ * should branch on, returned on a tool's success channel so it reaches the
+ * client as `structuredContent` instead of message text.
+ *
+ * @remarks
+ * Two channels, two jobs, one error shape:
+ *
+ * - {@link ToolRefusal} is a declared failure: the call itself was wrong, and
+ *   the agent reads one sentence (`isError: true`, message text only; core
+ *   never sends a failure's `structuredContent`).
+ * - `ToolOutcome` is an expected domain outcome: an id that does not exist, a
+ *   transition that is not allowed. The agent branches on its `_tag` and
+ *   fields (`isError: false`, `structuredContent` carries the envelope).
+ *
+ * Both carry {@link ToolFailure.fields} (`message`, `remediation`), so an error
+ * can move between channels without reshaping.
+ *
+ * Success members are not reshaped. Spread {@link ToolOutcome.ok} into each
+ * success struct so a client can discriminate on `ok`; a member that
+ * discriminates another way (`found: true | false`) stays legal.
+ *
+ * @example
+ * ```ts
+ * import { ToolOutcome } from "@effected/mcp-kit"
+ * import { Effect, Schema } from "effect"
+ * import { Tool } from "effect/ai"
+ *
+ * const NotFound = ToolOutcome.error("GoalNotFound", { id: Schema.Number })
+ * const Lookup = Tool.make("goal", {
+ * 	parameters: Schema.Struct({ id: Schema.Number }),
+ * 	success: ToolOutcome.envelope(Schema.Struct({ ...ToolOutcome.ok, goal: Goal }), [NotFound]),
+ * })
+ * // in the handler:
+ * findGoal(id).pipe(
+ * 	Effect.map((goal) => ({ ok: true as const, goal })),
+ * 	ToolOutcome.catchAsEnvelope({
+ * 		GoalNotFound: (e) => ({ id: e.id, message: `No goal ${e.id}.`, remediation: { hint: "List goals first.", suggestedTool: "goal" } }),
+ * 	}),
+ * )
+ * ```
+ *
+ * @public
+ */
+export declare class ToolOutcome {
+  private constructor();
+  /** `{ ok: true }` as schema fields, to spread into each success member. */
+  static readonly ok: {
+    readonly ok: Schema.Literal<true>;
+  };
+  /**
+   * The schema of one envelope error: `_tag`, {@link ToolFailure.fields} and
+   * `fields`. A field named `_tag`, `message` or `remediation` is rejected by
+   * the type, because it would replace the shared one.
+   */
+  static readonly error: <const Tag extends string, const Fields extends Schema.Struct.Fields = Record<never, never>>(tag: Tag, fields?: Fields & { readonly [K in "_tag" | "message" | "remediation"]?: never; }) => Schema.Struct<{
+    readonly _tag: Schema.Literal<Tag>;
+  } & typeof ToolFailure.fields & Fields>;
+  /**
+   * A tool's success schema: `success`, or `{ ok: false, error }` where `error`
+   * is one of `errors`. Object-rooted with {@link ToolOutputSchema.objectRooted},
+   * so core serves its `outputSchema` on every protocol revision.
+   *
+   * @remarks
+   * The failure member, its `ok` and its `error` carry default descriptions.
+   * `options` names the member (`identifier`, served once under `$defs`) or
+   * replaces its description.
+   */
+  static readonly envelope: <S extends Schema.Top, const Errors extends ReadonlyArray<Schema.Top>>(success: S, errors: Errors, options?: ToolOutcomeEnvelopeOptions) => Schema.Union<readonly [S, Schema.Struct<{
+    readonly ok: Schema.Literal<false>;
+    readonly error: Schema.Union<Errors>;
+  }>]>;
+  /** One `ok: false` value, for a handler that decides on a failure without catching an error. */
+  static readonly failure: <const Tag extends string, const I extends ToolOutcomeErrorInput>(tag: Tag, error: I) => ToolOutcomeFailure<Tag, I>;
+  /**
+   * Turns each handled tagged error into its `ok: false` value on the success
+   * channel; every other error stays in the error channel. Typed like core's
+   * `Effect.catchTags`: a case for a tag the effect cannot fail with is a type
+   * error, and the handled tags leave `E`.
+   *
+   * @remarks
+   * Write it inline in the effect's `pipe`. `E` is inferred from the effect
+   * being piped, so `effect.pipe(ToolOutcome.catchAsEnvelope({ … }))` checks
+   * every case name against the effect's real tags. Bound to a `const` first,
+   * the combinator never sees that effect: `E` infers as `unknown`, the
+   * unknown-tag check switches off, and a misspelled tag compiles and never
+   * matches. Core's `catchTags` looks a case up only among `cases`' own keys,
+   * so an error tagged `"toString"` or `"constructor"` never hits an inherited
+   * `Object.prototype` member and stays in the error channel.
+   */
+  static readonly catchAsEnvelope: <E, Cases extends { [K in Extract<E, {
+    readonly _tag: string;
+  }>["_tag"]]+?: (error: Extract<E, {
+    readonly _tag: K;
+  }>) => ToolOutcomeErrorInput; } & (unknown extends E ? Record<never, never> : { [K in Exclude<keyof Cases, Extract<E, {
+    readonly _tag: string;
+  }>["_tag"]>]: never; })>(cases: Cases) => <A, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A | ToolOutcomeFailures<Cases>, Exclude<E, {
+    readonly _tag: keyof Cases;
+  }>, R>;
+  /**
+   * Whether `value` is an `ok: false` envelope member: an object whose `ok` is
+   * exactly `false`. A success member that discriminates some other way, or a
+   * non-object, is not a failure. Narrows to `{ ok: false }` only: it checks
+   * the discriminant, not the `error` payload.
+   */
+  static readonly isFailure: (value: unknown) => value is {
+    readonly ok: false;
+  };
+}
+/**
+ * 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;
+}
+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 of a tool: any failure left undeclared loses its
+ * message on the wire, however carefully it was worded.
+ *
+ * **Structured data on a refusal is deliberately unreachable: put it in the
+ * message.** Core's `McpServer.registerToolkit` builds every failed call's
+ * result with `structuredContent` unset and no `_meta`, on every protocol
+ * revision. Under the default `failureMode: "error"` a declared `Error`
+ * failure sends `message` as the only text; under `failureMode: "return"`
+ * it sends the whole encoded failure JSON-stringified into the text, still
+ * with no `structuredContent`, which buries the human message in JSON a
+ * client must parse. So `refuse` takes no data argument: a list of valid
+ * names, the root that was searched, the id that was not found all belong
+ * in `reason`, truncated with {@link ToolFailure.truncate}. When an agent
+ * must branch on the data itself, return it on the success channel as an
+ * `ok: false` envelope, where `structuredContent` does reach the client.
+ *
+ * @example
+ * ```ts
+ * import { ToolFailure, ToolRefusal } from "@effected/mcp-kit";
+ * import { Tool } from "effect/ai";
+ *
+ * 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;
+}
+/**
+ * The narrow store {@link ToolReplay.wrap} reads and writes: `get` and `set`
+ * on string values, nothing else.
+ *
+ * @remarks
+ * Core's `KeyValueStore` already satisfies it structurally, so a
+ * `KeyValueStore` value can be passed as is. An application backed by its
+ * own table implements just these two methods, instead of stubbing the
+ * `remove`, `clear`, `size` and `keys` that `KeyValueStore.makeStringOnly` demands.
+ *
+ * `get` answers `undefined` for a missing key, the same contract as
+ * `KeyValueStore.get`. A failure from either method is never a tool error:
+ * a failed `get` is a miss and a failed `set` is a skipped write, both
+ * logged at debug level, so the error channel is `unknown`.
+ *
+ * @public
+ */
+interface ToolReplayStore {
+  /** The stored value for `key`, or `undefined` when nothing is stored under it. */
+  readonly get: (key: string) => Effect.Effect<string | undefined, unknown>;
+  /** Stores `value` under `key`, replacing any earlier value. */
+  readonly set: (key: string, value: string) => Effect.Effect<void, unknown>;
+}
+/**
+ * What {@link ToolReplay.wrap} needs to know about one tool.
+ *
+ * @typeParam Store - The type of {@link ToolReplayOptions.store}; when it is
+ * omitted, `wrap` requires `KeyValueStore` in `R` instead.
+ *
+ * @public
+ */
+interface ToolReplayOptions<P, S extends Schema.Top, Store extends ToolReplayStore | undefined = undefined> {
+  /** The served tool name. It must not contain `:`, the separator of the stored key ({@link ToolReplay.storeKey}). */
+  readonly tool: string;
+  /**
+   * The tool's success schema. Results are stored encoded through it and
+   * decoded through it on replay. It must declare {@link ToolReplay.marker} on
+   * each object member, or core's encoder drops the marker from the reply:
+   * build each member with {@link ToolReplay.success} so it cannot be left out.
+   */
+  readonly success: S;
+  /**
+   * The idempotency key for one call; `Option.none()` runs the handler with
+   * nothing stored or replayed.
+   *
+   * @remarks
+   * The key must identify the request completely. A replay compares nothing
+   * else: not the params, not the schema version. So a reused key with
+   * different params returns the FIRST call's result. When the params under
+   * one caller-supplied id can vary, fold a digest of them into the key.
+   */
+  readonly key: (params: P) => Option.Option<string>;
+  /**
+   * Where results are stored. Omitted, `wrap` reads core's `KeyValueStore`
+   * from `R`; given, it uses this store and `KeyValueStore` leaves `R`.
+   */
+  readonly store?: Store;
+}
+/**
+ * Idempotent replay for a write tool: a repeated call with the same key returns
+ * the first call's stored result, marked `_idempotentReplay: true`, instead of
+ * running the mutation again.
+ *
+ * @remarks
+ * The store is core's `KeyValueStore` (`effect/persistence`), required in `R`
+ * (`KeyValueStore.layerMemory`, `layerFileSystem` or `layerSql`), unless
+ * {@link ToolReplayOptions.store} supplies a {@link ToolReplayStore}: just
+ * `get` and `set`, for an application's own table. Then `R` carries no
+ * `KeyValueStore`.
+ *
+ * Inside an MCP server, pass the store. A service left in a handler's `R`
+ * has to be declared in the tool's `dependencies`, which makes it a
+ * request-level dependency that only MCP middleware can meet. Read
+ * `KeyValueStore` once when the handlers are built, with the effect form of
+ * `Toolkit.toLayer`, and hand it to `wrap` as `store`: a `KeyValueStore`
+ * satisfies {@link ToolReplayStore} as is.
+ *
+ * Semantics, per call:
+ *
+ * - A key of `Option.none()` runs the handler; nothing is read or stored.
+ * - A stored value that decodes through `success` is returned with the marker,
+ *   and the handler does not run.
+ * - A miss runs the handler and stores its result, best-effort. A store that
+ *   fails, a row that no longer decodes (written under an older schema, or
+ *   corrupt), and a failed write are each a miss or a skipped write, never a
+ *   tool error. Each is logged at debug level with the tool name.
+ * - A handler failure stores nothing, so a retry runs it again.
+ * - An `ok: false` result (a {@link ToolOutcome} envelope failure) is never
+ *   stored: a "not found" must not replay after the thing exists.
+ *
+ * This is replay, not exactly-once: two concurrent calls with one key both
+ * miss and both run.
+ *
+ * The key is the whole identity of a request. A hit compares neither the
+ * params nor the schema version (a row written under an older schema replays
+ * whenever it still decodes), and rows never expire: the store keeps a result
+ * until something removes it. A key reused with different params therefore
+ * replays the first result, so {@link ToolReplayOptions.key} must fold in a
+ * digest of any params that can vary under one id.
+ *
+ * Wrap it inside {@link ToolOutcome.catchAsEnvelope}, so the envelope sees the
+ * handler's real errors and replay sees only real successes.
+ *
+ * @example
+ * ```ts
+ * import { ToolReplay } from "@effected/mcp-kit"
+ * import { Option, Schema } from "effect"
+ *
+ * const Created = ToolReplay.success(Schema.Struct({ ok: Schema.Literal(true), id: Schema.Number }))
+ * const create = ToolReplay.wrap({
+ * 	tool: "goal_create",
+ * 	success: Created,
+ * 	key: (params: { readonly requestId?: string }) => Option.fromUndefinedOr(params.requestId),
+ * })(createGoal)
+ * ```
+ *
+ * @public
+ */
+export declare class ToolReplay {
+  private constructor();
+  /**
+   * The marker field, to spread into each object member of a replayable
+   * success schema. {@link ToolReplay.success} adds it for you.
+   */
+  static readonly marker: {
+    readonly _idempotentReplay: Schema.optionalKey<Schema.Literal<true>>;
+  };
+  /**
+   * A struct with {@link ToolReplay.marker} added. Use it for each object
+   * success member, so core's encoder keeps the marker on a replayed reply.
+   *
+   * @remarks
+   * Built with core's `fieldsAssign`, which, like `mapFields`, does not carry
+   * the struct's own `.check(...)` refinements over: apply checks to the
+   * result, not to the struct passed in.
+   */
+  static readonly success: <const Fields extends Schema.Struct.Fields>(schema: Schema.Struct<Fields>) => Schema.Struct<Struct.Simplify<Struct.Assign<Fields, typeof ToolReplay.marker>>>;
+  /**
+   * The `KeyValueStore` key one call is stored under: `<tool>:<key>`. Split on
+   * the first `:` to recover both parts; MCP tool names are `[A-Za-z0-9_.-]`.
+   */
+  static readonly storeKey: (tool: string, key: string) => string;
+  /**
+   * Wraps a handler with replay. Throws at wrap time when `tool` contains
+   * `:`, a wiring mistake, so it surfaces when the server is built.
+   *
+   * @remarks
+   * Call it where the handler is built, once: the effect form of
+   * `Toolkit.toLayer`, reading the store's services there and passing them as
+   * `store`. Calling it per request, inside the handler, rebuilds the JSON
+   * codec on every call and turns the wiring check's throw into a defect at
+   * the first call instead of a failure when the server is built.
+   */
+  static readonly wrap: <P, S extends Schema.Top, Store extends ToolReplayStore | undefined = undefined>(options: ToolReplayOptions<P, S, Store>) => (<E, R>(handler: (params: P) => Effect.Effect<S["Type"], E, R>) => (params: P) => Effect.Effect<S["Type"], E, R | ([Store] extends [ToolReplayStore] ? never : KeyValueStore.KeyValueStore) | S["DecodingServices"] | S["EncodingServices"]>);
+}
+export type { FormatUnknownKeysOptions, McpLaunchOptions, McpStdioOptions, McpStdioRegistrationServices, McpToolkitOptions, ToolOutcomeEnvelopeOptions, ToolOutcomeErrorInput, ToolOutcomeFailure, ToolOutcomeFailures, ToolReplayOptions, ToolReplayStore, UnionHandlerOptions, UnionTool, UnionToolOptions, UnknownKeysLevel };
+//# sourceMappingURL=index.d.ts.map