@effected/mcp-kit 0.0.0-stage → 0.13.0

package/ToolReplay.js

@@ -0,0 +1,129 @@
+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`.
+*
+* Inside an MCP server, pass the store. A service left in a handler's `R`
+* has to be declared in the tool's `dependencies`, which makes it a
+* request-level dependency that only MCP middleware can meet. Read
+* `KeyValueStore` once when the handlers are built, with the effect form of
+* `Toolkit.toLayer`, and hand it to `wrap` as `store`: a `KeyValueStore`
+* satisfies {@link ToolReplayStore} as is.
+*
+* Semantics, per call:
+*
+* - A key of `Option.none()` runs the handler; nothing is read or stored.
+* - A stored value that decodes through `success` is returned with the marker,
+*   and the handler does not run.
+* - A miss runs the handler and stores its result, best-effort. A store that
+*   fails, a row that no longer decodes (written under an older schema, or
+*   corrupt), and a failed write are each a miss or a skipped write, never a
+*   tool error. Each is logged at debug level with the tool name.
+* - A handler failure stores nothing, so a retry runs it again.
+* - An `ok: false` result (a {@link ToolOutcome} envelope failure) is never
+*   stored: a "not found" must not replay after the thing exists.
+*
+* This is replay, not exactly-once: two concurrent calls with one key both
+* miss and both run.
+*
+* The key is the whole identity of a request. A hit compares neither the
+* params nor the schema version (a row written under an older schema replays
+* whenever it still decodes), and rows never expire: the store keeps a result
+* until something removes it. A key reused with different params therefore
+* replays the first result, so {@link ToolReplayOptions.key} must fold in a
+* digest of any params that can vary under one id.
+*
+* Wrap it inside {@link ToolOutcome.catchAsEnvelope}, so the envelope sees the
+* handler's real errors and replay sees only real successes.
+*
+* @example
+* ```ts
+* import { ToolReplay } from "@effected/mcp-kit"
+* import { Option, Schema } from "effect"
+*
+* const Created = ToolReplay.success(Schema.Struct({ ok: Schema.Literal(true), id: Schema.Number }))
+* const create = ToolReplay.wrap({
+* 	tool: "goal_create",
+* 	success: Created,
+* 	key: (params: { readonly requestId?: string }) => Option.fromUndefinedOr(params.requestId),
+* })(createGoal)
+* ```
+*
+* @public
+*/
+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

@@ -0,0 +1,189 @@
+import { Effect, Layer, Runtime } from "effect";
+/**
+ * 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.
+   *
+   * **The `"connected"` report is asynchronous.** It is raised on a later
+   * tick, a `setTimeout(0)` after the server starts serving, so it can land
+   * after the first responses a test reads: reading stderr once, right
+   * after the `initialize` or `tools/list` response, can see an empty
+   * buffer. Wait for it with `McpProcess.stderrUntil` from
+   * `@effected/mcp-kit/testing` rather than reading it once.
+   *
+   * 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?: 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/kit/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
+ * module graph is loaded. Imported from `@effected/mcp-kit/guard`.
+ *
+ * @remarks
+ * {@link McpGuard.run} is `ProcessGuard.run` from `@effected/kit/guard`
+ * with an MCP launch in its `load`: it 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. A server on another transport (an LSP over
+ * `vscode-languageserver`, say) uses `ProcessGuard.run` directly and calls
+ * its `markConnected` itself. This entrypoint statically imports only
+ * `@effected/kit/guard`, which imports nothing: 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-kit/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();
+  /**
+   * Parse a test-only crash-injection setting into {@link McpGuardRunOptions.injectCrash}: `<at>:<kind>`, where `at`
+   * is `"load"` or `"connected"` and `kind` is `"uncaughtException"` or `"unhandledRejection"`. Anything else, or no
+   * value, is `undefined`. The same grammar as `ProcessGuard.parseInjectCrash` from `@effected/kit/guard`, which
+   * this is, so an MCP launcher need not import the engine guard for it.
+   *
+   * @example
+   * ```ts
+   * McpGuard.parseInjectCrash("load:uncaughtException"); // => { at: "load", kind: "uncaughtException" }
+   * ```
+   */
+  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 { InjectCrash, McpGuardHost, McpGuardPolicy, McpGuardRunOptions, McpGuardedServer };
+//# sourceMappingURL=guard.d.ts.map

package/guard.js

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