@gjermundgaraba/effect-actions 0.4.1 → 0.5.0

package/README.md

@@ -30,11 +30,13 @@ const app = Actions.implement({
 });
 
 export const routes = Layer.mergeAll(
-  Http.layer({}, app),
-  ActionMcp.layerHttp(
-    { protocols: [McpProtocol.v2026_07_28], name: "greetings", version: "1.0.0", path: "/mcp" },
-    app,
-  ),
+  Http.layer([app]),
+  ActionMcp.layerHttp([app], {
+    protocols: [McpProtocol.v2026_07_28],
+    name: "greetings",
+    version: "1.0.0",
+    path: "/mcp",
+  }),
 );
 ```
 
@@ -42,7 +44,7 @@ Serve `routes` with Effect's `HttpRouter` and you have `POST /api/actions/greeti
 and an MCP tool named `greet` at `/mcp`. The same `app` is also:
 
 ```ts
-const { toolkit, layer } = ActionToolkit.make({}, app); // native Effect AI Toolkit and its handler layer
+const { toolkit, layer } = ActionToolkit.make([app]); // native Effect AI Toolkit and its handler layer
 const cli = ActionCli.group(app); // greetings greet --input '{"name":"Ada"}'
 const remote = ActionCliClient.command(Http, "greetings", "greet"); // same command, over HTTP
 const catalog = ActionCatalog.make(Actions); // offline JSON contract, no handlers acquired
@@ -61,7 +63,7 @@ const greeting = Effect.gen(function* () {
 ## 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.
-- A handler may fail only with the errors its action declares. Each surface binds one `before` hook that runs before every handler it serves — on HTTP before the payload is even decoded — so a policy such as scope enforcement is written once per surface and no action of that surface can skip it.
+- A handler may fail only with the errors its action declares. Each surface binds one `before` hook that runs before every handler it serves — after successful input decoding — so a policy such as scope enforcement is written once per surface and no action of that surface can skip it.
 - The pieces are Effect's own. `Http.api` is a native `HttpApi`, so `OpenApi.fromApi`, Swagger, Scalar, and `HttpApiClient` work on it unchanged. MCP is Effect's native `McpServer`, one `Tool` per action, with no SDK runtime dependency.
 - Every action states its `access` (`"read"` or `"write"`, required), so authorization reads the contract instead of a hand-maintained list of mutation names.
 - Build-time services and per-request services are tracked separately in the types. Middleware is per group, so a public group and an authenticated group can share one mount path.
@@ -104,7 +106,7 @@ Authentication and authorization belong to the application. See [docs/setup.md](
 
 ## Acknowledgements
 
-A few idea (like the native Toolkit, CLI, and catalog projections) are inspired by the excellent [rat-stack](https://github.com/joelhooks/rat-stack) by Joel Hooks.
+A few ideas (like the native Toolkit, CLI, and catalog projections) are inspired by the excellent [rat-stack](https://github.com/joelhooks/rat-stack) by Joel Hooks.
 
 ## Contributing
 

package/dist/ActionCatalog.d.mts

@@ -2,7 +2,7 @@ import { Action_d_exports, Any } from "./Action.mjs";
 import { ActionGroup_d_exports, Any as Any$1 } from "./ActionGroup.mjs";
 import { JsonSchema } from "effect";
 //#region src/ActionCatalog.d.ts
-/** One contract, with independently rooted JSON schemas for its encoded values. */
+/** One contract, with independently rooted descriptions of its encoded values. */
 export interface Entry {
   readonly id: string;
   readonly group: string;
@@ -19,7 +19,7 @@ export interface Entry {
 }
 /** An offline contract document, not an authorization decision or a mounted endpoint. */
 export interface Catalog {
-  readonly version: "1";
+  readonly version: "3";
   readonly actions: ReadonlyArray<Entry>;
 }
 /**

package/dist/ActionCatalog.mjs

@@ -1,12 +1,13 @@
 import { assertDistinct } from "./internal/actions.mjs";
 import { JsonSchema, Schema } from "effect";
 //#region src/ActionCatalog.ts
-const jsonSchema = (codec) => {
-	const document = Schema.toJsonSchemaDocument(codec);
+/** Describe the JSON wire form; decoding on the server remains authoritative. */
+const describe = (codec) => {
+	const { schema, definitions } = Schema.toJsonSchemaDocument(codec);
 	return {
 		$schema: JsonSchema.META_SCHEMA_URI_DRAFT_2020_12,
-		...document.schema,
-		...Object.keys(document.definitions).length === 0 ? {} : { $defs: document.definitions }
+		...schema,
+		...Object.keys(definitions).length === 0 ? {} : { $defs: definitions }
 	};
 };
 /**
@@ -17,7 +18,7 @@ const jsonSchema = (codec) => {
 const make = (...groups) => {
 	assertDistinct("catalog group", groups.map((group) => group.name));
 	return {
-		version: "1",
+		version: "3",
 		actions: groups.flatMap((group) => group.actions.map((action) => ({
 			id: `${group.name}.${action.name}`,
 			group: group.name,
@@ -25,10 +26,10 @@ const make = (...groups) => {
 			description: action.description,
 			http: action.http,
 			mcp: action.mcp,
-			input: jsonSchema(action.input),
-			success: jsonSchema(action.success),
-			errors: action.errors.map(jsonSchema),
-			httpSchemaErrors: action.http ? group.schemaError?.errors.map(jsonSchema) ?? [] : []
+			input: describe(action.input),
+			success: describe(action.success),
+			errors: action.errors.map(describe),
+			httpSchemaErrors: action.http ? group.schemaError?.errors.map(describe) ?? [] : []
 		})))
 	};
 };

package/dist/ActionCli.d.mts

@@ -6,8 +6,8 @@ import { Effect, Scope } from "effect";
 import { Command } from "effect/unstable/cli";
 //#region src/ActionCli.d.ts
 /**
- * The hook a local command runs before the selected handler. A CLI encodes
- * nothing, so its refusal is a typed failure of the command effect rather than a
+ * The hook a local command runs before the selected handler. A CLI does not serialize
+ * failures, so its refusal is a typed failure of the command effect rather than a
  * declared surface error; the native parser has already decoded the input.
  */
 interface BeforeOptions<E, R> {

package/dist/ActionCli.mjs

@@ -1,26 +1,21 @@
+import { selectNamed } from "./internal/actions.mjs";
 import { dispatch } from "./internal/implementation.mjs";
 import { command as command$1 } from "./internal/cli.mjs";
 import { Effect } from "effect";
 import { Command } from "effect/unstable/cli";
 //#region src/ActionCli.ts
-const select = (group, name) => {
-	const action = group.actions.find((candidate) => candidate.name === name);
-	if (action === void 0) throw new Error(`Unknown action "${group.name}.${name}"`);
-	return action;
-};
 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.
 * The action name resolves against the bound group; no HTTP fallback exists.
 */
 const command = (app, name, options) => {
-	const action = select(app.group, name);
+	const action = selectNamed(app.group.actions, name, `action "${app.group.name}.${name}"`);
 	return command$1(action, (input) => local(app, action, options?.before, input), options);
 };
 /** Project every local action below its group namespace with default CLI options. */
 const group = (app, options) => {
-	const before = options?.before;
-	const commands = app.group.actions.map((action) => command$1(action, (input) => Effect.scoped(Effect.flatMap(app.build, (handlers) => dispatch(app.group, action, handlers, before)(input)))));
+	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)))));
 	return Command.make(options?.name ?? app.group.name).pipe(Command.withSubcommands(commands));
 };
 //#endregion

package/dist/ActionCliClient.d.mts

@@ -1,5 +1,6 @@
 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";
@@ -7,17 +8,21 @@ import { HttpClient } from "effect/unstable/http";
 import { HttpApi, HttpApiClient, HttpApiEndpoint, HttpApiGroup } from "effect/unstable/httpapi";
 import { Command } from "effect/unstable/cli";
 //#region src/ActionCliClient.d.ts
+/**
+ * What the host configures on Effect's native client: `baseUrl`, `transformClient`,
+ * `transformResponse`. The selectors and the client are the command's own.
+ */
+export type Connection = NonNullable<globalThis.Parameters<typeof HttpApiClient.make>[1]>;
 /** Parsing, rendering and native HTTP-endpoint configuration for one remote action. */
 export type Options<Output, ParsedParameters extends Command.Command.Config = never> = Options$1<Output, ParsedParameters> & {
-  /** Passed directly to Effect's native `HttpApiClient.endpoint`. */
-  readonly connection?: NonNullable<globalThis.Parameters<typeof HttpApiClient.make>[1]>;
+  readonly connection?: Connection;
 };
 /** Configuration for a remote aggregate group command. */
 export interface GroupOptions {
   /** Override the group command name. */
   readonly name?: string;
   /** Shared native HTTP-endpoint configuration for every remote action. */
-  readonly connection?: NonNullable<globalThis.Parameters<typeof HttpApiClient.make>[1]>;
+  readonly connection?: Connection;
 }
 type Group<Groups extends ReadonlyArray<Actions>, Name extends Groups[number]["name"]> = Extract<Groups[number], {
   readonly name: Name;
@@ -25,9 +30,7 @@ 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> = Extract<G["actions"][number], {
-  readonly http: true;
-}>["name"];
+type HttpNames<G extends Actions> = ServedNames<G, "http">;
 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>>>>, {
   readonly identifier: ActionName;

package/dist/ActionCliClient.mjs

@@ -1,3 +1,4 @@
+import { selectNamed } from "./internal/actions.mjs";
 import { command as command$1 } from "./internal/cli.mjs";
 import { Effect } from "effect";
 import { HttpClient } from "effect/unstable/http";
@@ -12,14 +13,11 @@ import { Command } from "effect/unstable/cli";
 const erasedApi = (api) => {
 	return api;
 };
-const selectGroup = (groups, name) => {
-	const group = groups.find((candidate) => candidate.name === name);
-	if (group === void 0) throw new Error(`Unknown HTTP group "${name}"`);
-	return group;
-};
+/** An action hidden from HTTP is unknown to this binding, exactly like a missing one. */
 const selectAction = (group, name) => {
-	const action = group.actions.find((candidate) => candidate.name === name);
-	if (action === void 0 || !action.http) throw new Error(`Unknown HTTP action "${group.name}.${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;
 };
 /**
@@ -28,14 +26,14 @@ const selectAction = (group, name) => {
 * keep dynamically supplied selector strings from reaching the native client.
 */
 const command = (http, groupName, actionName, options) => {
-	const group = selectGroup(http.groups, groupName);
+	const group = selectNamed(http.groups, groupName, `HTTP group "${groupName}"`);
 	const action = selectAction(group, actionName);
 	return command$1(action, (input) => Effect.flatMap(HttpClient.HttpClient, (httpClient) => {
 		const endpoint = HttpApiClient.endpoint(erasedApi(http.api), {
+			...options?.connection,
 			group: groupName,
 			endpoint: actionName,
-			httpClient,
-			...options?.connection
+			httpClient
 		});
 		return Effect.flatMap(endpoint, (method) => {
 			return method({ payload: input });
@@ -44,7 +42,7 @@ const command = (http, groupName, actionName, options) => {
 };
 /** Project all HTTP-enabled actions retained by one group below its group namespace. */
 const group = (http, groupName, options) => {
-	const actions = selectGroup(http.groups, groupName);
+	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 })] : []);
 	return Command.make(options?.name ?? actions.name).pipe(Command.withSubcommands(commands));
 };

package/dist/ActionGroup.d.mts

@@ -1,7 +1,7 @@
 import { Action, Action_d_exports, Any as Any$1, Codec, Handler } from "./Action.mjs";
 import { Actions, SchemaErrorPolicy } from "./internal/actions.mjs";
 import { Implementation } from "./internal/implementation.mjs";
-import { Effect, Scope } from "effect";
+import { Effect, Scope, Types } from "effect";
 declare namespace ActionGroup_d_exports {
   export { Any, Contracts, Group, Implementation, Options, SchemaErrorPolicy, contracts, make };
 }
@@ -28,10 +28,8 @@ export type Any = Group<string, ReadonlyArray<Any$1>, ReadonlyArray<Codec>>;
 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>;
 /** `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;
-/** Merges those per-group maps into one, rather than leaving a union of them. */
-type Merged<Maps> = (Maps extends unknown ? (map: Maps) => void : never) extends ((map: infer Merged) => void) ? Merged : never;
-/** Every action of `Groups`, keyed `<group>.<action>`. */
-export type Contracts<Groups extends ReadonlyArray<Actions>> = Merged<PerGroup<Groups[number]>>;
+/** Every action of `Groups`, keyed `<group>.<action>`: the per-group maps merged into one. */
+export type Contracts<Groups extends ReadonlyArray<Actions>> = Types.UnionToIntersection<PerGroup<Groups[number]>>;
 /**
  * Project groups into one map of their action contracts, keyed `<group>.<action>`:
  * the identity routes, tools and commands share. Deriving it from the groups

package/dist/ActionHttp.d.mts

@@ -24,10 +24,9 @@ export interface Options<Errors extends ReadonlyArray<Codec> = []> {
 /** What `Http.layer` binds around the implementations it serves. */
 export interface LayerOptions<Errors extends ReadonlyArray<Codec>, R> {
   /**
-   * Runs once per request, before the request payload is decoded, with the action
-   * contract it is about to run. It fails with the binding's own `errors`, so an
-   * unauthorized caller learns nothing about the action's input, and the refusal
-   * is encoded exactly like a declared error. Its services are request-time
+   * Runs once after successful payload decoding, before the selected handler,
+   * with its action contract. It fails with the binding's own `errors`, encoded
+   * exactly like a declared error. Its services are request-time
    * requirements, like a handler's.
    */
   readonly before?: (action: Any) => Effect.Effect<void, Errors[number]["Type"], R>;
@@ -48,7 +47,7 @@ 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>(options: LayerOptions<Errors, RB>, ...apps: Apps) => 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>;
+  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>;
 }
 /**
  * Bind the contract-level configuration once. Every route is `POST

package/dist/ActionHttp.mjs

@@ -1,7 +1,7 @@
 import { assertDistinct, projectedErrors } from "./internal/actions.mjs";
 import { dispatch } from "./internal/implementation.mjs";
 import { Effect, Layer } from "effect";
-import { HttpEffect, HttpRouter, HttpServerResponse } from "effect/unstable/http";
+import "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);
@@ -18,36 +18,18 @@ const schemaErrorMiddleware = (name, policy) => {
 		layer: HttpApiMiddleware.layerSchemaErrorTransform(SchemaErrors, (failure) => Effect.fail(policy.map(failure)))
 	};
 };
-/** The hook of one group, applied to every one of its endpoints. */
-const hookMiddleware = (name) => {
-	class Admission extends HttpApiMiddleware.Service()(`effect-actions/http/Admission/${name}`) {}
-	const implementation = (group, before) => {
-		if (before === void 0) return (httpEffect) => httpEffect;
-		const actions = new Map(httpActions(group).map((action) => [action.name, action]));
-		return (httpEffect, { endpoint }) => {
-			const action = actions.get(endpoint.identifier);
-			if (action === void 0) throw new Error(`Missing action: ${endpoint.identifier}`);
-			return Effect.flatMap(before(action), () => httpEffect);
-		};
-	};
-	return {
-		Admission,
-		layer: (group, before) => Layer.succeed(Admission, implementation(group, before))
-	};
-};
 function bind(options, group) {
 	const [first, ...rest] = httpActions(group).map((action) => endpoint(options, group, action));
 	if (first === void 0) return void 0;
 	const bound = HttpApiGroup.make(group.name).add(first, ...rest);
-	const hook = hookMiddleware(group.name);
 	if (group.schemaError === void 0) return {
-		native: bound.middleware(hook.Admission),
-		middleware: (before) => hook.layer(group, before)
+		native: bound,
+		middleware: Layer.empty
 	};
 	const policy = schemaErrorMiddleware(group.name, group.schemaError);
 	return {
-		native: bound.middleware(policy.SchemaErrors).middleware(hook.Admission),
-		middleware: (before) => Layer.merge(policy.layer, hook.layer(group, before))
+		native: bound.middleware(policy.SchemaErrors),
+		middleware: policy.layer
 	};
 }
 function apiOf(groups) {
@@ -66,22 +48,17 @@ const erasedHandlers = (handlers) => {
 	return handlers;
 };
 /** Register one group's handlers. Handler erasure is limited to native dynamic endpoint registration. */
-const groupHandlers = (api, app, middleware) => {
-	const entries = (record) => Object.fromEntries(httpActions(app.group).map((action) => [action.name, (request) => dispatch(app.group, action, record, void 0)(request.payload)]));
+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)]));
 	return Layer.unwrap(Effect.map(app.build, (record) => HttpApiBuilder.group(api, app.group.name, (builder) => builder.handleAll(entries(erasedHandlers(record)))))).pipe(Layer.provide(middleware));
 };
