@gjermundgaraba/effect-actions 0.5.0 → 0.7.0

package/README.md

@@ -7,7 +7,6 @@ Effect's own servers and clients underneath.
 ## Looks like this
 
 ```ts
-import { McpProtocol } from "effect/unstable/ai";
 import { Effect, Layer, Schema } from "effect";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
 import * as ActionGroup from "@gjermundgaraba/effect-actions/ActionGroup";
@@ -32,7 +31,6 @@ const app = Actions.implement({
 export const routes = Layer.mergeAll(
   Http.layer([app]),
   ActionMcp.layerHttp([app], {
-    protocols: [McpProtocol.v2026_07_28],
     name: "greetings",
     version: "1.0.0",
     path: "/mcp",
@@ -60,6 +58,9 @@ const greeting = Effect.gen(function* () {
 });
 ```
 
+Code that does not run Effects, such as a browser page, gets the same calls as Promises:
+`await ActionHttpClient.promise(Http, { baseUrl }).greetings.greet({ name: "Ada" })`.
+
 ## Why
 
 - Input, success, and errors are declared once. Routes, tools, commands, clients, OpenAPI, and the catalog are derived from that declaration, so they cannot disagree.
@@ -72,10 +73,10 @@ const greeting = Effect.gen(function* () {
 ## Install
 
 ```sh
-pnpm add @gjermundgaraba/effect-actions effect@4.0.0-rc.116
+pnpm add @gjermundgaraba/effect-actions effect@4.0.0-rc.117
 ```
 
-Add `@effect/platform-node@4.0.0-rc.116` to serve from Node. Every module is a subpath import
+Add `@effect/platform-node@4.0.0-rc.117` to serve from Node. Every module is a subpath import
 (`.../Action`, `.../ActionHttp`, ...); there is no package root, so a contracts-only bundle
 never loads a server.
 
@@ -100,8 +101,8 @@ in `node_modules/@gjermundgaraba/effect-actions/docs`) gives the same content.
 
 ## Status
 
-The `effect` peer is pinned to an exact Effect 4 release candidate and moves with it; expect a
-release of this package for each Effect release candidate it adopts. Actions are unary JSON over HTTP and MCP: no streaming, uploads, prompts, or resources.
+The `effect` peer accepts any Effect 4.0 release candidate from `4.0.0-rc.116` on; the package
+is built and tested against the release candidate in its `devDependencies` (see [docs/setup.md](docs/setup.md)). Actions are unary JSON over HTTP and MCP: no streaming, uploads, prompts, or resources.
 Authentication and authorization belong to the application. See [docs/setup.md](docs/setup.md).
 
 ## Acknowledgements

package/dist/Action.d.mts

@@ -30,7 +30,7 @@ type ResolvedMcp<Name extends string, Mcp extends false | McpOptions | undefined
   readonly openWorld: boolean;
 };
 /** What `make` needs to define an action. */
