@effected/mcp 0.1.0 → 0.2.0

package/ToolOutputSchema.js

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

package/ToolRefusal.js

@@ -0,0 +1,42 @@
+import { ToolFailure } from "./ToolFailure.js";
+import { Schema } from "effect";
+
+//#region src/ToolRefusal.ts
+/**
+* A tool call refused for a reason the caller can fix: the kit's ready-made
+* declared failure, built on {@link ToolFailure.fields}.
+*
+* @remarks
+* Core scrubs every undeclared failure and every defect to one generic
+* internal-error sentence, so a refusal the agent must act on (an unknown id,
+* a missing argument, a precondition) reaches it only when the tool declares
+* it. Declare `ToolRefusal` in the tool's `failure` schema and fail with
+* {@link ToolRefusal.refuse}; its message already carries the remediation,
+* because a declared `Error` failure sends `message` and nothing else.
+*
+* Audit every throw path when porting a tool: any failure left undeclared
+* loses its message on the wire, however carefully it was worded.
+*
+* @example
+* ```ts
+* const Lookup = Tool.make("lookup", { parameters, success, failure: ToolRefusal })
+* // in the handler:
+* return yield* ToolRefusal.refuse(`No run "${ToolFailure.truncate(id)}".`, { hint: "List runs first.", suggestedTool: "list_runs" })
+* ```
+*
+* @public
+*/
+var ToolRefusal = class ToolRefusal extends Schema.TaggedError()("ToolRefusal", ToolFailure.fields) {
+	/**
+	* A refusal for `reason`, with `remediation` folded into its message by
+	* {@link ToolFailure.message}. `reason` must already truncate any
+	* caller-supplied value it echoes, with {@link ToolFailure.truncate}.
+	*/
+	static refuse = (reason, remediation) => new ToolRefusal({
+		message: ToolFailure.message(reason, remediation),
+		remediation
+	});
+};
+
+//#endregion
+export { ToolRefusal };

package/guard.d.ts

