@gjermundgaraba/effect-actions 0.14.0 → 0.16.0

package/docs/Testing-failures.md

@@ -1,6 +1,9 @@
 # Testing failure modes
 
 What you see when something is wrong, and the fix. Search for a fragment of the message.
+A missing service's error can start
+`… with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined'`: search a line
+beneath it, `is missing the following properties from type 'Scope'`, instead.
 The tasks are in [Testing.md](Testing.md).
 
 - A route answers an empty 500, which a client method reports as `HttpClientError: Decode error (500 …)`: a defect, or a result that does not encode. `Testing.layer` logs the cause as an error on the process console, under `it.effect` too, and nothing for a request that succeeds or is refused: read the test's output, or collect it with a `Logger` or an `ErrorReporter` provided around the layer.
@@ -14,8 +17,5 @@ The tasks are in [Testing.md](Testing.md).
 - `Property '<field>' does not exist on type 'MethodError<Action<…>>'`, or on a built-in error, after `expect(error).toBeInstanceOf(…)`: `toBeInstanceOf` does not narrow the union of the action's errors. Compare with `toEqual(new X({ … }))`, or narrow with `instanceof` ([Assert on errors](Testing.md#assert-on-errors)).
 - A test passes whatever message an error carries: `toEqual` never compares a tagged error's `message`. Assert it separately ([Assert on errors](Testing.md#assert-on-errors)).
 - The test reads a service the handlers never changed: it was provided inside the routes and again to the test, two instances. Provide it once, around `Testing.layer`, with `Layer.provideMerge`.
-- `MCP tools/call "<name>" answered 404`: the endpoint is not at `/mcp`, the default. Pass `mcpClient` its `url`.
-- `MCP tools/call "<name>" returned an error: Invalid parameters for tool ...`: the endpoint serves another contract under that name. Pass `mcpClient` the served contract value.
 - A builder or handler fails with `NotFound: FileSystem.<method> (<path>)` for a file that exists, or a file route answers 500: with no `FileSystem` provided around `Testing.layer`, the routes read a no-op one. Provide `NodeFileSystem.layer` or `NodeServices.layer`. In a command test, the nearer of two provided is read: provide a fake `FileSystem` on the command, inside `NodeServices.layer`.
 - `Argument of type 'Layer<…, FileSystem | Generator | HttpPlatform | HttpRouter | Path>' is not assignable` at `HttpRouter.toWebHandler(routes)`: a web handler's routes need the platform services `Testing.layer(routes)` supplies itself. Provide `HttpServer.layerServices` to them.
-- `UrlError` from `HttpClientRequest.toWebResult` or `toWeb` of an `mcpRequest`, or an `HttpClientError` whose reason is `InvalidUrlError` from a client method or a sent `mcpRequest`: the `url` is relative, such as the default `/mcp`, which only the `HttpClient` of `Testing.layer` resolves. Pass an absolute one.

package/docs/Testing.md

@@ -16,23 +16,13 @@ When something fails, search [Testing-failures.md](Testing-failures.md). Reading
 
 Import `@gjermundgaraba/effect-actions/Testing`.
 
