@gjermundgaraba/effect-actions 0.10.0 → 0.12.0

package/dist/ActionMcp.d.mts

@@ -1,10 +1,10 @@
-import { ActionOf, BuildError, BuildServices, Holding, Known, Member, Protected, SelectedOf, Selection, Served, ServedRequest } from "./internal/implementation.mjs";
+import { ActionOf, BuildError, BuildServices, Holding, Known, Member, Protected, SelectedOf, Selection, Served, ServedRequest } from "./contract/implementation.mjs";
 import { Action_d_exports, Any } from "./Action.mjs";
-import { Any as Any$1, Matching, ProviderOf, RemoteRequest, Required } from "./internal/authentication.mjs";
+import { Any as Any$1, Matching, ProviderOf, RemoteRequest, Required, ServerBuildServices } from "./authentication/provider.mjs";
 import { Cause, Effect, Layer, Stdio } from "effect";
-import { HttpRouter } from "effect/http";
 import { McpSchema, McpServer } from "effect/ai";
-//#region src/ActionMcp.d.ts
+import { HttpRouter } from "effect/http";
+//#region src/mcp/ActionMcp.d.ts
 /**
  * An MCP server, over HTTP or stdio: every native `McpServer.layerStdio` option except
  * `protocols`, the server information, `instructions` and `extensions`, the actions `A` that
@@ -24,58 +24,52 @@ export interface Options<E = never, R = never, A extends Any = Any> extends Omit
   readonly features?: Layer.Layer<never, E, R> | undefined;
 }
 /**
- * One Streamable HTTP MCP endpoint: `Options`, and every native `McpServer.layerHttp` option
- * except `protocols`, `allowedOrigins` among them, with `path` defaulting to `/mcp`.
+ * One Streamable HTTP MCP endpoint, speaking MCP 2026-07-28, 2025-11-25 or 2025-06-18, as the
+ * client negotiates: `Options`, and every native `McpServer.layerHttp` option, `allowedOrigins`
+ * among them, except `protocols` and `allowSessionTermination`, which are fixed, with `path`
+ * defaulting to `/mcp`. A client of a 2025 revision opens a session with `initialize`, which
+ * lasts until that client ends it with a DELETE, answered 204, or the process stops.
  */