@@ -0,0 +1,157 @@
+import { Effect, Layer, Runtime } from "effect";
+//#region src/McpGuard.d.ts
+/**
+ * The slice of the host process the guard uses. Node's `process` satisfies it.
+ *
+ * @public
+ */
+interface McpGuardHost {
+  /** Register the `uncaughtException` listener. */
+  on(event: "uncaughtException", listener: (error: Error, origin: string) => void): unknown;
+  /** Register the `unhandledRejection` listener. */
+  on(event: "unhandledRejection", listener: (reason: unknown) => void): unknown;
+  /** Raise an `uncaughtException` to the registered listeners. Used only by {@link McpGuardRunOptions.injectCrash}. */
+  emit(event: "uncaughtException", error: Error, origin: "uncaughtException" | "unhandledRejection"): unknown;
+  /** Raise an `unhandledRejection` to the registered listeners. Used only by {@link McpGuardRunOptions.injectCrash}. */
+  emit(event: "unhandledRejection", reason: unknown, promise: Promise<unknown>): unknown;
+  /** Where every guard report is written. Never stdout: that is the JSON-RPC wire. */
+  readonly stderr: {
+    write(chunk: string): unknown;
+  };
+  /** End the process at once. */
+  exit(code?: number): never;
+}
+/**
+ * When a stray exception or rejection ends the process.
+ *
+ * @remarks
+ * `"exit"` exits 1 whenever it happens. `"exitBeforeConnect"` exits 1 until
+ * the server is serving, then logs and keeps serving: a server that dies
+ * mid-session deregisters every tool from the client. `"log"` never exits.
+ *
+ * @public
+ */
+interface McpGuardPolicy {
+  /** For `uncaughtException`. */
+  readonly onUncaught: "exit" | "exitBeforeConnect";
+  /** For `unhandledRejection`. Defaults to `"exit"`. */
+  readonly onRejection?: "exit" | "exitBeforeConnect" | "log" | undefined;
+}
+/**
+ * What {@link McpGuardRunOptions.load} resolves to: the server and the
+ * platform runner to launch it with.
+ *
+ * @public
+ */
+interface McpGuardedServer<ROut, E> {
+  /** The whole server layer, stdio included, with nothing left to provide. */
+  readonly layer: Layer.Layer<ROut, E, never>;
+  /** The platform's `runMain`, such as `NodeRuntime.runMain` from `@effect/platform-node`. */
+  readonly runMain: (effect: Effect.Effect<never, Error>, options: {
+    readonly teardown: Runtime.Teardown;
+  }) => void;
+  /** Formats a reported error from here on; the guard's own dependency-free formatter until then. */
+  readonly format?: ((error: unknown) => string) | undefined;
+}
+/**
+ * Options for {@link McpGuard.run}.
+ *
+ * @public
+ */
+interface McpGuardRunOptions<ROut, E> {
+  /** Prefixes every report the guard writes, as in `my-server: uncaughtException (…): …`. */
+  readonly label: string;
+  /** The process: pass `process`. */
+  readonly host: McpGuardHost;
+  /** Defaults to `{ onUncaught: "exit", onRejection: "exit" }`. */
+  readonly policy?: McpGuardPolicy | undefined;
+  /**
+   * Import and assemble the server. Everything that can throw while loading
+   * belongs here, behind a dynamic `import()`, so the guards are already
+   * listening when it runs.
+   */
+  readonly load: () => Promise<McpGuardedServer<ROut, E>>;
+  /**
+   * For a test of the guards themselves: raise one stray `kind` at `at`, so
+   * both halves of a policy can be driven end to end in a real process.
+   *
+   * @remarks
+   * - `"load"` raises it once both listeners are installed and before
+   *   `load()` is called, then waits for the guard to handle it: `load()`
+   *   is not called until the listener has run. If a test double's `exit`
+   *   throws instead of ending the process, `run` rejects with what it
+   *   threw and never calls `load()`. The pre-connect half of
+   *   the policy applies, so `"exitBeforeConnect"` exits 1 here, and only
+   *   an `onRejection` of `"log"` lets the process go on to load and serve.
+   *   The report uses the guard's own formatter, since no `format` is
+   *   loaded yet.
+   * - `"connected"` raises it on a timer right after the server is
+   *   serving, where `"exitBeforeConnect"` logs and keeps serving. A throw
+   *   from a test double's `exit` there is dropped.
+   *
+   * Either is raised only through `host.emit`, on a `setTimeout(0)` tick,
+   * never as a real throw or rejection, so the guard's listeners handle it
+   * the same way under the real `process` and under a test double. Under
+   * `process`, every listener registered for the event sees it, not only
+   * the guard's. It carries an `[injected]` message; a rejection is emitted
+   * with an already-handled rejected promise. `undefined`, or
+   * an `at` or `kind` outside these values, does nothing at all. Wire it to
+   * an environment variable only a test sets.
+   */
+  readonly injectCrash?: {
+    readonly at: "load" | "connected";
+    readonly kind: "uncaughtException" | "unhandledRejection";
+  } | undefined;
+}
+/**
+ * Crash guards for an MCP server process, installed before the server's
+ * module graph is loaded. Imported from `@effected/mcp/guard`.
+ *
+ * @remarks
+ * {@link McpGuard.run} registers `uncaughtException` and `unhandledRejection`
+ * listeners on `host`, then awaits `load()`, then launches the server with
+ * `McpStdio.launch` and `McpStdio.teardown` under the `runMain` it returned.
+ * This entrypoint has no static runtime import: it loads `effect` and the
+ * stdio wiring only after the guards are listening, so a throw while any of
+ * it evaluates is still reported on stderr.
+ *
+ * - "Connected" means the whole server layer has built, so stdin is being
+ *   read. That is before any client sends `initialize`.
+ * - `injectCrash` drives either half of the policy from a test, before
+ *   `load()` or once connected; unset, it does nothing.
+ * - A `load()` that rejects is reported as `startup failed` and exits 1
+ *   whatever the policy. Left to a log-only rejection listener, it would
+ *   let the event loop drain and exit 0 with no server.
+ * - Installing an `unhandledRejection` listener switches off Node's default
+ *   of throwing on one, so `"log"` really does keep the process running.
+ * - An exit from a guard skips Effect's finalizers and the teardown.
+ * - Keeping on serving after a crash works because the platform `runMain`
+ *   holds the process open while the server fiber lives.
+ * - A layer that fails to build is still reported by `McpStdio.launch`.
+ *
+ * @example
+ * ```ts
+ * import { McpGuard } from "@effected/mcp/guard";
+ *
+ * await McpGuard.run({
+ *   label: "my-server",
+ *   host: process,
+ *   policy: { onUncaught: "exitBeforeConnect", onRejection: "log" },
+ *   load: async () => {
+ *     const { NodeRuntime } = await import("@effect/platform-node");
+ *     const { Main } = await import("./server.js");
+ *     return { layer: Main, runMain: NodeRuntime.runMain };
+ *   },
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare class McpGuard {
+  private constructor();
+  /** Install the guards, load the server, and launch it. Resolves once the server is launched. */
+  static readonly run: <ROut, E>(options: McpGuardRunOptions<ROut, E>) => Promise<void>;
+}
+//#endregion
+export type { McpGuardHost, McpGuardPolicy, McpGuardRunOptions, McpGuardedServer };
+//# sourceMappingURL=guard.d.ts.map

