@gjermundgaraba/effect-actions 0.20.0 → 0.21.0

package/dist/ActionMcp.mjs

@@ -1,46 +1,28 @@
 import { Anyone, assertAuthentication } from "./contract/caller.mjs";
-import { assertOnce, heldOnce } from "./contract/names.mjs";
 import { projectedErrors } from "./contract/declared.mjs";
+import { assertOnce, heldOnce } from "./contract/names.mjs";
+import { toolSuccessOf } from "./contract/stream.mjs";
+import { acquire, answeringWhole } from "./contract/implementation.mjs";
+import { inputParseOptions } from "./contract/call.mjs";
 import { hintsOf } from "./contract/hints.mjs";
-import { acquire, provideHandlers, select, toList } from "./contract/implementation.mjs";
 import { promote, providerOf } from "./authentication/provider.mjs";
-import { inputParseOptions } from "./contract/call.mjs";
-import { defaultPath, fieldKey, httpProtocol, isMisplaced, liftOf, liftedFrom, protocols } from "./mcp/protocol.mjs";
+import { provideServed, selectFrom } from "./contract/serving.mjs";
 import { recordStepUp } from "./authentication/refusal.mjs";
 import { withStderrConsole } from "./stdio/console.mjs";
-import { McpCallError, client, request } from "./mcp/client.mjs";
-import { Cause, Context, Effect, ErrorReporter, Exit, Fiber, JsonPointer, Layer, Option, Predicate, Schema, Stdio, Stream } from "effect";
-import { AiError, McpSchema, McpServer } from "effect/ai";
+import { defaultPath, fieldKey, httpProtocol, isMisplaced, isObjectSchema, liftOf, liftedFrom, protocols, routingFormsOf, toolJsonSchema } from "./mcp/protocol.mjs";
+import { eventSchemasOf, refuseUnservable, serveWebhooks, withEvents } from "./mcp/bridge.mjs";
+import { progressNotifier } from "./mcp/progress.mjs";
+import { McpCallError } from "./mcp/reply.mjs";
+import { request } from "./mcp/request.mjs";
+import { client } from "./mcp/client.mjs";
+import { Cause, Context, Effect, ErrorReporter, Exit, Fiber, Layer, Option, Predicate, Schema, Stdio, Stream } from "effect";
 import { HttpRouter, HttpServerRequest } from "effect/http";
-import { Base64 } from "effect/encoding";
+import { AiError, McpSchema, McpServer } from "effect/ai";
 // src/mcp/ActionMcp.ts
-const isToolArgumentsSchema = 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 void 0;
-	const definitions = inlined !== void 0 && ![root, ...Object.values(document.definitions)].flatMap((schema) => isJson(schema) ? definitionsReferenced(schema) : []).includes(inlined) ? Object.fromEntries(Object.entries(document.definitions).filter(([name]) => name !== inlined)) : document.definitions;
-	return Object.keys(definitions).length === 0 ? root : {
-		...root,
-		$defs: definitions
-	};
-};
-const assertToolShapes = (lifted) => {
-	const inputs = lifted.map(([action]) => action).filter((action) => !isToolArgumentsSchema(toolJsonSchema(Schema.toCodecJson(action.input), true))).map(({ name }) => name);
+const assertToolsServable = (lifted) => {
+	const inputs = lifted.map(([action]) => action).flatMap(({ input, name }) => isObjectSchema(toolJsonSchema(Schema.toCodecJson(input), true)) ? [] : [name]);
 	if (inputs.length > 0) throw new Error(`MCP tool input must be one object with keys, such as a struct: ${inputs.join(", ")} (wrap a union, an array or a scalar in a field, omit input for no arguments, or leave the action out of actions)`);
-	const misplaced = lifted.filter(([action, lift]) => isMisplaced(action, lift)).map(([{ name }]) => name);
+	const misplaced = lifted.flatMap(([action, lift]) => isMisplaced(action, lift) ? [action.name] : []);
 	if (misplaced.length > 0) throw new Error(`MCP media must be the success or an array of it, or a top-level field of a struct success, one, optional or a required array: ${misplaced.join(", ")} (make the image such a field, or give an optional array as a required one, empty when absent; an image in input or an error is not served over MCP, so leave that action out of actions)`);
 };
 const nativeInternalErrorText = "Tool execution failed due to an internal server error.";
@@ -72,26 +54,30 @@ const toolOf = (action, outputSchema) => Effect.map(Schema.decodeUnknownEffect(M
 	},
 	_meta: action.mcp._meta === void 0 ? void 0 : { ...action.mcp._meta }
 }));
