@gjermundgaraba/effect-actions 0.1.0-rc.2 → 0.2.0

package/README.md

@@ -1,20 +1,10 @@
-# @gjermundgaraba/effect-actions
+# effect-actions
 
-Define an Effect action once, implement it once, and expose it through **HTTP, MCP, native Effect Toolkits, and CLIs**. Export an offline JSON catalog from the same contracts.
+Define an Effect action once. Serve it over HTTP and MCP, hand it to a model as a native
+Toolkit, run it from a CLI, and publish its contract as JSON. Same schemas, same handler,
+Effect's own servers and clients underneath.
 
-## Install
-
-```sh
-pnpm add @gjermundgaraba/effect-actions@rc effect@4.0.0-rc.116
-```
-
-For Node server wiring:
-
-```sh
-pnpm add @effect/platform-node@4.0.0-rc.116
-```
-
-## Quickstart
+## Looks like this
 
 ```ts
 import { McpProtocol } from "effect/unstable/ai";
@@ -48,297 +38,73 @@ export const routes = Layer.mergeAll(
 );
 ```
 
-Serve `routes` with Effect's `HttpRouter`. This creates `POST /api/actions/greetings/greet` and an
-MCP endpoint at `/mcp`. The HTTP response is `"Hello, Ada!"`; MCP returns
-`structuredContent: { value: "Hello, Ada!" }`; a declared error is an `isError` result
-whose text is the same JSON encoding HTTP sends as the body.
-See [examples/server.ts](examples/server.ts) for Node server wiring and the
-[authenticated demo](examples/README.md) for a runnable application.
-
-### Contracts
-
-- Omit `input` for an action without arguments.
-- `errors` is a list of failure schemas, defaulting to none. Each schema retains
-  its own `httpApiStatus` annotation.
-- A group's `errors` are added to every one of its actions, so a shared set, such as
-  authorization failures, is declared once. Its `schemaError` policy decides how HTTP
-  answers failed decoding or encoding; MCP keeps the native toolkit's answers. See
-  [schema-error policies](docs/behavior.md#schema-error-policies).
-- Actions default to both transports; use `http: false` or `mcp: false` to opt out.
-  Actions disabled on both remain available for explicitly mounted local CLI commands.
-- Action and group names match `[A-Za-z0-9_-]+` and are not `then`, which
-  would make a client thenable.
-- MCP input must have an object-root JSON Schema; the MCP adapter checks this at Layer
-  construction. HTTP allows scalar input. Results and errors may be any shape: MCP wraps
-  results as `{ value }` and reports errors as text, the protocol's own error channel.
-- `mcp.name` overrides the tool name (at most 128 characters). Tool hints default to
-  `readOnly: false`, `destructive: !readOnly`, `idempotent: false`, and `openWorld: true`.
-  Hints do not enforce authorization, approval, or retries.
-- Schemas must be service-free. Handlers may require services.
-- The group name is the OpenAPI tag and operation-ID prefix (`greetings.greet`).
-
-## HTTP client
-
-Save the quickstart above as `quickstart.ts`. Once its routes are served:
+Serve `routes` with Effect's `HttpRouter` and you have `POST /api/actions/greetings/greet`
+and an MCP tool named `greet` at `/mcp`. The same `app` is also:
 
 ```ts
-import { HttpApiClient } from "effect/unstable/httpapi";
-import { Effect } from "effect";
-import { FetchHttpClient } from "effect/unstable/http";
-import { Http } from "./quickstart.js";
-
-export const greeting = Effect.gen(function* () {
-  const client = yield* HttpApiClient.make(Http.api, { baseUrl: "http://127.0.0.1:3000" });
-
-  return yield* client.greetings.greet({ payload: { name: "Ada" } });
-}).pipe(Effect.provide(FetchHttpClient.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
 ```
 
-Run `greeting` with `Effect.runPromise`. Use Effect's native `HttpApiClient.make(Http.api,
-options)`: methods are grouped by action group and take explicit `{ payload: ... }`
-arguments, including `{ payload: {} }` for no-input actions. Inputs and results are
-decoded values; MCP-only actions are excluded. HTTP paths include the group: `<apiPath>/<group>/<action>`.
-Authentication headers can be added with `transformClient`. See
-[client details](docs/behavior.md#http-client-details) for error types and response modes.
-
-## Multiple groups
-
-An application can split its contracts and handlers into groups without splitting its
-endpoints. Configuration comes first, then the groups or implementations:
-
-```ts
-import { McpProtocol } from "effect/unstable/ai";
-
-const Http = ActionHttp.make({ apiPath: "/api/actions" }, PublicActions, UserActions);
-
-const routes = Layer.mergeAll(
-  Http.layer(PublicApp),
-  Http.layer(UserApp).pipe(Layer.provide(authentication.layer)),
-  ActionMcp.layerHttp(
-    { protocols: [McpProtocol.v2026_07_28], name: "my-app", version: "1.0.0", path: "/mcp" },
-    UserApp,
-    AuditApp,
-  ),
-);
-```
-
-- **Explicit mounting.** `Http.layer(...apps)` registers the routes of the supplied groups, and router
-  middleware provided to a layer applies to that layer alone: above, only the user group
-  requires authentication. Use separate calls when groups need different middleware. A group that is never mounted has no routes.
-- **Each adapter reads only what it serves.** A group without HTTP actions registers nothing
-  and is not built by `Http.layer`, nor one without tools by `ActionMcp.layerHttp`.
-- **Names.** Routes are `POST /api/actions/<group>/<action>`, and native client methods
-  are `client.<group>.<action>({ payload: ... })`. Group names must be unique within
-  `ActionHttp.make`; action names need only be unique within their group. Tool names
-  must be unique within each Toolkit or MCP projection. Adapters validate the
-  namespaces they serve, not another transport's names.
-- **MCP middleware is per endpoint.** An MCP endpoint is one route, so middleware provided
-  to `ActionMcp.layerHttp`, authentication included, covers all of its tools. Handlers can still
-  authorize each tool differently. Only tools that need different middleware, such as none
-  at all, need their own endpoint: one `ActionMcp.layerHttp` per `path`.
-
-Each group is its own native `HttpApiGroup`, so a host can also combine separately made
-`Http.api` values with `HttpApi.addHttpApi`. See [examples/app.ts](examples/app.ts).
-
-## Serving the document
-
-`Http.api` is a native `HttpApi`, carrying every route, description, declared error and
-policy error. Documents and documentation UIs are therefore Effect's own:
+And the client is Effect's own, typed from the same contract:
 
 ```ts
