@effected/mcp 0.9.0 → 0.10.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/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/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

@@ -42,10 +42,14 @@ var ToolFailure = class ToolFailure {
 	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`. */
+	/**
+	* 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,
-		remediation: Remediation
+		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

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"
+* 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/ToolReplay.js

@@ -0,0 +1,122 @@
+import { ToolOutcome } from "./ToolOutcome.js";
+import { Effect, Option, Schema } from "effect";
+import { KeyValueStore } from "effect/persistence";
+
+// src/ToolReplay.ts
+/**
+* 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`.
+*
+* 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"
+* 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
+*/
+var ToolReplay = class ToolReplay {
+	constructor() {}
+	/**
+	* The marker field, to spread into each object member of a replayable
+	* success schema. {@link ToolReplay.success} adds it for you.
+	*/
+	static marker = { _idempotentReplay: Schema.optionalKey(Schema.Literal(true).annotate({ description: "Present and true when this result replays an earlier call with the same idempotency key: the stored result is returned and the mutation did not run again." })) };
+	/**
+	* 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 success = (schema) => schema.pipe(Schema.fieldsAssign(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 storeKey = (tool, key) => `${tool}:${key}`;
+	/**
+	* Wraps a handler with replay. Throws at wrap time when `tool` contains
+	* `:`, a wiring mistake, so it surfaces when the server is built.
+	*/
+	static wrap = (options) => {
+		if (options.tool.includes(":")) throw new Error(`ToolReplay.wrap: tool name "${options.tool}" contains ":", the stored-key separator.`);
+		const { tool, success } = options;
+		const given = options.store;
+		const json = Schema.fromJsonString(Schema.toCodecJson(success));
+		const decode = Schema.decodeEffect(json);
+		const encode = Schema.encodeEffect(json);
+		return (handler) => (params) => {
+			const found = options.key(params);
+			if (Option.isNone(found)) return handler(params);
+			const storeKey = ToolReplay.storeKey(tool, found.value);
+			return Effect.gen(function* () {
+				const store = given ?? (yield* KeyValueStore.KeyValueStore);
+				const cached = yield* store.get(storeKey).pipe(Effect.flatMap((raw) => raw === void 0 ? Effect.succeedNone : Effect.asSome(decode(raw))), Effect.tapCause((cause) => Effect.logDebug("ToolReplay lookup failed; treating as a miss", {
+					tool,
+					cause
+				})), Effect.orElseSucceed(() => Option.none()));
+				if (Option.isSome(cached)) {
+					yield* Effect.annotateCurrentSpan("mcp.tool.replayed", true);
+					return withMarker(cached.value);
+				}
+				yield* Effect.annotateCurrentSpan("mcp.tool.replayed", false);
+				const result = yield* handler(params);
+				if (!ToolOutcome.isFailure(result)) yield* encode(result).pipe(Effect.flatMap((encoded) => store.set(storeKey, encoded)), Effect.tapCause((cause) => Effect.logDebug("ToolReplay store failed; result not stored", {
+					tool,
+					cause
+				})), Effect.ignore);
+				return result;
+			}).pipe(Effect.withSpan("ToolReplay.wrap", { attributes: { "mcp.tool.name": tool } }));
+		};
+	};
+};
+const withMarker = (value) => typeof value === "object" && value !== null && !Array.isArray(value) ? {
+	...value,
+	_idempotentReplay: true
+} : value;
+
+export { ToolReplay };

package/guard.d.ts

@@ -104,10 +104,21 @@ interface McpGuardRunOptions<ROut, E> {
    * 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;
+  readonly injectCrash?: InjectCrash | undefined;
+}
+/**
+ * One test-only injected crash, as {@link McpGuard.parseInjectCrash} returns
+ * it and {@link McpGuardRunOptions.injectCrash} takes it: which point of the
+ * launch to raise it at, and which process event to raise. The same shape as
+ * `ProcessGuardInjection` from `@effected/engine/guard`.
+ *
+ * @public
+ */
+interface InjectCrash {
+  /** `"load"`: before the server module loads. `"connected"`: once the server is serving. */
+  readonly at: "load" | "connected";
+  /** The process event raised to the guard's listeners. */
+  readonly kind: "uncaughtException" | "unhandledRejection";
 }
 /**
  * Crash guards for an MCP server process, installed before the server's
@@ -170,9 +181,9 @@ export declare class McpGuard {
    * McpGuard.parseInjectCrash("load:uncaughtException"); // => { at: "load", kind: "uncaughtException" }
    * ```
    */
-  static readonly parseInjectCrash: (value: string | undefined) => McpGuardRunOptions<unknown, unknown>["injectCrash"];
+  static readonly parseInjectCrash: (value: string | undefined) => InjectCrash | undefined;
   /** 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>;
 }
-export type { McpGuardHost, McpGuardPolicy, McpGuardRunOptions, McpGuardedServer };
+export type { InjectCrash, McpGuardHost, McpGuardPolicy, McpGuardRunOptions, McpGuardedServer };
 //# sourceMappingURL=guard.d.ts.map

package/index.d.ts

@@ -1,6 +1,7 @@
-import { Array, Context, Effect, JsonSchema, Layer, Runtime, Schema, Stdio } from "effect";
+import { Array, Context, Effect, JsonSchema, Layer, Option, Runtime, Schema, Stdio, Struct } from "effect";
 import { McpProtocol, McpSchema, McpServer, Tool, Toolkit } from "effect/ai";
 import { Remediation } from "@effected/engine";
+import { KeyValueStore } from "effect/persistence";
 /**
  * Options for {@link McpStdio.layer}.
  *
@@ -511,7 +512,11 @@ export declare class ToolFailure {
   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`. */
+  /**
+   * 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<{
@@ -532,6 +537,167 @@ export declare class ToolFailure {
    */
   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"
+ * 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.
@@ -636,5 +802,146 @@ export declare class ToolRefusal extends ToolRefusal_base {
    */
   static readonly refuse: (reason: string, remediation: Remediation) => ToolRefusal;
 }
-export type { FormatUnknownKeysOptions, McpLaunchOptions, McpStdioOptions, McpToolkitOptions, UnionHandlerOptions, UnionTool, UnionToolOptions, UnknownKeysLevel };
+/**
+ * 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` and `size` 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`.
+ *
+ * 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"
+ * 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.
+   */
+  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, McpToolkitOptions, ToolOutcomeEnvelopeOptions, ToolOutcomeErrorInput, ToolOutcomeFailure, ToolOutcomeFailures, ToolReplayOptions, ToolReplayStore, UnionHandlerOptions, UnionTool, UnionToolOptions, UnknownKeysLevel };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -3,6 +3,8 @@ import { ToolFailure } from "./ToolFailure.js";
 import { ToolInputSchema } from "./ToolInputSchema.js";
 import { McpToolkit } from "./McpToolkit.js";
 import { ToolOutputSchema } from "./ToolOutputSchema.js";