package/guard.js

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

package/index.d.ts

@@ -1,4 +1,4 @@
-import { Array, Effect, JsonSchema, Layer, Runtime, Schema, Stdio } from "effect";
+import { Array, Context, Effect, JsonSchema, Layer, Runtime, Schema, Stdio } from "effect";
 import { McpProtocol, McpSchema, McpServer, Tool, Toolkit } from "effect/unstable/ai";
 import { Remediation } from "@effected/engine";
 //#region src/McpStdio.d.ts
@@ -19,6 +19,26 @@ interface McpStdioOptions {
   /** Defaults to {@link McpStdio.protocols}. Read its ordering rules before overriding. */
   readonly protocols?: Array.NonEmptyReadonlyArray<McpProtocol.ProtocolAdapter> | undefined;
 }
+/**
+ * Options for {@link McpStdio.launch}.
+ *
+ * @public
+ */
+interface McpLaunchOptions {
+  /**
+   * Runs once the whole layer has built, and before the launch waits
+   * forever. By then the stdio protocol is reading stdin: the server is
+   * serving, although no client may have sent `initialize` yet.
+   *
+   * @remarks
+   * `McpGuard.run` (`@effected/mcp/guard`) uses it as its "connected"
+   * signal. A layer built after the server layer, as in
+   * `Layer.effectDiscard(ready).pipe(Layer.provide(Main))`, gives the same
+   * signal, but only if every consumer re-derives that `Layer.provide`
+   * builds its dependency first.
+   */
+  readonly onReady?: Effect.Effect<void> | undefined;
+}
 /**
  * Serve an MCP server over stdio without ever writing a log line or a failure
  * report onto stdout, which is the JSON-RPC wire.
@@ -107,8 +127,12 @@ export declare class McpStdio {
    * one graph does that, and so does building or providing the second
    * anywhere under the first one's `Effect.provide`: nested `Layer.build`
    * and `Effect.provide` fork the ambient memo map rather than starting a
-   * new one. Isolate each server with its own `ManagedRuntime`,
-   * `Effect.provide(layer, { local: true })` or its own process.
+   * new one. The tool registry is shared the same way. Isolate each server
+   * by wrapping its whole bundle (its toolkit layers together with this
+   * layer) in `Layer.fresh`, or with its own `ManagedRuntime`,
+   * `Effect.provide(layer, { local: true })` or its own process. Never put
+   * the `Layer.fresh` boundary between a toolkit and this layer: the server
+   * would serve an empty registry.
    *
    * Code after a completed `Effect.provide` of a stdio server never runs:
    * core's stdio protocol interrupts the fiber that built it when its stdin
@@ -129,8 +153,11 @@ export declare class McpStdio {
    * `Effect.provideService` reaches, and Effect's default logger writes
    * through `console.log` unless `LogToStderr` is set. For an MCP server
    * that is stdout, which is the wire.
+   *
+   * `options.onReady` runs after the layer has built and before the launch
+   * waits forever, as {@link McpLaunchOptions.onReady} describes.
    */
-  static readonly launch: <ROut, E, R>(layer: Layer.Layer<ROut, E, R>) => Effect.Effect<never, Error, R>;
+  static readonly launch: <ROut, E, R>(layer: Layer.Layer<ROut, E, R>, options?: McpLaunchOptions) => Effect.Effect<never, Error, R>;
   /**
    * Success or an interrupt-only exit maps to 0. Anything else goes to
    * `Runtime.defaultTeardown`.
@@ -239,6 +266,61 @@ interface McpToolkitOptions {
    */
   readonly unknownKeyMessage?: ((levels: ReadonlyArray<UnknownKeysLevel>) => string) | undefined;
 }