-export interface LayerHttpOptions<E = never, R = never, A extends Any = Any> extends Options<E, R, A>, Omit<Parameters<typeof McpServer.layerHttp>[0], "protocols" | "path"> {
+export interface LayerHttpOptions<E = never, R = never, A extends Any = Any> extends Options<E, R, A>, Omit<Parameters<typeof McpServer.layerHttp>[0], "protocols" | "path" | "allowSessionTermination"> {
   /** The endpoint's route; defaults to `/mcp`. */
   readonly path?: HttpRouter.PathInput;
   readonly authentication?: Any$1;
 }
-/**
- * The native server supplies its own request context to every tool call, and the registry
- * it registers the tools on, the endpoint's own; over HTTP the router its own, such as the
- * request.
- */
 type ToolRequestContext<R> = Exclude<R, McpSchema.McpRequestContext | McpServer.McpServer>;
 type HttpToolRequestContext<R> = Exclude<ToolRequestContext<R>, HttpRouter.Provided>;
-/**
- * What the native features owe, `R`, beside the registry, which the endpoint provides them,
- * so one registering through `McpServer.registerResource` owes it no host.
- */
 type Features<R> = Exclude<R, McpServer.McpServer>;
-/**
- * Where `D`, the descriptor given, is inferred, so the provider owed is that descriptor's.
- * Without one, tools `A` all public take none, even past a `D` given explicitly; protected
- * ones state theirs in `RequiredAuthentication` alone, as an absent `authentication` and the
- * one they require would intersect to `never`, reading as every option being wrong.
- */
 type Inferring<D, A extends Any> = [D] extends [undefined] ? [Protected<A>] extends [never] ? {
   readonly authentication?: undefined;
 } : unknown : {
   readonly authentication?: D;
 };
 /**
- * Serve MCP tools over one Streamable HTTP endpoint, speaking MCP 2026-07-28 only.
+ * Serve MCP tools over one Streamable HTTP endpoint, speaking MCP 2026-07-28, 2025-11-25 or
+ * 2025-06-18, as the client negotiates. A 2026-07-28 request stands alone; a client of a 2025
+ * revision opens a session with `initialize`, which holds what it sent there and no identity,
+ * and lasts until that client ends it with a DELETE, answered 204, or the process stops.
  *
  * Protected tools need the `authentication` descriptor their contracts name, and the
  * provider `Authentication.layer` builds from it. On an endpoint of protected tools only,
  * every request authenticates before it is decoded. On a mixed endpoint, anyone may discover
- * the server, list its tools, cancel, and call a public tool; everything else authenticates
- * first, so a protected tool's description is listed to anyone but run only for its caller.
- * A call refused with `Unauthenticated`, or with `Forbidden` naming scopes, is answered with
- * its HTTP status and challenge, 401 or 403, as MCP authorization requires; any other
- * failure is a tool result. In a tool call, what middleware provides per request wins over
+ * the server, list its tools, cancel, and call a public tool in a 2026-07-28 request;
+ * everything else authenticates first, a session's every request included, so a protected
+ * tool's description is listed to anyone but run only for its caller.
+ * On a Bearer endpoint, a protected tool's call refused with `Unauthenticated`, or with
+ * `Forbidden` naming scopes, is answered with its HTTP status and challenge, 401 or 403, as MCP
+ * authorization requires, unless its response has started; any other failure is a tool result. Claude Code connects with
+ * `claude mcp add --transport http <name> <url>`. In a tool call, what middleware provides per request wins over
  * what the endpoint was built with; native `features` read only what they were built with,
  * never a request's. Never provide an identity at startup: a tool call takes its identity
  * only from the request it authenticated.
+ * Guide: `docs/ActionMcp.md` in this package; in an application: `examples/mcp-tools/`.
  */
-export declare function layerHttp<const Apps extends Served, const O extends Selection<ActionOf<Member<Apps>>> = {}, E = never, R = never, const D extends Any$1 | undefined = undefined>(implementations: Apps, options: LayerHttpOptions<E, R, ActionOf<Member<Apps>>> & O & NoInfer<Known<O, LayerHttpOptions<E, R, Any>>> & NoInfer<Required<SelectedOf<O, Apps>>> & Matching<NoInfer<SelectedOf<O, Apps>>, NoInfer<D>> & Inferring<D, NoInfer<SelectedOf<O, Apps>>>): Layer.Layer<never, BuildError<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>> | Cause.IllegalArgumentError | E, BuildServices<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>> | HttpRouter.HttpRouter | HttpRouter.Request.From<"Requires", HttpToolRequestContext<RemoteRequest<Member<Apps>, SelectedOf<O, Apps>>>> | ProviderOf<D> | Features<R>>;
+export declare function layerHttp<const Apps extends Served, const O extends Selection<ActionOf<Member<Apps>>> = {}, E = never, R = never, const D extends Any$1 | undefined = undefined>(implementations: Apps, options: LayerHttpOptions<E, R, ActionOf<Member<Apps>>> & O & NoInfer<Known<O, LayerHttpOptions<E, R, Any>>> & NoInfer<Required<SelectedOf<O, Apps>>> & Matching<NoInfer<SelectedOf<O, Apps>>, NoInfer<D>> & Inferring<D, NoInfer<SelectedOf<O, Apps>>>): Layer.Layer<never, BuildError<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>> | Cause.IllegalArgumentError | E, ServerBuildServices<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>> | HttpRouter.HttpRouter | HttpRouter.Request.From<"Requires", HttpToolRequestContext<RemoteRequest<Member<Apps>, SelectedOf<O, Apps>>>> | ProviderOf<D> | Features<R>>;
 /**
  * Serve MCP tools through newline-delimited JSON-RPC on standard I/O, speaking MCP
  * 2026-07-28, 2025-11-25 or 2025-06-18, as the host negotiates: the whole
- * program of an MCP subprocess, which succeeds once the host closes its side and the calls in
- * flight, which that interrupts, have stopped. A signal interrupts it.
+ * program of an MCP subprocess, which succeeds once the host closes its side and every call
+ * in flight has been answered. A signal interrupts it.
  *
  * Effect logs go to stderr, since stdout carries the protocol. The host supplies the
  * `Stdio` service and the identity. Arguments are tool input only and never establish

package/dist/ActionMcp.mjs

@@ -1,105 +1,170 @@
-import { Anyone } from "./internal/actions.mjs";
-import { provideHandlers, select, toList } from "./internal/implementation.mjs";
-import { assertAuthentication, promote } from "./internal/authentication.mjs";
-import { httpProtocol } from "./internal/mcp.mjs";
-import { recordStepUp } from "./internal/refusal.mjs";
-import { logToStderr } from "./internal/console.mjs";
-import { bindTools } from "./internal/tools.mjs";
-import { Cause, Context, Effect, Exit, Fiber, JsonPointer, Layer, Predicate, Schema } from "effect";
+import { Anyone } from "./contract/rules.mjs";
+import { provideHandlers, select, toList } from "./contract/implementation.mjs";
+import { bindTools } from "./toolkit/tools.mjs";
+import { fieldKey, httpProtocol, isMisplaced, liftOf, liftedFrom, protocols } from "./mcp/protocol.mjs";
+import { assertAuthentication, promote, providerOf } from "./authentication/provider.mjs";
+import { recordStepUp } from "./authentication/refusal.mjs";
+import { withStderrConsole } from "./stdio/console.mjs";
+import { Cause, Context, Effect, ErrorReporter, Exit, Fiber, JsonPointer, Layer, Option, Predicate, References, Result, Schema, Stream } from "effect";
+import { AiError, McpSchema, McpServer, Tool, Toolkit } from "effect/ai";
 import { HttpRouter, HttpServerRequest } from "effect/http";
-import { McpProtocol, McpSchema, McpServer, Tool } from "effect/ai";
-//#region src/ActionMcp.ts
-/**
-* The revisions served over stdio: 2026-07-28 and the stateful revisions hosts open stdio
-* with, newest first; a host asking for another is offered 2025-11-25. A success is sent as it
-* is on each. 2026-07-28 carries any success as `structuredContent`; the adapters of 2025-11-25
-* and 2025-06-18 carry only an object there, and list only an object-rooted `outputSchema`. A
-* success they do not structure is text alone, a string as itself.
-*/
-const stdioProtocols = [
-	McpProtocol.v2026_07_28,
-	McpProtocol.v2025_11_25,
-	McpProtocol.v2025_06_18
-];
-/**
-* MCP has a JSON-only wire contract. Success is the encoded success as structured content,
-* and its JSON as text; declared failures are returned as JSON text. The native server
-* refuses undeclared arguments and publishes closed input schemas.
-*/
-const projection = {
+//#region src/mcp/ActionMcp.ts
+const strictToolProjection = {
 	label: "MCP tool",
 	tool: (tool) => tool.annotate(Tool.Strict, true)
 };
-/** Whether a JSON Schema is one the native server takes for a tool's arguments. */
-const isToolJson = Schema.is(McpSchema.ToolJson);
-/**
-* The JSON Schema root of `schema` as the native server lists it for a tool, a `$ref` at its
-* root resolved.
-*/
-const rootOf = (schema) => {
-	const document = Schema.toJsonSchemaDocument(Schema.toCodecJson(schema));
+const isToolArgumentsSchema = Schema.is(McpSchema.ToolJson);
+const nativeToolJsonSchema = (schema, strict) => {
+	const document = Schema.toJsonSchemaDocument(schema, { onExcessProperty: strict ? "error" : "ignore" });
 	const [scope, key] = Predicate.isString(document.schema.$ref) ? JsonPointer.parseUriFragment(document.schema.$ref) ?? [] : [];
-	return scope === "$defs" && key !== void 0 ? document.definitions[key] : document.schema;
+	const root = scope === "$defs" && key !== void 0 ? document.definitions[key] : document.schema;
+	return root === void 0 || Object.keys(document.definitions).length === 0 ? root : {
+		...root,
+		$defs: document.definitions
+	};
 };
-/**
-* Refuse, when the server is made, the actions of `apps` whose input is not one object, as the
-* root of a tool's arguments must be, naming every one, reading the JSON Schema the native
-* server reads: not a union, an array, a scalar, nor `Schema.Struct({})`, which takes any value
-* but `null`, where the native server dies when the layer builds, suggesting
-* `Tool.EmptyParams`.
-*/
-const assertShapes = (apps) => {
-	const inputs = apps.flatMap((app) => app.actions).filter((action) => !isToolJson(rootOf(action.input))).map(({ name }) => name);
+const assertToolShapes = (lifted) => {
+	const inputs = lifted.map(([action]) => action).filter((action) => !isToolArgumentsSchema(nativeToolJsonSchema(Schema.toCodecJson(action.input), true))).map(({ name }) => name);
 	if (inputs.length > 0) throw new Error(`MCP tool input must be one object with keys, such as a struct: ${inputs.join(", ")}`);
+	const misplaced = lifted.filter(([action, lift]) => isMisplaced(action, lift)).map(([{ name }]) => 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(", ")}`);
 };
+const nativeInternalErrorText = "Tool execution failed due to an internal server error.";
+const textErrorResult = (text) => new McpSchema.CallToolResult({
+	isError: true,
+	content: [{
+		type: "text",
+		text
+	}]
+});
+const nativeJsonTextOf = (encoded) => encoded === void 0 ? [] : [{
+	type: "text",
+	text: JSON.stringify(encoded)
+}];
+const contentBlockOf = ({ kind, field, value }) => ({
+	type: kind,
+	data: value.data,
+	mimeType: value.mimeType,
+	...field === void 0 ? {} : { _meta: { [fieldKey]: field } }
+});
+const parameterValidationErrorOf = (error) => AiError.isAiError(error) && Predicate.isTagged(error.reason, "ToolParameterValidationError") ? error.reason : void 0;
+const omitRequestServices = Context.omit(McpSchema.McpRequestContext, McpSchema.McpServerClient, HttpServerRequest.HttpServerRequest, References.CurrentLogLevel);
+const registerToolsLiftingMedia = Effect.fnUntraced(function* (toolkit, lifts) {
+	const registry = yield* McpServer.McpServer;
+	const built = yield* toolkit.pipe(Effect.updateContext((context) => Context.merge(context, Context.mergeAll(...Object.values(toolkit.tools).flatMap((tool) => {
+		const key = Context.Service(tool.id);
+		return Option.toArray(Context.getOption(context, key)).map((handler) => Context.make(key, {
+			...handler,
+			context: omitRequestServices(handler.context)
+		}));
+	})))));
+	const retainedServices = omitRequestServices(yield* Effect.context());
+	const propagateInterruptOrReportInternal = (cause) => {
+		const failure = Cause.findFail(cause);
+		return Result.isFailure(failure) && !Cause.hasDies(cause) ? Effect.failCause(failure.failure) : Effect.logError(cause).pipe(Effect.andThen(Effect.provideContext(ErrorReporter.report(cause), retainedServices)), Effect.as(textErrorResult(nativeInternalErrorText)));
+	};
+	const invalidParamsOrInternal = (cause) => {
+		const failure = Cause.findFail(cause);
+		if (Result.isSuccess(failure)) {
+			const { error } = failure.success;
+			const invalid = Context.get(Cause.reasonAnnotations(failure.success), Toolkit.FailureOrigin) === "parameters" ? parameterValidationErrorOf(error) : void 0;
+			if (invalid !== void 0) return Effect.fail(new McpSchema.InvalidParams({ message: invalid.message }));
+		}
+		return propagateInterruptOrReportInternal(cause);
+	};
+	const registrations = yield* Effect.forEach(Object.entries(built.tools), ([name, tool]) => Effect.gen(function* () {
+		const strict = Tool.getStrictMode(tool) === true;
+		const decodeOptions = {
+			onExcessProperty: strict ? "error" : "ignore",
+			errors: "all"
+		};
+		const lift = lifts.get(name);
+		const media = lift === void 0 || lift.fields.length === 0 ? void 0 : lift;
+		const structured = media === void 0 ? tool.successSchema : media.rest === void 0 ? void 0 : Schema.toCodecJson(media.rest);
+		const outputSchema = structured === void 0 ? void 0 : yield* Schema.decodeUnknownEffect(McpSchema.ToolOutputJson)(nativeToolJsonSchema(structured, false)).pipe(Effect.orDie);
+		const inputSchema = yield* Schema.decodeUnknownEffect(McpSchema.ToolJson)(nativeToolJsonSchema(tool.parametersSchema, strict)).pipe(Effect.orDie);
+		const liftedFieldNames = new Set(media?.fields.map(({ name }) => name));
+		const resultWithLiftedMedia = ({ encodedResult, result }) => {
+			if (media === void 0) return new McpSchema.CallToolResult({
+				isError: false,
+				structuredContent: encodedResult,
+				content: nativeJsonTextOf(encodedResult)
+			});
+			const blocks = liftedFrom(media, result).map(contentBlockOf);
+			if (structured === void 0) return new McpSchema.CallToolResult({
+				isError: false,
+				content: blocks
+			});
+			const encodedRestOfStruct = Predicate.isObject(encodedResult) ? Object.fromEntries(Object.entries(encodedResult).filter(([key]) => !liftedFieldNames.has(key))) : encodedResult;
+			return new McpSchema.CallToolResult({
+				isError: false,
+				structuredContent: encodedRestOfStruct,
+				content: [...nativeJsonTextOf(encodedRestOfStruct), ...blocks]
+			});
+		};
+		return {
+			tool: new McpSchema.Tool({
+				name,
+				description: Tool.getDescription(tool),
+				inputSchema,
+				outputSchema,
+				annotations: {
+					...Context.getOption(tool.annotations, Tool.Title).pipe(Option.map((title) => ({ title })), Option.getOrUndefined),
+					readOnlyHint: Context.get(tool.annotations, Tool.Readonly),
+					destructiveHint: Context.get(tool.annotations, Tool.Destructive),
+					idempotentHint: Context.get(tool.annotations, Tool.Idempotent),
+					openWorldHint: Context.get(tool.annotations, Tool.OpenWorld)
+				},
+				_meta: Context.getOrUndefined(tool.annotations, Tool.Meta)
+			}),
+			annotations: tool.annotations,
+			handle: (payload) => built.handle(name, payload ?? {}, void 0, decodeOptions).pipe(Stream.unwrap, Stream.runLast, Effect.flatMap(Effect.fromOption), Effect.flatMap((result) => !result.isFailure ? Effect.succeed(resultWithLiftedMedia(result)) : result.failureOrigin === "handler" ? Effect.succeed(new McpSchema.CallToolResult({
+				isError: true,
+				content: nativeJsonTextOf(result.encodedResult)
+			})) : Effect.failCause(Cause.annotate(Cause.fail(result.result), Context.make(Toolkit.FailureOrigin, result.failureOrigin ?? "result")))), Effect.catchCause(invalidParamsOrInternal), Effect.provideContext(retainedServices))
+		};
+	}));
+	for (const registration of registrations) yield* registry.addTool(registration);
+});
 const server = (apps, transport, features = Layer.empty, authentication) => {
-	const binding = bindTools(apps, authentication === void 0 ? projection : {
-		...projection,
+	const binding = bindTools(apps, authentication === void 0 ? strictToolProjection : {
+		...strictToolProjection,
 		handler: (run, action) => (input) => action.caller === Anyone ? run(input) : recordStepUp(promote(authentication, run(input)))
 	});
-	assertShapes(apps);
-	const names = new Set(apps.flatMap((app) => app.actions.map(({ name }) => name)));
+	const lifted = apps.flatMap((app) => app.actions.map((action) => [action, liftOf(action.success)]));
+	assertToolShapes(lifted);
+	const lifts = new Map(lifted.map(([{ name }, lift]) => [name, lift]));
 	const register = Effect.gen(function* () {
 		const registry = yield* McpServer.McpServer;
-		const claimed = registry.tools.flatMap(({ tool }) => names.has(tool.name) ? [tool.name] : []);
-		if (claimed.length > 0) return yield* Effect.die(/* @__PURE__ */ new Error(`Duplicate MCP tool: ${claimed.join(", ")}, claimed by an action and a native feature`));
+		const namesClaimedByFeatures = registry.tools.flatMap(({ tool }) => lifts.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`));
 		const handlers = yield* Layer.build(binding.layer);
-		yield* McpServer.registerToolkit(binding.toolkit).pipe(Effect.setContext(Context.add(handlers, McpServer.McpServer, registry)));
+		yield* registerToolsLiftingMedia(binding.toolkit, lifts).pipe(Effect.setContext(Context.add(handlers, McpServer.McpServer, registry)));
 	});
 	return Layer.effectDiscard(register).pipe(Layer.provide(features), Layer.provide(transport), Layer.fresh, provideHandlers(apps));
 };