+import { ToolOutcome } from "./ToolOutcome.js";
 import { ToolRefusal } from "./ToolRefusal.js";
+import { ToolReplay } from "./ToolReplay.js";
 
-export { McpStdio, McpToolkit, ToolFailure, ToolInputSchema, ToolOutputSchema, ToolRefusal };
+export { McpStdio, McpToolkit, ToolFailure, ToolInputSchema, ToolOutcome, ToolOutputSchema, ToolRefusal, ToolReplay };

package/node.d.ts

@@ -0,0 +1,126 @@
+import { Writable } from "node:stream";
+import { Effect } from "effect";
+/**
+ * Anything with a replaceable `write`: a patched stream (Node's
+ * `process.stdout` and `process.stderr`) and a sink captured writes go to (a
+ * Node `Writable`, {@link StdioCapture.nullWritable}, {@link StdioCapture.discard},
+ * {@link StdioCapture.toStderr}).
+ *
+ * @remarks
+ * A sink's `write` receives exactly the arguments the patched stream's
+ * `write` was called with, including any trailing callback, so a sink must
+ * call that callback itself, as a `Writable` does.
+ *
+ * @public
+ */
+interface StdioSink {
+  write(chunk: any, ...rest: Array<any>): boolean;
+}
+/**
+ * The two streams {@link StdioCapture.install} patches. Node's `process`
+ * satisfies it; pass it in from `main.ts`.
+ *
+ * @public
+ */
+interface StdioCaptureHost {
+  readonly stdout: StdioSink;
+  readonly stderr: StdioSink;
+}
+/**
+ * The sinks for one capture. `stderr` passes through to the real stream when
+ * omitted.
+ *
+ * @public
+ */
+interface StdioCaptureOptions {
+  readonly stdout: StdioSink;
+  readonly stderr?: StdioSink | undefined;
+}
+/**
+ * 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/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
+ */
+export declare class StdioCapture {
+  /** A sink that writes through the host's original, unpatched stderr: captured output stays visible off the wire. */
+  readonly toStderr: StdioSink;
+  private constructor();
+  /**
+   * 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 readonly install: (host: StdioCaptureHost) => StdioCapture;
+  /**
+   * 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 readonly discard: StdioSink;
+  /**
+   * 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 readonly nullWritable: () => Writable;
+  /**
+   * Runs `evaluate` with its writes captured, for code that is not Effect.
+   * A synchronous throw from `evaluate` rejects the returned promise.
+   */
+  run<A>(options: StdioCaptureOptions, evaluate: () => PromiseLike<A>): Promise<A>;
+  /**
+   * 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: StdioCaptureOptions): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+}
+export type { StdioCaptureHost, StdioCaptureOptions, StdioSink };
+//# sourceMappingURL=node.d.ts.map

package/node.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/mcp",
-	"version": "0.9.0",
+	"version": "0.10.0",
 	"private": false,
 	"description": "The boundary layer of an effect/ai MCP server: stdio wiring that keeps stdout the wire, tool-failure shaping, strict-input walkers, and test clients",
 	"keywords": [
@@ -39,6 +39,11 @@
 			"import": "./guard.js",
 			"default": "./guard.js"
 		},
+		"./node": {
+			"types": "./node.d.ts",
+			"import": "./node.js",
+			"default": "./node.js"
+		},
 		"./testing": {
 			"types": "./testing.d.ts",
 			"import": "./testing.js",
@@ -47,7 +52,7 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"@effected/engine": "^0.8.0",
+		"@effected/engine": "^0.9.0",
 		"effect": "^4.0.0"
 	},
 	"engines": {

package/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.59.1"
+      "packageVersion": "7.59.4"
     }
   ]
 }