-/**
-* A refused or failed request is never stored by a shared cache. Successful
-* responses keep whatever the host sets, since only the host knows what is public.
-*/
-const noStore = HttpRouter.middleware((httpEffect) => HttpEffect.withPreResponseHandler(httpEffect, (_request, response) => Effect.succeed(response.status < 400 ? response : HttpServerResponse.setHeader(response, "cache-control", "no-store"))));
 function make(options, ...groups) {
 	assertDistinct("action group", groups.map((group) => group.name));
 	const bound = new Map(groups.flatMap((group) => {
 		const binding = bind(options, group);
 		return binding === void 0 ? [] : [[group, binding]];
 	}));
-	const layer = (layerOptions, ...apps) => {
+	const layer = (apps, layerOptions = {}) => {
 		assertDistinct("implementation group", apps.map((app) => app.group.name));
 		for (const app of apps) if (!groups.includes(app.group)) throw new Error(`Implementation of group "${app.group.name}" is not served by this adapter`);
 		const served = apps.flatMap((app) => {
@@ -92,8 +69,8 @@ function make(options, ...groups) {
 			}];
 		});
 		const api = apiOf(served.map(({ native }) => native));
-		const before = layerOptions.before;
-		return served.reduce((layer, { app, middleware }) => layer.pipe(Layer.provide(groupHandlers(api, app, middleware(before)))), HttpApiBuilder.layer(api)).pipe(Layer.provide(noStore.layer));
+		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]));
 	};
 	return {
 		groups,

package/dist/ActionMcp.d.mts

@@ -1,26 +1,11 @@
-import { Action_d_exports, Any, Codec } from "./Action.mjs";
+import { Action_d_exports, Codec } from "./Action.mjs";
 import { AnyImplementation, BuildContext, BuildError, RequestContext } from "./internal/implementation.mjs";
-import { Cause, Effect, Layer } from "effect";
+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
-/** What every MCP transport binds around the tools it serves. */
-interface SurfaceOptions<Errors extends ReadonlyArray<Codec>, R> {
-  /**
-   * Failures the surface answers with instead of a handler: authorization, rate
-   * limits. Declared on every tool of this transport, so a refusal is returned
-   * as an `isError` result exactly like an action's own error.
-   */
-  readonly errors?: Errors;
-  /**
-   * Runs once per tool call, after the native server has decoded the arguments
-   * and before the selected handler, with the action contract it is about to run.
-   * It fails with this transport's `errors`. Its services are request-time
-   * requirements, like a handler's.
-   */
-  readonly before?: (action: Any) => Effect.Effect<void, Errors[number]["Type"], R>;
-}
 /** 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;
@@ -42,19 +27,19 @@ export interface StdioOptions<Errors extends ReadonlyArray<Codec> = [], R = neve
   readonly instructions?: string;
 }
 /** The native server supplies its own request context to every tool call. */
-type ToolRequestContext<App, RB> = Exclude<RequestContext<App> | RB, McpSchema.McpRequestContext>;
+type ToolRequestContext<App, RB> = Exclude<RequestContext<App, "mcp"> | RB, McpSchema.McpRequestContext>;
 /**
  * Serve MCP tools over one Streamable HTTP endpoint.
  *
  * 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>(options: Options<Errors, RB>, ...apps: Apps): Layer.Layer<never, BuildError<Apps[number]> | Cause.IllegalArgumentError, BuildContext<Apps[number]> | 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], "mcp"> | Cause.IllegalArgumentError, BuildContext<Apps[number], "mcp"> | HttpRouter.HttpRouter | HttpRouter.Request.From<"Requires", ToolRequestContext<Apps[number], RB>>>;
 /**
  * Serve MCP tools through newline-delimited JSON-RPC on standard I/O.
  *
  * 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>(options: StdioOptions<Errors, RB>, ...apps: Apps): Layer.Layer<never, BuildError<Apps[number]> | Cause.IllegalArgumentError, BuildContext<Apps[number]> | 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], "mcp"> | Cause.IllegalArgumentError, BuildContext<Apps[number], "mcp"> | Stdio | ToolRequestContext<Apps[number], RB>>;
 //#endregion

package/dist/ActionMcp.mjs

@@ -8,16 +8,8 @@ const registration = (apps, options) => {
 	return Layer.effectDiscard(McpServer.registerToolkit(binding.toolkit)).pipe(Layer.provide(binding.layer));
 };
 const server = (apps, options, transport) => registration(apps, options).pipe(Layer.provide(transport), Layer.fresh);
-/** The hook and surface errors an erased transport binds. */
-const toolOptions = (options) => {
-	const before = options.before;
-	return {
-		errors: options.errors,
-		before
-	};
-};
-function layerHttp(options, ...apps) {
-	return server(apps, toolOptions(options), McpServer.layerHttp({
+function layerHttp(apps, options) {
+	return server(apps, options, McpServer.layerHttp({
 		name: options.name,
 		version: options.version,
 		instructions: options.instructions,
@@ -26,8 +18,8 @@ function layerHttp(options, ...apps) {
 		allowedOrigins: options.allowedOrigins
 	}));
 }
-function layerStdio(options, ...apps) {
-	return server(apps, toolOptions(options), McpServer.layerStdio(options));
+function layerStdio(apps, options) {
+	return server(apps, options, McpServer.layerStdio(options));
 }
 //#endregion
 export { layerHttp, layerStdio };

package/dist/ActionToolkit.d.mts

@@ -1,23 +1,11 @@
 import { Action_d_exports, Any, Codec } from "./Action.mjs";
 import { AnyImplementation, BuildContext, BuildError, HandlerContext, Implementation } from "./internal/implementation.mjs";
-import { Effect, Layer, Schema } from "effect";
+import { SurfaceOptions } from "./internal/tools.mjs";
+import { Layer, Schema } from "effect";
 import { Tool, Toolkit } from "effect/unstable/ai";
 //#region src/ActionToolkit.d.ts
-/** What `make` binds around the implementations it projects. */
-export interface Options<Errors extends ReadonlyArray<Codec> = [], R = never> {
-  /**
-   * Failures the caller answers with instead of a handler: authorization, rate
-   * limits. Declared on every tool, so a refusal is returned as a tool failure
-   * exactly like an action's own error.
-   */
-  readonly errors?: Errors;
-  /**
-   * Runs once per tool call, before the selected handler, with the action contract
-   * it is about to run. It fails with this binding's `errors`. Its services join
-   * each tool's request requirements, like a handler's.
-   */
-  readonly before?: (action: Any) => Effect.Effect<void, Errors[number]["Type"], R>;
-}
+/** What the in-process caller binds around the implementations it projects. */
+export type Options<Errors extends ReadonlyArray<Codec> = [], R = never> = SurfaceOptions<Errors, R>;
 /** A native tool corresponding to an MCP-enabled action. */
 type NativeTool<A extends Any, E extends Codec, R> = A extends {
   readonly mcp: {
@@ -49,5 +37,5 @@ export interface Binding<Tools extends Record<string, Tool.Any>, E = never, R =
  * Build services are needed to construct `layer`; request services are needed
  * when the resulting toolkit handles a call.
  */
-export declare function make<const Apps extends ReadonlyArray<AnyImplementation>, const Errors extends ReadonlyArray<Codec> = [], RB = never>(options: Options<Errors, RB>, ...apps: Apps): Binding<ToolkitTools<Apps, Errors[number], RB>, BuildError<Apps[number]>, BuildContext<Apps[number]>>;
+export declare function make<const Apps extends ReadonlyArray<AnyImplementation>, const Errors extends ReadonlyArray<Codec> = [], RB = never>(apps: readonly [...Apps], options?: Options<Errors, RB>): Binding<ToolkitTools<Apps, Errors[number], RB>, BuildError<Apps[number], "mcp">, BuildContext<Apps[number], "mcp">>;
 //#endregion

package/dist/ActionToolkit.mjs

@@ -3,13 +3,8 @@ import { bindTools } from "./internal/tools.mjs";
 import "effect";
 import "effect/unstable/ai";
 //#region src/ActionToolkit.ts
-function make(options, ...apps) {
-	const before = options.before;
-	const toolOptions = {
-		errors: options.errors,
-		before
-	};
-	return bindTools(apps, "native", toolOptions);
+function make(apps, options = {}) {
+	return bindTools(apps, "native", options);
 }
 //#endregion
 export { make };

package/dist/internal/actions.mjs

@@ -4,12 +4,21 @@
 * a projection of that action declares. A schema the action already declares is
 * not repeated.
 */
-const projectedErrors = (action, surface) => [...action.errors, ...(surface ?? []).filter((error) => !action.errors.includes(error))];
+const projectedErrors = (action, surface) => [.../* @__PURE__ */ new Set([...action.errors, ...surface ?? []])];
 const validName = /^[A-Za-z0-9_-]+$/;
 /** Names become path segments, OpenAPI identifiers and client method keys. */
 const assertName = (what, name) => {
 	if (!validName.test(name) || name === "then") throw new Error(`Invalid ${what}: ${name}`);
 };
+/**
+* The one item of `items` named `name`, narrowed to that contract. A caller passes
+* a literal name, so a miss is a programming error reported as `Unknown <what>`.
+*/
+const selectNamed = (items, name, what) => {
+	const item = items.find((candidate) => candidate.name === name);
+	if (item === void 0) throw new Error(`Unknown ${what}`);
+	return item;
+};
 /** Each namespace is checked by whoever owns it: a group, the routes, or the MCP tools. */
 const assertDistinct = (what, names) => {
 	const seen = /* @__PURE__ */ new Set();
@@ -19,4 +28,4 @@ const assertDistinct = (what, names) => {
 	}
 };
 //#endregion
-export { assertDistinct, assertName, projectedErrors };
+export { assertDistinct, assertName, projectedErrors, selectNamed };

package/dist/internal/cli.d.mts

@@ -6,7 +6,7 @@ import { Command } from "effect/unstable/cli";
 interface CommonOptions<Output> {
   /** Override the command name. The action name is used by default. */
   readonly name?: string;
-  /** Human output. JSON remains available with `--json`. */
+  /** Human output. Adds a `--json` flag to the command that selects JSON instead. */
   readonly render?: (output: Output) => string;
 }
 /** The default projection accepts a whole canonical JSON input with `--input`. */
@@ -19,7 +19,7 @@ export interface ParametersOptions<Output, Parameters extends Command.Command.Co
   /** Native Effect CLI flags and arguments. */
   readonly parameters: Parameters;
   /** Maps native parsed parameters to the action's canonical JSON input. */
-  readonly input: (parsed: Command.Command.Config.Infer<Parameters>) => Schema.Json;
+  readonly input: (parsed: Command.Command.Config.InferValue<Parameters>) => Schema.Json;
 }
 /**
  * A command either accepts whole JSON input or has explicit native CLI parameters.