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

package/docs/ActionCatalog.md

@@ -0,0 +1,56 @@
+# ActionCatalog
+
+An offline JSON document describing groups: identities, metadata, and standalone JSON
+schemas. Built from contracts alone. No implementation, service, or server is involved.
+
+## API
+
+```ts
+import * as ActionCatalog from "@gjermundgaraba/effect-actions/ActionCatalog";
+
+const make: (...groups: ReadonlyArray<ActionGroup.Any>) => Catalog;
+
+interface Catalog {
+  readonly version: "1";
+  readonly actions: ReadonlyArray<Entry>;
+}
+
+interface Entry {
+  readonly id: string; // "<group>.<action>"
+  readonly group: string;
+  readonly name: string;
+  readonly description: string;
+  readonly http: boolean;
+  readonly mcp: false | { name; readOnly; destructive; idempotent; openWorld };
+  readonly input: JsonSchema.JsonSchema;
+  readonly success: JsonSchema.JsonSchema;
+  readonly errors: ReadonlyArray<JsonSchema.JsonSchema>; // own + inherited group errors
+  readonly httpSchemaErrors: ReadonlyArray<JsonSchema.JsonSchema>; // policy errors, HTTP only
+}
+```
+
+## Canonical
+
+```ts
+import * as ActionCatalog from "@gjermundgaraba/effect-actions/ActionCatalog";
+import { AuditActions, PublicActions, UserActions } from "./contracts.js";
+
+const catalog = ActionCatalog.make(PublicActions, UserActions, AuditActions);
+
+process.stdout.write(JSON.stringify(catalog, null, 2));
+```
+
+## Rules
+
+- Takes groups, not implementations. Nothing is acquired or started.
+- `id` is the stable `<group>.<action>` identity, equal to the HTTP operation ID.
+- Schemas describe encoded action values: the JSON on the wire, not MCP's `{ value }` envelope and not deployment URLs.
+- Each schema owns its `$defs`. Equal schema identifiers in different entries never replace each other. Recursive references stay local to their schema.
+- `errors` includes group-level errors. HTTP schema-policy errors are listed separately in `httpSchemaErrors`.
+- Local-only actions (`http: false`, `mcp: false`) are included. Presence in a catalog is descriptive. It is not authorization, tool publication, or proof that a route is mounted. The host decides what to publish.
+- The package adds no search, no catalog HTTP endpoint, and no TypeScript code generation.
+
+## Failure modes
+
+- Type error passing an implementation: `make` takes groups. Pass `app.group` or the group value itself.
+- Consumers see `{ value }` in MCP responses but not in the catalog: expected. The catalog describes action values; MCP wraps them.

package/docs/ActionCli.md

