@effected/mcp-kit 0.0.0-stage → 0.14.0

package/StdioCapture.js

@@ -0,0 +1,146 @@
+import { Effect, Fiber } from "effect";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { Writable } from "node:stream";
+
+// src/StdioCapture.ts
+/**
+* One registry per process, shared by every installed copy of this package
+* through a `Symbol.for` key on `globalThis`, so two copies never stack
+* patches or split the context they route on.
+*/
+const registry = (() => {
+	const key = Symbol.for("@effected/mcp-kit/StdioCapture");
+	const global = globalThis;
+	global[key] ??= {
+		storage: new AsyncLocalStorage(),
+		originals: /* @__PURE__ */ new WeakMap()
+	};
+	return global[key];
+})();
+/** Patches `stream` once and returns its original `write`; a stream already patched keeps its first patch. */
+const patch = (stream, pick) => {
+	const known = registry.originals.get(stream);
+	if (known !== void 0) return known;
+	const original = stream.write;
+	registry.originals.set(stream, original);
+	const { storage } = registry;
+	stream.write = function capturedWrite() {
+		const options = storage.getStore();
+		const sink = options === void 0 ? void 0 : pick(options);
+		return sink === void 0 ? original.apply(this, arguments) : sink.write.apply(sink, arguments);
+	};
+	return original;
+};
+const callbackOf = (rest) => {
+	const last = rest.at(-1);
+	return typeof last === "function" ? last : void 0;
+};
+/**
+* Diverts a host's stdout (and optionally stderr) writes to a sink, for code
+* running inside one async context only, while every other context keeps
+* writing to the real streams.
+*
+* @remarks
+* For an MCP server over stdio, stdout is the JSON-RPC wire. A chatty library
+* run in-process (a test runner, a bundler, a linter) must keep its output off
+* it while other handlers, and the transport itself, keep writing normally.
+*
+* `install` patches the host's `write` methods once, keeping the unbound
+* originals, and routes every write through an `AsyncLocalStorage`: inside a
+* {@link StdioCapture.run} or {@link StdioCapture.capture} context a write goes
+* to that context's sink, and outside it to the original stream.
+*
+* An Effect fiber resumes in the async context it suspended in, not the
+* context of whatever woke it, so a server fiber woken by code inside a
+* capture (its response written to a queue, say) keeps writing to the wire.
+*
+* Two kinds of write escape a capture and reach the original stream:
+*
+* - **Writes from a context the capture lost.** Callbacks registered outside the
+*   capture keep the context they were registered in: native addons, worker
+*   thread output relayed by the main thread, listeners on a child process's
+*   pipes attached earlier. On stdout, that is the wire.
+* - **Fibers started inside the capture keep capturing after it ends.** A fiber
+*   forked inside it (`Effect.forkDetach`, a memoized layer first built inside
+*   it, a background fiber a library starts) keeps writing to the sink, even
+*   after the capture's own work is done.
+*
+* @example
+* ```ts
+* import { StdioCapture } from "@effected/mcp-kit/node"
+*
+* const capture = StdioCapture.install(process)
+* // in a tool handler: keep the runner's own console output off the wire
+* const report = yield* runTests(files).pipe(capture.capture({ stdout: capture.toStderr }))
+* ```
+*
+* @public
+*/
+var StdioCapture = class StdioCapture {
+	/** A sink that writes through the host's original, unpatched stderr: captured output stays visible off the wire. */
+	toStderr;
+	constructor(toStderr) {
+		this.toStderr = toStderr;
+	}
+	/**
+	* Patches `host`'s two streams. Idempotent per stream, across every installed
+	* copy of this package: a stream already patched (through another host
+	* object, or another copy) keeps its one patch and its original `write`.
+	*/
+	static install = (host) => {
+		patch(host.stdout, (options) => options.stdout);
+		const stderr = patch(host.stderr, (options) => options.stderr);
+		return new StdioCapture({ write: (...args) => stderr.apply(host.stderr, args) });
+	};
+	/**
+	* A write-only sink that drops every write and calls the write's callback.
+	*
+	* @remarks
+	* It is a {@link StdioSink}, not a stream: it has no `on`, `pipe` target
+	* protocol or `setMaxListeners`, so it cannot stand in where a library
+	* expects a `Writable` (a test runner's logger stream that worker output
+	* is piped into, for one). Use {@link StdioCapture.nullWritable} there; it
+	* serves as a capture sink too.
+	*/
+	static discard = { write: (_chunk, ...rest) => {
+		const callback = callbackOf(rest);
+		if (callback !== void 0) queueMicrotask(callback);
+		return true;
+	} };
+	/**
+	* A new Node `Writable` that drops everything written to it: a real stream,
+	* so it works as a `pipe` target, takes `setMaxListeners`, emits `drain`
+	* and `finish`, and is also a {@link StdioSink} for a capture.
+	*
+	* @remarks
+	* A factory, not a shared value: a stream ends once, and a source piped in
+	* with the default `{ end: true }` ends its destination. Build one per
+	* consumer.
+	*/
+	static nullWritable = () => new Writable({
+		decodeStrings: false,
+		write: (_chunk, _encoding, callback) => callback()
+	});
+	/**
+	* Runs `evaluate` with its writes captured, for code that is not Effect.
+	* A synchronous throw from `evaluate` rejects the returned promise.
+	*/
+	run(options, evaluate) {
+		return registry.storage.run(options, async () => evaluate());
+	}
+	/**
+	* Runs an effect with its writes captured: on its own fiber, started inside
+	* the capture's context, so the context survives every suspension of that
+	* fiber. Interrupting the returned effect interrupts that fiber and waits
+	* for it.
+	*/
+	capture(options) {
+		const { storage } = registry;
+		return (self) => Effect.uninterruptibleMask((restore) => Effect.withFiber((parent) => {
+			const fiber = storage.run(options, () => Effect.runForkWith(parent.context)(self));
+			return Effect.ensuring(restore(Fiber.join(fiber)), Fiber.interrupt(fiber));
+		}));
+	}
+};
+
+export { StdioCapture };

