@gjermundgaraba/effect-actions 0.19.0 → 0.21.0

package/dist/mcp/client.d.mts

@@ -1,26 +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";
-//#region src/mcp/client.d.ts
-/**
- * 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
@@ -40,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
@@ -114,27 +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;
-//#endregion
+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 {};

package/dist/mcp/client.mjs

@@ -1,163 +1,89 @@
 import { Anyone } from "../contract/caller.mjs";
 import { Refusal } from "../contract/errors.mjs";
-import { assertOnce } from "../contract/names.mjs";
 import { projectedErrors } from "../contract/declared.mjs";
-import { checked } from "../contract/call.mjs";
-import { defaultPath, httpProtocol, liftOf, unliftedFrom } from "./protocol.mjs";
-import { Effect, Match, Option, Predicate, Schema } from "effect";
+import { assertOnce } from "../contract/names.mjs";
+import { progressSink } from "../contract/progress.mjs";
+import { elementOf } from "../contract/stream.mjs";
+import { checked, checkedStream, sendingJson, watchInput } from "../contract/call.mjs";
+import { split } from "../contract/listed.mjs";
+import { watching } from "../contract/watch.mjs";
+import { defaultPath, liftOf, unliftedFrom } from "./protocol.mjs";
+import { NoReply, NoStructuredContent, ProtocolError, StatusError, UndeclaredError, bodyOf, callError, failWith } from "./reply.mjs";
+import { request } from "./request.mjs";
+import { transportOf } from "./watch.mjs";
+import { Effect, Option, Schema, Stream } from "effect";
+import { HttpClient } from "effect/http";
 import { McpSchema } from "effect/ai";
-import { HttpClient, HttpClientRequest } from "effect/http";
-import { Sse } from "effect/encoding";
-//#region src/mcp/client.ts
-/** The routing headers and JSON-RPC body of the request `request` builds. */
-const statelessRequest = (method, params) => {
-	const { protocolVersion } = httpProtocol;
-	const name = method === "resources/read" ? params.uri : params.name;
-	return {
-		headers: {
-			accept: "application/json, text/event-stream",
-			"mcp-protocol-version": protocolVersion,
-			"mcp-method": method,
-			...Predicate.isString(name) ? { "mcp-name": name } : {}
-		},
-		body: {
-			jsonrpc: "2.0",
-			id: 1,
-			method,
-			params: {
-				...params,
-				_meta: {
-					"io.modelcontextprotocol/clientCapabilities": {},
-					"io.modelcontextprotocol/clientInfo": {
-						name: "effect-actions",
-						version: "0"
-					},
-					...params._meta,
-					"io.modelcontextprotocol/protocolVersion": protocolVersion
-				}
-			}
-		}
-	};
-};
-/** The endpoint answered with an HTTP status other than 200, and a body no declared error decodes. */
-var StatusError = class extends Schema.TaggedError()("StatusError", {
-	status: Schema.Int,
-	body: Schema.String
-}) {};
-/**
-* The endpoint answered with a JSON-RPC error, such as the native server's for an unknown tool.
-*/
-var ProtocolError = class extends Schema.TaggedError()("ProtocolError", {
-	code: Schema.Finite,
-	message: Schema.String
-}) {};
-/** The endpoint answered 200 without a JSON-RPC reply to read, as JSON or as an event stream. */
-var NoReply = class extends Schema.TaggedError()("NoReply", { body: Schema.String }) {};
-/** The tool returned an error whose text decodes as none of the action's declared errors. */
-var UndeclaredError = class extends Schema.TaggedError()("UndeclaredError", { text: Schema.String }) {};
-/** The tool returned a result without the structured content its action's success needs. */
-var NoStructuredContent = class extends Schema.TaggedError()("NoStructuredContent", { body: Schema.String }) {};
-const Reason = Schema.Union([
-	StatusError,
-	ProtocolError,
-	NoReply,
-	UndeclaredError,
-	NoStructuredContent
-]);
-const sentenceOf = Match.typeTags()({
-	StatusError: ({ status, body }) => `answered ${status}: ${body}`,
-	ProtocolError: ({ code, message }) => `failed with ${code}: ${message}`,
-	NoReply: ({ body }) => `had no reply: ${body}`,
-	UndeclaredError: ({ text }) => `returned an error: ${text}`,
-	NoStructuredContent: ({ body }) => `returned no structured content: ${body}`
-});
-/**
-* 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.
-*/
-var McpCallError = class extends Schema.TaggedError()("McpCallError", {
-	tool: Schema.String,
-	reason: Reason,
-	message: Schema.String
-}) {};
-const callError = (tool, reason) => new McpCallError({
-	tool,
-	reason,
-	message: `MCP tools/call "${tool}" ${sentenceOf(reason)}`
-});
+// src/mcp/client.ts
 const textOf = (block) => block?.type === "text" ? block.text : void 0;
 const ToolCallReply = Schema.Union([Schema.Struct({ result: McpSchema.CallToolResult }), Schema.Struct({ error: Schema.Struct({
 	code: Schema.Finite,
 	message: Schema.String
 }) })]);
 const decodeReply = Schema.decodeUnknownOption(Schema.fromJsonString(ToolCallReply));