@@ -0,0 +1,91 @@
+# ActionCli
+
+Native Effect CLI commands that run handlers in-process. The host provides every service;
+nothing is fetched over HTTP.
+
+## API
+
+```ts
+import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
+
+/** One explicitly selected action. */
+const command: <G, Name extends G["actions"][number]["name"], H, EX, RX, Parameters = never>(
+  app: Implementation<G, H, EX, RX>,
+  name: Name,
+  options?: Options<SuccessType, Parameters>,
+) => Command.Command<string, never, {}, EX | SchemaError | DeclaredErrors, Exclude<RX | HandlerContext, Scope>>;
+
+/** Every action of the group, including local-only ones, under the group name. */
+const group: <G, H, EX, RX>(
+  app: Implementation<G, H, EX, RX>,
+  options?: GroupOptions,
+) => Command.Command<string, {}, {}, EX | SchemaError | DeclaredErrors, ...>;
+
+interface GroupOptions {
+  readonly name?: string; // override the group command name
+}
+
+type Options<Output, Parameters extends Command.Command.Config = never> =
+  | JsonOptions<Output>
+  | ParametersOptions<Output, Parameters>;
+
+interface JsonOptions<Output> {
+  readonly name?: string; // override the command name; default is the action name
+  readonly render?: (output: Output) => string; // human output; --json still prints JSON
+}
+
+interface ParametersOptions<Output, Parameters> {
+  readonly name?: string;
+  readonly render?: (output: Output) => string;
+  readonly parameters: Parameters; // native Effect Flag / Argument config
+  readonly input: (parsed: Command.Command.Config.Infer<Parameters>) => Schema.Json; // encoded action input
+}
+```
+
+## Canonical
+
+```ts
+import { Console, Effect, Logger } from "effect";
+import { Command, Flag } from "effect/unstable/cli";
+import { NodeRuntime, NodeServices } from "@effect/platform-node";
+import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
+import { UserApp } from "./handlers.js";
+import { Users } from "./users.js";
+
+// Explicit syntax: `double --value 21`. No `--input` on this command.
+const command = ActionCli.command(UserApp, "double", {
+  parameters: { value: Flag.String("value") },
+  input: ({ value }) => ({ value }),
+});
+
+// Default syntax for a whole group: `users double --input '{"value":"21"}'`.
+const all = ActionCli.group(UserApp);
+
+Command.runWith(command, { version: "0.1.0" })(process.argv.slice(2)).pipe(
+  Effect.tapCause((cause) => Console.error(cause)),
+  Effect.provideService(Logger.LogToStderr, true),
+  Effect.provide(Users.layerMemory),
+  Effect.provide(NodeServices.layer),
+  NodeRuntime.runMain({ disableErrorReporting: true }),
+);
+```
+
+## Rules
+
+- `command(app, name)` selects one action by name from the bound group; the name is checked at the type level. `group(app)` puts every action under the group command, including actions with `http: false` and `mcp: false`.
+- Default syntax is `--input '<json>'` carrying the entire encoded input: nested objects, arrays, scalars. Omitting `--input` supplies `{}`, which must still satisfy the input schema.
+- `parameters` and `input` are supplied together or not at all. With them, the command has explicit native flags and arguments and no `--input`, so its syntax does not change when the schema changes.
+- `input(parsed)` returns encoded JSON. The action schema decodes it before dispatch; a mismatch is a `SchemaError` at runtime. Action fields are never turned into flags automatically.
+- Native `Flag` and `Argument` own names, aliases, ordering, defaults, and optionality. Use `Flag.optional` when omission must stay distinct from a default, and map the `Option` to a present or omitted field.
+- Output is validated and encoded before printing. Default output is JSON. `render(decoded)` gives human output; `--json` selects JSON again. Rendering cannot bypass validation.
+- Explicit flag names must not collide with the renderer's `--json` flag. A payload field named `json` is ordinary data; only the flag name is reserved.
+- Each invocation acquires the implementation in a scope and releases it after the call. Domain services and authority come from the host's provided layers. There is no HTTP fallback.
+- Group commands use the default JSON syntax. For a custom tree, compose individual `command` results with native `Command` combinators.
+
+## Failure modes
+
+- `SchemaError` on a valid-looking `--input`: the JSON is decoded input, so transforming codecs expect the encoded form (`"21"` for `FiniteFromString`, not `21`).
+- Command rejects `--input`: the command was built with `parameters`. Use its flags.
+- Type error: `name` is not an action of the group. Check `group.actions` names, not MCP tool names.
+- Handler cannot find a service: provide its Layer to the runtime (`Effect.provide`) before `runMain`. The command does not supply services.
+- `--json` flag conflict at definition: rename the native flag; the config property can keep its name.

package/docs/ActionCliClient.md

