@gjermundgaraba/effect-actions 0.1.0-rc.1 → 0.1.0

package/dist/Authentication.mjs

@@ -1,66 +1,37 @@
-import { Effect, Schema, SchemaAST } from "effect";
+import { Effect } from "effect";
 import { HttpEffect, HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
 //#region src/Authentication.ts
 /**
 * Authenticate each request and provide its identity to the downstream handler.
-* Only authentication failures are encoded, using each schema's httpApiStatus.
-* Dependencies remain native router request requirements. Acquired resources live
-* until the request scope closes, including while the handler is running.
+* `authenticate` fails with the response to send instead, so the host owns its
+* status, body and challenge headers. Dependencies remain native router request
+* requirements. Acquired resources live until the request scope closes, including
+* while the handler is running. Every response is marked `Cache-Control: no-store`,
+* including private failures serialized by enclosing middleware.
 */
-const middleware = (service, options) => {
-	const errors = options.errors.map((schema) => ({
-		matches: Schema.is(schema),
-		encode: HttpServerResponse.schemaJson(schema),
-		status: SchemaAST.resolveAt("httpApiStatus")(schema.ast) ?? 500
-	}));
-	return HttpRouter.middleware()((httpEffect) => options.authenticate.pipe(Effect.matchEffect({
-		onFailure: (error) => {
-			const selected = errors.find((candidate) => candidate.matches(error));
-			if (selected === void 0) return Effect.die(/* @__PURE__ */ new Error("Undeclared authentication error"));
-			return selected.encode(error, {
-				status: selected.status,
-				headers: options.headers?.(error)
-			}).pipe(Effect.orDie);
-		},
-		onSuccess: (identity) => Effect.provideService(httpEffect, service, identity)
-	}), HttpEffect.withPreResponseHandler((_request, response) => Effect.succeed(HttpServerResponse.setHeader(response, "cache-control", "no-store")))));
-};
-const oauthUrl = (value) => {
-	const url = new URL(value);
-	const loopback = [
-		"localhost",
-		"127.0.0.1",
-		"[::1]"
-	].includes(url.hostname);
-	if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback) || url.username !== "" || url.password !== "" || value.includes("#")) throw new Error("OAuth URLs must use HTTPS (or loopback HTTP) without credentials or fragment");
-	return url;
-};
-const scopeToken = /^[\x21\x23-\x5B\x5D-\x7E]+$/;
+const middleware = (service, authenticate) => HttpRouter.middleware()((httpEffect) => authenticate.pipe(Effect.matchEffect({
+	onFailure: Effect.succeed,
+	onSuccess: (identity) => Effect.provideService(httpEffect, service, identity)
+}), HttpEffect.withPreResponseHandler((_request, response) => Effect.succeed(HttpServerResponse.setHeader(response, "cache-control", "no-store")))));
+const quoted = (value) => `"${value.replace(/["\\]/g, "\\$&")}"`;
 /**
 * Publish RFC 9728 discovery independently from the authenticated routes.
 * This supplies metadata and challenges; the host still verifies access tokens.
 */
 const protectedResource = (options) => {
-	const resource = oauthUrl(options.resource);
-	if (options.authorizationServers.length === 0) throw new Error("An authorization server is required");
-	for (const issuer of options.authorizationServers) {
-		oauthUrl(issuer);
-		if (issuer.includes("?")) throw new Error("Authorization server issuers must not contain a query");
-	}
-	for (const scope of options.scopesSupported ?? []) if (!scopeToken.test(scope)) throw new Error("Invalid OAuth scope token");
+	const resource = new URL(options.resource);
 	const path = `/.well-known/oauth-protected-resource${resource.pathname === "/" ? "" : resource.pathname}`;
 	const discoveryUrl = new URL(resource);
 	discoveryUrl.pathname = path;
 	const metadataUrl = discoveryUrl.href;
 	const target = metadataUrl.slice(discoveryUrl.origin.length);
-	const metadata = {
+	const response = HttpServerResponse.jsonUnsafe({
 		resource: options.resource,
 		authorization_servers: options.authorizationServers,
-		bearer_methods_supported: ["header"]
-	};
-	if (options.scopesSupported !== void 0 && options.scopesSupported.length > 0) metadata.scopes_supported = options.scopesSupported;
-	if (options.resourceName !== void 0) metadata.resource_name = options.resourceName;
-	const response = HttpServerResponse.jsonUnsafe(metadata);
+		bearer_methods_supported: ["header"],
+		scopes_supported: options.scopesSupported,
+		resource_name: options.resourceName
+	});
 	return {
 		layer: HttpRouter.middleware((next) => Effect.gen(function* () {
 			const request = yield* HttpServerRequest.HttpServerRequest;
@@ -69,18 +40,14 @@ const protectedResource = (options) => {
 			return yield* next;
 		}), { global: true }),
 		metadataUrl,
+		/** The `WWW-Authenticate` value; parameter values are quoted and escaped. */
 		challenge: (challenge = {}) => {
-			const parameters = [`resource_metadata="${metadataUrl.replace(/["\\]/g, "\\$&")}"`];
-			if (challenge.error !== void 0) parameters.push(`error="${challenge.error}"`);
-			if (challenge.errorDescription !== void 0) {
-				if (!/^[\x20-\x21\x23-\x5B\x5D-\x7E]*$/.test(challenge.errorDescription)) throw new Error("Invalid OAuth error description");
-				parameters.push(`error_description="${challenge.errorDescription}"`);
-			}
-			if (challenge.scope !== void 0) {
-				if (!challenge.scope.split(" ").every((scope) => scopeToken.test(scope))) throw new Error("Invalid OAuth challenge scope");
-				parameters.push(`scope="${challenge.scope}"`);
-			}
-			return `Bearer ${parameters.join(", ")}`;
+			return `Bearer ${[
+				["resource_metadata", metadataUrl],
+				["error", challenge.error],
+				["error_description", challenge.errorDescription],
+				["scope", challenge.scope]
+			].flatMap(([name, value]) => value === void 0 ? [] : [`${name}=${quoted(value)}`]).join(", ")}`;
 		}
 	};
 };

package/dist/Testing.d.mts

@@ -1,14 +1,15 @@
-import { o as Actions } from "./implementation-DTqp_0DW.mjs";
-import { Client, ClientOptions, Http, t as ActionHttp_d_exports } from "./ActionHttp.mjs";
 import { Effect } from "effect";
+import { HttpApi, HttpApiClient, HttpApiGroup } from "effect/unstable/httpapi";
 //#region src/Testing.d.ts
 /** A web handler, such as `HttpRouter.toWebHandler(routes).handler`. */
 export type Handler = (request: Request) => Promise<Response>;
 /**
- * The typed HTTP client, calling `handler` in memory instead of the network.
+ * The native grouped HTTP client, calling `handler` in memory instead of the network.
  * `baseUrl` defaults to `http://localhost`.
  */
-export declare const httpClient: <G extends Actions>(http: Pick<Http<G>, "client">, handler: Handler, options?: ClientOptions) => Effect.Effect<Client<G>>;
+export declare const httpClient: <Id extends string, Groups extends HttpApiGroup.Constraint>(api: HttpApi.HttpApi<Id, Groups>, handler: Handler, options?: NonNullable<Parameters<typeof HttpApiClient.make>[1]>) => Effect.Effect<import("effect/Types").Simplify<{ readonly [Group in Extract<Groups, {
+  readonly topLevel: false;
+}> as HttpApiGroup.Identifier<Group>]: HttpApiClient.Client.GroupByEndpoint<Group, never, never>; } & HttpApiClient.Client.TopLevelMethods<Groups, never, never>>, never, Exclude<import("effect/unstable/httpapi/HttpApiMiddleware").MiddlewareClient<import("effect/unstable/httpapi/HttpApiEndpoint").Middleware<HttpApiGroup.Endpoints<Groups>>>, import("effect/unstable/http/HttpClient").HttpClient>>;
 /** A stateless 2026-07-28 request. */
 export interface McpRequestOptions {
   readonly url: string | URL;
@@ -23,11 +24,13 @@ export interface McpRequestOptions {
 export type McpRequestValue = string | number | boolean | null | undefined | ReadonlyArray<McpRequestValue> | {
   readonly [key: string]: McpRequestValue;
 };
+/** JSON-RPC `params`; `_meta` is merged shallowly over the defaults `mcpRequest` supplies. */
 export interface McpRequestParams {
   readonly _meta?: {
     readonly [key: string]: McpRequestValue;
   };
   readonly [key: string]: McpRequestValue;
 }
+/** Build one stateless 2026-07-28 JSON-RPC request, with client metadata defaulted. */
 export declare const mcpRequest: ({ url, method, params, headers: init }: McpRequestOptions) => Request;
 //#endregion

package/dist/Testing.mjs

@@ -1,14 +1,16 @@
 import { Effect, Layer, Predicate } from "effect";
+import { HttpApiClient } from "effect/unstable/httpapi";
 import { FetchHttpClient } from "effect/unstable/http";
 //#region src/Testing.ts
 /**
-* The typed HTTP client, calling `handler` in memory instead of the network.
+* The native grouped HTTP client, calling `handler` in memory instead of the network.
 * `baseUrl` defaults to `http://localhost`.
 */
-const httpClient = (http, handler, options) => http.client({
+const httpClient = (api, handler, options) => HttpApiClient.make(api, {
 	baseUrl: "http://localhost",
 	...options
 }).pipe(Effect.provide(FetchHttpClient.layer.pipe(Layer.provide(Layer.succeed(FetchHttpClient.Fetch, (input, init) => handler(new Request(input, init)))))));
+/** Build one stateless 2026-07-28 JSON-RPC request, with client metadata defaulted. */
 const mcpRequest = ({ url, method, params = {}, headers: init }) => {
 	const headers = new Headers(init);
 	headers.set("content-type", "application/json");

package/dist/TestingClient.d.mts

@@ -1,13 +1,16 @@
-import { Client } from "@modelcontextprotocol/client";
+import { Client, ClientOptions } from "@modelcontextprotocol/client";
 //#region src/TestingClient.d.ts
+/** How `withMcpClient` connects the official client. */
 export interface McpClientOptions {
   /** A web handler, such as `HttpRouter.toWebHandler(routes).handler`. */
   readonly fetch: (request: Request) => Promise<Response>;
   readonly path: string;
-  readonly mode?: "legacy" | "modern";
+  /** Passed directly to the official client; omitted options use its native default. */
+  readonly versionNegotiation?: ClientOptions["versionNegotiation"];
+  /** Defaults to `http://localhost`. */
   readonly baseUrl?: string | URL;
   readonly headers?: ConstructorParameters<typeof Headers>[0];
 }
 /** Connect an official client and always close its transport after the callback. */
-export declare const withMcpClient: <A>({ fetch, mode, path, baseUrl, headers }: McpClientOptions, run: (client: Client) => Promise<A>) => Promise<A>;
+export declare const withMcpClient: <A>({ fetch, path, baseUrl, headers, versionNegotiation }: McpClientOptions, run: (client: Client) => Promise<A>) => Promise<A>;
 //#endregion

package/dist/TestingClient.mjs

@@ -1,11 +1,11 @@
 import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
 //#region src/TestingClient.ts
 /** Connect an official client and always close its transport after the callback. */
-const withMcpClient = async ({ fetch, mode = "modern", path, baseUrl = "http://localhost", headers }, run) => {
+const withMcpClient = async ({ fetch, path, baseUrl = "http://localhost", headers, versionNegotiation }, run) => {
 	const client = new Client({
 		name: "test",
 		version: "0"
-	}, { versionNegotiation: { mode: mode === "modern" ? { pin: "2026-07-28" } : "legacy" } });
+	}, versionNegotiation === void 0 ? {} : { versionNegotiation });
 	try {
 		const transportOptions = { fetch: (input, init) => fetch(new Request(input, init)) };
 		if (headers !== void 0) transportOptions.requestInit = { headers };

package/dist/_virtual/_rolldown/runtime.mjs

@@ -0,0 +1,13 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+export { __exportAll };

package/dist/internal/actions.d.mts

@@ -0,0 +1,18 @@
+import { Action_d_exports, Any, Codec } from "../Action.mjs";
+import { HttpApiError } from "effect/unstable/httpapi";
+//#region src/internal/actions.d.ts
+/** Pure HTTP policy for native schema decoding and encoding failures. */
+export interface SchemaErrorPolicy<Errors extends ReadonlyArray<Codec>> {
+  readonly errors: Errors;
+  readonly map: (failure: HttpApiError.HttpApiSchemaError) => NoInfer<Errors[number]["Type"]>;
+}
+/** The contract half of a group: what adapters and clients need, without `implement`. */
+export interface Actions<Name extends string = string, A extends ReadonlyArray<Any> = ReadonlyArray<Any>, PolicyErrors extends ReadonlyArray<Codec> = ReadonlyArray<Codec>> {
+  readonly name: Name;
+  readonly actions: A;
+  /** How HTTP answers failed decoding or encoding; native behavior without one. MCP is unaffected. */
+  readonly schemaError: SchemaErrorPolicy<PolicyErrors> | undefined;
+}
+/** The errors a group's policy may answer with, by lookup rather than a conditional type. */
+export type PolicyError<G extends Actions> = NonNullable<G["schemaError"]>["errors"][number];
+//#endregion

package/dist/internal/actions.mjs

@@ -0,0 +1,16 @@
+//#region src/internal/actions.ts
+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}`);
+};
+/** 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();
+	for (const name of names) {
+		if (seen.has(name)) throw new Error(`Duplicate ${what}: ${name}`);
+		seen.add(name);
+	}
+};
+//#endregion
+export { assertDistinct, assertName };

package/dist/internal/cli.d.mts

@@ -0,0 +1,29 @@
+import "../Action.mjs";
+import { Effect, Schema } from "effect";
+import { Command } from "effect/unstable/cli";
+//#region src/internal/cli.d.ts
+/** Options shared by the local and HTTP command projections. */
+interface CommonOptions<Output> {
+  /** Override the command name. The action name is used by default. */
+  readonly name?: string;
+  /** Human output. JSON remains available with `--json`. */
+  readonly render?: (output: Output) => string;
+}
+/** The default projection accepts a whole canonical JSON input with `--input`. */
+export interface JsonOptions<Output> extends CommonOptions<Output> {
+  readonly parameters?: never;
+  readonly input?: never;
+}
+/** Supply native CLI parameters and map their parsed values to canonical action JSON. */
+export interface ParametersOptions<Output, Parameters extends Command.Command.Config> extends CommonOptions<Output> {
+  /** 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;
+}
+/**
+ * A command either accepts whole JSON input or has explicit native CLI parameters.
+ * The latter intentionally has no implicit `--input` mode.
+ */
+export type Options<Output, Parameters extends Command.Command.Config = never> = JsonOptions<Output> | ParametersOptions<Output, Parameters>;
+//#endregion

package/dist/internal/cli.mjs

@@ -0,0 +1,36 @@
+import { Console, Effect, Option, Schema } from "effect";
+import { Command, Flag } from "effect/unstable/cli";
+//#region src/internal/cli.ts
+const isParametersOptions = (options) => options?.parameters !== void 0;
+const jsonOutput = Flag.Boolean("json").pipe(Flag.optional, Flag.withDescription("Print machine-readable JSON"));
+const output = (action, execute, input, render, useJson) => Effect.gen(function* () {
+	const value = yield* execute(input);
+	const encoded = yield* Schema.encodeEffect(Schema.toCodecJson(action.success))(value);
+	const text = render !== void 0 && !useJson ? render(value) : JSON.stringify(encoded, null, 2);
+	yield* Console.log(text);
+});
+const defaultCommand = (action, execute, options) => {
+	const input = Flag.String("input").pipe(Flag.withDefault("{}"), Flag.withSchema(Schema.fromJsonString(Schema.toCodecJson(action.input))), Flag.withDescription("Whole canonical action input as JSON"));
+	const config = options?.render === void 0 ? { input } : {
+		input,
+		output: { json: jsonOutput }
+	};
+	return Command.make(options?.name ?? action.name, config, (parsed) => Effect.gen(function* () {
+		const useJson = "output" in parsed && Option.isSome(parsed.output.json) && parsed.output.json.value === true;
+		return yield* output(action, execute, parsed.input, options?.render, useJson);
+	})).pipe(Command.withDescription(action.description));
+};
+const parametersCommand = (action, execute, options) => {
+	if (options.render === void 0) return Command.make(options.name ?? action.name, options.parameters, (parsed) => Effect.flatMap(Schema.decodeUnknownEffect(Schema.toCodecJson(action.input))(options.input(parsed)), (input) => output(action, execute, input, void 0, true))).pipe(Command.withDescription(action.description));
+	return Command.make(options.name ?? action.name, {
+		parameters: options.parameters,
+		output: { json: jsonOutput }
+	}, (parsed) => Effect.flatMap(Schema.decodeUnknownEffect(Schema.toCodecJson(action.input))(options.input(parsed.parameters)), (input) => output(action, execute, input, options.render, Option.isSome(parsed.output.json) && parsed.output.json.value === true))).pipe(Command.withDescription(action.description));
+};
+/** Build one native command around an action-bound operation. */
+const command = (action, execute, options) => {
+	if (isParametersOptions(options)) return parametersCommand(action, execute, options);
+	return defaultCommand(action, execute, options);
+};
+//#endregion
+export { command };

package/dist/internal/implementation.d.mts

@@ -0,0 +1,39 @@
+import { Action_d_exports, Any } from "../Action.mjs";
+import { Actions } from "./actions.mjs";
+import { Effect, Scope } from "effect";
+//#region src/internal/implementation.d.ts
+/** Decoded values at the adapter dispatch boundary. */
+export type ErasedValue = Any["input"]["Type"];
+type ErasedHandler<R> = {
+  handle(input: ErasedValue): Effect.Effect<ErasedValue, ErasedValue, R>;
+}["handle"];
+/** An adapter's erased view of a record of handlers with request requirements `R`. */
+export type Handlers<R> = Readonly<Record<string, ErasedHandler<R>>>;
+/** Per-request requirements of the handler selected by an action name. */
+export type HandlerContext<H, Name extends keyof H> = H[Name] extends ((input: never) => Effect.Effect<infer _A, infer _E, infer R>) ? R : never;
+/** The union of per-request requirements declared by a handler record. */
+export type HandlersContext<H> = { readonly [K in keyof H]: HandlerContext<H, K>; }[keyof H];
+/**
+ * An acquired handler record for a group.
+ *
+ * The private field makes this class nominal: a structurally similar object,
+ * including one made by spreading an implementation, is not an implementation.
+ */
+export declare class Implementation<G extends Actions, H, EX, RX> {
+  #private;
+  /** The group whose exact handler record was built. */
+  readonly group: G;
+  private constructor();
+  /** Acquire the exact handler record in the adapter layer's scope. */
+  get build(): Effect.Effect<H, EX, RX | Scope.Scope>;
+  static make<G extends Actions, H, EX, RX>(group: G, build: Effect.Effect<H, EX, RX | Scope.Scope>): Implementation<G, H, EX, RX>;
+}
+/** Any nominal implementation of `G`, with its record and channels erased. */
+export type AnyImplementation<G extends Actions = Actions> = Implementation<G, any, any, any>;
+/** Per-request requirements of one implementation, or of a union of them. */
+export type RequestContext<App> = App extends Implementation<any, infer H, any, any> ? HandlersContext<H> : never;
+/** Handler-acquisition failures of one implementation, or of a union of them. */
+export type BuildError<App> = App extends Implementation<any, any, infer EX, any> ? EX : never;
+/** Handler-acquisition requirements of one implementation, or of a union of them. */
+export type BuildContext<App> = App extends Implementation<any, any, any, infer RX> ? RX : never;
+//#endregion

package/dist/internal/implementation.mjs

@@ -0,0 +1,37 @@
+import { Effect } from "effect";
+//#region src/internal/implementation.ts
+/**
+* An acquired handler record for a group.
+*
+* The private field makes this class nominal: a structurally similar object,
+* including one made by spreading an implementation, is not an implementation.
+*/
+var Implementation = class Implementation {
+	group;
+	#build;
+	constructor(group, build) {
+		this.group = group;
+		this.#build = build;
+	}
+	/** Acquire the exact handler record in the adapter layer's scope. */
+	get build() {
+		return this.#build;
+	}
+	static make(group, build) {
+		return new Implementation(group, build);
+	}
+};
+/**
+* Select and invoke a handler after an adapter has selected a concrete action.
+* `R` remains in the returned effect so transport layers cannot erase required
+* per-request services while assembling routes.
+*/
+const dispatch = (group, action, handlers) => {
+	const handle = handlers[action.name];
+	if (handle === void 0) throw new Error(`Missing handler: ${action.name}`);
+	return (input) => {
+		return Effect.withSpan(Effect.suspend(() => handle(input)), `${group.name}.${action.name}`, { captureStackTrace: false });
+	};
+};
+//#endregion
+export { Implementation, dispatch };

package/dist/internal/tools.mjs

@@ -0,0 +1,84 @@
+import { dispatch } from "./implementation.mjs";
+import { Effect, Schema } from "effect";
+import { Tool, Toolkit } from "effect/unstable/ai";
+//#region src/internal/tools.ts
+const isToolAction = (action) => action.mcp !== false;
+/** Only tool-enabled groups are acquired; each implementation appears once. */
+const toolApps = (apps) => apps.flatMap((app) => {
+	const actions = app.group.actions.filter(isToolAction);
+	return actions.length === 0 ? [] : [{
+		app,
+		actions
+	}];
+});
+/** Flatten the projected contracts only after deciding which groups are served. */
+const entries = (apps) => apps.flatMap(({ app, actions }) => actions.map((action) => ({
+	app,
+	action
+})));
+/** Fail before acquiring handlers when two exposed tools share a name. */
+const assertDistinctToolNames = (tools) => {
+	const names = /* @__PURE__ */ new Set();
+	for (const { action } of tools) {
+		const name = action.mcp.name;
+		if (names.has(name)) throw new Error(`Duplicate MCP tool: ${name}`);
+		names.add(name);
+	}
+};
+const annotate = (tool, mcp) => tool.annotate(Tool.Readonly, mcp.readOnly).annotate(Tool.Destructive, mcp.destructive).annotate(Tool.Idempotent, mcp.idempotent).annotate(Tool.OpenWorld, mcp.openWorld);
+/**
+* A native Effect AI tool. Its schemas retain action transforms and its result
+* is the action result itself, rather than an MCP response envelope.
+*/
+const nativeTool = (action) => annotate(Tool.make(action.mcp.name, {
+	description: action.description,
+	parameters: action.input,
+	success: action.success,
+	failure: Schema.Union(action.errors),
+	failureMode: "return"
+}), action.mcp);
+/**
+* MCP has a JSON-only wire contract. Success uses its documented `{ value }`
+* structured-content envelope; declared failures are returned as JSON text.
+*/
+const mcpTool = (action) => annotate(Tool.make(action.mcp.name, {
+	description: action.description,
+	parameters: Schema.toCodecJson(action.input),
+	success: Schema.toCodecJson(Schema.Struct({ value: action.success })),
+	failure: Schema.toCodecJson(Schema.Union(action.errors)),
+	failureMode: "return"
+}), action.mcp);
+/** MCP's input schema must describe a JSON object, including no-argument tools. */
+const assertMcpObjectInput = (action, tool) => {
+	const root = Tool.getJsonSchemaFromSchema(tool.parametersSchema);
+	if (root.$ref === void 0 && root.type !== "object") throw new Error(`${action.name}: MCP input must have an object root; omit input for no arguments`);
+};
+const project = (projection, entry) => {
+	const tool = projection === "native" ? nativeTool(entry.action) : mcpTool(entry.action);
+	if (projection === "mcp") assertMcpObjectInput(entry.action, tool);
+	return tool;
+};
+const handler = (projection, app, action, handlers) => {
+	const run = (input) => dispatch(app.group, action, handlers)(input);
+	return projection === "native" ? run : (input) => Effect.map(run(input), (value) => ({ value }));
+};
+/**
+* Project MCP-enabled actions and acquire their handlers exactly once per adapter layer.
+* Native and MCP differ only in tool codecs and the MCP success envelope; selection,
+* scoped acquisition, dispatch and native Toolkit binding stay identical.
+*/
+const bindTools = (apps, projection) => {
+	const served = toolApps(apps);
+	const selected = entries(served);
+	assertDistinctToolNames(selected);
+	const toolkit = Toolkit.make(...selected.map((entry) => project(projection, entry)));
+	return {
+		toolkit,
+		layer: toolkit.toLayer(Effect.map(Effect.forEach(served, ({ app, actions }) => Effect.map(app.build, (handlers) => {
+			const record = handlers;
+			return actions.map((action) => [action.mcp.name, handler(projection, app, action, record)]);
+		})), (built) => Object.fromEntries(built.flat())))
+	};
+};
+//#endregion
+export { bindTools };

package/docs/Action.md

@@ -0,0 +1,117 @@
+# Action
+
+One contract: a name, schemas for input, success and declared errors, and per-transport
+metadata. An action holds no behavior; handlers are bound by `ActionGroup.implement`.
+
+## API
+
+```ts
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+
+/** Any service-free schema. */
+type Codec = Schema.Codec<unknown, unknown, never, never>;
+
+function make<Name, Input = NoInput, Output, Errors = [], Http = true, Mcp = undefined>(
+  name: Name,
+  options: Options<Input, Output, Errors, Http, Mcp>,
+): Action<Name, Input, Output, Errors, Http, Mcp>;
+
+interface Options<Input, Output, Errors, Http, Mcp> {
+  readonly description: string;
+  readonly input?: Input; // omit for an action without arguments
+  readonly success: Output;
+  readonly errors?: Errors; // ReadonlyArray<Codec>; defaults to []
+  readonly http?: Http; // false hides the action from HTTP routes and clients
+  readonly mcp?: Mcp; // false hides the action from MCP; otherwise McpOptions
+}
+
+interface McpOptions {
+  readonly name?: string; // tool name; defaults to the action name; ^[A-Za-z0-9_-]{1,128}$
+  readonly readOnly?: boolean; // readOnlyHint, default false
+  readonly destructive?: boolean; // destructiveHint, default !readOnly
+  readonly idempotent?: boolean; // idempotentHint, default false
+  readonly openWorld?: boolean; // openWorldHint, default true
+}
+
+interface Action<Name, Input, Output, Errors, Http, Mcp> {
+  readonly name: Name;
+  readonly description: string;
+  readonly input: Input;
+  readonly success: Output;
+  readonly errors: Errors;
+  readonly http: Http;
+  readonly mcp: false | { name; readOnly; destructive; idempotent; openWorld }; // resolved
+}
+
+/** Receives decoded input; may fail only with the declared errors. */
+type Handler<A extends Any, R = never> = (
+  input: A["input"]["Type"],
+) => Effect.Effect<A["success"]["Type"], A["errors"][number]["Type"], R>;
+
+type Any; // any action with its schemas erased
+```
+
+## Canonical
+
+```ts
+import { Schema } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+
+export class UserNotFound extends Schema.TaggedError<UserNotFound>()(
+  "UserNotFound",
+  { id: Schema.String },
+  { httpApiStatus: 404 },
+) {}
+
+export const GetUser = Action.make("getUser", {
+  description: "Look up a user in your tenant.",
+  input: Schema.Struct({ id: Schema.String }),
+  success: Schema.Struct({ id: Schema.String, name: Schema.String }),
+  errors: [UserNotFound],
+  mcp: { name: "get_user", readOnly: true },
+});
+
+// No arguments: omit `input`. Identity comes from request context, never from input.
+export const WhoAmI = Action.make("whoAmI", {
+  description: "Inspect the authenticated actor.",
+  success: Schema.Struct({ id: Schema.String, tenantId: Schema.String }),
+  mcp: { readOnly: true },
+});
+
+// MCP-only: no HTTP route, no client method.
+export const ListChanges = Action.make("listChanges", {
+  description: "List renames in your tenant, oldest first.",
+  success: Schema.Struct({ changes: Schema.Array(Schema.String) }),
+  http: false,
+  mcp: { name: "list_changes", readOnly: true },
+});
+
+// Input decoding is the schema's: "21" on the wire, 21 in the handler.
+export const Double = Action.make("double", {
+  description: "Double a finite number supplied as a string.",
+  input: Schema.Struct({ value: Schema.FiniteFromString }),
+  success: Schema.Finite,
+  mcp: { readOnly: true },
+});
+```
+
+## Rules
+
+- Names match `[A-Za-z0-9_-]+`. `then` is rejected: it would make a client thenable.
+- Omit `input` for a no-argument action. The default is an empty object schema, which satisfies MCP's object-root requirement. Clients still pass `{ payload: {} }`.
+- `errors` is a list of schemas, default none. Each keeps its own `httpApiStatus` annotation; an unannotated error is served as HTTP 500. Group-level `errors` are appended to every action of the group (see [ActionGroup.md](ActionGroup.md)).
+- A handler may fail only with the declared errors. Anything else is a defect.
+- Both transports are on by default. `http: false` removes the route and the client method. `mcp: false` removes the tool. Both `false` makes a local-only action, reachable through `ActionCli` only.
+- MCP input must have an object-root JSON Schema. Scalar or array input is fine for HTTP, but `ActionMcp.layerHttp`, `ActionMcp.layerStdio`, and `ActionToolkit.make` throw when called with such an action. Success and error schemas may be any shape.
+- `mcp.name` is the tool name, at most 128 characters, unique within the group and within any Toolkit or MCP projection that serves the group. Default is the action name.
+- Hint defaults: `readOnly: false`, `destructive: !readOnly`, `idempotent: false`, `openWorld: true`. Hints are metadata for the model. They do not enforce authorization, approval, or retries.
+- Schemas must be service-free. Put service access in the handler.
+- The group name, not the action, is the OpenAPI tag and operation-ID prefix: `<group>.<action>`.
+- Object schemas strip excess fields on decode unless the schema is configured to reject them.
+
+## Failure modes
+
+- Throws at `make`: invalid name, name `then`, `mcp.name` longer than 128 characters or not matching the pattern.
+- Type error `Effect<..., X, ...> is not assignable` in `implement`: the handler fails with an undeclared error `X`. Add it to `errors` or handle it.
+- `<action>: MCP input must have an object root` thrown by `ActionMcp.layerHttp`, `ActionMcp.layerStdio`, or `ActionToolkit.make`: an MCP-enabled action has non-object input. Wrap it in `Schema.Struct` or set `mcp: false`.
+- Handler receives a string where a number was expected: the schema is `Schema.String`, not a transforming codec such as `Schema.FiniteFromString`.