-/**
-* What an anonymous caller of a mixed endpoint may send besides a public tool's call:
-* discovering the server and its tools, which the contracts describe, and cancelling.
-* Everything else, a native feature's listing, completion or subscription among them, and
-* any method a later revision adds, authenticates.
-*/
-const anonymous = /* @__PURE__ */ new Set([
+const anonymousMethods = /* @__PURE__ */ new Set([
 	"server/discover",
 	"tools/list",
 	"notifications/cancelled"
 ]);
-/**
-* Whether a request to an endpoint serving `actions` must authenticate before the native
-* server reads its body. An endpoint whose every tool is protected authenticates every
-* request, so a host signs in when it connects. Otherwise the request's routing headers
-* decide, which the native server refuses when they disagree with the body: discovery and a
-* call of a public tool authenticate only a caller presenting credentials, and everything
-* else authenticates, so native features are protected too. A request whose headers name
-* no public tool as it is authenticates: it fails closed.
-*/
 const requiresAuthentication = (actions) => {
 	const open = new Set(actions.filter(({ caller }) => caller === Anyone).map(({ name }) => name));
 	return (headers) => {
 		if (open.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 (anonymous.has(method)) return false;
+		if (anonymousMethods.has(method)) return false;
 		if (method !== "tools/call") return true;
 		const name = headers["mcp-name"];
 		return name === void 0 || !open.has(name);
 	};
 };
+const namesItsMethod = (request) => Effect.match(request.json, {
+	onFailure: () => true,
+	onSuccess: (body) => !Predicate.hasProperty(body, "method") || body.method === request.headers["mcp-method"]
+});
 function layerHttp(apps, { actions, features, path, authentication, ...options }) {
 	const selected = select(toList(apps), actions);
 	const served = selected.flatMap((app) => app.actions);
@@ -107,19 +172,20 @@ function layerHttp(apps, { actions, features, path, authentication, ...options }
 	const transport = server(selected, McpServer.layerHttp({
 		...options,
 		path: path ?? "/mcp",
-		protocols: [httpProtocol]
+		protocols,
+		allowSessionTermination: true
 	}), features, authentication);
 	if (authentication === void 0) return transport;
 	const required = requiresAuthentication(served);
-	const middleware = HttpRouter.middleware(Effect.map(authentication["~provider"], (runtime) => (route) => Effect.flatMap(HttpServerRequest.HttpServerRequest, (request) => runtime.http(route, !required(request.headers)))));
+	const middleware = HttpRouter.middleware(Effect.map(providerOf(authentication), (runtime) => (route) => Effect.flatMap(HttpServerRequest.HttpServerRequest, (request) => request.method !== "POST" || required(request.headers) ? runtime.http(route, false) : Effect.flatMap(namesItsMethod(request), (named) => runtime.http(route, named)))));
 	return transport.pipe(Layer.provide(middleware.layer));
 }
 function runStdio(apps, { actions, features, ...options }) {
 	const transport = server(select(toList(apps), actions), McpServer.layerStdio({
 		...options,
-		protocols: stdioProtocols
+		protocols
 	}), features);
-	return Layer.launch(transport).pipe(logToStderr, Effect.forkChild, Effect.flatMap(Fiber.await), Effect.flatMap((exit) => Exit.isFailure(exit) && !Cause.hasInterruptsOnly(exit.cause) ? Effect.failCause(exit.cause) : Effect.void));
+	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));
 }
 //#endregion
 export { layerHttp, runStdio };

package/dist/ActionRpc.d.mts

@@ -0,0 +1,147 @@
+import { Anyone, Certain, ErrorsOf } from "./contract/rules.mjs";
+import { BuiltIn, BuiltIns } from "./contract/errors.mjs";
+import { BuildError, Holding, Known, Member, MiddlewareOf, Protected, Selected, Served, Serving } from "./contract/implementation.mjs";
+import { Call } from "./contract/call.mjs";
+import { Action_d_exports, Any as Any$1, Errors } from "./Action.mjs";
+import { Any as Any$2, DescriptorOf, Identity, Matching, PublicOnly, RemoteRequest, Required, ServedProvider, ServerBuildServices, VerifierError } from "./authentication/provider.mjs";
+import { Context, Effect, Layer, Schema, Scope, Types } from "effect";
+import { HttpRouter } from "effect/http";
+import { Rpc, RpcClient, RpcClientError, RpcGroup, RpcMiddleware, RpcServer } from "effect/rpc";
+//#region src/rpc/ActionRpc.d.ts
+type BindingError = Errors[number];
+type ErrorOf<A extends Any$1, E extends Errors, D> = Schema.Union<ReadonlyArray<A["error"][number] | E[number] | VerifierError<A, D> | BuiltIns>>;
+type RpcOf<A extends Any$1, E extends Errors, D> = A extends Any$1 ? Rpc.Rpc<A["name"], A["input"], A["success"], ErrorOf<A, E, D>> : never;
+/**
+ * An RPC binding: actions, the errors every rpc declares, and the descriptor authenticating
+ * its protected ones. Plain data, so a copy of it, or one made by another installed copy of
+ * this package, serves the same; `layer` serves it and `client` calls it.
+ */
+export interface Binding<Actions extends ReadonlyArray<Any$1>, E extends Errors = [], D extends Any$2 | undefined = undefined> {
+  readonly authentication: D;
+  /** The exact actions bound to this binding. */
+  readonly actions: Actions;
+  /** The errors every rpc declares besides its action's own, as a list. */
+  readonly error: E;
+  /**
+   * The native group of one rpc per action, named after it, as clients see it:
+   * `RpcClient.make(Rpc.group)` is the native client.
+   */
+  readonly group: RpcGroup.RpcGroup<RpcOf<Actions[number], E, D>>;
+}
+/**
+ * Any RPC binding. Its group is any native group here, since native groups are invariant in
+ * their rpcs; `actions` carries the types.
+ */
+export interface Any {
+  readonly authentication?: Any$2 | undefined;
+  readonly actions: ReadonlyArray<Any$1>;
+  readonly error: Errors;
+  readonly group: RpcGroup.Any;
+}
+/** Contract-level configuration shared by servers and clients. */
+export interface Options<E extends Errors = Errors> {
+  /** Layer middleware's errors, which every rpc declares: one schema, or a list. */
+  readonly error?: E | E[number];
+  readonly authentication?: Any$2;
+}
+/**
+ * Bind actions once, for servers and clients alike, each as an rpc named after it, taking
+ * its action's input and answering its success. Every rpc declares its action's errors, the
+ * binding's `error`, and the built-in `InvalidInput`, `Unauthenticated` and `Forbidden`, so
+ * clients decode each as a typed failure; a protected one also declares what its descriptor's
+ * verifier fails with. Browser-safe, as an HTTP binding is.
+ * Guide: `docs/ActionRpc.md` in this package; in an application: `examples/live-rpc/`.
+ */
+export declare function make<const Actions extends ReadonlyArray<Any$1 & {
+  readonly caller: typeof Anyone;
+}>>(actions: Actions): Binding<Actions, [], undefined>;
+export declare function make<const Actions extends ReadonlyArray<Any$1>, const O extends Options = {}>(actions: Actions, options: O & Required<Actions[number]> & Matching<Actions[number], NoInfer<DescriptorOf<O>>> & NoInfer<Known<O, Options>>): Binding<Actions, ErrorsOf<O>, DescriptorOf<O>>;
+export declare function make<const Actions extends ReadonlyArray<Any$1>>(actions: Actions & PublicOnly<Actions>): Binding<Actions, [], undefined>;
+type Middleware = ReadonlyArray<RpcMiddleware.AnyService>;
+type IdOf<K> = K extends Context.Key<infer I extends RpcMiddleware.AnyId, unknown> ? I : never;
+type Through<M extends Middleware, R> = number extends M["length"] ? R | RpcMiddleware.Requires<IdOf<M[number]>> : M extends readonly [infer K, ...infer Rest extends Middleware] ? Through<Rest, true extends Types.IsUnion<IdOf<K>> ? R | RpcMiddleware.Requires<IdOf<K>> : RpcMiddleware.ApplyServices<IdOf<K>, R>> : R;
+type ForClient<K> = K extends {
+  readonly requiredForClient: infer F;
+} ? true extends F ? K : never : never;
+type ServerOnly<M extends Middleware, E extends Errors> = [Exclude<RpcMiddleware.Error<IdOf<M[number]>>, Extract<Certain<E>, BindingError>["Type"] | BuiltIn> | ForClient<M[number]>] extends [never] ? unknown : {
+  readonly "Layer middleware fails only with the binding's errors and needs no client": never;
+};
+type LayerRequest<App, A extends Any$1, M extends Middleware> = Exclude<Through<M, RemoteRequest<App, A>>, [Extract<Serving<App, A>, {
+  readonly caller: typeof Anyone;
+}>] extends [never] ? Identity<Protected<Serving<App, A>>> : never>;
+type RpcLayer<B extends Any, Apps extends Served, M extends Middleware, A extends Any$1 = B["actions"][number]> = Layer.Layer<never, BuildError<Holding<Member<Apps>, A>, A>, ServerBuildServices<Holding<Member<Apps>, A>, A> | RpcServer.Protocol | HttpRouter.Request.From<"Requires", LayerRequest<Member<Apps>, A, M>> | ServedProvider<Member<Apps>, A, B extends {
+  readonly authentication: infer D;
+} ? D : never> | IdOf<M[number]>>;
+/** `ActionRpc.layer`'s options. */
+export interface LayerOptions<M extends Middleware = [], A extends Any$1 = never> {
+  /**
+   * The actions it serves, among the binding's actions the implementations hold: `[GetUser]`.
+   * Defaults to every one of them. A layer whose middleware requires the identity lists
+   * protected actions only.
+   */
+  readonly actions?: ReadonlyArray<A> | undefined;
+  /**
+   * Native rpc middleware every served rpc runs, the first innermost: inside the
+   * authentication of a protected rpc, outside its decoding. Server-only: the binding's group,
+   * which clients use, carries none. A middleware requiring the identity needs a layer
+   * serving only protected actions.
+   */
+  readonly middleware?: M;
+}
+/**
+ * Serve the binding's actions among `implementations` with Effect's own `RpcServer`, or those
+ * its `actions` lists, as `ActionHttp.layer` selects them. The host provides the protocol,
+ * such as `RpcServer.layerProtocolWebsocket` or `layerProtocolHttp` and its JSON serialization:
+ * the layer refuses to build under a protocol that does not speak JSON. A protected rpc
+ * authenticates each message from its headers with the binding's descriptor, outermost; then
+ * the layer's `middleware` runs, then the input is decoded, a failure answering `InvalidInput`,
+ * then the implementation's `authorize` and the handler, as on every surface.
+ *
+ * The server serves its own copy of the binding's group, whose payloads, successes and errors
+ * are the actions' JSON and which carries no native middleware: the protocol decodes a payload before
+ * any middleware runs, and answers one that does not decode with a defect, so each handler
+ * runs the authentication and the middleware itself, then decodes the input. A defect is
+ * logged with its cause, reported to the call's `ErrorReporter`s, and answered as its
+ * request's generic failure, never failing the connection's other calls; a declared failure is
+ * the caller's answer, and not reported.
+ *
+ * The layer fails as the builders do, needs at startup what they need, and per request what
+ * each implementation's authorization and the handlers of the actions it serves need, as
+ * router request markers, until its `middleware` provides them: over a router-mounted
+ * protocol, the route's request context does too. The identity of a protected action is
+ * provided by its authentication alone.
+ */
+export declare function layer<const B extends Any, const Apps extends Served>(binding: B, implementations: Apps): RpcLayer<B, Apps, []>;
+export declare function layer<const B extends Any, const Apps extends Served, const O extends LayerOptions<Middleware, B["actions"][number]>>(binding: B, implementations: Apps, options: O & ServerOnly<MiddlewareOf<O, Middleware>, B["error"]> & NoInfer<Known<O, LayerOptions<Middleware>>>): RpcLayer<B, Apps, MiddlewareOf<O, Middleware>, Selected<O, B["actions"][number]>>;
+/**
+ * What one call of an action `A` fails with, beside the binding's errors `E`: its declared and
+ * built-in errors, and Effect's own `RpcClientError`. Input that does not encode is
+ * `InvalidInput`, and nothing is sent; an answer that does not decode is a defect, as the
+ * native client makes it.
+ */
+export type MethodError<A extends Any$1, E extends BindingError = never> = A["error"][number]["Type"] | E["Type"] | BuiltIns["Type"] | RpcClientError.RpcClientError;
+type Method<A extends Any$1, E extends BindingError> = Call<A, Effect.Effect<A["success"]["Type"], MethodError<A, E>>>;
+/**
+ * Every action of the binding `B`, as `client.<action>(input)`: a protected one may also fail
+ * with what its descriptor's verifier declares.
+ */
+export type Client<B extends Any> = { readonly [A in B["actions"][number] as A["name"]]: Method<A, B["error"][number] | VerifierError<A, B["authentication"]>>; };
+/**
+ * The native `RpcClient.make` options `client` takes: `spanPrefix`, `spanAttributes`,
+ * `generateRequestId` and `disableTracing`. `flatten` changes the client's shape, which the
+ * method types cannot follow.
+ */
+export type ClientOptions = Omit<NonNullable<Parameters<typeof RpcClient.make>[1]>, "flatten">;
+/**
+ * Effect's native `RpcClient` for a binding, one method per action taking the action's input
+ * directly: `client.greet({ name })`, as `ActionHttp.client`'s. The argument may be omitted
+ * when `{}` is a valid input. Requires the native client `Protocol` and a `Scope`, as
+ * `RpcClient.make` does; headers set with `RpcClient.withHeaders` around a call go with its
+ * message. The native client itself stays available: `RpcClient.make(Rpc.group)`.
+ *
+ * A call fails with a declared error value (the action's own, the binding's, a built-in
+ * `InvalidInput`, `Unauthenticated` or `Forbidden`, or on a protected rpc its descriptor's),
+ * or with Effect's own `RpcClientError` when the server could not be reached.
+ */
+export declare function client<const B extends Any>(binding: B, options?: ClientOptions): Effect.Effect<Client<B>, never, RpcClient.Protocol | Scope.Scope>;
+//#endregion

package/dist/ActionRpc.mjs

@@ -0,0 +1,113 @@
+import { InvalidInput } from "./contract/errors.mjs";
+import { Anyone, assertDistinct, assertOnce, assertOwnTags, errorList, projectedErrors } from "./contract/rules.mjs";
+import { acquire, provideHandlers, servedBy, toList } from "./contract/implementation.mjs";
+import { checked } from "./contract/call.mjs";
+import { assertAuthentication, providerOf, withVerifierErrors } from "./authentication/provider.mjs";
+import { Cause, Effect, ErrorReporter, Layer, Predicate, Result, Schema, SchemaTransformation } from "effect";
+import { HttpClientRequest, HttpServerRequest } from "effect/http";
+import { HttpApiBuilder } from "effect/http-api";
+import { Rpc, RpcClient, RpcGroup, RpcSerialization, RpcServer } from "effect/rpc";
+//#region src/rpc/ActionRpc.ts
+const declaredErrorsOf = (action, errors, authentication) => projectedErrors(action, withVerifierErrors(action, errors, authentication?.error));
+function make(actions, options = {}) {
+	assertOnce("action", actions);
+	const errors = errorList(options.error);
+	assertOwnTags("ActionRpc binding", errors);
+	assertAuthentication(actions, options.authentication);
+	return {
+		actions,
+		error: errors,
+		group: RpcGroup.make(...actions.map((action) => Rpc.make(action.name, {
+			payload: action.input,
+			success: action.success,
+			error: Schema.Union(declaredErrorsOf(action, errors, options.authentication))
+		}))),
+		authentication: options.authentication
+	};
+}
+const credentialFromRpcHeaders = (security, headers) => HttpApiBuilder.securityDecode(security).pipe(Effect.provideService(HttpServerRequest.HttpServerRequest, HttpServerRequest.fromClientRequest(HttpClientRequest.get("/", { headers }))), Effect.provideService(HttpServerRequest.ParsedSearchParams, {}));
+const authenticationStepOf = (authentication) => Effect.map(providerOf(authentication), (provider) => (effect, { headers }) => credentialFromRpcHeaders(authentication.security, headers).pipe(Effect.flatMap(provider.authenticate), Effect.flatMap((actor) => Effect.provideService(effect, authentication.identity, actor))));
+var InternalError = class extends Error {
+	[ErrorReporter.ignore] = true;
+	constructor() {
+		super("Internal server error");
+	}
+};
+var DeclaredFailure = class {
+	json;
+	[ErrorReporter.ignore] = true;
+	constructor(json) {
+		this.json = json;
+	}
+	toString() {
+		return Predicate.isString(this.json) ? this.json : JSON.stringify(this.json);
+	}
+};
+const DeclaredFromJson = Schema.Json.pipe(Schema.decodeTo(Schema.instanceOf(DeclaredFailure), SchemaTransformation.transform({
+	decode: (json) => new DeclaredFailure(json),
+	encode: (failure) => failure.json
+})));
+const callBoundaryOf = (error) => {
+	const encode = Schema.encodeUnknownEffect(Schema.toCodecJson(error));
+	const internal = (cause) => Effect.logError(cause).pipe(Effect.andThen(ErrorReporter.report(cause)), Effect.andThen(Effect.die(new InternalError())));
+	return (effect) => Effect.catchCause(effect, (cause) => {
+		if (Cause.hasDies(cause)) return internal(cause);
+		const failure = Cause.findFail(cause);
+		return Result.isSuccess(failure) ? encode(failure.success.error).pipe(Effect.matchCauseEffect({
+			onFailure: (unencoded) => internal(Cause.combine(cause, unencoded)),
+			onSuccess: (encoded) => Effect.fail(new DeclaredFailure(encoded))
+		})) : Effect.failCause(cause);
+	});
+};
+const handlerOf = (action, run, steps, error) => {
+	const decodeStrictly = Schema.decodeUnknownEffect(Schema.toCodecJson(action.input), {
+		errors: "all",
+		onExcessProperty: "error"
+	});
+	const encode = Schema.encodeUnknownEffect(Schema.toCodecJson(action.success));
+	const boundary = callBoundaryOf(error);
+	return (payload, options) => {
+		const call = Effect.suspend(() => decodeStrictly(payload)).pipe(Effect.mapError(InvalidInput.fromSchemaError), Effect.flatMap(run), Effect.flatMap(encode));
+		const wrapped = steps.reduce((inner, step) => Effect.suspend(() => step(inner, {
+			...options,
+			payload
+		})), call);
+		return boundary(wrapped);
+	};
+};
+function layer(binding, served, options = {}) {
+	const apps = servedBy("RPC binding", binding.actions, toList(served), options.actions);
+	const actions = apps.flatMap((app) => app.actions);
+	assertAuthentication(actions, binding.authentication);
+	const middleware = options.middleware ?? [];
+	assertDistinct("middleware", middleware, (key) => key.key);
+	const auth = actions.some((action) => action.caller !== Anyone) ? binding.authentication : void 0;
+	const jsonGroup = RpcGroup.make(...actions.map((action) => Rpc.make(action.name, {
+		payload: Schema.Json,
+		success: Schema.Json,
+		error: DeclaredFromJson
+	})));
+	const handlers = Layer.unwrap(Effect.gen(function* () {
+		const { codecFor } = yield* RpcServer.Protocol;
+		if (codecFor !== RpcSerialization.json.codecFor) return yield* Effect.die(/* @__PURE__ */ new Error("ActionRpc serves a protocol speaking JSON: RpcSerialization.layerJson, layerNdjson, layerJsonRpc or layerNdJsonRpc, not another codec, such as schema-binary's"));
+		const listedMiddleware = yield* Effect.forEach(middleware, (key) => Effect.service(key));
+		const authenticate = auth === void 0 ? void 0 : yield* authenticationStepOf(auth);
+		const bound = yield* acquire(apps);
+		const byName = Object.fromEntries(bound.map(([action, run]) => [action.name, handlerOf(action, run, action.caller === Anyone || authenticate === void 0 ? listedMiddleware : [...listedMiddleware, authenticate], Schema.Union(declaredErrorsOf(action, binding.error, binding.authentication)))]));
+		return jsonGroup.toLayer(byName);
+	})).pipe(provideHandlers(apps));
+	return RpcServer.layer(jsonGroup, { disableFatalDefects: true }).pipe(Layer.provide(handlers));
+}
+function client(binding, options) {
+	const group = binding.group;
+	return Effect.map(RpcClient.make(group, options), (client) => {
+		const native = client;
+		return Object.fromEntries(binding.actions.map((action) => {
+			const method = native[action.name];
+			if (method === void 0) throw new Error(`No client method for ${action.name}`);
+			return [action.name, checked(action, (payload) => method(payload))];
+		}));
+	});
+}
+//#endregion
+export { client, layer, make };