@@ -0,0 +1,77 @@
+# ActionCliClient
+
+Native Effect CLI commands that call the HTTP API through Effect's `HttpApiClient`. Runs no
+handler locally and manages no credentials.
+
+## API
+
+```ts
+import * as ActionCliClient from "@gjermundgaraba/effect-actions/ActionCliClient";
+
+/** One HTTP-enabled action retained by the binding. */
+const command: <const Groups, const GroupName, const ActionName, Parameters = never>(
+  http: Http<Groups>,
+  groupName: GroupName,
+  actionName: ActionName, // only actions with http: true
+  options?: Options<SuccessType, Parameters>,
+) => Command.Command<string, never, {}, ClientErrors, HttpClient.HttpClient | ClientServices>;
+
+/** Every HTTP-enabled action of one group under the group name. */
+const group: <const Groups, const GroupName>(
+  http: Http<Groups>,
+  groupName: GroupName,
+  options?: GroupOptions,
+) => Command.Command<string, {}, {}, ClientErrors, HttpClient.HttpClient | ClientServices>;
+
+type Options<Output, Parameters> = ActionCli.Options<Output, Parameters> & {
+  /** Passed directly to HttpApiClient.make: baseUrl, transformClient, transformResponse. */
+  readonly connection?: Parameters<typeof HttpApiClient.make>[1];
+};
+
+interface GroupOptions {
+  readonly name?: string;
+  readonly connection?: Parameters<typeof HttpApiClient.make>[1]; // shared by every action
+}
+```
+
+Parsing and rendering options (`name`, `render`, `parameters`, `input`) are the same as
+[ActionCli.md](ActionCli.md).
+
+## Canonical
+
+```ts
+import { Command } from "effect/unstable/cli";
+import { Console, Effect, Logger } from "effect";
+import { NodeHttpClient, NodeRuntime, NodeServices } from "@effect/platform-node";
+import * as ActionCliClient from "@gjermundgaraba/effect-actions/ActionCliClient";
+import { Http } from "./contracts.js";
+
+const command = ActionCliClient.command(Http, "public", "status", {
+  connection: { baseUrl: "http://127.0.0.1:3000" },
+});
+
+Command.runWith(command, { version: "0.1.0" })(process.argv.slice(2)).pipe(
+  Effect.tapCause((cause) => Console.error(cause)),
+  Effect.provideService(Logger.LogToStderr, true),
+  Effect.provide(NodeHttpClient.layerUndici), // the host supplies HttpClient
+  Effect.provide(NodeServices.layer),
+  NodeRuntime.runMain({ disableErrorReporting: true }),
+);
+```
+
+Authentication: `connection: { transformClient: HttpClient.mapRequest(HttpClientRequest.bearerToken(token)) }`.
+
+## Rules
+
+- Selectors resolve from `http.groups` only. `groupName` must be a bound group; `actionName` must be an action of that group with `http: true`. Runtime guards reject dynamically supplied strings that the types would not accept.
+- The host provides `HttpClient` and its configuration. Endpoint selection, credentials, and storage are the host's; nothing is inferred from action arguments.
+- Input is decoded by the action schema before dispatch, then passed to the native client at its normal codec boundary. Do not pre-encode values.
+- Output is validated and printed as JSON, or through `render` with `--json` available, exactly as in `ActionCli`.
+- Errors are the client's: declared errors, policy errors, `SchemaError`, and `HttpClientError`.
+
+## Failure modes
+
+- Type error on `actionName`: the action is `http: false`, or the group is not bound in this `Http`.
+- `HttpClient` missing at runtime: provide `NodeHttpClient.layerUndici` (or `FetchHttpClient.layer`) to the runtime.
+- Connection refused: `connection.baseUrl` is absent or wrong. It has no default.
+- 401 from the server: add `transformClient` to `connection`. The command adds no headers on its own.

package/docs/ActionGroup.md