+const internalError = (cause) => Effect.logError(cause).pipe(Effect.andThen(ErrorReporter.report(cause)), Effect.as(textErrorResult(nativeInternalErrorText)));
+const internalErrorOnDefect = (cause) => Cause.hasDies(cause) ? internalError(cause) : Effect.failCause(cause);
+const encoder = (schema) => {
+	const encode = Schema.encodeUnknownEffect(Schema.toCodecJson(schema));
+	return (value) => Effect.orDie(encode(value));
+};
 const registerTools = Effect.fnUntraced(function* (apps, authentication) {
 	const registry = yield* McpServer.McpServer;
-	const bound = yield* acquire(apps);
+	const bound = yield* acquire(apps, authentication);
 	const built = yield* Effect.context();
-	const internalError = (cause) => Effect.logError(cause).pipe(Effect.andThen(ErrorReporter.report(cause)), Effect.as(textErrorResult(nativeInternalErrorText)));
-	const internalErrorOnDefect = (cause) => Cause.hasDies(cause) ? internalError(cause) : Effect.failCause(cause);
-	for (const [action, run] of bound) {
-		const lift = liftOf(action.success);
+	for (const [action, handler] of bound) {
+		const toolSuccess = toolSuccessOf(action.success);
+		const run = answeringWhole(action, handler);
+		const lift = liftOf(toolSuccess);
 		const media = lift.fields.length === 0 ? void 0 : lift;
-		const structured = media === void 0 ? Schema.toCodecJson(action.success) : media.rest === void 0 ? void 0 : Schema.toCodecJson(media.rest);
+		const structuredSuccess = media === void 0 ? toolSuccess : media.rest;
+		const structured = structuredSuccess === void 0 ? void 0 : Schema.toCodecJson(structuredSuccess);
 		const outputSchema = structured === void 0 ? void 0 : yield* Schema.decodeUnknownEffect(McpSchema.ToolOutputJson)(toolJsonSchema(structured, false)).pipe(Effect.orDie);
 		const tool = yield* toolOf(action, outputSchema).pipe(Effect.orDie);
 		const decode = Schema.decodeUnknownEffect(Schema.toCodecJson(action.input), inputParseOptions);
-		const encoder = (schema) => {
-			const encode = Schema.encodeUnknownEffect(Schema.toCodecJson(schema));
-			return (value) => Effect.orDie(encode(value));
-		};
-		const encodeSuccess = encoder(action.success);
+		const encodeSuccess = encoder(toolSuccess);
 		const encodeFailure = encoder(Schema.Union(projectedErrors(action)));
-		const call = authentication === void 0 || action.caller === Anyone ? run : (input) => recordStepUp(promote(authentication, run(input)));
+		const reported = (input) => action.progress === void 0 ? run(input) : Effect.flatMap(progressNotifier(registry.notifications, action.progress), (sink) => run(input, sink));
+		const call = authentication === void 0 || action.caller === Anyone ? reported : (input) => recordStepUp(promote(authentication, reported(input)));
 		const liftedFieldNames = new Set(media?.fields.map(({ name }) => name));
 		const resultOf = (encoded, success) => {
 			if (media === void 0) return new McpSchema.CallToolResult({
@@ -114,10 +100,7 @@ const registerTools = Effect.fnUntraced(function* (apps, authentication) {
 		yield* registry.addTool({
 			tool,
 			annotations: Context.empty(),
-			handle: (payload) => Effect.annotateCurrentSpan({
-				tool: action.name,
-				parameters: payload ?? {}
-			}).pipe(Effect.andThen(() => decode(payload ?? {})), Effect.mapError(({ message }) => new McpSchema.InvalidParams({ message: new AiError.ToolParameterValidationError({
+			handle: (payload) => Effect.annotateCurrentSpan({ tool: action.name }).pipe(Effect.andThen(() => decode(payload ?? {})), Effect.mapError(({ message }) => new McpSchema.InvalidParams({ message: new AiError.ToolParameterValidationError({
 				toolName: action.name,
 				description: message
 			}).message })), Effect.flatMap((input) => call(input).pipe(Effect.matchEffect({
@@ -130,34 +113,63 @@ const registerTools = Effect.fnUntraced(function* (apps, authentication) {
 		});
 	}
 });
-const server = (apps, transport, features = Layer.empty, authentication) => {
+/**
+* Refuses event types an endpoint cannot serve as MCP events: one named twice, one named as MCP's
+* own, or one whose input or payload is no object.
+*/
+const assertEventsServable = (events) => {
+	assertOnce("MCP event", events);
+	const reserved = events.find(({ name }) => name.startsWith("mcp."));
+	if (reserved !== void 0) throw new Error(`MCP event name starts with "mcp.", which MCP keeps for its own events: ${reserved.name} (rename it, or serve it on another surface)`);
+	for (const event of events) eventSchemasOf(event);
+};
+/** The revisions an endpoint speaks, the 2026-07-28 one serving `serving`'s events if any. */
+const servingEvents = ([stateless, ...rest], serving) => serving.events.length === 0 ? [stateless, ...rest] : [withEvents(stateless, serving), ...rest];
+const server = (apps, serving, transport, features = Layer.empty) => {
+	const { events, authentication } = serving;
 	assertOnce("MCP tool", apps.flatMap((app) => app.actions), heldOnce);
-	const lifted = apps.flatMap((app) => app.actions.map((action) => [action, liftOf(action.success)]));
-	assertToolShapes(lifted);
+	const lifted = apps.flatMap((app) => app.actions.map((action) => [action, liftOf(toolSuccessOf(action.success))]));
+	assertToolsServable(lifted);
 	const names = new Set(lifted.map(([{ name }]) => name));
 	const register = Effect.gen(function* () {
 		const namesClaimedByFeatures = (yield* McpServer.McpServer).tools.flatMap(({ tool }) => names.has(tool.name) ? [tool.name] : []);
 		if (namesClaimedByFeatures.length > 0) return yield* Effect.die(/* @__PURE__ */ new Error(`Duplicate MCP tool: ${namesClaimedByFeatures.join(", ")}, claimed by an action and a native feature (rename the native tool, or leave the action out of actions)`));
+		yield* refuseUnservable(serving);
+		yield* serveWebhooks(serving);
 		yield* registerTools(apps, authentication);
 	});
-	return Layer.effectDiscard(register).pipe(Layer.provide(features), Layer.provide(transport), Layer.fresh, provideHandlers(apps));
+	return Layer.effectDiscard(register).pipe(Layer.provide(features), Layer.provide(transport), Layer.fresh, provideServed({
+		apps,
+		events
+	}));
 };
 const anonymousMethods = /* @__PURE__ */ new Set([
 	"server/discover",
 	"tools/list",
+	"events/list",
 	"notifications/cancelled"
 ]);
-const requiresAuthentication = (actions) => {
-	const open = new Set(actions.filter(({ caller }) => caller === Anyone).flatMap(({ name }) => [name, `=?base64?${Base64.encode(name)}?=`]));
+const namedMethods = /* @__PURE__ */ new Map([
+	["tools/call", "tool"],
+	["events/poll", "event"],
+	["events/stream", "event"]
+]);
+const openOf = (contracts) => new Set(contracts.filter(({ caller }) => caller === Anyone).flatMap(({ name }) => routingFormsOf(name)));
+const requiresAuthentication = (actions, events) => {
+	const open = {
+		tool: openOf(actions),
+		event: openOf(events)
+	};
 	return (headers) => {
-		if (open.size === 0) return true;
+		if (open.tool.size === 0 && open.event.size === 0) return true;
 		if (headers["mcp-protocol-version"] !== httpProtocol.protocolVersion) return true;
 		const method = headers["mcp-method"];
 		if (method === void 0) return true;
 		if (anonymousMethods.has(method)) return false;
-		if (method !== "tools/call") return true;
+		const named = namedMethods.get(method);
+		if (named === void 0) return true;
 		const name = headers["mcp-name"];
-		return name === void 0 || !open.has(name);
+		return name === void 0 || !open[named].has(name);
 	};
 };
 const namesItsMethod = (request) => Effect.match(request.json, {
@@ -165,23 +177,30 @@ const namesItsMethod = (request) => Effect.match(request.json, {
 	onSuccess: (body) => !Predicate.hasProperty(body, "method") || body.method === request.headers["mcp-method"]
 });
 const readsItsBody = (route) => Effect.flatMap(HttpServerRequest.HttpServerRequest, (request) => request.method === "POST" ? Effect.andThen(request.text, route) : route);
-function layerHttp(apps, { actions, features, path = defaultPath, authentication, requestScoped, allowSubscriptions = features !== void 0, ...options }) {
-	const selected = select(toList(apps), actions);
+function layerHttp(apps, { actions, features, path = defaultPath, authentication, requestScoped, allowSubscriptions, ...options }) {
+	const { apps: selected, events } = selectFrom(apps, actions);
 	const served = selected.flatMap((app) => app.actions);
+	const listed = events.flatMap((app) => app.events);
 	assertAuthentication(served, authentication);
-	const transport = server(selected, requestScoped === true ? McpServer.layerHttpRequestScoped({
+	assertAuthentication(listed, authentication, "event");
+	assertEventsServable(listed);
+	const serving = {
+		events,
+		authentication
+	};
+	const transport = server(selected, serving, requestScoped === true ? McpServer.layerHttpRequestScoped({
 		...options,
 		path,
-		protocols: [httpProtocol]
+		protocols: servingEvents([httpProtocol], serving)
 	}) : McpServer.layerHttp({
 		...options,
 		path,
-		protocols,
+		protocols: servingEvents(protocols, serving),
 		allowSessionTermination: true,
-		allowSubscriptions
-	}), features, authentication);
+		allowSubscriptions: allowSubscriptions ?? (features !== void 0 || events.length > 0)
+	}), features);
 	if (authentication === void 0) return transport.pipe(Layer.provide(HttpRouter.middleware(readsItsBody).layer));
-	const required = requiresAuthentication(served);
+	const required = requiresAuthentication(served, listed);
 	const middleware = HttpRouter.middleware(Effect.map(providerOf(authentication), (runtime) => (route) => Effect.flatMap(HttpServerRequest.HttpServerRequest, (request) => request.method !== "POST" || required(request.headers) ? runtime.http(readsItsBody(route), false) : Effect.flatMap(namesItsMethod(request), (named) => runtime.http(readsItsBody(route), named)))));
 	return transport.pipe(Layer.provide(middleware.layer));
 }
@@ -191,9 +210,15 @@ const jsonLinesOnly = Layer.effect(Stdio.Stdio, Effect.map(Stdio.Stdio, (stdio)
 	stdin: stdio.stdin.pipe(Stream.decodeText, Stream.splitLines, Stream.filter(isJsonLine), Stream.map((line) => `${line}\n`), Stream.encodeText)
 })));
 function runStdio(apps, { actions, features, ...options }) {
-	const transport = server(select(toList(apps), actions), McpServer.layerStdio({
+	const { apps: selected, events } = selectFrom(apps, actions);
+	assertEventsServable(events.flatMap((app) => app.events));
+	const serving = {
+		events,
+		authentication: void 0
+	};
+	const transport = server(selected, serving, McpServer.layerStdio({
 		...options,
-		protocols
+		protocols: servingEvents(protocols, serving)
 	}).pipe(Layer.provide(jsonLinesOnly)), features);
 	return Layer.launch(transport).pipe(withStderrConsole, Effect.forkChild, Effect.flatMap(Fiber.await), Effect.flatMap((exit) => Exit.isFailure(exit) && !Cause.hasInterruptsOnly(exit.cause) ? Effect.failCause(exit.cause) : Effect.void));
 }