-const replyOf = (response, text) => {
-	if (!(response.headers["content-type"] ?? "").startsWith("text/event-stream")) return decodeReply(text);
-	const data = [];
-	Sse.makeParser((event) => {
-		if (Predicate.isTagged(event, "Event")) data.push(event.data);
-	}).feed(text);
-	return Option.fromNullishOr(data.flatMap((message) => Option.toArray(decodeReply(message))).at(-1));
+/** `onProgress` given each `notifications/progress` value decoded, one that does not logged and dropped. */
+const decodedSink = (progress, onProgress) => {
+	const sink = progressSink(onProgress);
+	if (progress === void 0 || sink === void 0) return;
+	const decode = Schema.decodeUnknownEffect(Schema.toCodecJson(progress));
+	return { progress: (json) => Effect.matchEffect(decode(json), {
+		onFailure: (error) => Effect.logWarning("A progress value did not decode", error),
+		onSuccess: sink.progress
+	}) };
 };
-const failWith = (errors, text, otherwise) => Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.toCodecJson(Schema.Union(errors))))(text).pipe(Effect.mapError(() => otherwise), Effect.flatMap(Effect.fail));
-const callTool = (client, url, action, lift, refusedWith, input) => {
+const callTool = (client, url, action, success, refusedWith, input, sink) => {
 	const { name } = action;
+	const lift = liftOf(success);
+	const method = "tools/call";
 	return Effect.gen(function* () {
-		const encoded = yield* Schema.encodeEffect(Schema.toCodecJson(action.input))(input);
-		const response = yield* client.execute(request("tools/call", {
+		const response = yield* client.execute(request(method, {
 			name,
-			arguments: encoded
+			arguments: input,
+			...sink === void 0 ? {} : { _meta: { progressToken: "progress" } }
 		}, { url }));
-		const text = yield* response.text;
-		if (response.status !== 200) return yield* failWith(refusedWith, text, callError(name, new StatusError({
+		const messages = yield* bodyOf(method, name, response, sink);
+		const text = messages.join("\n");
+		if (response.status !== 200) return yield* failWith(refusedWith, text, callError(method, name, new StatusError({
 			status: response.status,
 			body: text
 		})));
-		const reply = replyOf(response, text);
-		if (Option.isNone(reply)) return yield* Effect.fail(callError(name, new NoReply({ body: text })));
-		if ("error" in reply.value) return yield* Effect.fail(callError(name, new ProtocolError(reply.value.error)));
+		const reply = Option.fromNullishOr(messages.flatMap((message) => Option.toArray(decodeReply(message))).at(-1));
+		if (Option.isNone(reply)) return yield* callError(method, name, new NoReply({ body: text }));
+		if ("error" in reply.value) return yield* callError(method, name, new ProtocolError(reply.value.error));
 		const { result } = reply.value;
 		if (result.isError === true) {
 			const error = textOf(result.content.find((block) => block.type === "text")) ?? "";
-			return yield* failWith(projectedErrors(action), error, callError(name, new UndeclaredError({ text: error })));
+			return yield* failWith(projectedErrors(action), error, callError(method, name, new UndeclaredError({ text: error })));
 		}
-		if (result.structuredContent === void 0 && lift.rest !== void 0) return yield* Effect.fail(callError(name, new NoStructuredContent({ body: text })));
-		return yield* Schema.decodeUnknownEffect(Schema.toCodecJson(action.success))(unliftedFrom(lift, result));
+		if (result.structuredContent === void 0 && lift.rest !== void 0) return yield* callError(method, name, new NoStructuredContent({ body: text }));
+		return yield* Schema.decodeUnknownEffect(Schema.toCodecJson(success))(unliftedFrom(lift, result));
 	});
 };
-function client(actions, { url = defaultPath, transformClient, authentication } = {}) {
+function client(contracts, { url = defaultPath, transformClient, authentication } = {}) {
+	const { actions, events } = split(contracts);
 	assertOnce("action", actions);
+	assertOnce("event", events);
+	const refusedWith = (contract) => [...Refusal.members, ...contract.caller === Anyone ? [] : authentication?.error ?? []];
 	return Effect.map(HttpClient.HttpClient, (native) => {
 		const http = transformClient === void 0 ? native : transformClient(native);
-		return Object.fromEntries(actions.map((action) => {
-			const lift = liftOf(action.success);
-			const refusedWith = [...Refusal.members, ...action.caller === Anyone ? [] : authentication?.error ?? []];
-			return [action.name, checked(action, (input) => callTool(http, url, action, lift, refusedWith, input))];
-		}));
+		const watch = (event, input, options) => Stream.unwrap(Effect.map(watchInput(event, input), ({ json }) => watching(transportOf({
+			http,
+			url,
+			event,
+			refusedWith: refusedWith(event)
+		}, json), options)));
+		return {
+			...Object.fromEntries(actions.map((action) => {
+				const call = (success, input, onProgress) => callTool(http, url, action, success, refusedWith(action), input, decodedSink(action.progress, onProgress));
+				const element = elementOf(action.success);
+				if (element !== void 0) {
+					const elements = Schema.Array(element);
+					return [action.name, checkedStream(action, sendingJson, (input, onProgress) => Stream.fromIterableEffect(call(elements, input, onProgress)))];
+				}
+				return [action.name, checked(action, sendingJson, (input, onProgress) => call(action.success, input, onProgress))];
+			})),
+			...events.length === 0 ? {} : { watch }
+		};
 	});
 }
-/**
-* 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.
-*/
-const request = (method, params = {}, { headers = {}, url = defaultPath } = {}) => {
-	const { headers: routingHeaders, body } = statelessRequest(method, params);
-	return HttpClientRequest.post(url).pipe(HttpClientRequest.setHeaders(headers), HttpClientRequest.setHeaders(routingHeaders), HttpClientRequest.bodyJsonUnsafe(body));
-};
-//#endregion
-export { McpCallError, client, request, statelessRequest };
+export { client };

package/dist/mcp/events.mjs

@@ -0,0 +1,142 @@
+import { eventCodes } from "../contract/codes.mjs";
+import { Subscribed, WebhookCallback, WebhookTarget, webhookFields } from "../contract/subscribe.mjs";
+import { ErrorReporter, Schema, Struct } from "effect";
+import { McpSchema } from "effect/ai";
+import { Rpc, RpcGroup } from "effect/rpc";
+// src/mcp/events.ts
+/** The extension's identifier, its key in `capabilities.extensions`. */
+const extension = "io.modelcontextprotocol/events";
+/** The `_meta` key a push stream's notifications carry its request id under. */
+const subscriptionIdKey = "io.modelcontextprotocol/subscriptionId";
+const codes = {
+	headerMismatch: -32020,
+	...eventCodes,
+	invalidParams: -32602,
+	internal: -32603
+};
+const Meta = Schema.optional(Schema.Record(Schema.String, Schema.Json));
+const Arguments = Schema.optional(Schema.Record(Schema.String, Schema.Json));
+const Cursor = Schema.optional(Schema.NullOr(Schema.String));
+/** A JSON-RPC error as an `events/*` request fails with, and a termination carries. */
+const WireError = Schema.Struct({
+	code: Schema.Int,
+	message: Schema.String,
+	data: Schema.optional(Schema.Json)
+});
+/** What an `events/*` handler fails with: the JSON-RPC error it answers. */
+var EventsError = class extends Schema.Error("effect-actions/McpEventsError")(WireError.fields) {
+	[ErrorReporter.ignore] = true;
+};
+/** One event type as `events/list` lists it. */
+const EventDescriptor = Schema.Struct({
+	name: Schema.String,
+	description: Schema.String,
+	delivery: Schema.Array(Schema.Literals([
+		"poll",
+		"push",
+		"webhook"
+	])),
+	inputSchema: McpSchema.ToolJson,
+	payloadSchema: McpSchema.ToolOutputJson
+});
+/** An occurrence on the wire: in a poll's `events`, and the params of an event notification. */
+const WireOccurrence = Schema.Struct({
+	eventId: Schema.String,
+	name: Schema.String,
+	timestamp: Schema.String,
+	data: Schema.Json,
+	cursor: Cursor
+});
+const subscription = {
+	_meta: Meta,
+	name: Schema.String,
+	arguments: Arguments,
+	cursor: Cursor,
+	maxAgeMs: Schema.optional(Schema.Finite)
+};
+var ListEvents = class extends Rpc.make("events/list", {
+	payload: {
+		_meta: Meta,
+		cursor: Schema.optional(Schema.String)
+	},
+	success: Schema.Struct({
+		resultType: Schema.Literal("complete"),
+		events: Schema.Array(EventDescriptor),
+		_meta: Meta
+	}),
+	error: EventsError
+}) {};
+var PollEvents = class extends Rpc.make("events/poll", {
+	payload: {
+		...subscription,
+		maxEvents: Schema.optional(Schema.Finite)
+	},
+	success: Schema.Struct({
+		resultType: Schema.Literal("complete"),
+		events: Schema.Array(WireOccurrence),
+		cursor: Cursor,
+		truncated: Schema.optional(Schema.Boolean),
+		hasMore: Schema.optional(Schema.Boolean),
+		nextPollMs: Schema.optional(Schema.Finite),
+		_meta: Meta
+	}),
+	error: EventsError
+}) {};
+var StreamEvents = class extends Rpc.make("events/stream", {
+	payload: subscription,
+	success: Schema.Struct({
+		resultType: Schema.Literal("complete"),
+		_meta: Meta
+	}),
+	error: EventsError
+}) {};
+var SubscribeEvents = class extends Rpc.make("events/subscribe", {
+	payload: {
+		...subscription,
+		delivery: WebhookCallback.mapFields(Struct.assign({ mode: Schema.Literal("webhook") })),
+		ttlMs: webhookFields.ttlMs
+	},
+	success: Schema.Struct({
+		resultType: Schema.Literal("complete"),
+		...Subscribed.fields,
+		_meta: Meta
+	}),
+	error: EventsError
+}) {};
+var UnsubscribeEvents = class extends Rpc.make("events/unsubscribe", {
+	payload: {
+		_meta: Meta,
+		name: Schema.String,
+		arguments: Arguments,
+		delivery: WebhookTarget
+	},
+	success: Schema.Struct({
+		resultType: Schema.Literal("complete"),
+		_meta: Meta
+	}),
+	error: EventsError
+}) {};
+const Active = Rpc.make("notifications/events/active", { payload: {
+	_meta: Meta,
+	cursor: Cursor,
+	truncated: Schema.optional(Schema.Boolean)
+} });
+const Occurred = Rpc.make("notifications/events/event", { payload: {
+	...WireOccurrence.fields,
+	_meta: Meta
+} });
+const Heartbeat = Rpc.make("notifications/events/heartbeat", { payload: {
+	_meta: Meta,
+	cursor: Cursor
+} });
+const Failed = Rpc.make("notifications/events/error", { payload: {
+	_meta: Meta,
+	error: WireError
+} });
+const Terminated = Rpc.make("notifications/events/terminated", { payload: {
+	_meta: Meta,
+	error: WireError
+} });
+const Requests = RpcGroup.make(ListEvents, PollEvents, StreamEvents, SubscribeEvents, UnsubscribeEvents);
+const Notifications = RpcGroup.make(Active, Occurred, Heartbeat, Failed, Terminated);
+export { Active, EventDescriptor, EventsError, Failed, Heartbeat, ListEvents, Notifications, Occurred, PollEvents, Requests, StreamEvents, SubscribeEvents, Terminated, UnsubscribeEvents, WireError, WireOccurrence, codes, extension, subscriptionIdKey };

package/dist/mcp/progress.mjs

@@ -0,0 +1,34 @@
+import { Effect, Option, Schema } from "effect";
+import { McpSchema } from "effect/ai";
+// src/mcp/progress.ts
+/** The `_meta` key a `notifications/progress` carries its value under, as JSON. */
+const progressKey = "effect-actions/progress";
+const tokenOf = Schema.decodeUnknownOption(McpSchema.ProgressToken);
+/**
+* Where a tool call's progress goes: a `notifications/progress` for each value, on the
+* `progressToken` its request carried, `progress` counting from 1, `message` the value's JSON and
+* `_meta` the value; none for a request without a token, so the values are checked and dropped.
+*/
+const progressNotifier = (notifications, progress) => Effect.map(Effect.service(McpSchema.McpRequestContext), ({ requestMetadata }) => {
+	const token = tokenOf(requestMetadata?.progressToken);
+	if (Option.isNone(token)) return;
+	const encode = Schema.encodeUnknownEffect(Schema.toCodecJson(progress));
+	let sent = 0;
+	return { progress: (value) => Effect.flatMap(Effect.orDie(encode(value)), (json) => {
+		sent += 1;
+		return notifications["notifications/progress"]({
+			progressToken: token.value,
+			progress: sent,
+			message: JSON.stringify(json),
+			_meta: { [progressKey]: json }
+		});
+	}) };
+});
+const Notified = Schema.fromJsonString(Schema.Struct({
+	method: Schema.Literal("notifications/progress"),
+	params: Schema.Struct({ _meta: Schema.Struct({ [progressKey]: Schema.Json }) })
+}));
+const notifiedOf = Schema.decodeUnknownOption(Notified);
+/** The value a frame's `notifications/progress` carries, or none for another frame. */
+const progressOf = (data) => Option.map(notifiedOf(data), (notified) => notified.params._meta[progressKey]);
+export { progressKey, progressNotifier, progressOf };

package/dist/mcp/protocol.mjs

@@ -1,9 +1,9 @@
 import { unsuspended } from "../contract/ast.mjs";
 import { Media, isMarked, kindOf } from "../contract/media.mjs";
-import { Predicate, Schema, SchemaAST } from "effect";
-import { McpProtocol } from "effect/ai";
+import { JsonPointer, Predicate, Schema, SchemaAST } from "effect";
 import { Base64 } from "effect/encoding";
-//#region src/mcp/protocol.ts
+import { McpProtocol, McpSchema } from "effect/ai";
+// src/mcp/protocol.ts
 const httpProtocol = McpProtocol.v2026_07_28;
 const protocols = [
 	McpProtocol.v2026_07_28,
@@ -11,6 +11,31 @@ const protocols = [
 	McpProtocol.v2025_06_18
 ];
 const defaultPath = "/mcp";
+const isObjectSchema = Schema.is(McpSchema.ToolJson);
+const isJson = Schema.is(Schema.Json);
+const definitionsReferenced = (value) => {
+	if (value === null || Predicate.isString(value) || Predicate.isNumber(value) || Predicate.isBoolean(value)) return [];
+	if (Array.isArray(value)) return value.flatMap(definitionsReferenced);
+	return Object.entries(value).flatMap(([field, nested]) => {
+		if (field !== "$ref") return definitionsReferenced(nested);
+		const [scope, key] = Predicate.isString(nested) ? JsonPointer.parseUriFragment(nested) ?? [] : [];
+		return scope === "$defs" && key !== void 0 ? [key] : [];
+	});
+};
+const toolJsonSchema = (schema, strict) => {
+	const document = Schema.toJsonSchemaDocument(schema, { onExcessProperty: strict ? "error" : "ignore" });
+	const [scope, key] = Predicate.isString(document.schema["$ref"]) ? JsonPointer.parseUriFragment(document.schema["$ref"]) ?? [] : [];
+	const inlined = scope === "$defs" && key !== void 0 ? key : void 0;
+	const root = inlined === void 0 ? document.schema : document.definitions[inlined];
+	if (root === void 0) return;
+	const definitions = inlined !== void 0 && ![root, ...Object.values(document.definitions)].flatMap((definition) => isJson(definition) ? definitionsReferenced(definition) : []).includes(inlined) ? Object.fromEntries(Object.entries(document.definitions).filter(([name]) => name !== inlined)) : document.definitions;
+	return Object.keys(definitions).length === 0 ? root : {
+		...root,
+		$defs: definitions
+	};
+};
+/** The forms an MCP routing header may carry `name` in: as sent, or base64-encoded in its sentinel. */
+const routingFormsOf = (name) => [name, `=?base64?${Base64.encode(name)}?=`];
 const fieldKey = "effect-actions/field";
 const isMedia = Schema.is(Media);
 const isMediaArray = Schema.is(Schema.Array(Media));
@@ -22,7 +47,7 @@ const wholeSuccessMediaOf = (suspended) => {
 		kind: one,
 		many: false
 	};
-	if (!SchemaAST.isArrays(ast) || ast.encoding !== void 0) return void 0;
+	if (!SchemaAST.isArrays(ast) || ast.encoding !== void 0) return;
 	const [kind, ...others] = new Set([...ast.elements, ...ast.rest].map(kindOfUnsuspended));
 	return kind === void 0 || others.length > 0 ? void 0 : {
 		kind,
@@ -95,16 +120,17 @@ const holdsMediaAnywhere = (ast) => {
 	}
 	return false;
 };
-const isMisplaced = (action, { rest }) => {
-	return [
-		action.input,
-		...action.error,
-		...rest === void 0 ? [] : [rest]
-	].some(({ ast }) => holdsMediaAnywhere(ast));
-};
+const isMisplaced = (action, { rest }) => [
+	action.input,
+	...action.error,
+	...rest === void 0 ? [] : [rest]
+].some(({ ast }) => holdsMediaAnywhere(ast));
 const liftedFrom = (lift, success) => lift.fields.flatMap(({ name, kind, many }) => {
-	const value = name === void 0 ? success : Predicate.hasProperty(success, name) ? success[name] : void 0;
-	return (many ? isMediaArray(value) ? value : [] : isMedia(value) ? [value] : []).map((media) => ({
+	const field = name !== void 0 && Predicate.hasProperty(success, name) ? success[name] : void 0;
+	const value = name === void 0 ? success : field;
+	const listed = isMediaArray(value) ? value : [];
+	const single = isMedia(value) ? [value] : [];
+	return (many ? listed : single).map((media) => ({
 		kind,
 		field: name,
 		value: media
@@ -133,5 +159,4 @@ const unliftedFrom = (lift, result) => {
 		return field.name === void 0 || value === void 0 ? [] : [[field.name, value]];
 	})]);
 };
-//#endregion
-export { defaultPath, fieldKey, httpProtocol, isMisplaced, liftOf, liftedFrom, protocols, unliftedFrom };
+export { defaultPath, fieldKey, httpProtocol, isMisplaced, isObjectSchema, liftOf, liftedFrom, protocols, routingFormsOf, toolJsonSchema, unliftedFrom };