+/**
+ * A `Tool.dynamic` made by {@link McpToolkit.unionTool}: served with the
+ * strict, object-rooted JSON Schema of a `Schema.Union` of objects, and
+ * carrying that union so {@link McpToolkit.unionHandler} can decode it.
+ *
+ * @remarks
+ * `annotate` and `addDependency` keep the type, so a chained
+ * `.annotate(Tool.Title, …)` still hands `unionHandler` the union. The
+ * declared failure is `failure` together with `McpSchema.InvalidParams`.
+ *
+ * @public
+ */
+interface UnionTool<Name extends string, P extends Schema.Decoder<unknown>, S extends Schema.Constraint, F extends Schema.Constraint, R = never> extends Tool.Dynamic<Name, {
+  readonly parameters: JsonSchema.JsonSchema;
+  readonly success: S;
+  readonly failure: Schema.Union<readonly [F, typeof McpSchema.InvalidParams]>;
+  readonly failureMode: "error";
+}, R> {
+  /** The union the tool decodes its arguments with. */
+  readonly unionParameters: P;
+  /** Add an annotation, keeping the union. */
+  annotate<I, V>(tag: Context.Key<I, V>, value: V): UnionTool<Name, P, S, F, R>;
+  /** Add a request-level dependency, keeping the union. */
+  addDependency<Identifier, Service>(tag: Context.Key<Identifier, Service>): UnionTool<Name, P, S, F, Identifier | R>;
+}
+/**
+ * Options for {@link McpToolkit.unionTool}.
+ *
+ * @public
+ */
+interface UnionToolOptions<P extends Schema.Decoder<unknown>, S extends Schema.Constraint, F extends Schema.Constraint, Dependencies extends ReadonlyArray<Context.Key<unknown, unknown>>> {
+  /** What the tool does, for the agent. */
+  readonly description?: string | undefined;
+  /** A `Schema.Union` of object schemas, discriminated by an `action`, `kind`, `_tag` or `type` literal. */
+  readonly parameters: P;
+  /** The success schema. Defaults to `Schema.Void`; object-root a union whose members are all objects with `ToolOutputSchema.objectRooted`. */
+  readonly success?: S | undefined;
+  /** Declared failures besides `InvalidParams`, such as `ToolRefusal`. Defaults to `Schema.Never`. */
+  readonly failure?: F | undefined;
+  /** Services the handler needs, as with `Tool.make`. */
+  readonly dependencies?: Dependencies | undefined;
+}
+/**
+ * Options for {@link McpToolkit.unionHandler}.
+ *
+ * @public
+ */
+interface UnionHandlerOptions {
+  /**
+   * Replaces the default `ToolInputSchema.formatUnknownKeys` rendering, as
+   * {@link McpToolkitOptions.unknownKeyMessage} does for the layer. Pass the
+   * same function to both for one report on every path.
+   */
+  readonly unknownKeyMessage?: ((levels: ReadonlyArray<UnknownKeysLevel>) => string) | undefined;
+}
 /**
  * Register a toolkit exactly as core's `McpServer.toolkit` does, except that a
  * strict tool's unknown arguments are all named, at every depth, in one
@@ -271,6 +353,8 @@ interface McpToolkitOptions {
  * shared by reference with `McpStdio.layer`'s own copy — provide both into
  * the same graph, as with `McpServer.toolkit`. Never wrap that layer in
  * `Layer.fresh`: tools would register into a second registry nobody serves.
+ * To give two servers separate registries, wrap each whole bundle (this
+ * layer together with `McpStdio.layer`) in `Layer.fresh` instead.
  *
  * Each call mints a fresh layer; bind the result to a `const` or the
  * registration runs twice.
@@ -288,6 +372,60 @@ interface McpToolkitOptions {
  */
 export declare class McpToolkit {
   private constructor();
+  /**
+   * A tool whose parameters are a `Schema.Union` of objects, which
+   * `Tool.make` cannot take: core dies at registration on a non-object
+   * `parameters` root.
+   *
+   * @remarks
+   * The tool is a `Tool.dynamic` served with Effect's strict JSON Schema
+   * document for `parameters` (`additionalProperties: false` on every
+   * object node, definitions as `$defs`), rewritten by
+   * `ToolInputSchema.objectRooted` to an object root carrying `type`,
+   * `oneOf` and `x-discriminator`. Write its handler with
+   * {@link McpToolkit.unionHandler}, which receives the decoded member.
+   *
+   * Registered through {@link McpToolkit.layer}, a union tool gets the same
+   * treatment as a strict `Tool.make` tool: every unknown key named in one
+   * `InvalidParams`, then a strict decode, both before the handler runs, so
+   * bad arguments answer JSON-RPC `-32602` on `2025-06-18` and an `isError`
+   * result on the later revisions, exactly as a `Tool.make` decode failure
+   * does. Registered through core's `McpServer.toolkit` it still decodes
+   * strictly, in the handler, but the `InvalidParams` is then a declared
+   * failure: an `isError` result on every revision.
+   *
+   * Never annotate it `Tool.Strict` true: core dies at registration on a
+   * strict tool with a raw JSON Schema.
+   *
+   * @example
+   * ```ts
+   * const Note = McpToolkit.unionTool("note", {
+   *   parameters: Schema.Union([AddNote, ListNotes]),
+   *   success: ToolOutputSchema.objectRooted(Schema.Union([Added, Listed])),
+   *   failure: ToolRefusal,
+   * }).annotate(Tool.Title, "Note")
+   * const handlers = Kit.toLayer({ note: McpToolkit.unionHandler(Note, (params) => handleNote(params)) })
+   * ```
+   */
+  static readonly unionTool: <const Name extends string, P extends Schema.Decoder<unknown>, S extends Schema.Constraint = typeof Schema.Void, F extends Schema.Constraint = typeof Schema.Never, const Dependencies extends ReadonlyArray<Context.Key<unknown, unknown>> = []>(name: Name, options: UnionToolOptions<P, S, F, Dependencies>) => UnionTool<Name, P, S, F, Context.Service.Identifier<Dependencies[number]>>;
+  /**
+   * The handler for a {@link McpToolkit.unionTool}: checks and decodes the
+   * raw payload exactly as {@link McpToolkit.layer} does, and passes the
+   * decoded member to `handler`.
+   *
+   * @remarks
+   * A payload carrying unknown keys fails with one `McpSchema.InvalidParams`
+   * naming every one of them, at every depth, in the
+   * `ToolInputSchema.formatUnknownKeys` report (or `options.unknownKeyMessage`'s),
+   * walked over the tool's served input schema. A payload that then does
+   * not decode fails `InvalidParams` worded as core words a `Tool.make`
+   * decode failure. It is the same implementation the layer runs, so a
+   * handler called directly (a test helper, or a toolkit registered through
+   * core's `McpServer.toolkit`) reports what a client of the layer sees.
+   * Under {@link McpToolkit.layer} the layer has already rejected a bad
+   * call before the handler runs, and its own `unknownKeyMessage` wins.
+   */
+  static readonly unionHandler: <Name extends string, P extends Schema.Decoder<unknown>, S extends Schema.Constraint, F extends Schema.Constraint, R, A, E, RH>(tool: UnionTool<Name, P, S, F, R>, handler: (params: P["Type"]) => Effect.Effect<A, E, RH>, options?: UnionHandlerOptions) => ((payload: unknown) => Effect.Effect<A, E | McpSchema.InvalidParams, RH>);
   /**
    * `McpServer.toolkit`'s registration layer, strict by default and naming
    * every unknown argument in one `InvalidParams`.
@@ -309,7 +447,13 @@ export declare class McpToolkit {
  *
  * Spread {@link ToolFailure.fields} into your tool's `Schema.TaggedError`, build
  * `message` with {@link ToolFailure.message}, and pass every caller-supplied
- * value through {@link ToolFailure.truncate} before echoing it.
+ * value through {@link ToolFailure.truncate} before echoing it. For a plain
+ * refusal with no fields of its own, `ToolRefusal` is this shape ready-made.
+ *
+ * Only a declared failure keeps its message: core scrubs an undeclared
+ * failure or a defect to "Tool execution failed due to an internal server
+ * error.", so audit every throw path a tool can take and declare each one the
+ * agent should read.
  *
  * @example
  * ```ts
@@ -348,5 +492,97 @@ export declare class ToolFailure {
   static readonly truncate: (value: string, limit?: number) => string;
 }
 //#endregion
-export type { FormatUnknownKeysOptions, McpStdioOptions, McpToolkitOptions, UnknownKeysLevel };
+//#region src/ToolOutputSchema.d.ts
+/**
+ * Shaping for a tool's `success` schema, so the `outputSchema` core serves
+ * is one every client accepts.
+ *
+ * @remarks
+ * MCP requires a tool's `outputSchema` to be rooted in an object, and a
+ * top-level `Schema.Union` emits a bare `anyOf`. Core drops such an
+ * `outputSchema` from `tools/list` on the stateful revisions and serves it
+ * verbatim on the stateless one, where strict clients reject it.
+ * `McpToolAudit`'s `objectRootedOutput` check reports it either way.
+ *
+ * {@link ToolOutputSchema.objectRooted} is the fix when every member of the
+ * union is an object shape; never apply it to a union with a primitive or
+ * array member. It works on the Effect
+ * schema, not on JSON Schema — unlike `ToolInputSchema.objectRooted`, which
+ * rewrites the served input document of a `Tool.dynamic`.
+ *
+ * @public
+ */
+export declare class ToolOutputSchema {
+  private constructor();
+  /**
+   * `schema` with `type: "object"` added beside the `anyOf` at its JSON
+   * Schema root, through a check that always passes. Decoding, encoding and
+   * the schema's type are unchanged.
+   *
+   * @remarks
+   * Order against `.annotate({ identifier })` does not matter. A check added
+   * after an identifier starts a new node that would drop the definition
+   * name, so the identifier the schema already resolves is carried onto the
+   * new check, and the served documents are equal either way (key order
+   * can differ when the schema carries a title or description). Applying it
+   * twice is a no-op.
+   *
+   * Every union member must be an object shape: the added `type: "object"`
+   * is a claim about the whole union, and nothing checks it. Do not use it
+   * on a union with a primitive or array member — the served schema would
+   * contradict the values the tool returns; give such a tool an object
+   * envelope instead.
+   *
+   * @example
+   * ```ts
+   * const Result = ToolOutputSchema.objectRooted(Schema.Union([Found, Missing])).annotate({ identifier: "Result" })
+   * Tool.make("lookup", { parameters, success: Result })
+   * ```
+   */
+  static readonly objectRooted: <S extends Schema.Top>(schema: S) => S;
+}
+//#endregion
+//#region src/ToolRefusal.d.ts
+declare const ToolRefusal_base: Schema.Class<ToolRefusal, Schema.TaggedStruct<"ToolRefusal", {
+  readonly message: Schema.String;
+  readonly remediation: Schema.Struct<{
+    readonly hint: Schema.String;
+    readonly suggestedTool: Schema.optionalKey<Schema.String>;
+    readonly suggestedArgs: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
+  }>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A tool call refused for a reason the caller can fix: the kit's ready-made
+ * declared failure, built on {@link ToolFailure.fields}.
+ *
+ * @remarks
+ * Core scrubs every undeclared failure and every defect to one generic
+ * internal-error sentence, so a refusal the agent must act on (an unknown id,
+ * a missing argument, a precondition) reaches it only when the tool declares
+ * it. Declare `ToolRefusal` in the tool's `failure` schema and fail with
+ * {@link ToolRefusal.refuse}; its message already carries the remediation,
+ * because a declared `Error` failure sends `message` and nothing else.
+ *
+ * Audit every throw path when porting a tool: any failure left undeclared
+ * loses its message on the wire, however carefully it was worded.
+ *
+ * @example
+ * ```ts
+ * const Lookup = Tool.make("lookup", { parameters, success, failure: ToolRefusal })
+ * // in the handler:
+ * return yield* ToolRefusal.refuse(`No run "${ToolFailure.truncate(id)}".`, { hint: "List runs first.", suggestedTool: "list_runs" })
+ * ```
+ *
+ * @public
+ */
+export declare class ToolRefusal extends ToolRefusal_base {
+  /**
+   * A refusal for `reason`, with `remediation` folded into its message by
+   * {@link ToolFailure.message}. `reason` must already truncate any
+   * caller-supplied value it echoes, with {@link ToolFailure.truncate}.
+   */
+  static readonly refuse: (reason: string, remediation: Remediation) => ToolRefusal;
+}
+//#endregion
+export type { FormatUnknownKeysOptions, McpLaunchOptions, McpStdioOptions, McpToolkitOptions, UnionHandlerOptions, UnionTool, UnionToolOptions, UnknownKeysLevel };
 //# sourceMappingURL=index.d.ts.map

package/index.js

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

package/internal/guardLaunch.js

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

package/package.json

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