@@ -0,0 +1,141 @@
+# ActionGroup
+
+A named set of actions. The group is what adapters serve, what clients are grouped by, and
+what `implement` binds handlers to. Shared errors and the HTTP schema-error policy live here.
+
+## API
+
+```ts
+import * as ActionGroup from "@gjermundgaraba/effect-actions/ActionGroup";
+
+function make<Name, Actions, Errors = [], PolicyErrors = []>(
+  options: Options<Name, Errors, PolicyErrors>,
+  ...actions: Actions
+): Group<Name, WithErrors<Actions, Errors>, PolicyErrors>;
+
+interface Options<Name, Errors, PolicyErrors> {
+  readonly name: Name; // HttpApiGroup identifier, OpenAPI tag, operation-ID prefix
+  readonly errors?: Errors; // added to every action's own errors
+  readonly schemaError?: SchemaErrorPolicy<PolicyErrors>; // HTTP only; MCP keeps native answers
+}
+
+interface SchemaErrorPolicy<Errors extends ReadonlyArray<Codec>> {
+  readonly errors: Errors;
+  readonly map: (failure: HttpApiError.HttpApiSchemaError) => Errors[number]["Type"];
+}
+
+interface Group<Name, Actions, PolicyErrors> {
+  readonly name: Name;
+  readonly actions: Actions;
+  readonly schemaError: SchemaErrorPolicy<PolicyErrors> | undefined;
+  /** Bind every handler at once; build-time services resolve once per adapter layer. */
+  readonly implement: <H extends HandlersFrom<Actions>, EX = never, RX = never>(
+    build: H | Effect.Effect<H, EX, RX>,
+  ) => Implementation<Group<Name, Actions, PolicyErrors>, H, EX, Exclude<RX, Scope.Scope>>;
+}
+
+/** Nominal. `group` is the bound contract; `build` acquires the handler record in a scope. */
+class Implementation<G, H, EX, RX> {
+  readonly group: G;
+  get build(): Effect.Effect<H, EX, RX | Scope.Scope>;
+}
+```
+
+`HandlersFrom<Actions>` is `{ [action name]: Handler<Action, R> }`, one key per action,
+all required.
+
+## Canonical
+
+```ts
+import { Effect, Schema } from "effect";
+import type { HttpApiError } from "effect/unstable/httpapi";
+import * as ActionGroup from "@gjermundgaraba/effect-actions/ActionGroup";
+import { Forbidden, authorize, CurrentActor } from "./auth.js";
+import { GetUser, RenameUser, WhoAmI } from "./contracts.js";
+import { Users } from "./users.js";
+
+class InvalidRequest extends Schema.TaggedError<InvalidRequest>()(
+  "InvalidRequest",
+  { message: Schema.String },
+  { httpApiStatus: 400 },
+) {}
+class InternalError extends Schema.TaggedError<InternalError>()(
+  "InternalError",
+  { message: Schema.String },
+  { httpApiStatus: 500 },
+) {}
+
+// Shared across groups: annotate the parameter. Inline, `map` is inferred from `errors`.
+const schemaError = {
+  errors: [InvalidRequest, InternalError],
+  map: ({ kind }: HttpApiError.HttpApiSchemaError) =>
+    kind === "Body" || kind === "ResponseHeaders"
+      ? new InternalError({ message: "The request could not be completed." })
+      : new InvalidRequest({ message: "The request does not match the action's input." }),
+};
+
+// `Forbidden` is declared once and joins every action's errors.
+export const UserActions = ActionGroup.make(
+  { name: "users", errors: [Forbidden], schemaError },
+  GetUser,
+  RenameUser,
+  WhoAmI,
+);
+
+// Build-time services (Users) are yielded in the builder, once per adapter layer.
+// Request-time services (CurrentActor) are yielded inside handlers.
+export const UserApp = UserActions.implement(
+  Effect.gen(function* () {
+    const users = yield* Users;
+
+    return {
+      getUser: ({ id }) =>
+        Effect.gen(function* () {
+          const actor = yield* authorize("users:read");
+
+          return yield* users.get(actor.tenantId, id);
+        }),
+      renameUser: ({ id, name }) =>
+        Effect.gen(function* () {
+          const actor = yield* authorize("users:write");
+
+          return yield* users.rename(actor, id, name);
+        }),
+      whoAmI: () => Effect.map(CurrentActor, ({ id, tenantId }) => ({ id, tenantId })),
+    };
+  }),
+);
+
+// No build-time services: pass the record directly.
+export const MathApp = MathActions.implement({ double: ({ value }) => Effect.succeed(value * 2) });
+```
+
+## Rules
+
+- `name` matches `[A-Za-z0-9_-]+` and must be unique within one `ActionHttp.make`. Action names must be unique within the group. MCP tool names must be unique within the group and within each Toolkit or MCP projection that serves it. Duplicates fail at `make`.
+- Group `errors` are appended to each action's own `errors`, so every handler of the group may fail with them.
+- `implement` takes a complete record or an Effect producing one. The record must have exactly one handler per action; a missing key is a compile error.
+- The builder Effect runs once per adapter layer that serves the implementation, in that layer's scope. An implementation served by HTTP and MCP is built twice. Acquire shared state in a Layer you provide to the adapters, not in the builder.
+- Services yielded in the builder are build-time requirements (`RX`). Services yielded in a handler are request-time requirements (`R` of the handler). Adapters keep these separate in their types. Use distinct tags for each kind; never provide a request-identity tag at startup (see [guarantees.md](guarantees.md)).
+- `Implementation` is nominal. Spreading its properties does not produce an implementation. Each `implement` call is a separate binding.
+- `build` exists for direct handler tests under `Effect.scoped`. It bypasses transport validation and is not a substitute for adapter tests. There is no public handler service or Layer.
+
+### Schema-error policy
+
+- Without a policy, HTTP answers decoding and encoding failures with Effect's native empty 400.
+- With a policy, `map` receives the native `HttpApiSchemaError` (`kind`, `cause`) and returns one of `errors`. HTTP uses that error's `httpApiStatus`, and the error appears in `Http.api`, in clients, and in OpenAPI.
+- `kind` values: `Payload` (input decoding) and `Body` (success encoding). Actions declare no parameters, query, or headers, so no other kind occurs.
+- MCP is unaffected. The native `McpServer` answers invalid arguments and unencodable results itself.
+- Policy errors extend the transport contract, not the handler contract. A handler cannot return them.
+- The policy runs only on the server. Client-side codec failures stay `SchemaError`.
+- HTTP decodes with `errors: "all"`, so `cause` carries every issue. Issues never retain the rejected values.
+- Groups served by one adapter may have different policies; each action answers with its own group's.
+- Domain errors, defects, interruptions, and protocol errors are not remapped. An unencodable declared error is a defect. A broken policy error is not recursively remapped.
+
+## Failure modes
+
+- Throws at `make`: duplicate action name, duplicate MCP tool name, invalid group name.
+- `Property 'x' is missing in type` at `implement`: the record lacks a handler for action `x`.
+- Handler compiles but returns an error not in `errors`: type error on the handler's error channel. Declare it on the action or the group.
+- `map` is not typed from `errors` when declared as a standalone constant: annotate its parameter as `HttpApiError.HttpApiSchemaError` (type import from `effect/unstable/httpapi`).
+- A service is resolved once and shared across requests when it should be per request: it was yielded in the builder. Move the `yield*` into the handler.

