@gjermundgaraba/effect-actions 0.20.0 → 0.21.0

package/dist/mcp/bridge.mjs

@@ -0,0 +1,283 @@
+import { Anyone, principalOf } from "../contract/caller.mjs";
+import { inputParseOptions } from "../contract/call.mjs";
+import { reported } from "../contract/reported.mjs";
+import { encodeUntaggedOf } from "../contract/occurrence.mjs";
+import { acquireFeeds, unkeyedHook } from "../contract/feed.mjs";
+import { NotServed, SubscriptionError, Unsupported } from "../Event.mjs";
+import { sentError } from "../contract/codes.mjs";
+import { Webhooks, offersWebhook, servedWebhooks, webhookSubscriber } from "../contract/webhooks.mjs";
+import { pushed, refusalIn } from "../contract/push.mjs";
+import { promote } from "../authentication/provider.mjs";
+import { recordStepUp } from "../authentication/refusal.mjs";
+import { Active, EventsError, Failed, Heartbeat, Notifications, Occurred, Requests, Terminated, codes, extension, subscriptionIdKey } from "./events.mjs";
+import { isObjectSchema, routingFormsOf, toolJsonSchema } from "./protocol.mjs";
+import { Cause, Context, Duration, Effect, Exit, Match, Option, Predicate, Result, Schema } from "effect";
+import { HttpEffect, HttpServerRequest, HttpServerResponse } from "effect/http";
+import { McpSchema } from "effect/ai";
+// src/mcp/bridge.ts
+const isGroup = (u) => Predicate.isObjectKeyword(u) && "merge" in u && Predicate.isFunction(u.merge) && "requests" in u && u.requests instanceof Map;
+const groupOf = (adapter, key) => {
+	const group = Predicate.hasProperty(adapter, key) ? adapter[key] : void 0;
+	if (!isGroup(group)) throw new Error(`Effect's MCP ${adapter.protocolVersion} adapter holds no ${key} group: effect-actions supports MCP events on effect 4.0.x (install the effect version its peer range names)`);
+	return group;
+};
+/**
+* The JSON Schemas `events/list` lists for `event`, refusing an input or a payload that is no
+* object.
+*/
+const eventSchemasOf = (event) => {
+	const inputSchema = toolJsonSchema(Schema.toCodecJson(event.input), true);
+	if (!isObjectSchema(inputSchema)) throw new Error(`MCP event input must be one object with keys, such as a struct: ${event.name} (wrap a union, an array or a scalar in a field, or omit input for no arguments)`);
+	const payloadSchema = toolJsonSchema(Schema.toCodecJson(event.payload), false);
+	if (!isObjectSchema(payloadSchema)) throw new Error(`MCP event payload must be one object, such as a struct: ${event.name} (wrap an array or a scalar in a field)`);
+	return {
+		inputSchema,
+		payloadSchema
+	};
+};
+const encodeServerInfo = Schema.encodeEffect(McpSchema.Implementation);
+const internalError = new EventsError({
+	code: codes.internal,
+	message: "Internal error"
+});
+const isSubscriptionError = Schema.is(SubscriptionError);
+const wireErrorOf = (cause) => {
+	const refusal = refusalIn(cause);
+	if (refusal !== void 0) return Effect.succeed(new EventsError(sentError(refusal)));
+	const failure = Cause.hasDies(cause) ? void 0 : Result.getOrUndefined(Cause.findFail(cause));
+	return isSubscriptionError(failure?.error) ? Effect.succeed(new EventsError(sentError(failure.error))) : Effect.as(reported(cause), internalError);
+};
+const headerMismatch = (request) => Effect.andThen(HttpEffect.appendPreResponseHandler((_request, response) => Effect.succeed(HttpServerResponse.setStatus(response, 400))).pipe(Effect.provideService(HttpServerRequest.HttpServerRequest, request)), Effect.fail(new EventsError({
+	code: codes.headerMismatch,
+	message: "Mcp-Name header does not match request parameters"
+})));
+const routedTo = (name) => Effect.flatMap(Effect.serviceOption(HttpServerRequest.HttpServerRequest), (request) => Option.isNone(request) || routingFormsOf(name).includes(request.value.headers["mcp-name"] ?? "") ? Effect.void : headerMismatch(request.value));
+const servedOf = (feed, delivery) => {
+	const { event } = feed;
+	const decode = Schema.decodeUnknownEffect(Schema.toCodecJson(event.input), inputParseOptions);
+	return {
+		feed,
+		decode: (args) => Effect.mapError(decode(args ?? {}), ({ message }) => new EventsError({
+			code: codes.invalidParams,
+			message: `Invalid arguments for event '${event.name}': ${message}`
+		})),
+		wire: encodeUntaggedOf(event),
+		listing: {
+			name: event.name,
+			description: event.description,
+			delivery,
+			...eventSchemasOf(event)
+		}
+	};
+};
+/**
+* Dies with the reason the endpoint of `serving` cannot serve one of its events, run where the
+* endpoint's layer is built: a protected one with a `subscription` hook, under an authentication
+* without a principal to key its polls by.
+*/
+const refuseUnservable = ({ events, authentication }) => authentication === void 0 ? Effect.void : Effect.flatMap(acquireFeeds(events), (feeds) => {
+	const refusal = unkeyedHook("MCP", feeds, authentication.principal !== void 0);
+	return refusal === void 0 ? Effect.void : Effect.die(new Error(refusal));
+});
+/**
+* Serves the feeds the endpoint of `serving` offers by webhook to `Webhooks`, where it is
+* provided, run where the endpoint's layer is built: it restores their kept subscriptions, and
+* dies where they cannot be kept.
+*/
+const serveWebhooks = (serving) => Effect.asVoid(Effect.flatMap(acquireFeeds(serving.events), (feeds) => servedWebhooks(feeds, serving.authentication)));
+/**
+* One push subscription, as `events/stream` holds it: what the feed's `pushed` sends, as
+* SEP-3415's notifications. Its confirmation is `active`, a later gap a fresh `active`, a
+* position a heartbeat, and a failure it reads on through `error`. A failure before `active` is
+* the request's error; a refusal after it ends the subscription with `terminated`.
+*/
+const delivered = ({ send, clientId, requestId, wire, _meta: resultMeta }, run) => {
+	const notify = (rpc, payload) => send("2026-07-28", clientId, {
+		tag: rpc._tag,
+		payload
+	});
+	return Effect.gen(function* () {
+		const _meta = { [subscriptionIdKey]: requestId };
+		let active = false;
+		const activate = (cursor, truncated) => {
+			active = true;
+			return notify(Active, {
+				_meta,
+				cursor,
+				truncated
+			});
+		};
+		const deliver = (sent) => Match.valueTags(sent, {
+			Gap: ({ cursor }) => activate(cursor, true),
+			Checked: ({ cursor }) => active ? notify(Heartbeat, {
+				_meta,
+				cursor
+			}) : activate(cursor, false),
+			Occurrence: (occurrence) => Effect.flatMap(wire(occurrence), (event) => notify(Occurred, {
+				...event,
+				_meta
+			})),
+			Failed: () => notify(Failed, {
+				_meta,
+				error: {
+					code: internalError.code,
+					message: internalError.message
+				}
+			})
+		});
+		const exit = yield* Effect.exit(run(deliver));
+		if (Exit.isFailure(exit)) {
+			if (Cause.hasInterruptsOnly(exit.cause)) return yield* Effect.interrupt;
+			const error = yield* wireErrorOf(exit.cause);
+			if (!active) return yield* error;
+			const { code, message, data } = error;
+			yield* notify(Terminated, {
+				_meta,
+				error: {
+					code,
+					message,
+					...data === void 0 ? {} : { data }
+				}
+			});
+		}
+		return {
+			resultType: "complete",
+			_meta: {
+				...resultMeta,
+				..._meta
+			}
+		};
+	});
+};
+/**
+* `base`, the 2026-07-28 adapter, also serving SEP-3415's `events/list`, `events/poll` and
+* `events/stream` for the event implementations of `serving`, and advertising the extension in
+* its discovery.
+*/
+const withEvents = (base, serving) => {
+	const { authentication } = serving;
+	const asSubscriber = (event, run) => authentication === void 0 || event.caller === Anyone ? run : recordStepUp(promote(authentication, run));
+	const installHandlers = (core, lifecycle, target) => Effect.gen(function* () {
+		const feeds = yield* acquireFeeds(serving.events);
+		const built = yield* Effect.context();
+		const send = target.context.sendNotification;
+		const meta = Effect.map(Effect.orDie(encodeServerInfo(target.context.serverInfo)), (serverInfo) => ({ "io.modelcontextprotocol/serverInfo": serverInfo }));
+		const webhooks = Context.getOption(built, Webhooks);
+		const webhookOffered = (event) => Option.isSome(webhooks) && offersWebhook(event, authentication);
+		const deliveryOf = (event) => [
+			"poll",
+			...send === void 0 ? [] : ["push"],
+			...webhookOffered(event) ? ["webhook"] : []
+		];
+		const served = new Map(feeds.map((feed) => [feed.event.name, servedOf(feed, deliveryOf(feed.event))]));
+		const servedNamed = (name) => {
+			const found = served.get(name);
+			return found === void 0 ? Effect.fail(new EventsError(sentError(SubscriptionError.of(name, new NotServed())))) : Effect.succeed(found);
+		};
+		const asWebhook = (feed, run) => Effect.catchCause(asSubscriber(feed.event, Effect.flatMap(webhookSubscriber(feed, authentication, webhooks), run)), (cause) => Effect.flatMap(wireErrorOf(cause), Effect.fail));
+		const fromBuilt = (handled) => Effect.updateContext(handled, (request) => Context.merge(built, request));
+		const handlers = Requests.of({
+			"events/list": () => Effect.map(meta, (_meta) => ({
+				resultType: "complete",
+				events: [...served.values()].map(({ listing }) => listing),
+				_meta
+			})),
+			"events/poll": ({ name, arguments: args, cursor, maxEvents }) => Effect.gen(function* () {
+				yield* routedTo(name);
+				const { feed, decode, wire } = yield* servedNamed(name);
+				const input = yield* decode(args);
+				const { page, events } = yield* Effect.gen(function* () {
+					const polled = yield* asSubscriber(feed.event, Effect.flatMap(principalOf(feed.event, authentication), (subscriber) => feed.poll(input, cursor ?? null, {
+						subscriber,
+						maxEvents
+					})));
+					return {
+						page: polled,
+						events: yield* Effect.forEach(polled.events, wire)
+					};
+				}).pipe(Effect.catchCause((cause) => Effect.flatMap(wireErrorOf(cause), Effect.fail)));
+				return {
+					resultType: "complete",
+					events,
+					cursor: page.cursor,
+					truncated: page.truncated,
+					hasMore: page.hasMore,
+					nextPollMs: Duration.toMillis(page.nextPoll),
+					_meta: yield* meta
+				};
+			}).pipe(fromBuilt),
+			"events/stream": ({ name, arguments: args, cursor }, { client, requestId }) => Effect.gen(function* () {
+				yield* routedTo(name);
+				const { feed, decode, wire } = yield* servedNamed(name);
+				const input = yield* decode(args);
+				if (send === void 0) return yield* new EventsError(sentError(SubscriptionError.of(name, new Unsupported({
+					feature: "deliveryMode",
+					value: "push"
+				}))));
+				return yield* delivered({
+					send,
+					clientId: client.id,
+					requestId,
+					wire,
+					_meta: yield* meta
+				}, (deliver) => asSubscriber(feed.event, Effect.flatMap(feed.stream(input), (open) => pushed(open, cursor ?? null, deliver))));
+			}).pipe(fromBuilt),
+			"events/subscribe": ({ name, arguments: args, delivery: { url, secret }, cursor, ttlMs }) => Effect.gen(function* () {
+				yield* routedTo(name);
+				const { feed, decode } = yield* servedNamed(name);
+				const input = yield* decode(args);
+				return {
+					resultType: "complete",
+					...yield* asWebhook(feed, ({ webhooks: service, ...subscriber }) => service.subscribe({
+						...subscriber,
+						input,
+						delivery: {
+							url,
+							secret
+						},
+						cursor: cursor ?? null,
+						ttlMs
+					})),
+					_meta: yield* meta
+				};
+			}).pipe(fromBuilt),
+			"events/unsubscribe": ({ name, arguments: args, delivery }) => Effect.gen(function* () {
+				yield* routedTo(name);
+				const { feed, decode } = yield* servedNamed(name);
+				const input = yield* decode(args);
+				yield* asWebhook(feed, ({ webhooks: service, feed: subscribed, principal }) => service.unsubscribe({
+					feed: subscribed,
+					principal,
+					input,
+					delivery
+				}));
+				return {
+					resultType: "complete",
+					_meta: yield* meta
+				};
+			}).pipe(fromBuilt)
+		});
+		yield* Effect.asVoid(base.installHandlers(core, lifecycle, {
+			...target,
+			context: {
+				...target.context,
+				serverInfo: {
+					...target.context.serverInfo,
+					extensions: {
+						...target.context.serverInfo.extensions,
+						[extension]: { listChanged: false }
+					}
+				}
+			}
+		}));
+		yield* target.install(base, Requests, handlers);
+	});
+	return {
+		...base,
+		clientRpcs: groupOf(base, "clientRpcs").merge(Requests),
+		handlerRpcs: groupOf(base, "handlerRpcs").merge(Requests),
+		serverNotificationRpcs: groupOf(base, "serverNotificationRpcs").merge(Notifications),
+		installHandlers
+	};
+};
+export { eventSchemasOf, refuseUnservable, serveWebhooks, withEvents };

