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

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), `Body` (success encoding), plus `Parameters`, `RequestHeaders`, `Query`, `ResponseHeaders`.
+- 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`.
+- `cause` may contain input values. Never reflect it into the response.
+- 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,131 @@
+# 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.
+- 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.

package/docs/ActionToolkit.md

@@ -0,0 +1,73 @@
+# ActionToolkit
+
+Implementations as Effect's native AI `Toolkit`, for programs that call tools in-process
+with `LanguageModel` or by hand. No server, no MCP envelope.
+
+## API
+
+```ts
+import * as ActionToolkit from "@gjermundgaraba/effect-actions/ActionToolkit";
+
+function make<const Apps extends ReadonlyArray<AnyImplementation>>(
+  ...apps: Apps
+): Binding<ToolkitTools<Apps>, BuildError<Apps[number]>, BuildContext<Apps[number]>>;
+
+interface Binding<Tools, E, R> {
+  readonly toolkit: Toolkit.Toolkit<Tools>; // native; tool names, schemas and requirements stay typed
+  /** Acquires handlers once in the layer scope; handler requirements remain at invocation. */
+  readonly layer: Layer.Layer<Tool.HandlersFor<Tools>, E, R>;
+}
+
+// Each MCP-enabled action becomes:
+Tool.Tool<
+  McpName,
+  {
+    parameters: A["input"];
+    success: A["success"];
+    failure: Schema.Union<A["errors"]>;
+    failureMode: "return";
+  },
+  HandlerRequirements
+>;
+```
+
+## Canonical
+
+```ts
+import { Effect, Stream } from "effect";
+import * as ActionToolkit from "@gjermundgaraba/effect-actions/ActionToolkit";
+import { UserApp } from "./handlers.js";
+
+const binding = ActionToolkit.make(UserApp);
+
+const program = Effect.gen(function* () {
+  const tools = yield* binding.toolkit; // bound handlers
+  const calls = yield* tools.handle("get_user", { id: "1" }); // encoded arguments
+  const results = yield* Stream.runCollect(calls);
+
+  return results;
+}).pipe(
+  Effect.provideService(CurrentActor, actor), // request service, around the whole call
+  Effect.provide(binding.layer), // build services resolved here
+);
+```
+
+With a model: pass `binding.toolkit` as `toolkit` to `LanguageModel.generateText` and provide `binding.layer`.
+
+## Rules
+
+- Selects MCP-enabled actions only, named by `mcp.name`, with the resolved hints. Groups with no selected tools are not built.
+- Successes are the action's native values. There is no `{ value }` wrapper. Declared failures are returned as native tool results (`failureMode: "return"`), not raised.
+- `tools.handle(name, encodedInput)` takes encoded arguments and returns an Effect producing a result stream. The handler starts while that stream is constructed, so request services must be provided around the entire `handle(...).pipe(Effect.flatMap(Stream.runCollect))`, not only around the stream.
+- `binding.layer` acquires each implementation once, in the layer's scope. Build-time requirements belong to the whole selected implementation.
+- Each tool carries only its own handler's request requirements, not those of sibling or disabled tools.
+- Supply identity at invocation, never when building the layer. Native context capture is not a security boundary.
+- This is not an MCP server. Use `ActionMcp` to expose the same actions to external clients.
+
+## Failure modes
+
+- Tool missing from the toolkit: the action has `mcp: false`. The Toolkit selects by MCP enablement.
+- `Duplicate MCP tool: <name>` thrown at `make`: two apps expose the same tool name. Rename with `mcp.name`.
+- `Service not found` for a request tag at call time: it was provided only to the stream, or only to the layer. Provide it around the whole call effect.
+- Type error on `binding.layer` requirements: a build-time service is missing. Provide its Layer before `binding.layer`.
+- Result is `{ value: ... }` when a plain value was expected: you are reading an MCP response, not a Toolkit result. The Toolkit never wraps.

package/docs/Authentication.md

@@ -0,0 +1,114 @@
+# Authentication
+
+Two helpers for hosts that own identity: router middleware that provides a request-scoped
+identity service, and RFC 9728 protected-resource discovery with bearer challenges. Token
+verification, login, and consent stay in the application.
+
+## API
+
+```ts
+import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
+
+/** Provide `service` on every request, or send the response `authenticate` fails with. */
+const middleware: <I, A, R>(
+  service: Context.Key<I, A>,
+  authenticate: Effect.Effect<A, HttpServerResponse.HttpServerResponse, R>,
+) => HttpRouter.Middleware<{
+  provides: I;
+  handles: never;
+  error: never;
+  requires: Exclude<R, HttpRouter.Provided>;
+  layerError: never;
+  layerRequires: never;
+}>;
+
+const protectedResource: (options: ProtectedResourceOptions) => {
+  layer: Layer.Layer<never, never, HttpRouter.HttpRouter>; // GET/HEAD /.well-known/oauth-protected-resource<path>
+  metadataUrl: string;
+  challenge: (challenge?: BearerChallengeOptions) => string; // WWW-Authenticate value
+};
+
+interface ProtectedResourceOptions {
+  readonly resource: string; // exact OAuth resource identifier; its path and query select the discovery path
+  readonly authorizationServers: NonEmptyReadonlyArray<string>;
+  readonly scopesSupported?: ReadonlyArray<string>;
+  readonly resourceName?: string;
+}
+
+interface BearerChallengeOptions {
+  readonly error?: "invalid_token" | "insufficient_scope";
+  readonly errorDescription?: string;
+  readonly scope?: string; // scopes needed for this request, space-separated
+}
+```
+
+## Canonical
+
+```ts
+import { Context, Effect, Layer, Option, Schema } from "effect";
+import { HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
+import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
+
+interface Actor {
+  readonly id: string;
+  readonly tenantId: string;
+}
+
+// Request-scoped tag. Never provided at startup.
+export class CurrentActor extends Context.Service<CurrentActor, Actor>()("app/CurrentActor") {}
+
+class Unauthenticated extends Schema.TaggedError<Unauthenticated>()(
+  "Unauthenticated",
+  { message: Schema.String },
+  { httpApiStatus: 401 },
+) {}
+
+const discovery = Authentication.protectedResource({
+  resource: "https://api.example.com/mcp",
+  authorizationServers: ["https://auth.example.com"],
+  scopesSupported: ["users:read", "users:write"],
+});
+
+// The host renders the failure response: status, body, 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);
+
+export const authentication = Authentication.middleware(
+  CurrentActor,
+  Effect.gen(function* () {
+    const request = yield* HttpServerRequest.HttpServerRequest;
+    const actor = yield* verifyToken(request); // Effect<Option<Actor>>
+
+    return Option.isNone(actor) ? yield* Effect.flip(unauthenticated) : actor.value;
+  }),
+);
+
+export const routes = Layer.mergeAll(
+  discovery.layer, // public
+  Http.layer(UserApp).pipe(Layer.provide(authentication.layer)),
+  mcp.pipe(Layer.provide(authentication.layer)),
+);
+```
+
+## Rules
+
+- `authenticate` succeeds with the identity value or fails with the `HttpServerResponse` to send. The host owns status, body, and `WWW-Authenticate`.
+- Provide the middleware's `.layer` to each HTTP route layer and MCP endpoint layer that needs identity. It is native `HttpRouter.middleware`; combine with `.combine(...)`.
+- Its dependencies are request requirements. Resources it acquires live until the request scope closes, including while the handler runs.
+- Every response through the middleware carries `Cache-Control: no-store`, including failures serialized by enclosing middleware.
+- Downstream action errors are handled by their transport. They are never serialized as authentication failures.
+- Use distinct tags for startup capabilities and request identities. Never provide `CurrentActor` or any identity or tenant tag in a startup layer or root context. Native context capture can let a startup value shadow the request value or satisfy a missing one, and the adapters add no isolation boundary. Types track that the tag is required, not where its value came from.
+- `protectedResource` publishes what it is given. The deployment must ensure `resource` and `authorizationServers` are valid OAuth URLs (HTTPS, or loopback HTTP in development).
+- Discovery is served at `/.well-known/oauth-protected-resource` followed by the resource's path and query, for `GET` and `HEAD`, matching that literal path and query. Other requests fall through to the host router. Mount `discovery.layer` outside the authenticated layers. Caching policy is the host's.
+- `challenge()` quotes and escapes parameter values; it never rejects them. Name only the scopes needed for the request in `scope`; `scopesSupported` advertises the full set in metadata.
+- Tool discovery is never filtered by actor. Authorization is a handler concern (`yield* CurrentActor`, then check).
+
+## Failure modes
+
+- Handler sees a stale or wrong actor: an identity tag was provided at startup. Remove it from every startup layer; provide it only through the middleware.
+- Type error `HttpRouter.Request.From<"Requires", CurrentActor>` unsatisfied: the layer serving that implementation was not wrapped with `authentication.layer`.
+- Discovery returns 404: the request path does not match `resource`'s path and query exactly, or `discovery.layer` is not merged into the served layer.
+- Discovery requires a token: `discovery.layer` was placed under the authentication middleware. Mount it separately.
+- 401 response lacks `WWW-Authenticate`: the host's failure response did not set it. Use `discovery.challenge(...)` in its headers.