package/docs/ActionHttp.md

@@ -0,0 +1,106 @@
+# ActionHttp
+
+JSON `POST` routes on Effect's `HttpApi`. One `ActionHttp.make` binds a mount path and a set
+of groups into a contract value shared by the server, every client, and the OpenAPI document.
+
+## API
+
+```ts
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+
+function make<const G extends ReadonlyArray<Actions>>(options: Options, ...groups: G): Http<G>;
+
+interface Options {
+  readonly apiPath: `/${string}`; // no default
+}
+
+interface Http<Groups> {
+  readonly groups: Groups; // the exact contracts bound, in declaration order
+  readonly api: HttpApi.HttpApi<"actions", ...>; // native HttpApi, one HttpApiGroup per group
+  /** Serve implementations. Errors and requirements are unions over exactly these apps. */
+  readonly layer: <const Apps extends ReadonlyArray<AnyImplementation<Groups[number]>>>(
+    ...apps: Apps
+  ) => Layer.Layer<
+    never,
+    BuildError<Apps[number]>,
+    | BuildContext<Apps[number]>
+    | HttpRouter.HttpRouter
+    | HttpRouter.Request.From<"Requires", RequestContext<Apps[number]>>
+    | Etag.Generator | FileSystem | HttpPlatform.HttpPlatform | Path
+  >;
+}
+```
+
+Route shape: `POST <apiPath>/<group>/<action>`. Operation ID: `<group>.<action>`.
+
+## Canonical
+
+```ts
+import { Layer } from "effect";
+import { HttpRouter, HttpServerResponse } from "effect/unstable/http";
+import { HttpApiScalar, HttpApiSwagger, OpenApi } from "effect/unstable/httpapi";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import { PublicActions, UserActions } from "./contracts.js";
+import { PublicApp, UserApp } from "./handlers.js";
+import { authentication } from "./auth.js";
+
+// Contract: shared by server and clients.
+export const Http = ActionHttp.make({ apiPath: "/api/actions" }, PublicActions, UserActions);
+
+// One layer per middleware set. Middleware provided to a layer applies to that layer only.
+const routes = Layer.mergeAll(
+  Http.layer(PublicApp),
+  Http.layer(UserApp).pipe(Layer.provide(authentication.layer)),
+);
+
+// Documents are Effect's own, reading the same contract.
+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" }),
+);
+
+export const layer = Layer.mergeAll(routes, documentation);
+```
+
+Serve with `HttpRouter.serve(layer).pipe(Layer.provide(NodeHttpServer.layer(createServer, { port })), Layer.launch)`.
+
+### Client
+
+The client is Effect's native grouped `HttpApiClient` over `Http.api`:
+
+```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));
+```
+
+## Rules
+
+- `apiPath` has no default. Group names must be unique within one `make`. Action names need only be unique within their group; equal action names in different groups do not collide.
+- `Http.layer(...apps)` mounts only the supplied implementations. A group that is never passed to `layer` has no routes. A group with no HTTP-enabled actions is not built at all.
+- Middleware is per layer call. Groups that need different middleware go in separate `Http.layer` calls, merged with `Layer.mergeAll`.
+- Request-time handler services are `HttpRouter.Request.From<"Requires", R>`. Supply them with router middleware (`Authentication.middleware`, `HttpRouter.middleware`), `HttpRouter.provideRequest`, or the request context. Build-time services are ordinary layer requirements.
+- `Http.api` is a plain `HttpApi`. Anything Effect can do with an `HttpApi` works: `OpenApi.fromApi`, `HttpApiSwagger.layer`, `HttpApiScalar.layer`, `HttpApi.addHttpApi` to combine with other APIs, `HttpApiClient.make`.
+- Client calls always take `{ payload }`. No-input actions take `{ payload: {} }`. Pass `null` or `undefined` only when the codec accepts it. There is no flat client.
+- Client effects fail with the declared errors, the group's policy errors, `SchemaError` for local codec failures, and native `HttpClientError`. MCP-only actions are absent from the client.
+- Add authentication headers with the native `transformClient` option. Use `HttpApiClient.makeWith` for custom error or service channels. Native per-call response modes are available.
+- Wire format without a policy: input failure is an empty 400, success is the encoded body, a declared error is its JSON encoding with its `httpApiStatus`, an encoding failure is an empty 400, a defect is an empty 500. Full table in [guarantees.md](guarantees.md).
+- Each handler runs in a span named `<group>.<action>`, a child of the request span. Decoding and encoding are outside it.
+
+## Failure modes
+
+- Route returns 404: the implementation was never passed to `Http.layer`, or the action has `http: false`, or the path lacks the group segment.
+- Type error listing `HttpRouter.Request.From<"Requires", CurrentActor>` as unsatisfied: a handler yields a request service and no middleware provides it. Wrap that `Http.layer` call with the middleware's `.layer`.
+- Two groups share a name: `make` throws. Rename one.
+- `Implementation of group "x" is not served by this adapter`: `Http.layer` received an implementation whose group was not passed to `ActionHttp.make`. Add the group to `make` or drop the app.
+- Client method missing for an action: the action is `http: false`.
+- Empty 400 on a valid-looking request: input did not decode. Set a `schemaError` policy on the group to get a typed body, and check `Content-Type: application/json`.
+- 415: wrong or missing content type.