-| API                                     | Purpose                                                                       |
-| --------------------------------------- | ----------------------------------------------------------------------------- |
-| `layer(routes)`                         | A `Layer<HttpClient>` answering requests with `routes` in memory.             |
-| `layer(handler)`                        | A `Layer<HttpClient>` answering requests with a web handler the test serves.  |
-| `mcpClient(actions, options?)`          | An Effect of a client calling each action's tool, like `ActionHttp.client`.   |
-| `mcpRequest(method, params?, options?)` | One MCP request, as the native `HttpClientRequest` the test sends.            |
-| `McpCallError`                          | A client method's failure for an answer it cannot decode; `message` holds it. |
-
-| Option                         | Meaning                                                                         |
-| ------------------------------ | ------------------------------------------------------------------------------- |
-| `url`                          | The endpoint; default `/mcp`, the `ActionMcp.layerHttp` default.                |
-| `mcpClient`: `transformClient` | Wraps the native `HttpClient`, as `ActionHttp.client` takes it: a bearer token. |
-| `mcpRequest`: `headers`        | Request headers.                                                                |
-
-Exported types: `McpClient<Actions>`, `McpClientOptions`, `McpRequestOptions`, and `McpParams`,
-the `params` of `mcpRequest`. A helper passing on a tool's `arguments` types them `Schema.Json`,
-and whole `params` `McpParams`, never `unknown`.
+| API              | Purpose                                                                      |
+| ---------------- | ---------------------------------------------------------------------------- |
+| `layer(routes)`  | A `Layer<HttpClient>` answering requests with `routes` in memory.            |
+| `layer(handler)` | A `Layer<HttpClient>` answering requests with a web handler the test serves. |
+
+MCP tools are tested with `ActionMcp.client` and `ActionMcp.request`
+([Test MCP tools](#test-mcp-tools)).
 
 ## Test an implementation in process
 
@@ -113,7 +103,7 @@ const as = (token: string) => ({
 ```
 
 Both clients take it: `ActionHttp.client(Http, as("reader"))` and
-`Testing.mcpClient([GetStatus, ...Notes], as("ada"))`.
+`ActionMcp.client([GetStatus, ...Notes], as("ada"))`.
 
 - Never provide the identity to `layer`, around it or to the routes. It is a type error: only a
   provider of their own descriptor satisfies them.
@@ -130,16 +120,18 @@ each case are the table in [guarantees.md](guarantees.md#wire-behavior).
 
 ## Test MCP tools
 
-`Testing.mcpClient(actions, options?)` gives one method per action, calling its tool and decoding
+`ActionMcp.client(actions, options?)` gives one method per action, calling its tool and decoding
 the result as `ActionHttp.client` decodes a route's, an image included. Pass the contract values
-the endpoint serves, such as `implementation.actions`.
+the endpoint serves, such as `implementation.actions`. Its failures:
+[ActionMcp-failures.md](ActionMcp-failures.md).
 
 A method fails with the action's declared errors and the built-in ones as decoded values, and with
 `McpCallError` for any other answer, a result without its structured content included;
 structured content that does not decode as the success is a `SchemaError`, and a request that
 fails Effect's `HttpClientError`. Only a tool's result carries the action's own errors: an HTTP
-answer other than 200 decodes as a refusal alone, so an error a verifier declares, typed over
-`ActionHttp.client`, is an `McpCallError` here
+answer other than 200 decodes as a refusal, or, given the endpoint's `authentication`, as an error
+its verifier declares for a protected tool, as `ActionHttp.client` types it; otherwise it is an
+`McpCallError`
 ([kitchen-sink/test/identity/identity.test.ts](../examples/kitchen-sink/test/identity/identity.test.ts)).
 
 A method decodes a refusal alike whether the endpoint answered a 401 or a 403 or returned a tool
@@ -148,8 +140,8 @@ yourself and read its status.
 
 For that, and for what the client's types will not send or its decoding hides (`tools/list`, an
 `Origin` header, a refusal's challenge, a malformed call), build the request with
-`Testing.mcpRequest`. It returns a native `HttpClientRequest`:
-`yield* HttpClient.execute(Testing.mcpRequest("tools/call", { name: "whoAmI", arguments: {} }))`
+`ActionMcp.request`. It returns a native `HttpClientRequest`:
+`yield* HttpClient.execute(ActionMcp.request("tools/call", { name: "whoAmI", arguments: {} }))`
 succeeds with the response whatever its status, to read `response.status`, `response.headers`
 and `yield* response.json`
 ([kitchen-sink/test/identity/identity.test.ts](../examples/kitchen-sink/test/identity/identity.test.ts)

package/docs/guarantees.md

@@ -6,21 +6,22 @@ What a caller sees on each surface for each outcome of a call, and what the libr
 
 One call, on each surface. An HTTP route is `POST <prefix>/<action>` with a JSON body, the prefix `/api` by default. "Its JSON" is the value as its schema's JSON codec encodes it, such as `{"_tag":"NoteNotFound","id":"9"}`. A built-in error's JSON is `{"_tag":"InvalidInput","message":"…","issues":[{"path":["name"],"message":"…"}]}`, `{"_tag":"Unauthenticated","message":"…"}` or `{"_tag":"Forbidden","message":"…"}`, a `Forbidden` with the `scopes` it names. The CLI column is a command under `Command.run`.
 
-| Case                                                                   | HTTP                                                                                                                                                            | MCP                                                                                                                                                                                                                                                                                | RPC                                                                                                         | Toolkit                                                                                                             | CLI                                                                                                                                                                  |
-| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Success                                                                | its JSON as the body; an empty **200** for an action without `success`                                                                                          | `isError: false`, `structuredContent` its JSON, and the same JSON as one text block; both `null` for an action without `success`                                                                                                                                                   | the call's success                                                                                          | a result with `isFailure: false`: `result` the value, `encodedResult` its JSON                                      | its JSON on stdout, indented, or `render`'s text; nothing for an action without `success`                                                                            |
-| Input that does not decode                                             | **400** `InvalidInput`                                                                                                                                          | `isError: true`, text `Invalid parameters for tool '<name>': …`                                                                                                                                                                                                                    | the typed `InvalidInput`                                                                                    | a result with `isFailure: true`: `result` an `AiError` whose `reason` is a `ToolParameterValidationError`           | `InvalidInput`'s JSON on stderr, exit 1; a missing flag or a rejected choice is Effect CLI's own parse error instead                                                 |
-| Undeclared input field                                                 | refused, nested ones too: **400** `InvalidInput` naming its path                                                                                                | refused, as input that does not decode                                                                                                                                                                                                                                             | refused: `InvalidInput` naming its path                                                                     | **dropped**: the call runs without it                                                                               | refused, in `--input` and in a flag's JSON value: `InvalidInput`                                                                                                     |
-| Declared error                                                         | its JSON with its `httpApiStatus`, **422** without one                                                                                                          | `isError: true`, its JSON as one text block, no `structuredContent`                                                                                                                                                                                                                | the call's typed failure                                                                                    | a result with `isFailure: true`: `result` the error, `encodedResult` its JSON                                       | its JSON on stderr; the command fails with a `UserError` whose `cause` is the error; exit 1 by default                                                               |
-| Protected action, credential missing or not verified                   | **401** `Unauthenticated` with the scheme's challenge, or what the verifier fails with, before the body is read; a public route reads no credential             | the same HTTP answer in place of a JSON-RPC one, before the arguments are decoded; on an endpoint that also serves a public tool, that tool's call and `tools/list` need no credential, but one a request presents is still verified ([Protect tools](ActionMcp.md#protect-tools)) | the typed `Unauthenticated`, or what the verifier fails with, before the payload is decoded; never a status | no credential: the host provides the identity around the call ([Name the caller](ActionToolkit.md#name-the-caller)) | no credential: the host provides the identity to the command ([Name the caller](ActionCli.md#name-the-caller))                                                       |
-| `Unauthenticated` or `Forbidden` from the authorizer or a handler      | its JSON with **401** or **403**, after the input is decoded; on a protected route under Bearer, a 401 and a `Forbidden` naming `scopes` also carry a challenge | `isError: true`, its JSON as text; on an endpoint under Bearer, a protected tool's `Unauthenticated` or `Forbidden` naming `scopes` is the HTTP **401** or **403** instead, with its JSON and challenge                                                                            | the call's typed failure; never a status or a challenge                                                     | a result with `isFailure: true`, as a declared error                                                                | as a declared error                                                                                                                                                  |
-| Defect, undeclared failure, or a success or error that does not encode | an empty **500**                                                                                                                                                | `isError: true`, text `Tool execution failed due to an internal server error.`                                                                                                                                                                                                     | that call's defect, an `Error` whose message is `Internal server error`; the connection's other calls go on | a defect is the call's defect; the rest fail the call with an `AiError`, `Failed to encode result for tool …`       | a failure no schema encodes is a `UserError` whose `cause` is it, printed as its tag and message; a defect or a success that does not encode is the command's defect |
-| Unknown path, method or name                                           | a path no layer serves, or a method other than `POST` on a route: **404**                                                                                       | another HTTP method: an empty **405** with `Allow: POST, DELETE`, signed out the **401** of an endpoint with authentication; an unknown tool: a JSON-RPC error `-32602`, with **200** over HTTP                                                                                    | an rpc the layer does not serve ends its call with `Unknown request tag`                                    | Effect's own                                                                                                        | Effect CLI's own                                                                                                                                                     |
-| Body that is not JSON, or not typed as JSON                            | not JSON: **400** `InvalidInput`; `Content-Type` missing or not JSON: **415**; both after authentication on a protected route                                   | not JSON: a JSON-RPC error `-32700` with **200**; `Content-Type` missing or not JSON: an empty **415**; over stdio, a line that is not JSON goes unanswered                                                                                                                        | the protocol's own                                                                                          | —                                                                                                                   | a flag or `--input` that is not the JSON its field takes: `InvalidInput`                                                                                             |
-
-- **Typed clients.** `ActionHttp.client`, `ActionRpc.client`, `Testing.mcpClient` and `Action.client` fail with a declared or built-in error as its decoded value. Each drops undeclared fields as it encodes an input, since TypeScript lets a wider value through, and fails with `InvalidInput` for an input that does not encode, sending nothing. `Action.client` has no wire but passes input, success and failure through the same JSON codecs; an undeclared failure or a success that does not encode is its call's defect. A verifier's declared error reaches `Testing.mcpClient` as an `McpCallError`: over MCP it is the endpoint's HTTP answer.
+| Case                                                                   | HTTP                                                                                                                                                            | MCP                                                                                                                                                                                                                                                                                | RPC                                                                                                         | Toolkit                                                                                                                       | CLI                                                                                                                       |
+| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| Success                                                                | its JSON as the body; an empty **200** for an action without `success`                                                                                          | `isError: false`, `structuredContent` its JSON, and the same JSON as one text block; both `null` for an action without `success`                                                                                                                                                   | the call's success                                                                                          | a result with `isFailure: false`: `result` the value, `encodedResult` its JSON                                                | its JSON on stdout, indented, or `render`'s text; nothing for an action without `success`                                 |
+| Input that does not decode                                             | **400** `InvalidInput`                                                                                                                                          | `isError: true`, text `Invalid parameters for tool '<name>': …`                                                                                                                                                                                                                    | the typed `InvalidInput`                                                                                    | a result with `isFailure: true`: `result` an `AiError` whose `reason` is a `ToolParameterValidationError`                     | `InvalidInput`'s JSON on stderr, exit 1; a missing flag or a rejected choice is Effect CLI's own parse error instead      |
+| Undeclared input field                                                 | refused, nested ones too: **400** `InvalidInput` naming its path                                                                                                | refused, as input that does not decode                                                                                                                                                                                                                                             | refused: `InvalidInput` naming its path                                                                     | **dropped**: the call runs without it                                                                                         | refused, in `--input` and in a flag's JSON value: `InvalidInput`                                                          |
+| Declared error                                                         | its JSON with its `httpApiStatus`, **422** without one                                                                                                          | `isError: true`, its JSON as one text block, no `structuredContent`                                                                                                                                                                                                                | the call's typed failure                                                                                    | a result with `isFailure: true`: `result` the error, `encodedResult` its JSON                                                 | its JSON on stderr; the command fails with a `UserError` whose `cause` is the error; exit 1 by default                    |
+| Protected action, credential missing or not verified                   | **401** `Unauthenticated` with the scheme's challenge, or what the verifier fails with, before the body is read; a public route reads no credential             | the same HTTP answer in place of a JSON-RPC one, before the arguments are decoded; on an endpoint that also serves a public tool, that tool's call and `tools/list` need no credential, but one a request presents is still verified ([Protect tools](ActionMcp.md#protect-tools)) | the typed `Unauthenticated`, or what the verifier fails with, before the payload is decoded; never a status | no credential: the host provides the identity around the call ([Name the caller](ActionToolkit.md#name-the-caller))           | no credential: the host provides the identity to the command ([Name the caller](ActionCli.md#name-the-caller))            |
+| `Unauthenticated` or `Forbidden` from the authorizer or a handler      | its JSON with **401** or **403**, after the input is decoded; on a protected route under Bearer, a 401 and a `Forbidden` naming `scopes` also carry a challenge | `isError: true`, its JSON as text, in a **200** over HTTP; on an endpoint under Bearer, a protected tool's step-up refusal is the HTTP **401** or **403** instead, with its JSON and challenge, unless a handler's notification has started the response                           | the call's typed failure; never a status or a challenge                                                     | a result with `isFailure: true`, as a declared error                                                                          | as a declared error                                                                                                       |
+| Defect, undeclared failure, or a success or error that does not encode | an empty **500**                                                                                                                                                | `isError: true`, text `Tool execution failed due to an internal server error.`                                                                                                                                                                                                     | that call's defect, an `Error` whose message is `Internal server error`; the connection's other calls go on | a defect or a rejected failure is the call's defect; the rest fail it with an `AiError`, `Failed to encode result for tool …` | an accepted error that does not encode is a `UserError` printed as its tag and message; the rest are the command's defect |
+| Unknown path, method or name                                           | a path no layer serves, or a method other than `POST` on a route: **404**                                                                                       | another HTTP method: an empty **405** with `Allow: POST, DELETE`, signed out the **401** of an endpoint with authentication; an unknown tool: a JSON-RPC error `-32602`, with **200** over HTTP                                                                                    | an rpc the layer does not serve ends its call with `Unknown request tag`                                    | Effect's own                                                                                                                  | Effect CLI's own                                                                                                          |
+| Body that is not JSON, or not typed as JSON                            | not JSON: **400** `InvalidInput`; `Content-Type` missing or not JSON: **415**; both after authentication on a protected route                                   | not JSON: a JSON-RPC error `-32700` with **200**; `Content-Type` missing or not JSON: an empty **415**; over stdio, a line that is not JSON goes unanswered                                                                                                                        | the protocol's own                                                                                          | —                                                                                                                             | a flag or `--input` that is not the JSON its field takes: `InvalidInput`                                                  |
+
+- **Typed clients.** `ActionHttp.client`, `ActionRpc.client`, `ActionMcp.client` and `Action.client` fail with a declared or built-in error as its decoded value. Each drops undeclared fields as it encodes an input, since TypeScript lets a wider value through, and fails with `InvalidInput` for an input that does not encode, sending nothing. `Action.client` has no wire but passes input, success and failure through the same JSON codecs; an undeclared failure or a success that does not encode is its call's defect. Over MCP a verifier's declared error is the endpoint's HTTP answer: `ActionMcp.client` decodes it given the endpoint's `authentication`, and fails with an `McpCallError` without.
 - **An action without input** takes `{}` and nothing else, on every surface. Over HTTP, send the body `{}` typed as JSON: no body is a **400**, and no `Content-Type` a **415**.
 - **A media field**, `Action.Image`, is `{ "data": "<base64>", "mimeType": "image/png" }` inside the JSON on every surface but MCP, which lifts it out of `structuredContent` into a block of its own: [Return images and other media](ActionMcp.md#return-images-and-other-media).
+- **A failure the action's errors reject**, undeclared or breaking a check, is its call's defect on every surface, beside the `SchemaError` saying why. A class error's checks are not rerun: one built with `disableChecks` is accepted, and fails to encode instead.
 - **Internal failures are never sent.** The cause of a defect goes to the log and, over HTTP, MCP and RPC, to the call's `ErrorReporter`s: those the server runs with, as provided around `HttpRouter.serve` or `Testing.layer`, win over those provided to one surface's layer, which only fill in what a request lacks.
 - **Messages for invalid input.** A message for input that does not decode names paths and what the schema expects, never a field's value. A path names every key it passes through, a record's keys and an undeclared key included, so never key a record by a secret such as an email or a token. A schema's own `message` annotation, or a filter's message, is sent as written, so never put the input in one.
 - **Earlier MCP revisions.** The MCP column is MCP 2026-07-28. A 2025-11-25 or 2025-06-18 client, over HTTP or stdio, gets `structuredContent` only for a success that is an object, and any other success as its text block alone, a string unquoted; a 2025-06-18 client gets invalid arguments as a JSON-RPC error instead of a result. Over HTTP such a client opens a session, which on an endpoint serving a protected tool only a signed-in caller does: it signs in for every request there, a public tool's call and `tools/list` included. Stdio authenticates nothing: the host provides the identity around `runStdio` ([Serve tools over stdio](ActionMcp.md#serve-tools-over-stdio)).
@@ -38,6 +39,6 @@ What the library does not do, where a reader might expect it to:
 - **Limit requests.** A rate limit is the handler's, failing with an error its action declares, or middleware's.
 - **Allow browsers across origins.** CORS for JSON routes is the host's, with `HttpRouter.cors`; an MCP endpoint refuses a browser `Origin` it does not list ([Allow browser clients](ActionMcp.md#allow-browser-clients)).
 - **Stream, upload or retry.** Actions are unary JSON calls. One decoded input, one success or one declared error. Every HTTP route is a `POST`, a read-only action's included; RPC needs a protocol speaking JSON.
-- **Expire MCP sessions, or serve MCP features other than tools.** A session a client of a 2025 revision opens over HTTP lasts until that client ends it or the process stops ([Serve tools over HTTP](ActionMcp.md#serve-tools-over-http)). Prompts and resources are Effect's native ones, given as `features` ([Add native prompts and resources](ActionMcp.md#add-native-prompts-and-resources)).
+- **Expire MCP sessions, or serve MCP features other than tools.** A session a client of a 2025 revision opens over HTTP lasts until that client ends it or the process stops, and a `requestScoped` endpoint opens none ([Serve tools over HTTP](ActionMcp.md#serve-tools-over-http)). Prompts and resources are Effect's native ones, given as `features` ([Add native prompts and resources](ActionMcp.md#add-native-prompts-and-resources)).
 - **Mix identities.** An action names one identity service, and a remote surface one authentication descriptor.
 - **Harden a deployment.** Real token validation, request limits and error reporting are the application's. The examples mark each shortcut they take `DEMO ONLY`: [examples](../examples/README.md).

package/examples/kitchen-sink/README.md

@@ -226,16 +226,20 @@ search for in the file.
 
 ### ActionMcp
 
-| Export or option                                 | File                                                |
-| ------------------------------------------------ | --------------------------------------------------- |
-| `layerHttp`, public and protected tools together | `src/routes.ts` (`mcp`)                             |
-| `layerHttp`: `authentication`, `instructions`    | `src/routes.ts` (`mcp`)                             |
-| `layerHttp`: `actions`, one action left off      | `src/routes.ts` (`mcp`), `src/Actions.ts` (`Tools`) |
-| `layerHttp`: `allowedOrigins`                    | `src/routes.ts` (`mcp`), `test/routes.test.ts`      |
-| `layerHttp`: `features`, a resource and a prompt | `src/issues/guide.ts`                               |
-| CORS for a browser MCP client                    | `src/request-policy.ts` (`cors`)                    |
-| `runStdio`, the host naming the caller           | `src/stdio.ts`                                      |
-| An image block from a media field                | `src/attachments/Attachments.ts` (`GetAttachment`)  |
+| Export or option                                 | File                                                          |
+| ------------------------------------------------ | ------------------------------------------------------------- |
+| `layerHttp`, public and protected tools together | `src/routes.ts` (`mcp`)                                       |
+| `layerHttp`: `authentication`, `instructions`    | `src/routes.ts` (`mcp`)                                       |
+| `layerHttp`: `actions`, one action left off      | `src/routes.ts` (`mcp`), `src/Actions.ts` (`Tools`)           |
+| `layerHttp`: `allowedOrigins`                    | `src/routes.ts` (`mcp`), `test/routes.test.ts`                |
+| `layerHttp`: `features`, a resource and a prompt | `src/issues/guide.ts`                                         |
+| CORS for a browser MCP client                    | `src/request-policy.ts` (`cors`)                              |
+| `runStdio`, the host naming the caller           | `src/stdio.ts`                                                |
+| An image block from a media field                | `src/attachments/Attachments.ts` (`GetAttachment`)            |
+| `client`: `transformClient`                      | `test/routes.test.ts`                                         |
+| `client`, decoding an image                      | `test/attachments/attachments.test.ts`                        |
+| `client`: `authentication`, a verifier's error   | `test/identity/identity.test.ts`                              |
+| `request`: `headers`, `url`                      | `test/attachments/attachments.test.ts`, `test/routes.test.ts` |
 
 ### ActionRpc
 
@@ -271,22 +275,18 @@ search for in the file.
 
 ### Testing
 
-| Export or option                                 | File                                                          |
-| ------------------------------------------------ | ------------------------------------------------------------- |
-| `layer(routes)`                                  | `test/identity/identity.test.ts`                              |
-| `layer(routes)`, twice, over shared builders     | `test/routes.test.ts` (`shared`)                              |
-| `layer(handler)`, over `HttpRouter.toWebHandler` | `test/request-policy.test.ts`                                 |
-| `mcpClient`: `transformClient`                   | `test/routes.test.ts`                                         |
-| `mcpClient`, decoding an image                   | `test/attachments/attachments.test.ts`                        |
-| `McpCallError`                                   | `test/identity/identity.test.ts`                              |
-| `mcpRequest`: `headers`, `url`                   | `test/attachments/attachments.test.ts`, `test/routes.test.ts` |
-| RPC in memory, over Effect's HTTP protocol       | `test/identity/session.test.ts`                               |
-| A service the test and the routes both read      | `test/identity/session.test.ts` (`served`)                    |
-| A test replacing one service                     | `test/identity/identity.test.ts` (`servedWith`)               |
-| `Action.client`, a caller per call               | `test/issues/issues.test.ts`                                  |
-| A scripted `LanguageModel`                       | `test/issues/assistant.test.ts`, `test/support/scripted.ts`   |
-| A test replacing the model the routes are given  | `test/assistant/assistant.test.ts` (`served`)                 |
-| An error's message asserted beside its fields    | `test/issues/issues.test.ts`                                  |
+| Export or option                                 | File                                                        |
+| ------------------------------------------------ | ----------------------------------------------------------- |
+| `layer(routes)`                                  | `test/identity/identity.test.ts`                            |
+| `layer(routes)`, twice, over shared builders     | `test/routes.test.ts` (`shared`)                            |
+| `layer(handler)`, over `HttpRouter.toWebHandler` | `test/request-policy.test.ts`                               |
+| RPC in memory, over Effect's HTTP protocol       | `test/identity/session.test.ts`                             |
+| A service the test and the routes both read      | `test/identity/session.test.ts` (`served`)                  |
+| A test replacing one service                     | `test/identity/identity.test.ts` (`servedWith`)             |
+| `Action.client`, a caller per call               | `test/issues/issues.test.ts`                                |
+| A scripted `LanguageModel`                       | `test/issues/assistant.test.ts`, `test/support/scripted.ts` |
+| A test replacing the model the routes are given  | `test/assistant/assistant.test.ts` (`served`)               |
+| An error's message asserted beside its fields    | `test/issues/issues.test.ts`                                |
 
 ## Not shown
 

package/examples/kitchen-sink/test/attachments/attachments.test.ts

@@ -4,6 +4,7 @@ import { Array, Effect, flow, Layer } from "effect";
 import { HttpClient, HttpClientRequest } from "effect/http";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
 import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
 import * as Testing from "@gjermundgaraba/effect-actions/Testing";
 import { Http } from "../../src/Api.js";
 import { GetAttachment } from "../../src/attachments/Attachments.js";
@@ -42,7 +43,7 @@ describe("attachments, over HTTP and MCP", () => {
     Effect.gen(function* () {
       const attachment = yield* attached;
       const http = yield* ActionHttp.client(Http, as("ada", "acme"));
-      const mcp = yield* Testing.mcpClient([GetAttachment], as("ada", "acme"));
+      const mcp = yield* ActionMcp.client([GetAttachment], as("ada", "acme"));
 
       expect(attachment).toMatchObject({ name: "crash.png", mimeType: "image/png", size: 68 });
 
@@ -56,7 +57,7 @@ describe("attachments, over HTTP and MCP", () => {
       // As sent: the tool's result holds the rest of the success as JSON, and the image as a
       // content block of its own, which a model receives as an image.
       const call = yield* HttpClient.execute(
-        Testing.mcpRequest(
+        ActionMcp.request(
           "tools/call",
           { name: "getAttachment", arguments: { id: attachment.id } },
           { headers: { authorization: "Bearer ada", "x-workspace": "acme" } },

package/examples/kitchen-sink/test/identity/identity.test.ts

@@ -3,10 +3,11 @@ import { Array, Effect, flow, Layer } from "effect";
 import { HttpClient, HttpClientRequest } from "effect/http";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
 import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
 import * as Testing from "@gjermundgaraba/effect-actions/Testing";
 import { Http } from "../../src/Api.js";
 import { Directory } from "../../src/identity/directory.js";
-import { IssuerUnavailable, QuotaExceeded, WhoAmI } from "../../src/identity/Identity.js";
+import { IssuerUnavailable, Login, QuotaExceeded, WhoAmI } from "../../src/identity/Identity.js";
 import { memory } from "../../src/memory.js";
 import { publicRoutes } from "../../src/routes.js";
 
@@ -97,7 +98,7 @@ describe("a bearer token", () => {
 
       // A protected tool's call without a token: the endpoint's own 401, before any tool runs.
       const refused = yield* HttpClient.execute(
-        Testing.mcpRequest("tools/call", { name: "whoAmI", arguments: {} }),
+        ActionMcp.request("tools/call", { name: "whoAmI", arguments: {} }),
       );
 
       expect(refused.status).toBe(401);
@@ -110,14 +111,20 @@ describe("a bearer token", () => {
   it.effect("fails with the verifier's declared error, a typed 503, when the issuer is down", () =>
     Effect.gen(function* () {
       const http = yield* ActionHttp.client(Http, as("ada", "acme"));
-      const mcp = yield* Testing.mcpClient([WhoAmI], as("ada", "acme"));
+
+      // Over MCP it is the endpoint's HTTP answer, before any tool runs, not a tool's result: the
+      // client decodes it given the descriptor the endpoint serves with.
+      const mcp = yield* ActionMcp.client([WhoAmI], {
+        ...as("ada", "acme"),
+        authentication: Login,
+      });
 
       expect(yield* Effect.flip(http.whoAmI())).toEqual(
         new IssuerUnavailable({ retryAfterSeconds: 30 }),
       );
-      // Over MCP it is the endpoint's HTTP answer, before any tool runs, not a tool's result:
-      // the client fails with the error that holds such an answer.
-      expect(yield* Effect.flip(mcp.whoAmI())).toBeInstanceOf(Testing.McpCallError);
+      expect(yield* Effect.flip(mcp.whoAmI())).toEqual(
+        new IssuerUnavailable({ retryAfterSeconds: 30 }),
+      );
     }).pipe(Effect.provide(servedWith(issuerDown))),
   );
 });

package/examples/kitchen-sink/test/routes.test.ts

@@ -3,6 +3,7 @@ import { Effect, flow, Layer } from "effect";
 import { HttpClient, HttpClientRequest } from "effect/http";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
 import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
 import * as Testing from "@gjermundgaraba/effect-actions/Testing";
 import { Tools } from "../src/Actions.js";
 import { AdminHttp, Http } from "../src/Api.js";
@@ -43,7 +44,7 @@ describe("the public port", () => {
 
   it.effect("lists the tools to a signed-out MCP client, the unlisted action left out", () =>
     Effect.gen(function* () {
-      const listing = yield* HttpClient.execute(Testing.mcpRequest("tools/list"));
+      const listing = yield* HttpClient.execute(ActionMcp.request("tools/list"));
       const text = yield* listing.text;
 
       expect(listing.status).toBe(200);
@@ -55,7 +56,7 @@ describe("the public port", () => {
   it.effect("serves one store to both surfaces: an issue filed over HTTP is read as a tool", () =>
     Effect.gen(function* () {
       const http = yield* ActionHttp.client(Http, ada);
-      const mcp = yield* Testing.mcpClient(Tools, ada);
+      const mcp = yield* ActionMcp.client(Tools, ada);
       const issue = yield* http.createIssue({ title: "Crash", body: "On save." });
 
       expect(yield* mcp.getIssue({ id: issue.id })).toEqual(issue);
@@ -66,7 +67,7 @@ describe("the public port", () => {
     Effect.gen(function* () {
       // The request policy lets both through: one is the request's own origin, one is listed.
       const from = (url: string, origin: string) =>
-        HttpClient.execute(Testing.mcpRequest("tools/list", {}, { url, headers: { origin } }));
+        HttpClient.execute(ActionMcp.request("tools/list", {}, { url, headers: { origin } }));
 
       const listed = yield* from("/mcp", "http://localhost:6274");
       const sameHost = yield* from("http://127.0.0.1/mcp", "http://127.0.0.1");

package/examples/live-rpc/README.md

@@ -7,6 +7,9 @@ identity of its own. A message naming no room is about the default one, `lobby`.
 
 Start here if a client keeps a connection open and calls often, or if the application already
 speaks Effect RPC. For a JSON API or MCP tools, start from [notes-service](../notes-service/).
+To serve these same actions as JSON too, see
+[ActionRpc.md](../../docs/ActionRpc.md#serve-the-rpcs): kitchen-sink's `src/routes.ts` and
+`src/server.ts` merge both.
 Actions are unary, so nothing streams: the page reads again, passing the last id it holds.
 
 ## Run it
@@ -28,10 +31,10 @@ Effect program, `connect(url)` for one that calls with promises. The tokens are
 
 ## When you copy this
 
-Three choices here show a feature. Decide each for your application before keeping it:
+Four choices here show a feature. Decide each for your application before keeping it:
 
 - **`listRooms` is public** to show a public rpc beside protected ones. It tells a signed-out
-  caller every room's name.
+  caller every room's name and how many messages it holds; a room appears once someone posts.
 - **A message naming no room is about `lobby`**, to show a default in request context. Yours may
   refuse instead.
 - **The room is a header, not an input**, because `authorize` sees the action and not its input:
@@ -39,6 +42,8 @@ Three choices here show a feature. Decide each for your application before keepi
   check belongs in the store, never in a helper each handler must remember to call: the store's
   method takes the member and refuses, as `MessageStore.remove` in `src/chat/store.ts` takes the
   author and refuses with `NotAuthor`.
+- **`browser.ts` takes a message already gone as removed**, `MessageNotFound` included, since
+  that is what the page asked for. Yours may tell the user it was not there.
 
 ## Layout
 

package/examples/mcp-tools/test/routes.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from "@effect/vitest";
 import { ConfigProvider, Effect, Layer, Schema } from "effect";
 import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/http";
+import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
 import * as Testing from "@gjermundgaraba/effect-actions/Testing";
 import { fakeFarm, picture } from "../src/printers/fake.js";
 import { PrintFarm } from "../src/printers/farm.js";
@@ -59,7 +60,7 @@ describe("the tools, over MCP", () => {
   it.effect("lists every tool with the hints its contract states", () =>
     Effect.gen(function* () {
       // A raw request, for what no typed client shows: here, the listing itself.
-      const response = yield* HttpClient.execute(Testing.mcpRequest("tools/list"));
+      const response = yield* HttpClient.execute(ActionMcp.request("tools/list"));
       const { result } = yield* HttpClientResponse.schemaBodyJson(Listed)(response);
 
       const hints = (readOnlyHint: boolean, destructiveHint: boolean, idempotentHint: boolean) => ({
@@ -97,7 +98,7 @@ describe("the tools, over MCP", () => {
     Effect.gen(function* () {
       // A client method per tool: it sends `tools/call` and decodes the result, the image
       // from its image block, as the handler returned it.
-      const mcp = yield* Testing.mcpClient(Printers);
+      const mcp = yield* ActionMcp.client(Printers);
 
       expect(yield* mcp.get_camera_snapshot({ printer_id: "mk4-1" })).toEqual({
         printer: {
@@ -113,7 +114,7 @@ describe("the tools, over MCP", () => {
 
   it.effect("answers the farm's refusal as the tool's declared error, message and all", () =>
     Effect.gen(function* () {
-      const mcp = yield* Testing.mcpClient(Printers);
+      const mcp = yield* ActionMcp.client(Printers);
       const error = yield* Effect.flip(mcp.get_camera_snapshot({ printer_id: "mini-1" }));
 
       expect(error).toBeInstanceOf(PrintFarmError);
@@ -124,7 +125,7 @@ describe("the tools, over MCP", () => {
   it.effect("accepts the browser origins the configuration lists, and no other", () =>
     Effect.gen(function* () {
       const from = (origin: string) =>
-        HttpClient.execute(Testing.mcpRequest("tools/list", {}, { headers: { origin } }));
+        HttpClient.execute(ActionMcp.request("tools/list", {}, { headers: { origin } }));
 
       expect((yield* from("https://console.example.test")).status).toBe(200);
       expect((yield* from("https://wall.example.test")).status).toBe(200);
@@ -142,7 +143,7 @@ describe("the tools, over MCP", () => {
       expect(asked.headers["access-control-allow-headers"]).toContain("MCP-Protocol-Version");
 
       const listed = yield* HttpClient.execute(
-        Testing.mcpRequest(
+        ActionMcp.request(
           "tools/list",
           {},
           { headers: { origin: "https://console.example.test" } },
@@ -170,7 +171,7 @@ describe("the tools, over MCP", () => {
       expect(asked.headers["access-control-allow-origin"]).toBe("https://console.example.test");
 
       const called = yield* HttpClient.execute(
-        Testing.mcpRequest(
+        ActionMcp.request(
           "tools/list",
           {},
           { headers: { origin: "https://elsewhere.example.test" } },

package/examples/notes-service/README.md

@@ -25,6 +25,10 @@ node --import tsx examples/notes-service/src/cli.ts list-notes
 node --import tsx examples/notes-service/src/cli.ts export notes.md   # a command written by hand
 node --import tsx examples/notes-service/src/cli.ts import notes.md   # one importNotes call
 
+# The stdio server, given one MCP 2026-07-28 request on stdin
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"getStatus","arguments":{},"_meta":{"io.modelcontextprotocol/clientCapabilities":{},"io.modelcontextprotocol/protocolVersion":"2026-07-28"}}}' |
+  node --import tsx examples/notes-service/src/stdio.ts
+
 vp test examples/notes-service
 ```
 
@@ -35,7 +39,9 @@ claude mcp add --transport http notes http://127.0.0.1:3000/mcp --header "Author
 codex mcp add notes --url http://127.0.0.1:3000/mcp --bearer-token-env-var NOTES_TOKEN
 ```
 
-`src/stdio.ts` is the other way in: a subprocess the host starts, with a store of its own.
+`src/stdio.ts` is another way in: a subprocess the host starts, with a store of its own.
+`src/worker.ts` serves the same routes as a `fetch` handler, for a serverless host such as
+Cloudflare Workers ([ActionMcp.md](../../docs/ActionMcp.md#serve-tools-over-http)).
 
 The server reads `HOST` (default `127.0.0.1`), `PORT` (default 3000) and `PUBLIC_URL`, the
 address it tells OAuth clients it is at; the CLI reads `NOTES_URL` and `NOTES_TOKEN`. Change the port and set all three to match.
@@ -64,6 +70,7 @@ src/
 ├── Api.ts             the HTTP binding of every domain's actions
 ├── routes.ts          every surface of the host: /api, /mcp, /healthz, the OpenAPI document
 ├── server.ts          entrypoint: the HTTP server
+├── worker.ts          entrypoint: a fetch handler for a serverless host
 ├── stdio.ts           entrypoint: MCP for a local agent
 ├── commands.ts        the commands calling the server, one written by hand, and their connection
 ├── cli.ts             entrypoint: the commands, given that connection
@@ -71,6 +78,7 @@ src/
 test/
 ├── notes/             in process, with Action.client
 ├── routes.test.ts     over HTTP and MCP in memory, with Testing.layer
+├── worker.test.ts     the worker's own fetch handler, with Testing.layer
 └── commands.test.ts   the commands and their connection, against the same routes in memory
 ```
 
@@ -81,8 +89,9 @@ test/
   on the server, each named for its role, never the domain: `notes.ts` beside `Notes.ts` is one
   file on a disk that ignores case (TS1149).
 - **One entrypoint per way of running it.** Each chooses its own implementations: `server.ts`
-  picks the store and the HTTP server, `stdio.ts` names the local user, a test provides its own
-  store. Nothing below an entrypoint knows which it got.
+  picks the store and the HTTP server, `worker.ts` the routes for a serverless host, `stdio.ts`
+  names the local user, a test provides its own store. Nothing below an entrypoint knows which
+  it got.
 - **In a monorepo** the contract files and `Api.ts` are the package the server, the CLI and the
   website all depend on; the lowercase files and `routes.ts` are the server.
 
@@ -99,6 +108,7 @@ test/
 | One implementation served over HTTP and MCP                   | `src/routes.ts`                  |
 | Config, a body limit and the host's own routes                | `src/server.ts`, `src/routes.ts` |
 | The same actions over stdio, the host naming the caller       | `src/stdio.ts`                   |
+| A serverless entrypoint, the MCP endpoint `requestScoped`     | `src/worker.ts`, `src/routes.ts` |
 | A CLI derived from the binding: an argument, a field on stdin | `src/commands.ts`                |
 | A command written by hand beside the derived ones             | `src/commands.ts`                |
 | A bulk import as one action, its command reading a file       | `src/notes/`, `src/commands.ts`  |

package/examples/notes-service/src/notes/Notes.ts

@@ -83,7 +83,8 @@ export const UpdateNote = Action.make("updateNote", {
   readOnly: false,
   caller: CurrentUser,
   // No `destructiveHint`: an update replaces the body, so it is destructive, MCP's default for
-  // a write. `createNote` and `importNotes`, which only add, say `false`.
+  // a write, as is any update of what is stored, a flag such as "read" included.
+  // `createNote` and `importNotes`, which only add, say `false`.
 });
 
 export const DeleteNote = Action.make("deleteNote", {
@@ -98,12 +99,13 @@ export const DeleteNote = Action.make("deleteNote", {
 // tools and the CLI then all have it, and the whole list is decoded, so checked, before the
 // handler writes any of it. A command of your own only reads the file and calls this once
 // (commands.ts). `importNotes` adds and removes nothing, so `destructiveHint` is `false`.
+// Each note is `createNote`'s input: an action's `input` is a schema already, used as it is.
 export const ImportNotes = Action.make("importNotes", {
   description:
     "Create several notes at once, such as those `notes export` wrote. Every note is checked " +
     "before any is written: an import holding one that is not valid writes none.",
   input: {
-    notes: Schema.Array(Schema.Struct({ title: Title, body: Body }))
+    notes: Schema.Array(CreateNote.input)
       .check(
         Schema.isMinLength(1, { message: "An import holds at least one note." }),
         Schema.isMaxLength(100, { message: "An import holds at most 100 notes." }),

package/examples/notes-service/src/routes.ts

@@ -17,17 +17,6 @@ const implementations = [status, notes, identity];
 // reads its body; `getStatus` answers anyone.
 const api = ActionHttp.layer(Http, implementations);
 
-// The same actions as MCP tools at `/mcp`. Listing the tools and calling `getStatus` need no
-// token, because `getStatus` is public: an endpoint of protected tools alone asks a token for
-// the listing too. Any other call answers 401 with where to sign in, and so does a client of
-// an MCP revision with sessions when it opens one, since a session may call any tool.
-const mcp = ActionMcp.layerHttp(implementations, {
-  name: "notes-service",
-  version: "1.0.0",
-  instructions: "Notes belong to the signed-in user. Read a note before updating it.",
-  authentication: Login,
-});
-
 // The host's own routes sit beside the actions' on the same router.
 const health = HttpRouter.add("GET", "/healthz", HttpServerResponse.text("ok"));
 
@@ -40,6 +29,27 @@ const openApi = HttpRouter.add(
   HttpServerResponse.jsonUnsafe(OpenApi.fromApi(Http.api)),
 );
 
-// What the host serves. It still requires `NoteStore`: the entrypoint chooses which one, and a
-// test chooses its own.
-export const routes = Layer.mergeAll(api, mcp, health, openApi).pipe(Layer.provide(authenticate));
+// What the host serves: the JSON routes, the same actions as MCP tools at `/mcp`, and the host's
+// own routes. Listing the tools and calling `getStatus` need no token, because `getStatus` is
+// public: an endpoint of protected tools alone asks a token for the listing too. Any other call
+// answers 401 with where to sign in, and so does a client of an MCP revision with sessions when
+// it opens one, since a session may call any tool. It still requires `NoteStore`: the entrypoint
+// chooses which one, and a test chooses its own. The entrypoint also chooses how the MCP
+// endpoint runs: one server for every request, or one per request.
+const serving = (requestScoped: boolean) =>
+  Layer.mergeAll(
+    api,
+    ActionMcp.layerHttp(implementations, {
+      name: "notes-service",
+      version: "1.0.0",
+      instructions: "Notes belong to the signed-in user. Read a note before updating it.",
+      authentication: Login,
+      requestScoped,
+    }),
+    health,
+    openApi,
+  ).pipe(Layer.provide(authenticate));
+
+export const routes = serving(false);
+
+export const requestScopedRoutes = serving(true);

package/examples/notes-service/src/worker.ts

@@ -0,0 +1,20 @@
+import { Layer } from "effect";
+import { HttpRouter, HttpServer } from "effect/http";
+import { NoteStore } from "./notes/store.js";
+import { requestScopedRoutes } from "./routes.js";
+
+// Entrypoint for a host that calls `fetch` per request and runs nothing between requests, such
+// as Cloudflare Workers, which takes this default export. The handler is built once, when the
+// module loads, as Effect's `HttpRouter.toWebHandler` asks on Workers: a build started inside
+// `fetch` would belong to that request. Building these routes does no I/O, which Workers refuses
+// outside a request. `toWebHandler` reads no `MaxBodySize`, so the host limits request bodies.
+const app = HttpRouter.toWebHandler(
+  requestScopedRoutes.pipe(
+    // DEMO ONLY: each instance of the worker holds notes of its own, lost when it stops. A
+    // deployment provides a store every instance reaches.
+    Layer.provide(NoteStore.layerMemory),
+    Layer.provide(HttpServer.layerServices),
+  ),
+);
+
+export default { fetch: (request: Request) => app.handler(request) };