-import { HttpRouter, HttpServerResponse } from "effect/unstable/http";
-import { HttpApiScalar, HttpApiSwagger, OpenApi } from "effect/unstable/httpapi";
+const greeting = Effect.gen(function* () {
+  const client = yield* HttpApiClient.make(Http.api, { baseUrl });
 
-const documentation = Layer.mergeAll(
-  HttpRouter.add("GET", "/openapi.json", HttpServerResponse.jsonUnsafe(OpenApi.fromApi(Http.api))),
-  HttpApiSwagger.layer(Http.api, { path: "/docs" }),
-  HttpApiScalar.layer(Http.api, { path: "/reference" }),
-);
+  return yield* client.greetings.greet({ payload: { name: "Ada" } });
+});
 ```
 
-Each is an ordinary route layer, so it takes whatever middleware it is provided. The same
-value gives Effect's grouped client: `HttpApiClient.make(Http.api)`.
-
-## More projections
+## Why
 
-The same implementation can be used without an HTTP server:
+- 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. Shared failures such as `Forbidden` are declared once on the group.
+- 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.
+- 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.
+- Tests run in memory. Call the routes through a web handler with the same typed client, or drive the official MCP client, without opening a port.
 
-```ts
-import * as ActionToolkit from "@gjermundgaraba/effect-actions/ActionToolkit";
-import * as ActionCatalog from "@gjermundgaraba/effect-actions/ActionCatalog";
-import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
-import * as ActionCliClient from "@gjermundgaraba/effect-actions/ActionCliClient";
-import { Argument } from "effect/unstable/cli";
+## Install
 
-// Using Actions, Http, and app from the quickstart:
-const tools = ActionToolkit.make(app); // { toolkit, layer }, native Effect Toolkit
-const catalog = ActionCatalog.make(Actions); // JSON-serializable; no handlers acquired
-const command = ActionCli.group(app); // greetings greet --input '{"name":"Ada"}'
-const local = ActionCli.command(app, "greet", {
-  parameters: { name: Argument.String("name") },
-  input: ({ name }) => ({ name }),
-}); // greet Ada
-const remote = ActionCliClient.command(Http, "greetings", "greet"); // host supplies HttpClient
+```sh
+pnpm add @gjermundgaraba/effect-actions effect@4.0.0-rc.116
 ```
 