package/docs/ActionMcp.md

@@ -0,0 +1,132 @@
+# ActionMcp
+
+MCP tools from implementations, on Effect's native `McpServer`. One `Tool` per MCP-enabled
+action. Two transports: a Streamable HTTP endpoint mounted on the router, or newline-delimited
+JSON-RPC on standard I/O for a subprocess.
+
+## API
+
+```ts
+import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
+
+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]>>
+>;
+
+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]>
+>;
+
+interface Options {
+  readonly name: string; // server info
+  readonly version: string;
+  readonly protocols: ReadonlyArray<McpProtocol>; // required, e.g. [McpProtocol.v2026_07_28]
+  readonly path: HttpRouter.PathInput; // no default
+  readonly allowedOrigins?: ReadonlyArray<string>; // passed to McpServer.layerHttp
+  readonly instructions?: string;
+}
+
+interface StdioOptions {
+  readonly name: string;
+  readonly version: string;
+  readonly protocols: ReadonlyArray<McpProtocol>;
+  readonly instructions?: string;
+}
+```
+
+## Canonical
+
+```ts
+import { Layer } from "effect";
+import { McpProtocol } from "effect/unstable/ai";
+import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
+import { AuditApp, PublicApp, UserApp } from "./handlers.js";
+import { authentication } from "./auth.js";
+
+const allowedOrigins = ["http://localhost:3000"];
+
+// One endpoint is one route: its middleware covers every tool on it.
+// Tools with different middleware needs get their own endpoint.
+const publicMcp = ActionMcp.layerHttp(
+  {
+    protocols: [McpProtocol.v2026_07_28],
+    name: "app-public",
+    version: "1.0.0",
+    path: "/mcp/public",
+    allowedOrigins,
+  },
+  PublicApp,
+);
+
+const mcp = ActionMcp.layerHttp(
+  {
+    protocols: [McpProtocol.v2026_07_28],
+    name: "app",
+    version: "1.0.0",
+    path: "/mcp",
+    allowedOrigins,
+  },
+  UserApp,
+  AuditApp,
+).pipe(Layer.provide(authentication.layer));
+
+export const layer = Layer.mergeAll(publicMcp, mcp);
+```
+
+Subprocess:
+
+```ts
+import { NodeRuntime, NodeStdio } from "@effect/platform-node";
+import { Console, Effect, Layer, Logger } from "effect";
+import { McpProtocol } from "effect/unstable/ai";
+import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
+
+const layer = ActionMcp.layerStdio(
+  { name: "app-stdio", version: "1.0.0", protocols: [McpProtocol.v2026_07_28] },
+  app,
+).pipe(Layer.provide(NodeStdio.layer));
+
+// stdout is protocol-only; logs go to stderr.
+Layer.launch(layer).pipe(
+  Effect.tapCause((cause) => Console.error(cause)),
+  Effect.provideService(Logger.LogToStderr, true),
+  NodeRuntime.runMain({ disableErrorReporting: true }),
+);
+```
+
+## Rules
+
+- `protocols` is required and takes Effect's native `McpProtocol` adapters. Effect owns negotiation, revision rejection, and sessions. `[McpProtocol.v2026_07_28]` gives a stateless endpoint that needs no initialize handshake.
+- `path` has no default. `layerHttp` uses the single-endpoint Streamable HTTP transport, never the two-endpoint HTTP+SSE form, whatever revision is negotiated.
+- An endpoint is one route. Middleware provided to `layerHttp` covers all of its tools. To serve tools under different middleware, mount them on different paths with separate `layerHttp` calls.
+- Only MCP-enabled actions become tools, under `mcp.name` with the resolved hints. A group with no tools is not built.
+- Every MCP-enabled action must have object-root input. Checked synchronously when `layerHttp` or `layerStdio` is called, before any handler is acquired; a violation throws. The `IllegalArgumentError` in the layer's error channel comes from the native transport, not from this check.
+- Success is `structuredContent: { value: <encoded success> }`. A declared error is an `isError` result whose text content is the error's JSON encoding, the same bytes HTTP sends as the body, and no `structuredContent`.
+- Invalid arguments and unencodable results are answered by the native `McpServer`: an `isError` result with a message for the model. Group `schemaError` policies do not apply.
+- Defects and encoding failures produce the generic `isError` text `Tool execution failed due to an internal server error.`; the cause is logged, not sent.
+- Tool discovery is not filtered by actor. Every caller sees every tool of the endpoint. Authorization happens in the handler.
+- Cancellation is Effect's native RPC interruption.
+- Handlers may yield `McpSchema.McpRequestContext` for the client's declared information; the native server supplies it to every tool call, so it is never a router or host requirement.
+- stdio: the host supplies `Stdio` (`NodeStdio.layer`) and any request-time services explicitly, including the trusted principal. There is no authentication middleware. Tool arguments never establish identity. Keep stdout for protocol messages only and route logs to stderr.
+- Each endpoint or subprocess owns a fresh native tool registry. That isolates tool names, not application context.
+
+## Failure modes
+
+- `<action>: MCP input must have an object root; omit input for no arguments` thrown at the `layerHttp` or `layerStdio` call: the action has scalar or array input. Wrap it in a struct or set `mcp: false`.
+- `Duplicate MCP tool: <name>` thrown at the `layerHttp` or `layerStdio` call: two apps on one endpoint expose the same tool name. Rename with `mcp.name` or split the endpoint.
+- Type error listing `HttpRouter.Request.From<"Requires", ...>`: a handler yields a request service and the endpoint has no middleware providing it. Provide it with `Layer.provide(middleware.layer)` on that `layerHttp`.
+- Public tool requires a token: it shares an endpoint with protected tools. Give it its own path.
+- Client reports a broken transport from a stdio subprocess: something printed to stdout. Set `Logger.LogToStderr` and remove `console.log`.
+- Older MCP client cannot connect: the client expects a revision not listed in `protocols`. Add the adapter for that revision.