@gjermundgaraba/effect-actions 0.9.0 → 0.10.0

package/docs/ActionMcp.md

@@ -1,69 +1,70 @@
 # 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. Both speak MCP 2026-07-28 only.
+MCP tools from implementations, on Effect's native `McpServer`. One `Tool` per served action,
+named after it. Two transports: a Streamable HTTP endpoint mounted on the router, or newline-delimited
+JSON-RPC on standard I/O for a subprocess. HTTP speaks MCP 2026-07-28 only; stdio also speaks
+2025-11-25 and 2025-06-18, as the host negotiates.
 
 ## API
 
 Import `@gjermundgaraba/effect-actions/ActionMcp`.
 
-| API                         | Purpose                                                                       |
-| --------------------------- | ----------------------------------------------------------------------------- |
-| `layerHttp(apps, options)`  | Serve a readonly collection of implementations at a Streamable HTTP endpoint. |
-| `layerStdio(apps, options)` | Serve implementations over a subprocess's standard I/O.                       |
-| `Options`, `StdioOptions`   | Configuration for the two transports.                                         |
-
-The options are the native `McpServer.layerHttp` / `McpServer.layerStdio` options, except
-`protocols`, plus this surface's `errors` and `before`. The native ones pass through unchanged.
-
-| Option                               | Meaning                                                                                               |
-| ------------------------------------ | ----------------------------------------------------------------------------------------------------- |
-| `name`, `version`                    | Required native server information.                                                                   |
-| `description`, `websiteUrl`, `icons` | Optional native server information, sent to clients with `name` and `version`.                        |
-| `instructions`                       | Optional native server instructions.                                                                  |
-| `extensions`                         | Optional native server capability extensions.                                                         |
-| `path`                               | Required HTTP endpoint path; HTTP only, no default.                                                   |
-| `allowedOrigins`                     | Optional exact Origin allowlist; HTTP only, not CORS configuration.                                   |
-| `errors`                             | Optional surface error codecs, declared on every served tool.                                         |
-| `before`                             | Optional Effectful hook receiving the selected `Action.Any`; fails only with declared surface errors. |
-
-Both layers retain served implementations' build failures and requirements, plus native
-`IllegalArgumentError`. HTTP needs the router and wraps handler/hook services as request
-requirements. stdio needs `Stdio` and the caller's request services. Native `McpRequestContext`
-is supplied by the server, not owed by the host.
+| API                                   | Purpose                                                                                            |
+| ------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `layerHttp(implementations, options)` | Serve implementations at a Streamable HTTP endpoint.                                               |
+| `runStdio(implementations, options)`  | Serve implementations as a subprocess's program on standard I/O; succeeds when the host closes it. |
+
+The options, exported as `LayerHttpOptions` and `Options` (the server's, which `LayerHttpOptions` extends), are the native
+`McpServer.layerHttp` / `McpServer.layerStdio` options, except `protocols`, plus `actions` and `features`, and for `layerHttp`, `authentication`. The native ones pass through unchanged; `path` gains a default. Each implementation brings its
+authorization ([Action.md](Action.md#implementations)); an endpoint serving protected actions
+names their authentication descriptor and requires its provider
+([Authentication.md](Authentication.md)).
+
+| Option                               | Meaning                                                                        |
+| ------------------------------------ | ------------------------------------------------------------------------------ |
+| `name`, `version`                    | Required native server information.                                            |
+| `description`, `websiteUrl`, `icons` | Optional native server information, sent to clients with `name` and `version`. |
+| `instructions`                       | Optional native server instructions.                                           |
+| `extensions`                         | Optional native server capability extensions.                                  |
+| `path`                               | HTTP endpoint path; HTTP only, defaults to `/mcp`.                             |
+| `allowedOrigins`                     | Optional exact Origin allowlist; HTTP only, not CORS configuration.            |
+| `authentication`                     | HTTP only: the protected tools' descriptor, required where one is served.      |
+| `actions`                            | Optional actions that are tools, among the implementations'; defaults to all.  |
+| `features`                           | Optional native resources, prompts and tools served beside the actions' tools. |
+
+`implementations` is one implementation or a list. Every tool declares its action's errors plus the
+built-in `InvalidInput`, `Unauthenticated` and `Forbidden`. `layerHttp`'s layer and `runStdio`'s
+program retain the build failures and requirements of their builders, plus native
+`IllegalArgumentError`. HTTP needs the router, the descriptor's provider where it serves a
+protected action, and wraps handler and authorizer services as request requirements until middleware provided around it provides them, the
+identity excepted, which the provider supplies. stdio needs `Stdio` and the caller's request
+services, the identity of its protected tools included. Native `McpRequestContext`
+is supplied by the server, not required of the host. The server also fails as its `features` do
+and needs what they need, except the registry, `McpServer.McpServer`, which the endpoint provides,
+such as to a feature registering with `McpServer.registerResource`.
 
 ## Canonical
 
-```ts
+One endpoint serves the public and the protected tools: discovery and `status` answer anyone,
+and every other request authenticates before the endpoint decodes it.
+
+```ts example=mcp.ts
 import { Layer } from "effect";
 import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
-import { AuditApp, PublicApp, UserApp } from "./handlers.js";
-import { authentication, authorize, Forbidden } from "./auth.js";
+import { authenticate } from "./authentication.js";
+import { Login } from "./binding.js";
+import { double, status, userActions } from "./handlers.js";
 
-const allowedOrigins = ["http://localhost:3000"];
+const allowedOrigins = ["http://localhost:3000", "http://127.0.0.1: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([PublicApp], {
-  name: "app-public",
-  version: "1.0.0",
-  path: "/mcp/public",
-  allowedOrigins,
-});
-
-const mcp = ActionMcp.layerHttp([UserApp, AuditApp], {
-  name: "app",
-  version: "1.0.0",
-  path: "/mcp",
+// One URL: discovery and `status` answer anyone; a protected tool's call authenticates
+// before its arguments are decoded, with the 401 an MCP client signs in on.
+export const layer = ActionMcp.layerHttp([status, userActions, double], {
+  name: "effect-actions",
+  version: "0.0.0",
   allowedOrigins,
-  // The same rule the HTTP binding runs, declared here so a refusal is an
-  // ordinary tool failure rather than a transport error.
-  errors: [Forbidden],
-  before: authorize,
-}).pipe(Layer.provide(authentication.layer));
-
-export const layer = Layer.mergeAll(publicMcp, mcp);
+  authentication: Login,
+}).pipe(Layer.provide(authenticate));
 ```
 
 ### Cross-origin browsers
@@ -72,25 +73,21 @@ export const layer = Layer.mergeAll(publicMcp, mcp);
 native router CORS outside the route middleware. This CORS layer is global to the router;
 choose its policy for every route it covers.
 
-```ts
+```ts example=mcp-browser.ts
 import { Effect, Layer } from "effect";
 import { HttpRouter } from "effect/http";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
 import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
-import { Actions } from "./quickstart.js";
+import { Greet } from "./quickstart.js";
 
 const allowedOrigins = ["https://ui.example.com"];
 
-const app = Actions.implement({ greet: ({ name }) => Effect.succeed(`Hello, ${name}!`) });
+const actions = Action.implement(Greet, ({ name }) => Effect.succeed(`Hello, ${name}!`));
 
-const mcp = ActionMcp.layerHttp([app], {
-  name: "greetings",
-  version: "1.0.0",
-  path: "/mcp",
-  allowedOrigins,
-});
+const mcp = ActionMcp.layerHttp(actions, { name: "greetings", version: "1.0.0", allowedOrigins });
 
 // Global router CORS handles preflight outside route-level authentication.
-// This example is public; protected endpoints still need authentication and a hook.
+// This example is public; an endpoint serving protected actions takes their `authentication`.
 export const routes = Layer.mergeAll(
   mcp,
   HttpRouter.cors({
@@ -110,69 +107,117 @@ export const routes = Layer.mergeAll(
 
 ### Subprocess
 
-```ts
+```ts example=mcp-stdio.ts
 import { NodeRuntime, NodeStdio } from "@effect/platform-node";
-import { Console, Effect, Layer, Logger, Schema } from "effect";
+import { Effect, Schema } from "effect";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
-import * as ActionGroup from "@gjermundgaraba/effect-actions/ActionGroup";
+import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
 import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
 
 const Status = Action.make("status", {
   description: "Report whether the subprocess is ready.",
-  success: Schema.Struct({ ready: Schema.Boolean }),
-  access: "read",
-});
-
-const app = ActionGroup.make({ name: "stdio" }, Status).implement({
-  status: () => Effect.log("status called").pipe(Effect.as({ ready: true })),
+  success: { ready: Schema.Boolean },
+  readOnly: true,
+  caller: Action.Anyone,
 });
 
-const layer = ActionMcp.layerStdio([app], {
-  name: "effect-actions-stdio",
-  version: "0.1.0",
-}).pipe(Layer.provide(NodeStdio.layer));
+const status = Action.implement(Status, () =>
+  Effect.log("status called").pipe(Effect.as({ ready: true })),
+);
 
-// Protocol messages use stdout exclusively. Runtime diagnostics remain on stderr.
-Layer.launch(layer).pipe(
-  Effect.tapCause((cause) => Console.error(cause)),
-  Effect.provideService(Logger.LogToStderr, true),
-  NodeRuntime.runMain({ disableErrorReporting: true }),
+// Serves until the host closes stdin, then exits 0. Protocol messages use stdout
+// exclusively: runStdio writes its program's Effect logs and `Console` output to stderr, and
+// `logToStderr`, applied last, does so for the layers provided around it, and reports a failure
+// there rather than as runMain would, on stdout.
+ActionMcp.runStdio(status, { name: "effect-actions-stdio", version: "0.1.0" }).pipe(
+  Effect.provide(NodeStdio.layer),
+  ActionCli.logToStderr,
+  NodeRuntime.runMain,
 );
 ```
 
+### Native features
+
+Effect's own resources, prompts and tools join an endpoint's tools as its `features`, one layer
+merging them:
+
+```ts
+ActionMcp.layerHttp(app, {
+  name: "acme",
+  version: "1.0.0",
+  features: Layer.mergeAll(
+    McpServer.resource({ uri: "docs://readme", name: "README", content: Effect.succeed("# Acme") }),
+    McpServer.prompt({ name: "triage", content: () => Effect.succeed("Triage the issue.") }),
+  ),
+});
+```
+
+They are native: no implementation's authorization runs for them. On an endpoint
+naming a descriptor, every request a feature answers authenticates, its listings, completions
+and subscriptions included, so a public resource or prompt beside protected tools takes an
+endpoint of its own. The features register before the actions, and a native tool named as an
+action is refused when the endpoint builds: Effect's registry keeps one tool per name, and the
+endpoint's authentication decides by that name. A service they need, provided around the endpoint, is shared with the rest of the graph; one
+provided to the `features` layer itself is built once per endpoint.
+
+A feature runs with the services it was built with, never a request's: Effect's `resource` and
+`prompt` run their content in their build context alone, so a feature cannot read the caller.
+Content that depends on the caller is an action. Never provide an identity at startup to
+satisfy a feature.
+
 ## Rules
 
-- Both transports serve MCP 2026-07-28 and no other revision; there is no `protocols` option. Over HTTP the endpoint is stateless: no initialize handshake, no session, and every request stands alone. Effect owns version checks and rejects any other revision. Stdio has no sessions, so it could serve an older host, but it refuses one deliberately, for uniformity: a client that works over one transport works over the other.
-- `path` has no default. `layerHttp` uses the single-endpoint Streamable HTTP transport, never the two-endpoint HTTP+SSE form.
-- Requests reaching the native MCP handler with an `Origin` header receive **403** unless that exact origin is listed in `allowedOrigins`. Requests without `Origin` pass this check. Authentication middleware wrapping the endpoint runs first and may reject the request before native Origin validation; the allowlist does not protect authentication from untrusted-origin requests.
+- HTTP serves MCP 2026-07-28 and no other revision: it is stateless, every request standing alone. The stateful revisions keep a session per `initialize`, which Effect's HTTP runtime never expires and which no identity owns. Stdio serves 2026-07-28, 2025-11-25 and 2025-06-18, whichever the host negotiates. There is no `protocols` option; Effect owns version checks and negotiation.
+- `path` defaults to `/mcp`. `layerHttp` uses the single-endpoint Streamable HTTP transport, never the two-endpoint HTTP+SSE form.
+- Requests reaching the native MCP handler with an `Origin` header receive **403** unless that exact origin is listed in `allowedOrigins`. Requests without `Origin` pass this check. The endpoint's authentication runs first and may reject the request before native Origin validation; the allowlist does not protect authentication from untrusted-origin requests: a check that must run before it is global middleware ([Authentication.md](Authentication.md#rules)).
 - `allowedOrigins` is an Origin allowlist, not CORS configuration. Cross-origin browser clients also need outer CORS middleware or a proxy to handle preflight and add response headers. Without it, an allowed-origin `OPTIONS` request receives **405** and even a successful `POST` has no `Access-Control-Allow-Origin`. Keep preflight outside authentication and apply CORS headers to refusals too.
-- 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. The layer's types drop an action's requirements only when its type is certainly hidden (a literal `mcp: false`, see [Action.md](Action.md)); an `mcp` that may be `false` at runtime keeps them.
-- Every MCP-enabled action must have object-root input; the native server refuses anything else when the layer is built. Omit `input` for a tool with no arguments.
-- Success is `structuredContent: <encoded success>`, of any JSON type, and one text block holding the same JSON, as the specification recommends. The tool's `outputSchema` describes the 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`.
-- With a text field (`mcp.text`), a success is `content: [<field>, <JSON of the rest>]` and `structuredContent: <the rest>`. The field is sent once, verbatim, and is left out of `structuredContent` and of the listed `outputSchema`. Use it for a body the model should read raw, such as a page of Markdown: in structured content it would be JSON-escaped, and sent twice. The field must be a top-level property of the success's JSON Schema. A success without the field as a string, such as one that omits an optional field, is sent whole.
-- Besides `content`, `structuredContent` and `isError: false`, the server adds `_meta["io.modelcontextprotocol/serverInfo"]` and `resultType: "complete"` to every result. `serverInfo` is the layer's `name`, `version`, `description`, `websiteUrl` and `icons`, as given, so a result's encoded size is the size of its own fields plus a fixed overhead per endpoint, the same over HTTP and stdio.
-- 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.
+- An endpoint serving a protected action names its descriptor, `authentication: Login`, and requires its provider, `Layer.provide(authenticate)`; the types refuse one without it, and `layerHttp` throws for plain JavaScript. One serving only public actions names none, and authenticates nothing.
+- An endpoint whose every tool is protected authenticates every request before reading its body, so a host signs in when it connects.
+- A mixed endpoint, serving public and protected tools on one URL, decides from the request's MCP routing headers before the native server reads its body, as the native server refuses a request whose headers disagree with its body. Discovery, `server/discover` and `tools/list`, `notifications/cancelled`, and a call of a public tool pass without a credential; a credential presented there is verified, and refused with 401 if it does not verify, while one its scheme decodes as empty passes as none. Every other request authenticates: a protected tool's call, before its arguments are decoded, and every native feature's request, `prompts/get`, `resources/read`, their listings, `completion/complete` and `subscriptions/listen` included, as does a method a later revision adds. The `Mcp-Name` header is compared as it is: a `tools/call` naming no public tool by it, a Base64-encoded name (`=?base64?...?=`) included, authenticates, and so does a request whose headers name no method: it fails closed.
+- So signed-out callers of a mixed endpoint list every tool, protected ones included, and call the public ones; a protected tool's call answers the 401 an MCP client signs in on, then retries. To keep protected tools unlisted to signed-out callers, serve the public tools on an endpoint of their own, with separate `layerHttp` calls on different paths.
+- A public tool never gets the identity, signed in or not; an action whose answer depends on the caller is protected. Middleware provided around `layerHttp` covers every request to the endpoint, before its authentication; an endpoint takes no layer middleware of its own, so middleware that reads the identity is not available over MCP ([ActionHttp.md](ActionHttp.md#rules)).
+- Every action of the implementations passed becomes a tool, named after the action, with the action's `mcp` hints, its `title` and `_meta` included, unless `actions` lists the tools: then only those, each behind its implementation's authorizer and from its builder's one run, and an implementation holding none of them is not built. To keep an action off MCP, leave it out of `actions`: `ActionMcp.layerHttp([users, pages], { name, version, actions: Tools })` ([Action.md](Action.md#contracts)). Only a listed action's input must suit MCP, and only listed actions' names must be unique. The types take only actions of the implementations, and owe only what the listed actions' handlers and authorizers, and the builders holding them, need. Whether the endpoint authenticates follows the listed actions alone.
+- Builders and request services follow the [dependency lifetimes](guarantees.md#dependency-lifetimes), and authorization the [authorization rules](guarantees.md#authorization). Only the tool registry is fresh per endpoint.
+- A handler may yield `McpServer.McpServer`, its endpoint's registry, to send notifications such as progress: the endpoint provides it, and no host owes it. Served on another surface too, where nothing provides it, read it with `Effect.serviceOption`.
+- Every served action's input must be one object with keys, as a tool's arguments are: fields, a struct or a class, identified, recursive or suspended, a record, or a declared type whose JSON Schema is an object. `layerHttp` and `runStdio` read the JSON Schema the native server reads, and throw for any other when they are called, naming the actions: a union, an array, a scalar, or an object without keys such as `Schema.Struct({})`. Omit `input`, or give `{}`, for a tool with no arguments.
+- A tool's `inputSchema` is its input's JSON Schema, on every revision, closed with `additionalProperties: false` where the input declares its fields; a record's lists its value schema there instead. Undeclared arguments are refused on every revision, as invalid arguments.
+- A success is sent as it is. On 2026-07-28, over HTTP and stdio, it is `structuredContent: <encoded success>`, of any JSON type (`null` for an action that returns nothing), and one text block holding the same JSON, and the tool's `outputSchema` describes the encoded success. Stdio's earlier revisions, 2025-11-25 and 2025-06-18, structure less: they carry only an object as `structuredContent`, and list only an object-rooted `outputSchema`. A success they do not structure is text alone: its JSON, or a string success the string itself. 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`.
+- On 2026-07-28, over HTTP and over stdio, the native server adds `_meta["io.modelcontextprotocol/serverInfo"]` and `resultType: "complete"` to every result, beside a tool result's own fields (`isError: false` on a success); the earlier revisions stdio speaks add neither. `serverInfo` is the options' `name`, `version`, `description`, `websiteUrl` and `icons`, as given, so a 2026-07-28 result's encoded size is the size of its own fields plus a fixed overhead per endpoint or subprocess.
+- Invalid arguments are answered by the native `McpServer`: from 2025-11-25 on, an `isError` result with a message for the model, such as `Invalid parameters for tool 'greet': Expected string\n  at ["name"]`; on earlier stdio revisions, a JSON-RPC error. HTTP's `InvalidInput` does not apply. A protected tool's call from a caller without a credential that verifies gets the 401 first, before its arguments are decoded, malformed ones included, on a mixed endpoint as on one of protected tools alone.
 - 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 `before`.
-- Cancellation is Effect's native RPC interruption. Over HTTP there is no session, so `notifications/cancelled` interrupts nothing; a tool call ends with its HTTP request, whose lifetime (for example, whether a client disconnect interrupts it) is the host's.
+- Every caller sees every tool of the endpoint ([guarantees.md](guarantees.md#scope)); authorization happens in each implementation's `authorize`.
+- Cancellation is Effect's native RPC interruption. Over HTTP there is no session, so `notifications/cancelled` interrupts nothing. A tool call ends with its HTTP request, whose lifetime (for example, whether a client disconnect interrupts it) is the host's.
 - 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.
+- `runStdio` is the subprocess's whole program: it serves until the host closes stdin, then succeeds, so the process exits 0. Closing stdin interrupts every call in flight; `runStdio` succeeds once they have stopped, after any uninterruptible region has completed. An interrupted call gets no result: no answer, or a JSON-RPC error. MCP hosts close stdin to shut a server down; a script piping requests keeps stdin open until it has read every answer. A signal interrupts it, as any program. Provide `Stdio` and its services to it and run it, `NodeRuntime.runMain`.
+- stdio is a local surface and takes no `authentication`: the host supplies `Stdio` (`NodeStdio.layer`) and any request-time services explicitly around `runStdio`, the identity of every protected tool included, `Effect.provideService(CurrentActor, actor)`. Each implementation's `authorize` runs for its protected tools. Tool arguments never establish identity.
+- `runStdio` gives its program a `Console` that writes every method through the `error` of the console it runs with, to stderr, since stdout carries the protocol: every console logger, the default one included, `Console.log`, and the counters, timers and group labels Node's console prints on stdout. A counter or a timer prints its label and its count or the milliseconds since it started, a group prints its label without indenting what follows, and `clear` does nothing. Layers provided around `runStdio` run outside its program: apply `ActionCli.logToStderr` last, before `runMain`, as the example does, which moves their default logger to stderr and reports there what `runMain` would report on stdout, a failure of such a layer or a defect, with the exit code `runMain` gives ([ActionCli.md](ActionCli.md#rules)). It does not move their `Console` output or a logger writing through `Console.log`, such as `Logger.consoleJson`; log JSON with `Logger.withConsoleError(Logger.formatJson)` instead. Keep the global `console.log` and other direct writes off stdout.
 - Each endpoint or subprocess owns a fresh native tool registry. That isolates tool names, not application context.
-- `errors` are the failures this transport answers with rather than a handler. They join every tool's declared failures, so a refusal is returned exactly like an action's own error and no caller sees a protocol-level error instead. A schema an action already declares is not repeated.
-- `before` runs after successful native argument decoding and before the selected handler, with its action contract. Invalid arguments skip the hook and handler. A hook failure prevents the handler from running; its services join handler request requirements.
+- Every tool declares the built-in errors ([guarantees.md](guarantees.md#wire-behavior)). An authorizer's refusal is an `isError` result whose text is its JSON, `{"_tag":"Forbidden","message":"Not allowed."}`, exactly like an action's own error.
+- The authorizer runs after the native server decodes the tool's arguments.
+- On an endpoint naming a Bearer descriptor, a protected tool's step-up refusal is an HTTP 401 or 403 instead of a tool result ([guarantees.md](guarantees.md#authorization)); a public tool's is its `isError` result, signed in or not; without one, or under a descriptor of another scheme, a tool's refusal is an `isError` tool result, and only the authentication's own refusal is a 401 or 403. On a `Forbidden`'s `insufficient_scope` challenge, an MCP client re-authorizes with those scopes and retries.
+- That holds only while nothing of the response has been sent. Once a handler's notification, such as progress, has started a 200 event stream, a later refusal is the tool's `isError` result in it. An authorizer runs before its handler, so its refusal is always the status.
+- Authentication refuses before the MCP handler too: an HTTP 401 or 403. An MCP client reads the 401's `WWW-Authenticate` challenge and finds its authorization server through the discovery `Authentication.layer` publishes for a protected resource ([Authentication.md](Authentication.md)).
 
 ## Failure modes
 
-- Layer build dies while registering tools, with a defect whose `SchemaError` message says `Expected "object"` or `Missing key`: an MCP-enabled action has scalar, array, or empty-struct input, which the native server refuses. It is not in the layer's error channel, so it cannot be caught by tag. Wrap the input in a struct with at least one field, omit `input` for no arguments, or set `mcp: false`.
-- `Duplicate MCP tool: <name>` thrown at the `layerHttp` or `layerStdio` call: two actions 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: over HTTP a request answers `400` with JSON-RPC error `-32020`, over stdio `initialize` answers JSON-RPC error `-32022`. The client speaks a 2025 revision, which opens with `initialize`. Only 2026-07-28 is served; pin the client to it (the official client: `versionNegotiation: { mode: { pin: "2026-07-28" } }`).
+- `MCP tool input must be one object with keys, such as a struct: <name>, ...` thrown by `layerHttp` or `runStdio`: those actions' input is a union, an array, a scalar, or an object without keys such as `Schema.Struct({})`. Wrap a union in a field, `input: { notification: Schema.Union([Email, Sms]) }`, omit `input` (or give `{}`) for no arguments, or leave the action out of `actions`.
+- `Type 'CurrentActor' is not assignable to type 'never'` where the server is launched, with `CurrentActor` among the endpoint's startup requirements rather than its `Request<"Requires", ...>`: a feature reads a request service, which it never receives ([native features](#native-features)). Serve that content as an action.
+- A native `McpServer.resource`, `McpServer.prompt` or `McpServer.toolkit` layer merged beside `layerHttp` builds without error and is never served: `resources/list` is empty, `prompts/list` is not found, and `tools/list` lists only the actions. Each endpoint's registry is its own: pass them as its `features`.
+- An MCP client gets an `isError` refusal instead of the 401 or 403 it re-authorizes on: the handler sent a notification before refusing, so the response had already started. Refuse in the implementation's `authorize`, before the handler runs.
+- `Duplicate MCP tool: <name>` thrown at the `layerHttp` or `runStdio` call: two implementations on one endpoint serve actions of the same name. Split the endpoint, or rename one action. `actions` tells apart only separate contracts sharing a name, listing one; two implementations of the same contract stay both listed: pass one implementation.
+- `Duplicate MCP tool: <name>, claimed by an action and a native feature`, a defect when the endpoint builds: a native tool among its `features` has an action's name. Rename the native tool, or leave the action out of `actions`.
+- `Listed in actions, but no implementation holds it: <names>` thrown at the `layerHttp` or `runStdio` call: those actions are not among the implementations' actions, by identity. `(another contract)` marks one whose name an implementation holds, as a second copy of the contracts module makes. Pass the implementation holding it, or list the contract it implements.
+- `No overload matches this call` at `layerHttp`, ending `Type 'string' is not assignable to type 'never'` on its options: the endpoint serves a protected action and names no `authentication`, or one of another identity. Give its descriptor. `Protected action '<name>' requires its matching authentication descriptor` thrown by `layerHttp`: the same, from plain JavaScript.
+- `Provider<CurrentActor, "example.Login">` among the endpoint's requirements, or `Type 'Provider<...>' is not assignable to type 'never'` where the server is launched: the descriptor's provider is not provided. `Layer.provide(authenticate)` on that `layerHttp` ([Authentication.md](Authentication.md#failure-modes)).
+- `Type 'X' is not assignable to type 'never'` where the server is launched, or `Request<"Requires", X>` in the endpoint's type: a handler or an authorizer yields a request service that no middleware around the endpoint provides. Provide it with router middleware on that `layerHttp`; never an identity at startup. `X` the identity, on an endpoint serving public tools: a public handler reads it, which no public tool gets. Make that action protected.
+- A public tool's call answers 401: it presented a credential that does not verify. Send a valid one, or none.
+- A protected tool's call answers 401 to a signed-in host after a while: its token expired; the host refreshes it, or signs in again, on the challenge's `invalid_token`.
+- A prompt or resource demands credentials: it is served on an endpoint naming a descriptor, where every feature request authenticates. Serve it on an endpoint without protected tools.
+- A stdio program owes `CurrentActor`, `Type 'CurrentActor' is not assignable to type 'never'` at `runMain`: it serves a protected tool, whose caller the host supplies. Provide it around `runStdio`; stdio takes no `authentication`.
+- Client reports a broken transport from a stdio subprocess: something wrote to stdout, such as `console.log`, or a layer provided around `runStdio` did, through the default logger without `Logger.LogToStderr` outermost, or through `Console` or a logger such as `Logger.consoleJson`, which `LogToStderr` does not move. Remove the write, apply `ActionCli.logToStderr` last, or log JSON with `Logger.withConsoleError(Logger.formatJson)`.
+- A stdio host asking for 2025-03-26 or 2024-11-05 is offered 2025-11-25 in the `initialize` result, as MCP negotiates, and disconnects if it cannot speak it. Update the host.
+- An MCP client cannot connect over HTTP: a request answers `400` with JSON-RPC error `-32020`. The client opens with `initialize`, as the 2025 revisions do, and HTTP serves only 2026-07-28. Pin the client to it (the official client: `versionNegotiation: { mode: { pin: "2026-07-28" } }`), or serve that host over stdio. Codex is such a client: it opens HTTP with `initialize` (measured on 0.159.0), so serve it over stdio.
 - An Origin-bearing request reaches the native handler and gets an empty 403: its `Origin` is not in `allowedOrigins`. Add the exact origin only if the deployment trusts it.
-- A disallowed Origin receives 401 instead: wrapping authentication rejected it before the native Origin check. Put any required pre-authentication Host/Origin policy in outer host middleware.
+- A disallowed Origin receives 401 instead: the endpoint's authentication rejected it before the native Origin check. A Host or Origin check that must run before authentication is global middleware ([Authentication.md](Authentication.md#rules)).
 - Browser calls fail despite an allowed Origin: configure CORS outside authentication and the MCP handler (see the browser example above). The native allowlist alone neither handles preflight nor adds CORS response headers.
-- `Object literal may only specify known properties, and 'protocols'`: the revision is fixed. Delete the option.
-- Layer build dies with `MCP tool '<name>' cannot send '<field>' as text: it is not a top-level property of its success`: the success's JSON Schema has no such top-level property, as for a union of structs. Make the success one struct.
-- A refusal arrives as a generic internal-error result: the hook failed with an error this transport does not declare, which is a defect. Add its schema to `errors`.
+- `Object literal may only specify known properties, and 'protocols'`: the revisions are fixed. Delete the option.

package/docs/ActionToolkit.md

@@ -1,71 +1,133 @@
 # 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.
+with `LanguageModel` or by hand. No server. A tool takes and gives JSON, as a model does; code
+of your own calls the implementations typed, with `Action.client` ([Action.md](Action.md#clients)).
 
 ## API
 
 Import `@gjermundgaraba/effect-actions/ActionToolkit`.
 
-| API                    | Purpose                                                                                       |
-| ---------------------- | --------------------------------------------------------------------------------------------- |
-| `make(apps, options?)` | Project a readonly collection of implementations; omit options for an unguarded binding.      |
-| `binding.toolkit`      | Native `Toolkit` with typed tool names, schemas and per-tool request requirements.            |
-| `binding.layer`        | Acquire handlers in the layer's scope; requires their startup services, not request identity. |
-| `Options`, `Binding`   | Public configuration and binding types.                                                       |
+| API                               | Purpose                                                                                                             |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `make(implementations, options?)` | Project an implementation or a list; returns `{ toolkit, layer }`.                                                  |
+| `toolkit`                         | A native `Toolkit`: `toolkit.tools` holds the tool definitions by name, with typed schemas, MCP hints and approval. |
+| `layer`                           | The handler layer: builds handlers and built authorizers in its scope; requires build-time services.                |
 
-Options: `errors` declares surface error codecs on every tool; `before` is an Effectful hook
-receiving the selected `Action.Any`, failing only with those errors. Both are optional.
+| Option          | Meaning                                                                                                                                    |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `actions`       | The actions that are tools, among the implementations': `[GetUser, RenameUser]`. Defaults to every action of them.                         |
+| `needsApproval` | `(call) =>` a boolean, or an `Effect` of one: the calls `LanguageModel` asks approval for instead of running them ([Approval](#approval)). |
 
-Each tool keeps the action's native input/success codecs, combines action and surface failures
-in a native union, and uses `failureMode: "return"`. Its request requirements are its handler's
-plus the hook's; build failures and services belong to the binding layer.
+Exported types: `Tools`, what `make` returns; `Options`, what it takes; `ToolCall<A>`, the call `needsApproval` receives, `A` the union of its actions, for a rule written apart from `make`.
+
+A local surface: each implementation's `authorize` runs before the handlers of its protected
+actions, and the caller provides the identity.
+
+Each tool takes and gives the JSON encoding of the action's schemas, as a model speaks and
+as an MCP tool does, combines the action's errors with the built-in `InvalidInput`,
+`Unauthenticated` and `Forbidden` in a native union, and uses `failureMode: "return"`. Its request requirements are its handler's and its authorizer's, and a protected
+action's identity, whether or not anything reads it; build failures and services belong to the
+handler layer.
 
 ## Canonical
 
-```ts
+```ts example=toolkit-authorized.ts
 import { NodeRuntime } from "@effect/platform-node";
 import { Console, Effect, Layer, Stream } from "effect";
 import * as ActionToolkit from "@gjermundgaraba/effect-actions/ActionToolkit";
-import { actors, authorize, CurrentActor, Forbidden } from "./auth.js";
-import { UserApp } from "./handlers.js";
+import { actors, CurrentActor } from "./authorization.js";
+import { double, userActions } from "./handlers.js";
 import { Users } from "./users.js";
 
-// The in-process caller binds the same rule as the guarded servers.
-const binding = ActionToolkit.make([UserApp], { errors: [Forbidden], before: authorize });
+// The implementations' `authorize` runs for the in-process caller as for the servers.
+const { toolkit, layer } = ActionToolkit.make([userActions, double]);
 
 const program = Effect.gen(function* () {
-  const tools = yield* binding.toolkit;
-  const calls = yield* tools.handle("get_user", { id: "1" }); // encoded arguments
+  const tools = yield* toolkit;
+  const calls = yield* tools.handle("getUser", { id: "1" }); // encoded arguments
   const results = yield* Stream.runCollect(calls);
   yield* Console.log(results);
 }).pipe(
   Effect.provideService(CurrentActor, actors.alice), // identity around the whole invocation
-  Effect.provide(binding.layer.pipe(Layer.provide(Users.layerMemory))), // startup services only
+  Effect.provide(layer.pipe(Layer.provide(Users.layerMemory))), // startup services only
 );
 
 program.pipe(NodeRuntime.runMain);
 ```
 
-With a model: pass `binding.toolkit` as `toolkit` to `LanguageModel.generateText` and provide `binding.layer`.
+With a model: pass `toolkit` as `toolkit` to `LanguageModel.generateText` and provide `layer`.
+Beside tools of your own, or provider-defined ones such as a web search, merge the toolkits
+natively and provide every handler layer:
+
+```ts
+LanguageModel.generateText({ prompt, toolkit: Toolkit.merge(toolkit, WebKit) }).pipe(
+  Effect.provide(Layer.mergeAll(layer, WebKitHandlers)),
+);
+```
+
+### Approval
+
+```ts example=toolkit-approval.ts
+import { Effect, Option } from "effect";
+import { LanguageModel } from "effect/ai";
+import * as ActionToolkit from "@gjermundgaraba/effect-actions/ActionToolkit";
+import { type Actor, CurrentActor } from "./authorization.js";
+import { double, userActions } from "./handlers.js";
+
+// A model's writes wait for their caller's approval, except a rename of the caller itself:
+// `call.name` narrows `call.input` across both implementations. Without a caller, it asks.
+export const { toolkit, layer } = ActionToolkit.make([userActions, double], {
+  needsApproval: (call) =>
+    !call.action.readOnly &&
+    Effect.map(
+      Effect.serviceOption(CurrentActor),
+      Option.match({
+        onNone: () => true,
+        onSome: ({ id }) => call.name !== "renameUser" || call.input.id !== id,
+      }),
+    ),
+});
+
+// One turn: the caller is provided around it, for the approval, `authorize` and the handlers.
+export const chat = (actor: Actor, prompt: string) =>
+  LanguageModel.generateText({ prompt, toolkit }).pipe(Effect.provideService(CurrentActor, actor));
+```
+
+A call that needs approval ends the turn with a `tool-approval-request` part instead of a
+result; the host answers it with a native `tool-approval-response` prompt part in the next turn.
+Every write, whoever calls: `needsApproval: (call) => !call.action.readOnly`. A
+toolkit made for another agent or policy from the same implementations runs with this `layer`:
+provide it once. So does one of fewer tools, such as an agent's
+`ActionToolkit.make(userActions, { actions: [GetUser] }).toolkit`.
 
 ## Rules
 
-- Selects MCP-enabled actions only, named by `mcp.name`, with resolved hints. Groups with no selected tools are not built. The toolkit's type follows `ActionMcp`'s rule: only an action whose `mcp` type is exactly `false` has no tool; one whose `mcp` may be `false` at runtime is typed as a tool with its handler's requirements. `make(apps, options?)` accepts a readonly implementation collection; options may be omitted.
-- Successes are the action's native values, whole: `mcp.text` does not apply. 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, plus the hook's, not those of sibling or disabled tools.
-- Supply identity at invocation, never when building the layer. Native context capture is not a security boundary.
+- Every action of the implementations passed becomes a tool, named after the action, with its `mcp` hints, unless `actions` lists the tools: then only those, each behind its implementation's authorizer and from its builder's one run, and an implementation holding none of them is not built. `make(implementations)` accepts one implementation or a list, such as `[userActions, double]`. The types take only actions of the implementations, and type `toolkit` and `layer`'s build services by the listed actions alone; `needsApproval`'s `call` is typed by every action of the implementations. Options whose `actions` may be absent, such as a value typed `ActionToolkit.Options<A>`, serve every action when it is absent and the listed ones when given, so their types owe what every action owes, and hold only the tools present either way ([guarantees.md](guarantees.md#names)).
+- A result's `result` is the action's decoded success or declared failure, and its `encodedResult` the JSON a model reads, such as `"42"` for a `BigInt`. Declared failures are returned as native tool results (`failureMode: "return"`), not raised.
+- `tools.handle(name, encodedInput)` takes JSON arguments, as a model sends them: an ISO string for a `Schema.Date`, `null` for an absent `Schema.optional` field. It 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.
+- Builders, calls and identity follow the [dependency lifetimes](guarantees.md#dependency-lifetimes), and authorization the [authorization rules](guarantees.md#authorization): `layer` builds, a call releases what it acquired when it ends, whether a model's turn or `tools.handle` makes it, and identity is supplied at invocation, never when building the layer. A protected tool's call owes its identity in its type; one call without it anyway, as from plain JavaScript, fails with `Unauthenticated` before `authorize` runs. The innermost caller provided wins: a call made under a narrower identity runs as that one.
+- A model loop in a route yields `toolkit` in its implementation's builder, `Action.implement(Chat, Effect.map(toolkit, (tools) => ({ prompt }) => ...), { authorize })`, and passes `tools` to `LanguageModel.generateText`; the route's layer takes the toolkit's `layer`, `ActionHttp.layer(ChatHttp, chat).pipe(Layer.provide(layer))`. That is one build, in the routes' layer graph, shared with every surface serving the same implementations. `Effect.provide(layer)` in the handler builds it for every call unless a surface of the graph serves the same implementations, and `HttpRouter.provideRequest(layer)` once, but in a layer graph of its own: a second build when another surface serves them and has not built them first.
+- Each tool carries only its own handler's request requirements, plus its authorizer's, not those of sibling actions.
+- `needsApproval` is one function over every call a model makes, before the call runs: `(call, context) =>`, where `call` is `{ name, action, input }`, the input decoded, and `context` is Effect's native approval context. `call` is typed by every action of the implementations, whatever `actions` lists, and checking `call.name` narrows `call.action` and `call.input` to that action's, across implementations too: `(call) => call.name === "erase" && call.input.id !== "draft"`. It gives a boolean, or an `Effect` of one that requires nothing: it runs in the caller's context, so it reads the caller with `Effect.serviceOption`. Default: no tool needs approval.
+- A `needsApproval` Effect that fails means no approval is needed, as `LanguageModel` decides natively. Its `Effect` cannot fail in its type: decide in `needsApproval` what a failure means, `Effect.orElseSucceed(() => true)` to ask when a policy cannot be read.
+- Tools belong to what runs them, their implementation's handlers behind its authorizer: the `layer` of a `make` call serves the tools it selected in any `toolkit` of the same implementations, a toolkit of fewer `actions` included, so toolkits made per agent or per approval policy run with one handler layer, built once. Two implementations never run each other's handlers, even with tools of one name, such as two implementations of one action behind different authorizers, whatever order their layers are provided in.
+- `toolkit` is a native `Toolkit`: `Toolkit.merge` combines it with other tools, and `yield* toolkit` gives the handled toolkit once the handler layers of all its tools are provided.
+- `LanguageModel` enforces approval; `tools.handle` ignores it, like any caller that is not a model's turn. It is not authorization, which stays the implementation's `authorize`. MCP has no such field, so `ActionMcp` takes no such option.
 - This is not an MCP server. Use `ActionMcp` to expose the same actions to external clients.
-- `errors` are the failures the caller answers with rather than a handler. They join every tool's declared failures, so a refusal is an ordinary returned tool failure. A schema an action already declares is not repeated.
-- `before` runs after successful argument decoding and before the selected handler, with its action contract. Invalid arguments skip both. Its services join each tool's requirements, supplied by the caller.
+- Every tool declares the built-in errors ([guarantees.md](guarantees.md#wire-behavior)), so an authorizer's refusal, or a handler's built-in failure, is an ordinary returned tool failure.
 
 ## Failure modes
 
-- Tool missing from the toolkit: the action has `mcp: false`. The Toolkit selects by MCP enablement.
-- Type error on `before`'s error channel: it fails with an error this binding does not declare. Add its schema to `errors`.
-- `Duplicate MCP tool: <name>` thrown at `make`: two selected actions 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. Provide it around the whole call effect. Providing it to `binding.layer` does not fail: the startup value is captured and served to every call (see [guarantees.md](guarantees.md)).
-- A returned failure that is an `AiError` with reason `ToolParameterValidationError`, not a declared error: the arguments did not decode. The hook and the handler did not run.
-- Type error on `binding.layer` requirements: a build-time service is missing. Provide its Layer before `binding.layer`.
+- Tool missing from the toolkit: its implementation was not passed to `make`, or `actions` leaves it out.
+- `Listed in actions, but no implementation holds it: <names>` thrown at `make`: those actions are not among the implementations' actions, by identity. `(another contract)` marks one whose name an implementation holds, as a second copy of the contracts module makes. Pass the implementation holding it, or list the contract it implements.
+- A defect when a tool handles a call: no `layer` of its implementation is provided, only one of another implementation with tools of the same names, such as another implementation of the same actions, which the types accept. Provide a `layer` made from the implementations the `toolkit` was made from.
+- A job or an agent beside `HttpRouter.serve`, or a model loop in a route given `layer` with `HttpRouter.provideRequest`, reads other state than the routes, or its builder runs twice: its `layer` builds in another layer graph than the routes. Put it inside the layer the server serves, a route's toolkit in its builder ([Rules](#rules)), or provide `Action.layer` and the services they share above both ([dependency lifetimes](guarantees.md#dependency-lifetimes)).
+- Every toolkit of an implementation answering with one set of startup services: two layers of it, built apart with different services, were provided together, and one of them serves its tools. Use separate implementations for separate services.
+- Type error on `needsApproval`'s `Effect`, which requires a service such as the caller: `needsApproval` requires nothing. Read the caller with `Effect.serviceOption(CurrentActor)`, which gives `Option.none()` without one.
+- `Property '<field>' does not exist` on `call.input`: `call` is a union over every action of the toolkit, and another action's input lacks the field. Check `call.name` first.
+- `Duplicate tool: <name>` thrown at `make`: two implementations serve actions of the same name. Rename one action. `actions` tells apart only separate contracts sharing a name, listing one; two implementations of the same contract stay both listed: pass one implementation.
+- `Service not found` for a request tag at call time: it was provided only to the stream. Provide it around the whole call effect. Providing a service to `layer` does not fail: that startup value fills in for every call that lacks its own ([guarantees.md](guarantees.md#dependency-lifetimes)), so never provide an identity there; a protected tool's call still owes it in its type.
+- `Type 'CurrentActor' is not assignable to type 'never'` where a program calling a tool runs: the tool's action is protected, and its call owes the caller, whatever the handler reads. Provide it around the call, or around the turn.
+- A returned failure whose `result` is an `AiError` with reason `ToolParameterValidationError` (`failureOrigin: "parameters"`), not a declared error: the arguments did not decode. Authorization and the handler did not run.
+- Type error on `layer` requirements: a build-time service is missing. Provide its Layer before `layer`.