package/ToolFailure.js

@@ -0,0 +1,75 @@
+import { Schema } from "effect";
+import { Remediation } from "@effected/kit";
+
+// src/ToolFailure.ts
+const isHighSurrogate = (code) => code >= 55296 && code <= 56319;
+/**
+* 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
+*/
+var ToolFailure = class ToolFailure {
+	constructor() {}
+	/** The cap, in UTF-16 code units, on a caller-supplied value echoed into a message. */
+	static ECHO_LIMIT = 200;
+	/** The larger cap for a value the engine produced (a path, a diagnostic), not one a caller typed. */
+	static ENGINE_ECHO_LIMIT = 2e3;
+	/**
+	* 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 fields = {
+		message: Schema.String.annotate({ description: "What went wrong, as one plain sentence." }),
+		remediation: Remediation.annotate({ description: "What to do next: a hint, and optionally the tool to call next and the arguments to call it with." })
+	};
+	/**
+	* `"<raw> <hint> Try <suggestedTool>."`, dropping any empty part, so a
+	* missing tool or an empty hint never leaves a double space.
+	*/
+	static message = (raw, remediation) => [
+		raw,
+		remediation.hint,
+		remediation.suggestedTool === void 0 ? "" : `Try ${remediation.suggestedTool}.`
+	].filter((part) => part !== "").join(" ");
+	/**
+	* `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 truncate = (value, limit = ToolFailure.ECHO_LIMIT) => {
+		if (value.length <= limit) return value;
+		const end = limit > 0 && isHighSurrogate(value.charCodeAt(limit - 1)) ? limit - 1 : limit;
+		return `${value.slice(0, end)}…`;
+	};
+};
+
+export { ToolFailure };

package/ToolInputSchema.js

@@ -0,0 +1,180 @@
+import { ToolFailure } from "./ToolFailure.js";
+import { Result } from "effect";
+
+// src/ToolInputSchema.ts
+const MAX_DEPTH = 256;
+const MAX_ECHOED = 20;
+const DISCRIMINANTS = [
+	"action",
+	"kind",
+	"_tag",
+	"type"
+];
+const REF_PREFIX = "#/$defs/";
+const isNode = (u) => typeof u === "object" && u !== null && !Array.isArray(u);
+const resolveRef = (node, root, seen = /* @__PURE__ */ new Set()) => {
+	const ref = node.$ref;
+	if (typeof ref !== "string" || !ref.startsWith(REF_PREFIX) || seen.has(ref)) return node;
+	const defs = root.$defs;
+	const name = ref.slice(8).replaceAll("~1", "/").replaceAll("~0", "~");
+	const target = isNode(defs) && Object.hasOwn(defs, name) ? defs[name] : void 0;
+	if (!isNode(target)) return node;
+	const { $ref: _ref, ...siblings } = node;
+	return resolveRef({
+		...target,
+		...siblings
+	}, root, /* @__PURE__ */ new Set([...seen, ref]));
+};
+const literalValues = (node) => {
+	if (!isNode(node)) return void 0;
+	if (Array.isArray(node.enum)) return node.enum;
+	return "const" in node ? [node.const] : void 0;
+};
+const discriminantOf = (members) => members.length === 0 ? void 0 : DISCRIMINANTS.find((key) => members.every((member) => isNode(member.properties) && literalValues(member.properties[key]) !== void 0));
+const selectMember = (members, value, root) => {
+	const resolved = members.filter(isNode).map((member) => resolveRef(member, root));
+	const key = discriminantOf(resolved);
+	if (key !== void 0) return resolved.find((member) => literalValues(member.properties[key])?.includes(value[key]) === true);
+	const objects = resolved.filter((member) => isNode(member.properties) || member.type === "object");
+	return objects.length === 1 ? objects[0] : void 0;
+};
+const matchesPattern = (pattern, key) => Result.getOrUndefined(Result.try(() => new RegExp(pattern, "u").test(key))) === true;
+const collect = (payload, root) => {
+	const out = [];
+	const walk = (value, raw, path, depth) => {
+		if (depth > MAX_DEPTH || !isNode(raw)) return;
+		const node = resolveRef(raw, root);
+		const parts = [node, ...Array.isArray(node.allOf) ? node.allOf.filter(isNode).map((m) => resolveRef(m, root)) : []];
+		const members = Array.isArray(node.oneOf) ? node.oneOf : Array.isArray(node.anyOf) ? node.anyOf : void 0;
+		const additional = parts.map((part) => part.additionalProperties).find(isNode);
+		const isClosed = parts.some((part) => part.additionalProperties === false);
+		if (Array.isArray(value)) {
+			const prefix = Array.isArray(node.prefixItems) ? node.prefixItems : [];
+			if (prefix.length === 0 && !isNode(node.items) && members !== void 0) {
+				const arrays = members.filter(isNode).map((member) => resolveRef(member, root)).filter((member) => member.type === "array");
+				if (arrays.length === 1) walk(value, arrays[0], path, depth + 1);
+				return;
+			}
+			for (const [index, item] of value.entries()) walk(item, index < prefix.length ? prefix[index] : node.items, [...path, String(index)], depth + 1);
+			return;
+		}
+		if (!isNode(value)) return;
+		const declared = parts.filter((part) => isNode(part.properties));
+		if (declared.length === 0 && members !== void 0) {
+			const member = selectMember(members, value, root);
+			if (member !== void 0) walk(value, member, path, depth + 1);
+			return;
+		}
+		const properties = Object.create(null);
+		for (const part of declared) for (const [key, schema] of Object.entries(part.properties)) properties[key] = schema;
+		const patterns = parts.flatMap((part) => isNode(part.patternProperties) ? Object.entries(part.patternProperties) : []);
+		const accepted = Object.keys(properties);
+		const extra = [];
+		const patterned = [];
+		for (const key of Object.keys(value)) {
+			if (Object.hasOwn(properties, key)) continue;
+			const match = patterns.find(([pattern]) => matchesPattern(pattern, key));
+			if (match === void 0) extra.push(key);
+			else patterned.push([key, match[1]]);
+		}
+		if (extra.length > 0 && isClosed) {
+			const acceptedPatterns = patterns.map(([pattern]) => pattern);
+			out.push({
+				path,
+				unknown: extra,
+				accepted,
+				...acceptedPatterns.length > 0 ? { acceptedPatterns } : {}
+			});
+		}
+		for (const key of accepted) if (Object.hasOwn(value, key)) walk(value[key], properties[key], [...path, key], depth + 1);
+		for (const [key, schema] of patterned) walk(value[key], schema, [...path, key], depth + 1);
+		if (additional !== void 0) for (const key of extra) walk(value[key], additional, [...path, key], depth + 1);
+	};
+	walk(payload, root, [], 0);
+	return out;
+};
+/**
+* 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
+*/
+var ToolInputSchema = class {
+	constructor() {}
+	/** Every level of `payload` that carries a key `schema` does not accept. */
+	static unknownKeys = (payload, schema) => collect(payload, schema);
+	/**
+	* `Unrecognized parameter(s): a, b.c. Accepted params: x, y.` per level,
+	* followed by `Accepted keys matching: ^x-.` when the level also accepts
+	* keys by pattern. A level that accepts keys only by pattern names its
+	* patterns alone, never `Accepted params: (none).` Each echoed key and
+	* pattern is truncated, and at most 20 keys, 20 patterns and 20 levels are
+	* named; a trailing `(and N more levels).` counts the levels left out.
+	*/
+	static formatUnknownKeys = (levels, options = {}) => {
+		const limit = options.echoLimit ?? ToolFailure.ECHO_LIMIT;
+		const sentences = levels.slice(0, MAX_ECHOED).map((level) => {
+			const shown = level.unknown.slice(0, MAX_ECHOED).map((key) => ToolFailure.truncate([...level.path, key].join("."), limit));
+			const more = level.unknown.length > MAX_ECHOED ? ` (and ${level.unknown.length - MAX_ECHOED} more)` : "";
+			const patterns = (level.acceptedPatterns ?? []).slice(0, MAX_ECHOED).map((pattern) => ToolFailure.truncate(pattern, limit));
+			const params = level.accepted.length > 0 ? ` Accepted params: ${level.accepted.join(", ")}.` : patterns.length === 0 ? " Accepted params: (none)." : "";
+			const matching = patterns.length > 0 ? ` Accepted keys matching: ${patterns.join(", ")}.` : "";
+			return `Unrecognized parameter(s): ${shown.join(", ")}${more}.${params}${matching}`;
+		});
+		const hidden = levels.length > MAX_ECHOED ? ` (and ${levels.length - MAX_ECHOED} more levels).` : "";
+		return `${sentences.join(" ")}${hidden}`;
+	};
+	/**
+	* `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 objectRooted = (schema) => {
+		const root = resolveRef(schema, schema);
+		const members = Array.isArray(root.anyOf) ? root.anyOf : Array.isArray(root.oneOf) ? root.oneOf : void 0;
+		if (root.type === void 0 && members !== void 0) {
+			const resolved = members.filter(isNode).map((member) => resolveRef(member, schema));
+			const key = resolved.length === members.length ? discriminantOf(resolved) : void 0;
+			if (key !== void 0) {
+				const { anyOf: _anyOf, oneOf: _oneOf, ...rest } = root;
+				return {
+					type: "object",
+					...rest,
+					oneOf: resolved,
+					"x-discriminator": key
+				};
+			}
+		}
+		return root;
+	};
+};
+
+export { ToolInputSchema };

package/ToolOutcome.js

@@ -0,0 +1,119 @@
+import { ToolFailure } from "./ToolFailure.js";
+import { ToolOutputSchema } from "./ToolOutputSchema.js";
+import { Effect, Schema } from "effect";
+
+// src/ToolOutcome.ts
+/**
+* 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
+*/
+var ToolOutcome = class ToolOutcome {
+	constructor() {}
+	/** `{ ok: true }` as schema fields, to spread into each success member. */
+	static ok = { ok: Schema.Literal(true).annotate({ description: "true: the call succeeded." }) };
+	/**
+	* 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 error = (tag, fields) => Schema.Struct({
+		_tag: Schema.Literal(tag).annotate({ description: "The error's tag: the value to branch on." }),
+		...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 envelope = (success, errors, options) => ToolOutputSchema.objectRooted(Schema.Union([success, Schema.Struct({
+		ok: Schema.Literal(false).annotate({ description: "false: the call hit an expected error, described in error." }),
+		error: Schema.Union(errors).annotate({ description: "The expected error. Branch on its _tag." })
+	}).annotate({
+		description: options?.description ?? "An expected error the caller should branch on, returned in place of a result.",
+		...options?.identifier === void 0 ? {} : { identifier: options.identifier }
+	})]));
+	/** One `ok: false` value, for a handler that decides on a failure without catching an error. */
+	static failure = (tag, error) => ({
+		ok: false,
+		error: {
+			...error,
+			_tag: tag
+		}
+	});
+	/**
+	* 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 catchAsEnvelope = (cases) => (self) => {
+		const handlers = {};
+		for (const [tag, handle] of Object.entries(cases)) handlers[tag] = (error) => Effect.succeed(ToolOutcome.failure(tag, handle(error)));
+		return Effect.catchTags(self, handlers);
+	};
+	/**
+	* 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 isFailure = (value) => typeof value === "object" && value !== null && value.ok === false;
+};
+
+export { ToolOutcome };

package/ToolOutputSchema.js

@@ -0,0 +1,65 @@
+import { Schema, SchemaAST } from "effect";
+
+// 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 });
+	};
+};
+
+export { ToolOutputSchema };

package/ToolRefusal.js

@@ -0,0 +1,57 @@
+import { ToolFailure } from "./ToolFailure.js";
+import { Schema } from "effect";
+
+// 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 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
+*/
+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
+	});
+};
+
+export { ToolRefusal };