package/dist/mcp/client.d.mts

@@ -1,25 +1,18 @@
 import { BuiltIn } from "../contract/errors.mjs";
+import { Any, Received, SubscriptionError, WatchOptions } from "../Event.mjs";
 import { Call } from "../contract/call.mjs";
-import { Any } from "../Action.mjs";
-import { Any as Any$1, VerifierError } from "../authentication/provider.mjs";
-import { Effect, Schema } from "effect";
-import { Headers, HttpClient, HttpClientError, HttpClientRequest } from "effect/http";
-/**
- * An MCP request's parameters, as `request` takes them: JSON, with any `_meta`, leaving
- * out an `undefined` one, as a caller may. A helper passing on whole params types them as this,
- * and a tool's `arguments` as `Schema.Json`, never `unknown`.
- */
-export interface Params {
-  readonly _meta?: {
-    readonly [key: string]: Schema.Json;
-  };
-  readonly [key: string]: Schema.Json | undefined;
-}
+import { Answer } from "../contract/stream.mjs";
+import { WatchArgs, WatchRequirement } from "../contract/watch.mjs";
+import { Any as Any$1 } from "../Action.mjs";
+import { Any as Any$2, VerifierError } from "../authentication/provider.mjs";
+import { McpCallError } from "./reply.mjs";
+import { Effect, Schema, Stream } from "effect";
+import { HttpClient, HttpClientError } from "effect/http";
 /**
  * Where `client` sends, through what client, and what the endpoint's authentication declares: the
  * client `transformClient` returns may fail with `E` and require `R`.
  */