-export interface Options<Input extends Codec, Output extends Codec, Errors extends ReadonlyArray<Codec>, Acc extends Access = Access, Http extends boolean = boolean, Mcp extends false | McpOptions | undefined = McpOptions | undefined> {
+export interface Options<Input extends Codec, Output extends Codec, Errors extends ReadonlyArray<Codec>, Acc extends Access = Access, Mcp extends false | McpOptions | undefined = McpOptions | undefined> {
   readonly description: string;
   /** Omit for an action without arguments. */
   readonly input?: Input;
@@ -43,32 +43,40 @@ export interface Options<Input extends Codec, Output extends Codec, Errors exten
    * library itself authorizes nothing.
    */
   readonly access: Acc;
-  /** `false` hides the action from HTTP routes and clients. */
-  readonly http?: Http;
   /** `false` hides the action from MCP; otherwise tool metadata. */
   readonly mcp?: Mcp;
 }
 /** A pure contract: schemas and transport metadata. Implementations are bound by `ActionGroup.implement`. */
-export interface Action<Name extends string, Input extends Codec, Output extends Codec, Errors extends ReadonlyArray<Codec>, Acc extends Access = Access, Http extends boolean = boolean, Mcp extends false | McpOptions | undefined = McpOptions | undefined> {
+export interface Action<Name extends string, Input extends Codec, Output extends Codec, Errors extends ReadonlyArray<Codec>, Acc extends Access = Access, Mcp extends false | McpOptions | undefined = McpOptions | undefined> {
   readonly name: Name;
   readonly description: string;
   readonly input: Input;
   readonly success: Output;
   readonly errors: Errors;
   readonly access: Acc;
-  readonly http: Http;
   readonly mcp: ResolvedMcp<Name, Mcp>;
 }
 /** Any action, with its schemas erased. */
-export type Any = Action<string, Codec, Codec, ReadonlyArray<Codec>, Access, boolean, false> | Action<string, Codec, Codec, ReadonlyArray<Codec>, Access, boolean, McpOptions> | Action<string, Codec, Codec, ReadonlyArray<Codec>, Access, boolean, undefined>;
+export type Any = Action<string, Codec, Codec, ReadonlyArray<Codec>, Access, false> | Action<string, Codec, Codec, ReadonlyArray<Codec>, Access, McpOptions> | Action<string, Codec, Codec, ReadonlyArray<Codec>, Access, undefined>;
 /** Receives decoded input; may fail only with the declared errors. */
 export type Handler<A extends Any, R = never> = (input: A["input"]["Type"]) => Effect.Effect<A["success"]["Type"], A["errors"][number]["Type"], R>;
 /** An empty object schema that also produces the object root MCP requires. */
 declare const NoInput: Schema.$Record<Schema.String, Schema.Never>;
+type AnyOptions = Options<Codec, Codec, ReadonlyArray<Codec>, Access, false | McpOptions | undefined>;
+/**
+ * The `mcp` option `make` received. Only a required literal `false` hides the action:
+ * options that may carry something else, such as a conditional spread, `false | undefined`
+ * or a broadly typed variable, may serve it, so its requirements are kept.
+ */
+type McpOf<O extends AnyOptions> = [O] extends [{
+  readonly mcp: false;
+}] ? false : O extends {
+  readonly mcp: infer Mcp extends false | McpOptions | undefined;
+} ? Mcp : "mcp" extends keyof O ? O["mcp"] | undefined : undefined;
 /**
  * Define an action contract. Names are `[A-Za-z0-9_-]+`, other than `then`.
- * Actions can be local-only by setting both transports to `false`.
+ * HTTP serves every action of a group it binds; `mcp: false` hides one from MCP.
  */
-export declare function make<const Name extends string, Input extends Codec = typeof NoInput, Output extends Codec = never, const Errors extends ReadonlyArray<Codec> = [], const Acc extends Access = Access, const Http extends boolean = true, const Mcp extends false | McpOptions | undefined = undefined>(name: Name, options: Options<Input, Output, Errors, Acc, Http, Mcp>): Action<Name, Input, Output, Errors, Acc, Http, Mcp>;
+export declare function make<const Name extends string, const O extends AnyOptions>(name: Name, options: O & { readonly [K in Exclude<keyof O, keyof AnyOptions>]: never; }): Action<Name, "input" extends keyof O ? Exclude<O["input"], undefined> : typeof NoInput, O["success"], "errors" extends keyof O ? Exclude<O["errors"], undefined> : [], O["access"], McpOf<O>>;
 //#endregion
 export { Action_d_exports };

package/dist/Action.mjs

@@ -24,7 +24,6 @@ function make(name, options) {
 		success: options.success,
 		errors: options.errors ?? [],
 		access,
-		http: options.http !== false,
 		mcp
 	};
 }

package/dist/ActionCatalog.d.mts

@@ -8,7 +8,6 @@ export interface Entry {
   readonly group: string;
   readonly name: string;
   readonly description: string;
-  readonly http: boolean;
   readonly mcp: Any["mcp"];
   readonly input: JsonSchema.JsonSchema;
   readonly success: JsonSchema.JsonSchema;
@@ -19,13 +18,13 @@ export interface Entry {
 }
 /** An offline contract document, not an authorization decision or a mounted endpoint. */
 export interface Catalog {
-  readonly version: "3";
+  readonly version: "4";
   readonly actions: ReadonlyArray<Entry>;
 }
 /**
  * Describe the supplied groups without acquiring implementations. Schemas describe
  * encoded action values, not MCP's `{ value }` envelope or deployment-specific URLs.
- * Local-only actions are included; the host chooses what, if anything, to publish.
+ * The host chooses what, if anything, to publish.
  */
 export declare const make: (...groups: ReadonlyArray<Any$1>) => Catalog;
 //#endregion

package/dist/ActionCatalog.mjs

@@ -1,4 +1,4 @@
-import { assertDistinct } from "./internal/actions.mjs";
+import { assertDistinct, policyErrors } from "./internal/actions.mjs";
 import { JsonSchema, Schema } from "effect";
 //#region src/ActionCatalog.ts
 /** Describe the JSON wire form; decoding on the server remains authoritative. */
@@ -13,23 +13,22 @@ const describe = (codec) => {
 /**
 * Describe the supplied groups without acquiring implementations. Schemas describe
 * encoded action values, not MCP's `{ value }` envelope or deployment-specific URLs.
-* Local-only actions are included; the host chooses what, if anything, to publish.
+* The host chooses what, if anything, to publish.
 */
 const make = (...groups) => {
 	assertDistinct("catalog group", groups.map((group) => group.name));
 	return {
-		version: "3",
+		version: "4",
 		actions: groups.flatMap((group) => group.actions.map((action) => ({
 			id: `${group.name}.${action.name}`,
 			group: group.name,
 			name: action.name,
 			description: action.description,
-			http: action.http,
 			mcp: action.mcp,
 			input: describe(action.input),
 			success: describe(action.success),
 			errors: action.errors.map(describe),
-			httpSchemaErrors: action.http ? group.schemaError?.errors.map(describe) ?? [] : []
+			httpSchemaErrors: group.schemaError === void 0 ? [] : policyErrors(group.schemaError).map(describe)
 		})))
 	};
 };

package/dist/ActionCli.mjs

@@ -4,6 +4,10 @@ import { command as command$1 } from "./internal/cli.mjs";
 import { Effect } from "effect";
 import { Command } from "effect/unstable/cli";
 //#region src/ActionCli.ts
+/**
+* Acquire the implementation in a scope of its own, run one action through the hook
+* and its handler, and release it: every local command, selected or grouped.
+*/
 const local = (app, action, before, input) => Effect.scoped(Effect.flatMap(app.build, (handlers) => dispatch(app.group, action, handlers, before)(input)));
 /**
 * Project one explicitly selected local action into a native Effect CLI command.
@@ -15,7 +19,7 @@ const command = (app, name, options) => {
 };
 /** Project every local action below its group namespace with default CLI options. */
 const group = (app, options) => {
-	const commands = app.group.actions.map((action) => command$1(action, (input) => Effect.scoped(Effect.flatMap(app.build, (handlers) => dispatch(app.group, action, handlers, options?.before)(input)))));
+	const commands = app.group.actions.map((action) => command$1(action, (input) => local(app, action, options?.before, input)));
 	return Command.make(options?.name ?? app.group.name).pipe(Command.withSubcommands(commands));
 };
 //#endregion

package/dist/ActionCliClient.d.mts

@@ -1,6 +1,5 @@
 import { Action_d_exports, Codec } from "./Action.mjs";
 import { Actions } from "./internal/actions.mjs";
-import { ServedNames } from "./internal/implementation.mjs";
 import { Options as Options$1 } from "./internal/cli.mjs";
 import { ActionHttp_d_exports, Api, Http } from "./ActionHttp.mjs";
 import { Effect } from "effect";
@@ -30,20 +29,20 @@ type Group<Groups extends ReadonlyArray<Actions>, Name extends Groups[number]["n
 type Selected<G extends Actions, Name extends G["actions"][number]["name"]> = Extract<G["actions"][number], {
   readonly name: Name;
 }>;
-type HttpNames<G extends Actions> = ServedNames<G, "http">;
+type ActionNames<G extends Actions> = G["actions"][number]["name"];
 type ApiGroups<Groups extends ReadonlyArray<Actions>, Errors extends ReadonlyArray<Codec>> = Api<Groups[number], Errors[number]> extends HttpApi.HttpApi<"actions", infer ApiGroups> ? ApiGroups : never;
-type Endpoint<Groups extends ReadonlyArray<Actions>, Errors extends ReadonlyArray<Codec>, GroupName extends Groups[number]["name"], ActionName extends HttpNames<Group<Groups, GroupName>>> = Extract<HttpApiGroup.EndpointsWithIdentifier<ApiGroups<Groups, Errors>, Extract<GroupName, HttpApiGroup.Identifier<ApiGroups<Groups, Errors>>>>, {
+type Endpoint<Groups extends ReadonlyArray<Actions>, Errors extends ReadonlyArray<Codec>, GroupName extends Groups[number]["name"], ActionName extends ActionNames<Group<Groups, GroupName>>> = Extract<HttpApiGroup.EndpointsWithIdentifier<ApiGroups<Groups, Errors>, Extract<GroupName, HttpApiGroup.Identifier<ApiGroups<Groups, Errors>>>>, {
   readonly identifier: ActionName;
 }>;
-type NativeMethod<Groups extends ReadonlyArray<Actions>, Errors extends ReadonlyArray<Codec>, GroupName extends Groups[number]["name"], ActionName extends HttpNames<Group<Groups, GroupName>>> = HttpApiClient.Client.Method<Extract<Endpoint<Groups, Errors, GroupName, ActionName>, HttpApiEndpoint.ConstraintRequest>, never, never>;
-type RemoteCommand<Groups extends ReadonlyArray<Actions>, Errors extends ReadonlyArray<Codec>, GroupName extends Groups[number]["name"], ActionName extends HttpNames<Group<Groups, GroupName>>> = Command.Command<string, never, {}, Effect.Error<ReturnType<NativeMethod<Groups, Errors, GroupName, ActionName>>>, HttpClient.HttpClient | Effect.Services<ReturnType<NativeMethod<Groups, Errors, GroupName, ActionName>>>>;
-type RemoteGroupCommand<Groups extends ReadonlyArray<Actions>, Errors extends ReadonlyArray<Codec>, GroupName extends Groups[number]["name"]> = Command.Command<string, {}, {}, Effect.Error<ReturnType<NativeMethod<Groups, Errors, GroupName, HttpNames<Group<Groups, GroupName>>>>>, HttpClient.HttpClient | Effect.Services<ReturnType<NativeMethod<Groups, Errors, GroupName, HttpNames<Group<Groups, GroupName>>>>>>;
+type NativeMethod<Groups extends ReadonlyArray<Actions>, Errors extends ReadonlyArray<Codec>, GroupName extends Groups[number]["name"], ActionName extends ActionNames<Group<Groups, GroupName>>> = HttpApiClient.Client.Method<Extract<Endpoint<Groups, Errors, GroupName, ActionName>, HttpApiEndpoint.ConstraintRequest>, never, never>;
+type RemoteCommand<Groups extends ReadonlyArray<Actions>, Errors extends ReadonlyArray<Codec>, GroupName extends Groups[number]["name"], ActionName extends ActionNames<Group<Groups, GroupName>>> = Command.Command<string, never, {}, Effect.Error<ReturnType<NativeMethod<Groups, Errors, GroupName, ActionName>>>, HttpClient.HttpClient | Effect.Services<ReturnType<NativeMethod<Groups, Errors, GroupName, ActionName>>>>;
+type RemoteGroupCommand<Groups extends ReadonlyArray<Actions>, Errors extends ReadonlyArray<Codec>, GroupName extends Groups[number]["name"]> = Command.Command<string, {}, {}, Effect.Error<ReturnType<NativeMethod<Groups, Errors, GroupName, ActionNames<Group<Groups, GroupName>>>>>, HttpClient.HttpClient | Effect.Services<ReturnType<NativeMethod<Groups, Errors, GroupName, ActionNames<Group<Groups, GroupName>>>>>>;
 /**
- * Project one HTTP action retained by the binding into a native Effect CLI command.
+ * Project one action of the binding into a native Effect CLI command.
  * Group and action selectors resolve exclusively from `http.groups`; runtime guards
  * keep dynamically supplied selector strings from reaching the native client.
  */
-export declare const command: <const Groups extends ReadonlyArray<Actions>, const Errors extends ReadonlyArray<Codec>, const GroupName extends Groups[number]["name"], const ActionName extends HttpNames<Group<Groups, GroupName>>, ParsedParameters extends Command.Command.Config = never>(http: Http<Groups, Errors>, groupName: GroupName, actionName: ActionName, options?: Options<Selected<Group<Groups, GroupName>, ActionName>["success"]["Type"], ParsedParameters>) => RemoteCommand<Groups, Errors, GroupName, ActionName>;
-/** Project all HTTP-enabled actions retained by one group below its group namespace. */
+export declare const command: <const Groups extends ReadonlyArray<Actions>, const Errors extends ReadonlyArray<Codec>, const GroupName extends Groups[number]["name"], const ActionName extends ActionNames<Group<Groups, GroupName>>, ParsedParameters extends Command.Command.Config = never>(http: Http<Groups, Errors>, groupName: GroupName, actionName: ActionName, options?: Options<Selected<Group<Groups, GroupName>, ActionName>["success"]["Type"], ParsedParameters>) => RemoteCommand<Groups, Errors, GroupName, ActionName>;
+/** Project every action of one bound group below its group namespace. */
 export declare const group: <const Groups extends ReadonlyArray<Actions>, const Errors extends ReadonlyArray<Codec>, const GroupName extends Groups[number]["name"]>(http: Http<Groups, Errors>, groupName: GroupName, options?: GroupOptions) => RemoteGroupCommand<Groups, Errors, GroupName>;
 //#endregion

package/dist/ActionCliClient.mjs

@@ -13,21 +13,14 @@ import { Command } from "effect/unstable/cli";
 const erasedApi = (api) => {
 	return api;
 };
-/** An action hidden from HTTP is unknown to this binding, exactly like a missing one. */
-const selectAction = (group, name) => {
-	const what = `HTTP action "${group.name}.${name}"`;
-	const action = selectNamed(group.actions, name, what);
-	if (!action.http) throw new Error(`Unknown ${what}`);
-	return action;
-};
 /**
-* Project one HTTP action retained by the binding into a native Effect CLI command.
+* Project one action of the binding into a native Effect CLI command.
 * Group and action selectors resolve exclusively from `http.groups`; runtime guards
 * keep dynamically supplied selector strings from reaching the native client.
 */
 const command = (http, groupName, actionName, options) => {
 	const group = selectNamed(http.groups, groupName, `HTTP group "${groupName}"`);
-	const action = selectAction(group, actionName);
+	const action = selectNamed(group.actions, actionName, `HTTP action "${groupName}.${actionName}"`);
 	return command$1(action, (input) => Effect.flatMap(HttpClient.HttpClient, (httpClient) => {
 		const endpoint = HttpApiClient.endpoint(erasedApi(http.api), {
 			...options?.connection,
@@ -40,10 +33,10 @@ const command = (http, groupName, actionName, options) => {
 		});
 	}), options);
 };
-/** Project all HTTP-enabled actions retained by one group below its group namespace. */
+/** Project every action of one bound group below its group namespace. */
 const group = (http, groupName, options) => {
 	const actions = selectNamed(http.groups, groupName, `HTTP group "${groupName}"`);
-	const commands = actions.actions.flatMap((action) => action.http ? [options?.connection === void 0 ? command(http, groupName, action.name) : command(http, groupName, action.name, { connection: options.connection })] : []);
+	const commands = actions.actions.map((action) => options?.connection === void 0 ? command(http, groupName, action.name) : command(http, groupName, action.name, { connection: options.connection }));
 	return Command.make(options?.name ?? actions.name).pipe(Command.withSubcommands(commands));
 };
 //#endregion

package/dist/ActionGroup.d.mts

@@ -1,31 +1,35 @@
 import { Action, Action_d_exports, Any as Any$1, Codec, Handler } from "./Action.mjs";
-import { Actions, SchemaErrorPolicy } from "./internal/actions.mjs";
+import { Actions, SchemaErrorAnswer, SchemaErrorPolicy } from "./internal/actions.mjs";
 import { Implementation } from "./internal/implementation.mjs";
 import { Effect, Scope, Types } from "effect";
 declare namespace ActionGroup_d_exports {
-  export { Any, Contracts, Group, Implementation, Options, SchemaErrorPolicy, contracts, make };
+  export { Any, Contracts, Group, Implementation, Options, SchemaErrorAnswer, SchemaErrorPolicy, contracts, make };
 }
 type HandlersFrom<Actions extends ReadonlyArray<Any$1>> = { readonly [A in Actions[number] as A["name"]]: Handler<A, any>; };
 /** Group-level errors join each action's own, so a shared set is declared once. */
-type WithErrors<Actions extends ReadonlyArray<Any$1>, Errors extends ReadonlyArray<Codec>> = { readonly [K in keyof Actions]: Actions[K] extends Action<infer Name, infer Input, infer Output, infer Own, infer Access, infer Http, infer Mcp> ? Action<Name, Input, Output, readonly [...Own, ...Errors], Access, Http, Mcp> : never; };
+type WithErrors<Actions extends ReadonlyArray<Any$1>, Errors extends ReadonlyArray<Codec>> = { readonly [K in keyof Actions]: Actions[K] extends Action<infer Name, infer Input, infer Output, infer Own, infer Access, infer Mcp> ? Action<Name, Input, Output, readonly [...Own, ...Errors], Access, Mcp> : never; };
 /** What `make` needs to define a group. */
-export interface Options<Name extends string, Errors extends ReadonlyArray<Codec>, PolicyErrors extends ReadonlyArray<Codec>> {
+export interface Options<Name extends string, Errors extends ReadonlyArray<Codec>, Invalid extends Codec = never, Internal extends Codec = never> {
   /** The `HttpApiGroup` identifier, and so the OpenAPI tag and operation-ID prefix. */
   readonly name: Name;
   /** Failures every action of the group may have, added to each action's own. */
   readonly errors?: Errors;
-  /** How HTTP answers failed decoding or encoding of these actions; MCP keeps its native answers. */
-  readonly schemaError?: SchemaErrorPolicy<PolicyErrors>;
+  /**
+   * How HTTP answers a request that fails decoding (`invalid`) and a result that fails
+   * encoding (`internal`); without one, both are Effect's empty 400. MCP keeps its
+   * native answers.
+   */
+  readonly schemaError?: SchemaErrorPolicy<Invalid, Internal>;
 }
 /** A named set of action contracts: what adapters serve and what `implement` binds. */
-export interface Group<Name extends string, Actions$1 extends ReadonlyArray<Any$1>, PolicyErrors extends ReadonlyArray<Codec> = ReadonlyArray<Codec>> extends Actions<Name, Actions$1, PolicyErrors> {
+export interface Group<Name extends string, Actions$1 extends ReadonlyArray<Any$1>, PolicyError extends Codec = Codec> extends Actions<Name, Actions$1, PolicyError> {
   /** Bind every handler at once, resolving build-time services once per adapter layer. */
-  readonly implement: <H extends HandlersFrom<Actions$1>, EX = never, RX = never>(build: H | Effect.Effect<H, EX, RX>) => Implementation<Group<Name, Actions$1, PolicyErrors>, H, NoInfer<EX>, NoInfer<Exclude<RX, Scope.Scope>>>;
+  readonly implement: <H extends HandlersFrom<Actions$1>, EX = never, RX = never>(build: H | Effect.Effect<H, EX, RX>) => Implementation<Group<Name, Actions$1, PolicyError>, H, NoInfer<EX>, NoInfer<Exclude<RX, Scope.Scope>>>;
 }
 /** Any group, with its actions and error schemas erased. */
-export type Any = Group<string, ReadonlyArray<Any$1>, ReadonlyArray<Codec>>;
+export type Any = Group<string, ReadonlyArray<Any$1>, Codec>;
 /** Define a group. Invalid or duplicate action and MCP names fail here, at definition time. */
-export declare function make<const Name extends string, const Actions extends ReadonlyArray<Any$1>, const Errors extends ReadonlyArray<Codec> = [], const PolicyErrors extends ReadonlyArray<Codec> = []>(options: Options<Name, Errors, PolicyErrors>, ...actions: Actions): Group<Name, WithErrors<Actions, Errors>, PolicyErrors>;
+export declare function make<const Name extends string, const Actions extends ReadonlyArray<Any$1>, const Errors extends ReadonlyArray<Codec> = [], Invalid extends Codec = never, Internal extends Codec = never>(options: Options<Name, Errors, Invalid, Internal>, ...actions: Actions): Group<Name, WithErrors<Actions, Errors>, Invalid | Internal>;
 /** `G extends unknown` distributes, so each group maps only its own actions. */
 type PerGroup<G extends Actions> = G extends unknown ? { readonly [A in G["actions"][number] as `${G["name"]}.${A["name"]}`]: A; } : never;
 /** Every action of `Groups`, keyed `<group>.<action>`: the per-group maps merged into one. */
@@ -37,4 +41,4 @@ export type Contracts<Groups extends ReadonlyArray<Actions>> = Types.UnionToInte
  */
 export declare function contracts<const Groups extends ReadonlyArray<Actions>>(...groups: Groups): Contracts<Groups>;
 //#endregion
-export { ActionGroup_d_exports, type Implementation, type SchemaErrorPolicy };
+export { ActionGroup_d_exports, type Implementation, type SchemaErrorAnswer, type SchemaErrorPolicy };

package/dist/ActionGroup.mjs

@@ -1,7 +1,13 @@
 import { assertDistinct, assertName } from "./internal/actions.mjs";
 import { Implementation } from "./internal/implementation.mjs";
-import { Effect } from "effect";
+import { Effect, Predicate } from "effect";
 //#region src/ActionGroup.ts
+/** Refuse a record without an own-property function for every action, before anything is served. */
+const assertHandlers = (group, handlers) => {
+	const missing = group.actions.filter((action) => !(Object.hasOwn(handlers, action.name) && Predicate.isFunction(handlers[action.name])));
+	if (missing.length > 0) throw new Error(`Missing handlers for group "${group.name}": ${missing.map((action) => action.name).join(", ")}`);
+	return handlers;
+};
 function make(options, ...declared) {
 	const { name } = options;
 	assertName("action group name", name);
@@ -16,7 +22,7 @@ function make(options, ...declared) {
 		actions,
 		schemaError: options.schemaError,
 		implement: (build) => {
-			const built = Effect.isEffect(build) ? build : Effect.succeed(build);
+			const built = Effect.isEffect(build) ? Effect.map(build, (handlers) => assertHandlers(group, handlers)) : Effect.succeed(assertHandlers(group, build));
 			return Implementation.make(group, built);
 		}
 	};

package/dist/ActionHttp.d.mts

@@ -31,11 +31,9 @@ export interface LayerOptions<Errors extends ReadonlyArray<Codec>, R> {
    */
   readonly before?: (action: Any) => Effect.Effect<void, Errors[number]["Type"], R>;
 }
-type Endpoint<A extends Any, E extends Codec> = A extends {
-  readonly http: false;
-} ? never : A extends Any ? HttpApiEndpoint.HttpApiEndpoint<A["name"], "POST", `/${string}`, never, never, Schema.toCodecJson<A["input"]>, never, Schema.toCodecJson<A["success"]>, Schema.toCodecJson<A["errors"][number] | E>, never> : never;
+type Endpoint<A extends Any, E extends Codec> = A extends Any ? HttpApiEndpoint.HttpApiEndpoint<A["name"], "POST", `/${string}`, never, never, Schema.toCodecJson<A["input"]>, never, Schema.toCodecJson<A["success"]>, Schema.toCodecJson<A["errors"][number] | E>, never> : never;
 type ApiGroup<G extends Actions, E extends Codec> = G extends Actions ? [Endpoint<G["actions"][number], never>] extends [never] ? never : HttpApiGroup.HttpApiGroup<G["name"], Endpoint<G["actions"][number], PolicyError<G> | E>> : never;
-/** The native `HttpApi` of every HTTP-enabled action of `G`, one group per action group. */
+/** The native `HttpApi` of every action of `G`, one group per action group. */
 export type Api<G extends Actions, E extends Codec = never> = HttpApi.HttpApi<"actions", ApiGroup<G, E>>;
 /** A namespaced HTTP binding. */
 export interface Http<Groups extends ReadonlyArray<Actions>, Errors extends ReadonlyArray<Codec> = []> {
@@ -47,7 +45,13 @@ export interface Http<Groups extends ReadonlyArray<Actions>, Errors extends Read
    * around every request they answer. Build failures, build services and request
    * services are unions over precisely those apps and that hook.
    */
-  readonly layer: <const Apps extends ReadonlyArray<AnyImplementation<Groups[number]>>, RB = never>(apps: readonly [...Apps], options?: LayerOptions<Errors, RB>) => Layer.Layer<never, BuildError<Apps[number], "http">, BuildContext<Apps[number], "http"> | HttpRouter.HttpRouter | HttpRouter.Request.From<"Requires", RequestContext<Apps[number], "http"> | RB> | Etag.Generator | FileSystem | HttpPlatform.HttpPlatform | Path>;
+  readonly layer: <const Apps extends ReadonlyArray<AnyImplementation<Groups[number]>>, RB = never>(apps: readonly [...Apps], options?: LayerOptions<Errors, RB>) => Layer.Layer<never, BuildError<Apps[number]>, BuildContext<Apps[number]> | HttpRouter.HttpRouter | HttpRouter.Request.From<"Requires", RequestContext<Apps[number]> | RB> | Etag.Generator | FileSystem | HttpPlatform.HttpPlatform | Path>;
+  /**
+   * Serve the OpenAPI document of `api` with `GET path`, by default
+   * `<apiPath>/openapi.json`. It is a plain route: middleware provided to this layer
+   * covers it, and none is applied otherwise.
+   */
+  readonly openApi: (path?: HttpRouter.PathInput) => Layer.Layer<never, never, HttpRouter.HttpRouter>;
 }
 /**
  * Bind the contract-level configuration once. Every route is `POST

package/dist/ActionHttp.mjs

@@ -1,10 +1,9 @@
-import { assertDistinct, projectedErrors } from "./internal/actions.mjs";
+import { answerSchemaError, assertDistinct, policyErrors, projectedErrors } from "./internal/actions.mjs";
 import { dispatch } from "./internal/implementation.mjs";
 import { Effect, Layer } from "effect";
-import "effect/unstable/http";
+import { HttpRouter, HttpServerResponse } from "effect/unstable/http";
 import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiMiddleware, OpenApi } from "effect/unstable/httpapi";
 //#region src/ActionHttp.ts
-const httpActions = (group) => group.actions.filter((action) => action.http);
 const endpoint = (options, group, action) => HttpApiEndpoint.post(action.name, `${options.apiPath}/${group.name}/${action.name}`, {
 	payload: action.input,
 	success: action.success,
@@ -12,14 +11,14 @@ const endpoint = (options, group, action) => HttpApiEndpoint.post(action.name, `
 }).annotate(OpenApi.Description, action.description);
 /** The native middleware declares the policy's errors on every endpoint it wraps. */
 const schemaErrorMiddleware = (name, policy) => {
-	class SchemaErrors extends HttpApiMiddleware.Service()(`effect-actions/http/SchemaErrors/${name}`, { error: policy.errors }) {}
+	class SchemaErrors extends HttpApiMiddleware.Service()(`effect-actions/http/SchemaErrors/${name}`, { error: policyErrors(policy) }) {}
 	return {
 		SchemaErrors,
-		layer: HttpApiMiddleware.layerSchemaErrorTransform(SchemaErrors, (failure) => Effect.fail(policy.map(failure)))
+		layer: HttpApiMiddleware.layerSchemaErrorTransform(SchemaErrors, (failure) => Effect.fail(answerSchemaError(policy, failure)))
 	};
 };
 function bind(options, group) {
-	const [first, ...rest] = httpActions(group).map((action) => endpoint(options, group, action));
+	const [first, ...rest] = group.actions.map((action) => endpoint(options, group, action));
 	if (first === void 0) return void 0;
 	const bound = HttpApiGroup.make(group.name).add(first, ...rest);
 	if (group.schemaError === void 0) return {
@@ -49,7 +48,10 @@ const erasedHandlers = (handlers) => {
 };
 /** Register one group's handlers. Handler erasure is limited to native dynamic endpoint registration. */
 const groupHandlers = (api, app, middleware, before) => {
-	const entries = (record) => Object.fromEntries(httpActions(app.group).map((action) => [action.name, (request) => dispatch(app.group, action, record, before)(request.payload)]));
+	const entries = (record) => Object.fromEntries(app.group.actions.map((action) => {
+		const run = dispatch(app.group, action, record, before);
+		return [action.name, (request) => run(request.payload)];
+	}));
 	return Layer.unwrap(Effect.map(app.build, (record) => HttpApiBuilder.group(api, app.group.name, (builder) => builder.handleAll(entries(erasedHandlers(record)))))).pipe(Layer.provide(middleware));
 };
 function make(options, ...groups) {
@@ -72,10 +74,13 @@ function make(options, ...groups) {
 		const [first, ...rest] = served.map(({ app, middleware }) => groupHandlers(api, app, middleware, layerOptions.before));
 		return first === void 0 ? HttpApiBuilder.layer(api) : HttpApiBuilder.layer(api).pipe(Layer.provide([first, ...rest]));
 	};
+	const api = apiOf([...bound.values()].map(({ native }) => native));
+	const openApi = (path = `${options.apiPath}/openapi.json`) => HttpRouter.add("GET", path, HttpServerResponse.jsonUnsafe(OpenApi.fromApi(api)));
 	return {
 		groups,
-		api: apiOf([...bound.values()].map(({ native }) => native)),
-		layer
+		api,
+		layer,
+		openApi
 	};
 }
 //#endregion

package/dist/ActionHttpClient.d.mts

@@ -0,0 +1,33 @@
+import { Action_d_exports, Any, Codec } from "./Action.mjs";
+import { Actions } from "./internal/actions.mjs";
+import { ActionHttp_d_exports, Http } from "./ActionHttp.mjs";
+import { ClientOptions } from "./internal/fetchClient.mjs";
+//#region src/ActionHttpClient.d.ts
+/**
+ * The native `HttpApiClient.make` options except `transformResponse`, plus `fetch`;
+ * see the options table in docs/ActionHttpClient.md.
+ */
+export interface Options extends Omit<ClientOptions, "transformResponse"> {
+  readonly fetch?: typeof globalThis.fetch;
+}
+/**
+ * One action as a Promise of its decoded success. An action whose input may be empty,
+ * such as one declared without `input`, may be called without an argument.
+ */
+export type Method<A extends Any> = {} extends A["input"]["Type"] ? (input?: A["input"]["Type"]) => Promise<A["success"]["Type"]> : (input: A["input"]["Type"]) => Promise<A["success"]["Type"]>;
+/** Every action of the binding, as `client.<group>.<action>(input)`. */
+export type Client<Groups extends ReadonlyArray<Actions>> = { readonly [G in Groups[number] as [G["actions"][number]] extends [never] ? never : G["name"]]: { readonly [A in G["actions"][number] as A["name"]]: Method<A>; }; };
+/**
+ * A Promise client for an HTTP binding, for code that does not run Effects, such as a
+ * browser page. It is Effect's native `HttpApiClient` over `fetch`, built once, and
+ * each call runs one request: nothing is retried.
+ *
+ * A call resolves with the action's decoded success. It rejects with what the native
+ * client fails with: a declared error value (the action's, its group's schema-error
+ * policy's, or the binding's surface `errors`), a native `HttpClientError` when the
+ * server could not be reached or answered with a status or body the contract does not
+ * declare, or a `SchemaError` when the input does not encode or the success does not
+ * decode.
+ */
+export declare function promise<const Groups extends ReadonlyArray<Actions>, const Errors extends ReadonlyArray<Codec>>(http: Http<Groups, Errors>, options?: Options): Client<Groups>;
+//#endregion

package/dist/ActionHttpClient.mjs

@@ -0,0 +1,16 @@
+import { fetchApiClient } from "./internal/fetchClient.mjs";
+import { Effect } from "effect";
+//#region src/ActionHttpClient.ts
+function promise(http, { baseUrl, transformClient, fetch } = {}) {
+	const send = fetch ?? ((input, init) => globalThis.fetch(input, init));
+	const native = Effect.runSync(fetchApiClient(http.api, send, {
+		baseUrl,
+		transformClient
+	}));
+	return Object.fromEntries(Object.entries(native).map(([group, endpoints]) => [group, Object.fromEntries(Object.entries(endpoints).map(([action, endpoint]) => {
+		const method = (input) => Effect.runPromise(endpoint({ payload: input ?? {} }));
+		return [action, method];
+	}))]));
+}
+//#endregion
+export { promise };

package/dist/ActionMcp.d.mts

@@ -1,45 +1,35 @@
 import { Action_d_exports, Codec } from "./Action.mjs";
-import { AnyImplementation, BuildContext, BuildError, RequestContext } from "./internal/implementation.mjs";
+import { AnyImplementation, BuildContext, BuildError, HiddenFromMcp, RequestContext } from "./internal/implementation.mjs";
 import { SurfaceOptions } from "./internal/tools.mjs";
 import { Cause, Layer } from "effect";
 import { HttpRouter } from "effect/unstable/http";
 import { McpSchema, McpServer } from "effect/unstable/ai";
 import { Stdio } from "effect/Stdio";
 //#region src/ActionMcp.d.ts
-/** One Streamable HTTP MCP endpoint; its fields become the native server info. */
-export interface Options<Errors extends ReadonlyArray<Codec> = [], R = never> extends SurfaceOptions<Errors, R> {
-  readonly name: string;
-  readonly version: string;
-  /** Native protocol adapters to serve; negotiation and sessions are owned by Effect. */
-  readonly protocols: Parameters<typeof McpServer.layerHttp>[0]["protocols"];
-  /** Route of the Streamable HTTP endpoint; no default. */
-  readonly path: HttpRouter.PathInput;
-  /** Browser origins accepted by the native server; passed through to `McpServer.layerHttp`. */
-  readonly allowedOrigins?: ReadonlyArray<string>;
-  readonly instructions?: string;
-}
-/** Server information for an MCP subprocess connected through standard I/O. */
-export interface StdioOptions<Errors extends ReadonlyArray<Codec> = [], R = never> extends SurfaceOptions<Errors, R> {
-  readonly name: string;
-  readonly version: string;
-  /** Native protocol adapters to serve; negotiation is owned by Effect. */
-  readonly protocols: Parameters<typeof McpServer.layerStdio>[0]["protocols"];
-  readonly instructions?: string;
-}
+/**
+ * One Streamable HTTP MCP endpoint: every native `McpServer.layerHttp` option except
+ * `protocols` (server information, `path`, `allowedOrigins`, `instructions`,
+ * `extensions`, ...), plus the surface's `errors` and `before`.
+ */
+export interface Options<Errors extends ReadonlyArray<Codec> = [], R = never> extends Omit<Parameters<typeof McpServer.layerHttp>[0], "protocols">, SurfaceOptions<Errors, R> {}
+/** An MCP subprocess on standard I/O: every native `McpServer.layerStdio` option except `protocols`. */
+export interface StdioOptions<Errors extends ReadonlyArray<Codec> = [], R = never> extends Omit<Parameters<typeof McpServer.layerStdio>[0], "protocols">, SurfaceOptions<Errors, R> {}
 /** The native server supplies its own request context to every tool call. */
-type ToolRequestContext<App, RB> = Exclude<RequestContext<App, "mcp"> | RB, McpSchema.McpRequestContext>;
+type ToolRequestContext<App, RB> = Exclude<RequestContext<App, HiddenFromMcp> | RB, McpSchema.McpRequestContext>;
 /**
- * Serve MCP tools over one Streamable HTTP endpoint.
+ * Serve MCP tools over one Streamable HTTP endpoint, speaking MCP 2026-07-28 only.
  *
  * Middleware provided around this layer has the normal HTTP lifetime. Native
  * context capture applies: never provide request-identity tags at startup.
  */
-export declare function layerHttp<const Apps extends ReadonlyArray<AnyImplementation>, const Errors extends ReadonlyArray<Codec> = [], RB = never>(apps: readonly [...Apps], options: Options<Errors, RB>): Layer.Layer<never, BuildError<Apps[number], "mcp"> | Cause.IllegalArgumentError, BuildContext<Apps[number], "mcp"> | HttpRouter.HttpRouter | HttpRouter.Request.From<"Requires", ToolRequestContext<Apps[number], RB>>>;
+export declare function layerHttp<const Apps extends ReadonlyArray<AnyImplementation>, const Errors extends ReadonlyArray<Codec> = [], RB = never>(apps: readonly [...Apps], options: Options<Errors, RB>): Layer.Layer<never, BuildError<Apps[number], HiddenFromMcp> | Cause.IllegalArgumentError, BuildContext<Apps[number], HiddenFromMcp> | HttpRouter.HttpRouter | HttpRouter.Request.From<"Requires", ToolRequestContext<Apps[number], RB>>>;
 /**
- * Serve MCP tools through newline-delimited JSON-RPC on standard I/O.
+ * Serve MCP tools through newline-delimited JSON-RPC on standard I/O, speaking MCP
+ * 2026-07-28 only. An older host is refused deliberately, for uniformity with HTTP,
+ * even though stdio has no sessions.
  *
  * The host supplies the `Stdio` service. Arguments are tool input only and
  * never establish request identity or authority.
  */
-export declare function layerStdio<const Apps extends ReadonlyArray<AnyImplementation>, const Errors extends ReadonlyArray<Codec> = [], RB = never>(apps: readonly [...Apps], options: StdioOptions<Errors, RB>): Layer.Layer<never, BuildError<Apps[number], "mcp"> | Cause.IllegalArgumentError, BuildContext<Apps[number], "mcp"> | Stdio | ToolRequestContext<Apps[number], RB>>;
+export declare function layerStdio<const Apps extends ReadonlyArray<AnyImplementation>, const Errors extends ReadonlyArray<Codec> = [], RB = never>(apps: readonly [...Apps], options: StdioOptions<Errors, RB>): Layer.Layer<never, BuildError<Apps[number], HiddenFromMcp> | Cause.IllegalArgumentError, BuildContext<Apps[number], HiddenFromMcp> | Stdio | ToolRequestContext<Apps[number], RB>>;
 //#endregion

package/dist/ActionMcp.mjs

@@ -1,8 +1,13 @@
 import "./internal/implementation.mjs";
 import { bindTools } from "./internal/tools.mjs";
 import { Layer } from "effect";
-import { McpServer } from "effect/unstable/ai";
+import { McpProtocol, McpServer } from "effect/unstable/ai";
 //#region src/ActionMcp.ts
+/**
+* The one protocol revision served. 2026-07-28 is stateless over HTTP: no
+* initialize handshake and no session, so every request stands alone.
+*/
+const protocols = [McpProtocol.v2026_07_28];
 const registration = (apps, options) => {
 	const binding = bindTools(apps, "mcp", options);
 	return Layer.effectDiscard(McpServer.registerToolkit(binding.toolkit)).pipe(Layer.provide(binding.layer));
@@ -10,16 +15,15 @@ const registration = (apps, options) => {
 const server = (apps, options, transport) => registration(apps, options).pipe(Layer.provide(transport), Layer.fresh);
 function layerHttp(apps, options) {
 	return server(apps, options, McpServer.layerHttp({
-		name: options.name,
-		version: options.version,
-		instructions: options.instructions,
-		path: options.path,
-		protocols: options.protocols,
-		allowedOrigins: options.allowedOrigins
+		...options,
+		protocols
 	}));
 }
 function layerStdio(apps, options) {
-	return server(apps, options, McpServer.layerStdio(options));
+	return server(apps, options, McpServer.layerStdio({
+		...options,
+		protocols
+	}));
 }
 //#endregion
 export { layerHttp, layerStdio };