@gjermundgaraba/effect-actions 0.20.0 → 0.21.0

package/dist/mcp/client.mjs

@@ -1,162 +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";
 // 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)}`
-});
 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));
-};
-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,8 +1,8 @@
 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";
+import { McpProtocol, McpSchema } from "effect/ai";
 // src/mcp/protocol.ts
 const httpProtocol = McpProtocol.v2026_07_28;
 const protocols = [
@@ -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,4 +159,4 @@ const unliftedFrom = (lift, result) => {
 		return field.name === void 0 || value === void 0 ? [] : [[field.name, value]];
 	})]);
 };
-export { defaultPath, fieldKey, httpProtocol, isMisplaced, liftOf, liftedFrom, protocols, unliftedFrom };
+export { defaultPath, fieldKey, httpProtocol, isMisplaced, isObjectSchema, liftOf, liftedFrom, protocols, routingFormsOf, toolJsonSchema, unliftedFrom };

package/dist/mcp/reply.d.mts

@@ -0,0 +1,79 @@
+import "../contract/progress.mjs";
+import "../Action.mjs";
+import { Effect, Schema, Stream } from "effect";
+import { HttpClientError } from "effect/http";
+declare const StatusError_base: Schema.Class<StatusError, Schema.TaggedStruct<"StatusError", {
+  readonly status: Schema.Int;
+  readonly body: Schema.String;
+}>, import("effect/Cause").YieldableError & {
+  readonly brand: unique symbol;
+}>;
+/** The endpoint answered with an HTTP status other than 200, and a body no declared error decodes. */
+export 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 & {
+  readonly brand: unique symbol;
+}>;
+/**
+ * The endpoint answered with a JSON-RPC error, such as the native server's for an unknown tool.
+ */
+export declare class ProtocolError extends ProtocolError_base {}
+declare const NoReply_base: Schema.Class<NoReply, Schema.TaggedStruct<"NoReply", {
+  readonly body: Schema.String;
+}>, import("effect/Cause").YieldableError & {
+  readonly brand: unique symbol;
+}>;
+/** The endpoint answered 200 without a JSON-RPC reply to read, as JSON or as an event stream. */
+export declare class NoReply extends NoReply_base {}
+declare const UndeclaredError_base: Schema.Class<UndeclaredError, Schema.TaggedStruct<"UndeclaredError", {
+  readonly text: Schema.String;
+}>, import("effect/Cause").YieldableError & {
+  readonly brand: unique symbol;
+}>;
+/** The tool returned an error whose text decodes as none of the action's declared errors. */
+export declare class UndeclaredError extends UndeclaredError_base {}
+declare const NoStructuredContent_base: Schema.Class<NoStructuredContent, Schema.TaggedStruct<"NoStructuredContent", {
+  readonly body: Schema.String;
+}>, import("effect/Cause").YieldableError & {
+  readonly brand: unique symbol;
+}>;
+/** The tool returned a result without the structured content its action's success needs. */
+export declare class NoStructuredContent extends NoStructuredContent_base {}
+declare const FrameTooLarge_base: Schema.Class<FrameTooLarge, Schema.TaggedStruct<"FrameTooLarge", {
+  readonly maxEventSize: Schema.Int;
+}>, import("effect/Cause").YieldableError & {
+  readonly brand: unique symbol;
+}>;
+/**
+ * The endpoint's event stream held more than `maxEventSize` characters with no frame ending, the
+ * most a client holds while it waits for one.
+ *
+ * **Gotchas**
+ *
+ * - The limit is on what is held unended, as Effect's SSE parser checks it after each chunk: a frame larger than it that ends within the chunk carrying it is read.
+ */
+export declare class FrameTooLarge extends FrameTooLarge_base {}
+declare const McpCallError_base: Schema.Class<McpCallError, Schema.TaggedStruct<"McpCallError", {
+  readonly method: Schema.String;
+  readonly target: Schema.String;
+  readonly reason: Schema.Union<readonly [typeof StatusError, typeof ProtocolError, typeof NoReply, typeof UndeclaredError, typeof NoStructuredContent, typeof FrameTooLarge]>;
+  readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError & {
+  readonly brand: unique symbol;
+}>;
+/**
+ * An answer a client cannot read as the contract's: `method` is the request, `tools/call` or an
+ * `events/*` one, `target` the tool or event it named, and `reason` says what was wrong, with what
+ * the endpoint sent, so a caller branches on it with
+ * `Effect.catchReason("McpCallError", "StatusError", ...)`. `message` names all three.
+ * 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 {}
+export {};

package/dist/mcp/reply.mjs

@@ -0,0 +1,99 @@
+import { progressOf } from "./progress.mjs";
+import { Effect, Match, Option, Predicate, Schema, Stream } from "effect";
+import { Sse } from "effect/encoding";
+// src/mcp/reply.ts
+/** 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 }) {};
+/**
+* The endpoint's event stream held more than `maxEventSize` characters with no frame ending, the
+* most a client holds while it waits for one.
+*
+* **Gotchas**
+*
+* - The limit is on what is held unended, as Effect's SSE parser checks it after each chunk: a frame larger than it that ends within the chunk carrying it is read.
+*/
+var FrameTooLarge = class extends Schema.TaggedError()("FrameTooLarge", { maxEventSize: Schema.Int }) {};
+const Reason = Schema.Union([
+	StatusError,
+	ProtocolError,
+	NoReply,
+	UndeclaredError,
+	NoStructuredContent,
+	FrameTooLarge
+]);
+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}`,
+	FrameTooLarge: ({ maxEventSize }) => `sent more than ${maxEventSize} characters of an event stream with no frame ending`
+});
+/**
+* An answer a client cannot read as the contract's: `method` is the request, `tools/call` or an
+* `events/*` one, `target` the tool or event it named, and `reason` says what was wrong, with what
+* the endpoint sent, so a caller branches on it with
+* `Effect.catchReason("McpCallError", "StatusError", ...)`. `message` names all three.
+* 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", {
+	method: Schema.String,
+	target: Schema.String,
+	reason: Reason,
+	message: Schema.String
+}) {};
+const callError = (method, target, reason) => new McpCallError({
+	method,
+	target,
+	reason,
+	message: `MCP ${method} "${target}" ${sentenceOf(reason)}`
+});
+const isEventStream = (response) => (response.headers["content-type"] ?? "").startsWith("text/event-stream");
+/**
+* The data of each frame of the event stream `response` is, as it arrives: more than the parser
+* holds with no frame ending fails `method` on `name` with `FrameTooLarge`.
+*/
+const framesOf = (method, name, response) => Stream.suspend(() => {
+	const data = [];
+	const parser = Sse.makeParser((event) => {
+		if (Predicate.isTagged(event, "Event")) data.push(event.data);
+	});
+	return Stream.decodeText(response.stream).pipe(Stream.mapEffect((chunk) => {
+		const error = parser.feed(chunk);
+		return error === void 0 ? Effect.succeed(data.splice(0)) : Effect.fail(callError(method, name, new FrameTooLarge({ maxEventSize: error.reason.maxEventSize })));
+	}), Stream.flattenIterable);
+});
+/**
+* The messages of `response`, read as it arrives: the data of each frame of an event stream, or
+* the body itself as one. Each `notifications/progress` frame hands its value to `sink` and is
+* left out, so a long call holds the frames its reply is read from, not every value it reported.
+* A stateless request's notifications are its own.
+*/
+const bodyOf = (method, name, response, sink) => isEventStream(response) ? Stream.runCollect(Stream.filterEffect(framesOf(method, name, response), (data) => Option.match(progressOf(data), {
+	onNone: () => Effect.succeed(true),
+	onSome: (value) => sink === void 0 ? Effect.succeed(false) : Effect.as(sink.progress(value), false)
+}))) : Effect.map(response.text, (text) => [text]);
+/** Fails with the error of `errors` that `text` decodes as, or with `otherwise`. */
+const failWith = (errors, text, otherwise) => Schema.decodeEffect(Schema.fromJsonString(Schema.toCodecJson(Schema.Union(errors))))(text).pipe(Effect.mapError(() => otherwise), Effect.flatMap(Effect.fail));
+export { FrameTooLarge, McpCallError, NoReply, NoStructuredContent, ProtocolError, StatusError, UndeclaredError, bodyOf, callError, failWith, framesOf, isEventStream };