-export interface ClientOptions<D extends Any$1 | undefined = Any$1 | undefined, E = HttpClientError.HttpClientError, R = never> {
+export interface ClientOptions<D extends Any$2 | undefined = Any$2 | undefined, E = HttpClientError.HttpClientError, R = never> {
   /**
    * The endpoint, resolved by the `HttpClient`: relative under `Testing.layer`. Defaults to `/mcp`,
    * the default `layerHttp` path, so a call to an endpoint on another `path` fails with an
@@ -39,72 +32,19 @@ export interface ClientOptions<D extends Any$1 | undefined = Any$1 | undefined,
    */
   readonly authentication?: D;
 }
-/** Where a `request` goes, and with what headers. */
-export interface RequestOptions {
-  /**
-   * The endpoint, resolved by the `HttpClient` that sends the request: relative under `Testing.layer`.
-   * Defaults to `/mcp`, as `client`'s does; converting to a web `Request` needs an absolute
-   * one.
-   */
-  readonly url?: string;
-  /**
-   * Headers sent beside the routing ones `request` fills in, such as `Authorization`; a routing
-   * header wins over a given one of its name.
-   */
-  readonly headers?: Headers.Input;
-}
-declare const StatusError_base: Schema.Class<StatusError, Schema.TaggedStruct<"StatusError", {
-  readonly status: Schema.Int;
-  readonly body: Schema.String;
-}>, import("effect/Cause").YieldableError>;
-/** The endpoint answered with an HTTP status other than 200, and a body no declared error decodes. */
-declare class StatusError extends StatusError_base {}
-declare const ProtocolError_base: Schema.Class<ProtocolError, Schema.TaggedStruct<"ProtocolError", {
-  readonly code: Schema.Finite;
-  readonly message: Schema.String;
-}>, import("effect/Cause").YieldableError>;
+type CallError<A extends Any$1, D> = A["error"][number]["Type"] | VerifierError<A, D>["Type"] | BuiltIn | Schema.SchemaError | HttpClientError.HttpClientError | McpCallError;
+/** What a watch of `W` may fail with, under the endpoint's descriptor `D`. */
+type WatchError<W extends Any, D> = SubscriptionError | BuiltIn | VerifierError<W, D>["Type"] | Schema.SchemaError | HttpClientError.HttpClientError | McpCallError;
 /**
- * The endpoint answered with a JSON-RPC error, such as the native server's for an unknown tool.
+ * Every action of `Contracts` as `client.<action>(input)`, calling its tool; one answering a
+ * stream returns a `Stream` of the elements its tool collected. Where it lists event types,
+ * `watch(event, input, options)` subscribes to one. Each call and watch also fails with `E` and
+ * requires `R`, what its `transformClient` adds.
  */
-declare class ProtocolError extends ProtocolError_base {}
-declare const NoReply_base: Schema.Class<NoReply, Schema.TaggedStruct<"NoReply", {
-  readonly body: Schema.String;
-}>, import("effect/Cause").YieldableError>;
-/** The endpoint answered 200 without a JSON-RPC reply to read, as JSON or as an event stream. */
-declare class NoReply extends NoReply_base {}
-declare const UndeclaredError_base: Schema.Class<UndeclaredError, Schema.TaggedStruct<"UndeclaredError", {
-  readonly text: Schema.String;
-}>, import("effect/Cause").YieldableError>;
-/** The tool returned an error whose text decodes as none of the action's declared errors. */
-declare class UndeclaredError extends UndeclaredError_base {}
-declare const NoStructuredContent_base: Schema.Class<NoStructuredContent, Schema.TaggedStruct<"NoStructuredContent", {
-  readonly body: Schema.String;
-}>, import("effect/Cause").YieldableError>;
-/** The tool returned a result without the structured content its action's success needs. */
-declare class NoStructuredContent extends NoStructuredContent_base {}
-declare const McpCallError_base: Schema.Class<McpCallError, Schema.TaggedStruct<"McpCallError", {
-  readonly tool: Schema.String;
-  readonly reason: Schema.Union<readonly [typeof StatusError, typeof ProtocolError, typeof NoReply, typeof UndeclaredError, typeof NoStructuredContent]>;
-  readonly message: Schema.String;
-}>, import("effect/Cause").YieldableError>;
-/**
- * An answer a client method cannot read as the action's success or a declared error: `reason`
- * says which, with what the endpoint sent, so a caller branches on it with
- * `Effect.catchReason("McpCallError", "StatusError", ...)`. `message` names the tool and the
- * reason. Structured content that does not decode as the success is a `SchemaError` instead,
- * and a request that fails an `HttpClientError`.
- *
- * **Gotchas**
- *
- * - `returned an error: Invalid parameters for tool …`, an `UndeclaredError`, from a call its types allowed: the endpoint serves another contract under that name; give `client` the served contract value.
- */
-export declare class McpCallError extends McpCallError_base {}
-type CallError<A extends Any, D> = A["error"][number]["Type"] | VerifierError<A, D>["Type"] | BuiltIn | Schema.SchemaError | HttpClientError.HttpClientError | McpCallError;
-/**
- * Every action of `Actions` as `client.<action>(input)`, calling its tool. Each call also fails
- * with `E` and requires `R`, what its `transformClient` adds.
- */
-export type Client<Actions extends ReadonlyArray<Any>, D = undefined, E = never, R = never> = { readonly [A in Actions[number] as A["name"]]: Call<A, Effect.Effect<A["success"]["Type"], CallError<A, D> | E, R>>; };
+export type Client<Contracts extends ReadonlyArray<Any$1 | Any>, D = undefined, E = never, R = never> = { readonly [A in Extract<Contracts[number], Any$1> as A["name"]]: Call<A, Answer<A["success"], CallError<A, D> | E, R>>; } & Watching<Extract<Contracts[number], Any>, D, E, R>;
+type Watching<Listed extends Any, D, E, R> = [Listed] extends [never] ? unknown : {
+  readonly watch: <W extends Listed, SE = never, const O extends WatchOptions<unknown> = {}>(event: W, ...args: WatchArgs<W, SE, O>) => Stream.Stream<Received<W>, WatchError<W, D> | E | SE, R | WatchRequirement<O>>;
+};
 /**
  * A client of an MCP endpoint served by `layerHttp`, one method per action calling
  * its tool with one stateless request, as `ActionHttp.client` calls routes: the input is
@@ -113,26 +53,19 @@ export type Client<Actions extends ReadonlyArray<Any>, D = undefined, E = never,
  * every field is, from its blocks alone. A declared error the tool returns, the action's own
  * or a refusal, is its decoded value, and so is a refusal the endpoint's authentication answers
  * with: a test telling a 401 or 403 from a tool result asserts the status of a request `request`
- * builds. The argument may be omitted when `{}` is a valid input. Requires the native
- * `HttpClient`, such as the one `Testing.layer` provides.
+ * builds. The argument may be omitted when `{}` is a valid input. Where `contracts` lists event
+ * types, `watch` subscribes to one as `Action.client`'s does, holding `events/stream` open, or
+ * polling `events/poll` with `mode: "poll"` or where the endpoint cannot push. Requires the
+ * native `HttpClient`, such as the one `Testing.layer` provides.
  *
  * **Gotchas**
  *
  * - It drops undeclared input fields as it encodes, and fails with `InvalidInput`, sending nothing, for an input that does not encode.
+ * - A call of an action answering a stream returns a `Stream` of the elements its tool collected, the first arriving once the whole stream has ended on the server.
+ * - A watch of an event the endpoint does not serve fails with `Event.SubscriptionError`, reason `NotServed`, as an endpoint serving events answers its first request; one serving none answers `events/*` with a 404, failing with `McpCallError`'s `StatusError`.
+ * - A watch reconnects after the transport fails, a status such as 503, or 60 seconds without an answer or a frame, a second later and doubling to 30 seconds, each reconnect logged as a warning; any other failure ends it.
+ * - A call given `onProgress` sends a `progressToken` and reads each `notifications/progress` as its frame arrives; a call without one sends none, so the endpoint sends no progress.
  */
-export declare function client<const Actions extends ReadonlyArray<Any>, D extends Any$1 | undefined = undefined>(actions: Actions, options?: ClientOptions<D>): Effect.Effect<Client<Actions, D>, never, HttpClient.HttpClient>;
-export declare function client<const Actions extends ReadonlyArray<Any>, E, R, D extends Any$1 | undefined = undefined>(actions: Actions, options: ClientOptions<D, E, R>): Effect.Effect<Client<Actions, D, E, R>, never, HttpClient.HttpClient>;
-/**
- * One stateless MCP request of `method` with `params`, as `layerHttp` serves it,
- * as the native request value: the JSON-RPC envelope, the 2026-07-28 headers (`Accept`,
- * `MCP-Protocol-Version`, `MCP-Method`), `mcp-name` from
- * `params.uri` for `resources/read` and `params.name` otherwise, and the client metadata in
- * `_meta` are filled in, under any `_meta` given, such as a `progressToken`; the protocol
- * version is always the request's own. The test sends it: `HttpClient.execute` answers the
- * response as the endpoint sent it, whatever its status, and `HttpClientRequest.toWebResult`
- * gives the web `Request` a web handler or `fetch` takes, once `url` is absolute. It is for a test
- * asserting on what `client` decodes away, such as `tools/list`, a refusal's challenge, or
- * a call its types would not send.
- */
-export declare const request: (method: string, params?: Params, { headers, url }?: RequestOptions) => HttpClientRequest.HttpClientRequest;
+export declare function client<const Contracts extends ReadonlyArray<Any$1 | Any>, D extends Any$2 | undefined = undefined>(contracts: Contracts, options?: ClientOptions<D>): Effect.Effect<Client<Contracts, D>, never, HttpClient.HttpClient>;
+export declare function client<const Contracts extends ReadonlyArray<Any$1 | Any>, E, R, D extends Any$2 | undefined = undefined>(contracts: Contracts, options: ClientOptions<D, E, R>): Effect.Effect<Client<Contracts, D, E, R>, never, HttpClient.HttpClient>;
 export {};