-- **Toolkit:** MCP-enabled actions become native tools with their declared names and
-  hints. Calls retain invocation-service requirements and return native results, not
-  MCP envelopes. See [examples/toolkit.ts](examples/toolkit.ts).
-- **MCP stdio:** `ActionMcp.layerStdio({ name, version, protocols }, ...apps)` runs a
-  subprocess server using a host-provided `Stdio` service and trusted process principal.
-  See [examples/mcp-stdio.ts](examples/mcp-stdio.ts). Stdout is protocol-only.
-- **Catalog:** standalone input/output/error JSON schemas with local `$defs`, plus
-  metadata and group-qualified identities. See [examples/catalog.ts](examples/catalog.ts).
-- **Local CLI:** `.command(app, "actionName", options?)` selects one action; `.group(app,
-options?)` selects a group, including local-only actions. The host supplies services.
-- **Remote CLI:** `ActionCliClient` projects HTTP contracts into commands using native
-  `HttpApiClient`; it never executes local handlers or manages credentials. See
-  [examples/cli.ts](examples/cli.ts) and [examples/cli-client.ts](examples/cli-client.ts).
-
-Generated CLI commands accept whole-input `--input '<json>'`. For a human-oriented
-command, supply native Effect flags/arguments through `parameters` and map them to
-encoded action input with `input`. Explicitly configured commands do not also accept
-`--input`; their syntax is independent of schema changes. Commands print validated
-JSON by default; an optional renderer enables human output with `--json` available.
-See [CLI boundaries](docs/behavior.md#cli-boundaries) for codecs and configuration.
-
-## Adapter options
-
-| API                                    | Options                                                                  |
-| -------------------------------------- | ------------------------------------------------------------------------ |
-| `ActionGroup.make(options, …actions)`  | `name`, `errors`, `schemaError`                                          |
-| `ActionHttp.make(options, …groups)`    | `apiPath`                                                                |
-| `Http.layer(...apps)`                  | None                                                                     |
-| `ActionMcp.layerHttp(options, …apps)`  | `name`, `version`, `path`, `protocols`, `allowedOrigins`, `instructions` |
-| `ActionMcp.layerStdio(options, …apps)` | `name`, `version`, `protocols`, `instructions`                           |
+Add `@effect/platform-node@4.0.0-rc.116` 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.
 
-`apiPath` and MCP `path` have no defaults. `Http` has two members: `api` and `layer`. MCP `protocols` is required and takes Effect’s native `McpProtocol` adapters.
-Effect owns protocol negotiation and sessions.
+## Docs
 
-See [adapter behavior](docs/behavior.md) for shared schema-error policies,
-dependency lifetimes, wire formats, and MCP protocol support.
+The reference in [docs/](docs/README.md) is written for coding agents: one card per module
+with the API, a canonical snippet, the rules, and the failure modes.
 
-## Scope
+- [docs/README.md](docs/README.md): start here, includes the adapter decision list.
+- [docs/guarantees.md](docs/guarantees.md): cross-cutting rules for lifetimes, wire formats, and scope.
+- [docs/CONTEXT.md](docs/CONTEXT.md): the vocabulary the docs and the code use.
+- [examples/](examples/README.md): a runnable authenticated application with three groups, two MCP endpoints, OpenAPI, and every other projection.
 
-HTTP means JSON POST endpoints, not Effect's RPC wire protocol. HTTP and MCP use
-Effect's servers: `HttpApi` and one `McpServer` `Tool` per action; there is no MCP SDK
-runtime dependency. Actions are unary:
-no streaming, uploads, prompts, resources, retries, or code-execution sandbox.
-
-Authentication and authorization belong to the application. Tool discovery is
-not filtered by actor. The example's bearer tokens are **demo-only**; production
-needs real token validation, MCP authorization discovery, request limits, and
-error reporting.
-
-## Development and packaging
-
-Requires a supported Node.js version (24 LTS recommended) and [Vite+](https://viteplus.dev).
+## For agents
 
 ```sh
-vp install
-vp check
-vp test
-vp run test:package
-vp run example
+npx skills add gjermundgaraba/effect-actions --skill effect-actions
 ```
 
-`vp run dev` watches the library build. `vp check` also verifies the compile-time
-assertions in `tests/types.spec.ts`. Tests cover both transports, official MCP clients,
-request-context handling, schema-error policies, and cancellation.
-
-`vp run build` emits module-preserving ESM and declarations into `dist/`. The entry points
-are one subpath per module: `/Action`, `/ActionGroup`, `/ActionHttp`, `/ActionMcp`,
-`/ActionToolkit`, `/ActionCatalog`, `/ActionCli`, `/ActionCliClient`, `/Authentication`,
-`/Testing`, and `/TestingClient`. There is no package root, so a contracts-only or browser bundle never
-loads the MCP server or the optional client peer.
-`vp run test:package` builds and checks a tarball in an isolated consumer with
-`skipLibCheck: false`.
+The skill is generated from `docs/`, so pointing an agent at `docs/` (in this repository or
+in `node_modules/@gjermundgaraba/effect-actions/docs`) gives the same content.
 
-## Authentication and OAuth discovery
+## Status
 
-`Authentication.middleware(CurrentActor, authenticate)` provides an application-defined
-context service for each request. `authenticate` is an Effect that succeeds with the
-identity or fails with the `HttpServerResponse` to send instead, so the host owns the
-status, body and any Bearer challenge: `HttpServerResponse.schemaJson(Unauthenticated)(error,
-{ status: 401, headers })`. Responses use `Cache-Control: no-store`, including failures handled
-by enclosing middleware. Provide the returned middleware's `.layer` to HTTP and MCP route
-layers. See [examples/app.ts](examples/app.ts).
+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.
+Authentication and authorization belong to the application. See [docs/setup.md](docs/setup.md).
 
-Use distinct service tags for startup capabilities and request identities. Never supply
-`CurrentActor` or other request-identity tags through startup layers or root context:
-native Effect context capture can shadow request values or supply missing runtime values.
-The adapters do not provide an additional context-isolation boundary.
+## Acknowledgements
 
-Authentication dependencies are request requirements, as with native `HttpRouter.middleware`.
-Use `.combine(...)` with middleware that provides them. Acquired resources stay alive
-until the request scope closes. Downstream action errors are handled by their transport,
-not serialized as authentication failures.
-
-`Authentication.protectedResource({ resource, authorizationServers, scopesSupported })`
-returns `{ layer, metadataUrl, challenge }`. Mount its public `layer` separately from
-protected routes. It publishes [RFC 9728 metadata](https://www.rfc-editor.org/rfc/rfc9728.html)
-at `/.well-known/oauth-protected-resource` followed by the resource path and query. Discovery
-matches that literal path and query for GET and HEAD; other requests reach the host router.
-Caching policy belongs to the host. `challenge()`
-returns the `WWW-Authenticate` value; pass `{ error: "invalid_token" }` or
-`{ error: "insufficient_scope", scope: "admin" }` where appropriate. Parameter values are
-quoted and escaped, never rejected. Supported scopes are advertised in metadata; the
-challenge names only scopes needed for that request. The helper publishes what it is given:
-your deployment is responsible for these being valid OAuth URLs (HTTPS, or loopback HTTP in
-development), and your application owns login, consent, and token verification.
-
-```ts
-const discovery = Authentication.protectedResource({
-  resource: "https://api.example.com/mcp",
-  authorizationServers: ["https://auth.example.com"],
-});
+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.
 
-// The response sent when authentication fails; the host owns status, body and challenge.
-const unauthenticated = HttpServerResponse.schemaJson(Unauthenticated)(
-  new Unauthenticated({ message: "A bearer token is required." }),
-  { status: 401, headers: { "www-authenticate": discovery.challenge({ error: "invalid_token" }) } },
-).pipe(Effect.orDie);
-
-const authentication = Authentication.middleware(
-  CurrentActor,
-  Effect.gen(function* () {
-    const actor = yield* verifyToken; // Effect<Option<Actor>, never, HttpServerRequest>
-
-    return Option.isNone(actor) ? yield* Effect.flip(unauthenticated) : actor.value;
-  }),
-);
-
-const routes = Layer.mergeAll(
-  discovery.layer,
-  protectedRoutes.pipe(Layer.provide(authentication.layer)),
-);
-```
-
-## Testing
-
-Import from `@gjermundgaraba/effect-actions/Testing`; it requires no MCP client dependency.
-`withMcpClient` lives in `@gjermundgaraba/effect-actions/TestingClient` and needs the optional
-peer `@modelcontextprotocol/client@^2.0.0`. Only that entry point loads the peer.
-
-```ts
-const web = HttpRouter.toWebHandler(routes.pipe(Layer.provide(HttpServer.layerServices)));
-
-const greeting = Effect.gen(function* () {
-  const client = yield* httpClient(Http.api, web.handler);
-
-  return yield* client.greetings.greet({ payload: { name: "Ada" } });
-});
-```
+## Contributing
 
-- `httpClient(Http.api, handler, options?)` is the native grouped HTTP client calling a web handler in
-  memory. `options` are the client's connection options; `baseUrl` defaults to `http://localhost`.
-- `mcpRequest({ url, method, params?, headers? })` builds a stateless 2026-07-28 request.
-  `params` takes whatever `JSON.stringify` accepts, `undefined` fields included, so tests can
-  send malformed arguments.
-  Caller `params._meta` fields override the default client capabilities
-  and information; application metadata is preserved. The protocol version stays pinned to
-  2026-07-28 in both the request header and metadata. Metadata is merged shallowly.
-- `withMcpClient({ fetch, path, versionNegotiation?, baseUrl?, headers? }, async client => ...)`
-  connects the official client and closes it in a `finally` block.
-  `versionNegotiation` is passed directly to the official client (whose default is legacy).
-  For a stateless endpoint, pass `versionNegotiation: { mode: { pin: "2026-07-28" } }`.
+See [CONTRIBUTING.md](CONTRIBUTING.md). MIT licensed.

package/dist/ActionHttp.mjs

@@ -7,23 +7,35 @@ const httpActions = (group) => group.actions.filter((action) => action.http);
 const endpoint = (apiPath, group, action) => HttpApiEndpoint.post(action.name, `${apiPath}/${group.name}/${action.name}`, {
 	payload: action.input,
 	success: action.success,
-	error: [...action.errors, ...group.schemaError?.errors ?? []]
+	error: action.errors
 }).annotate(OpenApi.Description, action.description);
-function erasedApi(groups, options) {
-	const [first, ...rest] = groups.flatMap((group) => {
-		const [first, ...rest] = httpActions(group).map((action) => endpoint(options.apiPath, group, action));
-		return first === void 0 ? [] : [HttpApiGroup.make(group.name).add(first, ...rest)];
-	});
-	const empty = HttpApi.make("actions");
-	return first === void 0 ? empty : empty.add(first, ...rest);
-}
-const schemaErrorMiddleware = (policy) => {
-	class SchemaErrors extends HttpApiMiddleware.Service()("effect-actions/http/SchemaErrors", { error: policy.errors }) {}
+/** 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 }) {}
 	return {
 		SchemaErrors,
 		layer: HttpApiMiddleware.layerSchemaErrorTransform(SchemaErrors, (failure) => Effect.fail(policy.map(failure)))
 	};
 };
+function bind(options, group) {
+	const [first, ...rest] = httpActions(group).map((action) => endpoint(options.apiPath, group, action));
+	if (first === void 0) return void 0;
+	const native = HttpApiGroup.make(group.name).add(first, ...rest);
+	if (group.schemaError === void 0) return {
+		native,
+		policy: Layer.empty
+	};
+	const policy = schemaErrorMiddleware(group.name, group.schemaError);
+	return {
+		native: native.middleware(policy.SchemaErrors),
+		policy: policy.layer
+	};
+}
+function apiOf(groups) {
+	const [first, ...rest] = groups;
+	const empty = HttpApi.make("actions").annotate(HttpApi.ParseOptions, { errors: "all" });
+	return first === void 0 ? empty : empty.add(first, ...rest);
+}
 /**
 * `HttpApiBuilder.handleAll` registers a dynamically assembled record. The
 * action selected by the native router determines the input before `dispatch`
@@ -34,32 +46,33 @@ const schemaErrorMiddleware = (policy) => {
 const erasedHandlers = (handlers) => {
 	return handlers;
 };
-/** Build routes for one group. Handler erasure is limited to native dynamic endpoint registration. */
-const groupLayer = (options, app) => {
-	const actions = httpActions(app.group);
-	if (actions.length === 0) return Layer.empty;
-	const api = erasedApi([app.group], options);
-	const entries = (record) => Object.fromEntries(actions.map((action) => [action.name, (request) => dispatch(app.group, action, record)(request.payload)]));
-	const handlers = (record) => HttpApiBuilder.group(api, app.group.name, (builder) => builder.handleAll(entries(record)));
-	if (app.group.schemaError === void 0) return Layer.unwrap(Effect.map(app.build, (record) => HttpApiBuilder.layer(api).pipe(Layer.provide(handlers(erasedHandlers(record))))));
-	const schemaErrors = schemaErrorMiddleware(app.group.schemaError);
-	const policyApi = api.middleware(schemaErrors.SchemaErrors);
-	const policyHandlers = (record) => HttpApiBuilder.group(policyApi, app.group.name, (builder) => {
-		const dynamicEntries = entries(record);
-		return builder.handleAll(dynamicEntries);
-	});
-	return Layer.unwrap(Effect.map(app.build, (record) => HttpApiBuilder.layer(policyApi).pipe(Layer.provide(policyHandlers(erasedHandlers(record))), Layer.provide(schemaErrors.layer))));
+/** Register one group's handlers. Handler erasure is limited to native dynamic endpoint registration. */
+const groupHandlers = (api, app, policy) => {
+	const entries = (record) => Object.fromEntries(httpActions(app.group).map((action) => [action.name, (request) => dispatch(app.group, action, record)(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(policy));
 };
 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 = (...apps) => {
 		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`);
-		return apps.map((app) => groupLayer(options, app)).reduce((all, app) => Layer.merge(all, app), Layer.empty);
+		const served = apps.flatMap((app) => {
+			const binding = bound.get(app.group);
+			return binding === void 0 ? [] : [{
+				app,
+				...binding
+			}];
+		});
+		const api = apiOf(served.map(({ native }) => native));
+		return served.reduce((layer, { app, policy }) => layer.pipe(Layer.provide(groupHandlers(api, app, policy))), HttpApiBuilder.layer(api));
 	};
 	return {
 		groups,
-		api: erasedApi(groups, options),
+		api: apiOf([...bound.values()].map(({ native }) => native)),
 		layer
 	};
 }

package/dist/ActionMcp.d.mts

@@ -1,6 +1,6 @@
 import { AnyImplementation, BuildContext, BuildError, RequestContext } from "./internal/implementation.mjs";
 import { Cause, Layer } from "effect";
-import { McpServer } from "effect/unstable/ai";
+import { McpSchema, McpServer } from "effect/unstable/ai";
 import { HttpRouter } from "effect/unstable/http";
 import { Stdio } from "effect/Stdio";
 //#region src/ActionMcp.d.ts
@@ -24,18 +24,20 @@ export interface StdioOptions {
   readonly protocols: Parameters<typeof McpServer.layerStdio>[0]["protocols"];
   readonly instructions?: string;
 }
+/** The native server supplies its own request context to every tool call. */
+type ToolRequestContext<App> = Exclude<RequestContext<App>, 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>>(options: Options, ...apps: Apps): Layer.Layer<never, BuildError<Apps[number]> | Cause.IllegalArgumentError, BuildContext<Apps[number]> | HttpRouter.HttpRouter | HttpRouter.Request.From<"Requires", RequestContext<Apps[number]>>>;
+export declare function layerHttp<const Apps extends ReadonlyArray<AnyImplementation>>(options: Options, ...apps: Apps): Layer.Layer<never, BuildError<Apps[number]> | Cause.IllegalArgumentError, BuildContext<Apps[number]> | HttpRouter.HttpRouter | HttpRouter.Request.From<"Requires", ToolRequestContext<Apps[number]>>>;
 /**
  * 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>>(options: StdioOptions, ...apps: Apps): Layer.Layer<never, BuildError<Apps[number]> | Cause.IllegalArgumentError, BuildContext<Apps[number]> | Stdio | RequestContext<Apps[number]>>;
+export declare function layerStdio<const Apps extends ReadonlyArray<AnyImplementation>>(options: StdioOptions, ...apps: Apps): Layer.Layer<never, BuildError<Apps[number]> | Cause.IllegalArgumentError, BuildContext<Apps[number]> | Stdio | ToolRequestContext<Apps[number]>>;
 //#endregion

package/dist/internal/tools.mjs

@@ -55,8 +55,9 @@ const assertMcpObjectInput = (action, tool) => {
 };
 const project = (projection, entry) => {
 	const tool = projection === "native" ? nativeTool(entry.action) : mcpTool(entry.action);
-	if (projection === "mcp") assertMcpObjectInput(entry.action, tool);
-	return tool;
+	if (projection === "native") return tool;
+	assertMcpObjectInput(entry.action, tool);
+	return tool.annotate(Tool.Strict, true);
 };
 const handler = (projection, app, action, handlers) => {
 	const run = (input) => dispatch(app.group, action, handlers)(input);

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>`.
+- HTTP strips undeclared input fields. MCP tools are strict (`Tool.Strict`): undeclared arguments are an invalid-arguments result and input schemas publish `additionalProperties: false`. HTTP cannot be strict natively: `HttpApi.ParseOptions` also governs error encoding, where `onExcessProperty: "error"` rejects an error's own `stack`.
+
+## 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`.