@gjermundgaraba/effect-actions 0.5.0 → 0.7.0

package/docs/ActionGroup.md

@@ -15,18 +15,20 @@ Import `@gjermundgaraba/effect-actions/ActionGroup`.
 | `app.group`, `app.build`          | Bound contract and scoped handler acquisition.                                          |
 | `contracts(...groups)`            | Exact action types keyed by `<group>.<action>`.                                         |
 
-Exported types: `Group`, `Any`, `Options`, `Implementation`, `Contracts`, `SchemaErrorPolicy`.
+Exported types: `Group`, `Any`, `Options`, `Implementation`, `Contracts`, `SchemaErrorPolicy`,
+`SchemaErrorAnswer`.
 
-The optional `schemaError` group option contains `errors` (policy error codecs) and
-`map(failure)` (a native `HttpApiSchemaError` to one of their decoded values). It affects HTTP only.
-Handler records require every action key. Each handler's input, success and declared errors
-come from its action; request requirements stay distinct from the builder's requirements.
+The optional `schemaError` group option is a `SchemaErrorPolicy`: two answers, `invalid` and
+`internal`, each a `schema` (a declared error codec) and `make(failure)` (the native
+`HttpApiSchemaError` to that error's decoded value). The library decides which answer applies.
+It affects HTTP only. Handler records require every action key. Each handler's input, success
+and declared errors come from its action; request requirements stay distinct from the
+builder's requirements.
 
 ## Canonical
 
 ```ts
 import { Effect, Schema } from "effect";
-import type { HttpApiError } from "effect/unstable/httpapi";
 import * as ActionGroup from "@gjermundgaraba/effect-actions/ActionGroup";
 import { CurrentActor } from "./auth.js";
 import { GetUser, RenameUser, WhoAmI } from "./contracts.js";
@@ -43,13 +45,17 @@ class InternalError extends Schema.TaggedError<InternalError>()(
   { httpApiStatus: 500 },
 ) {}
 
-// Shared across groups: annotate the parameter. Inline, `map` is inferred from `errors`.
+// A request that does not decode is the caller's fault; a result that does not
+// encode is the server's. Shared across groups as a constant.
 const schemaError = {
-  errors: [InvalidRequest, InternalError],
-  map: ({ kind }: HttpApiError.HttpApiSchemaError) =>
-    kind === "Body" || kind === "ResponseHeaders"
-      ? new InternalError({ message: "The request could not be completed." })
-      : new InvalidRequest({ message: "The request does not match the action's input." }),
+  invalid: {
+    schema: InvalidRequest,
+    make: () => new InvalidRequest({ message: "The request does not match the action's input." }),
+  },
+  internal: {
+    schema: InternalError,
+    make: () => new InternalError({ message: "The request could not be completed." }),
+  },
 };
 
 export const UserActions = ActionGroup.make(
@@ -87,7 +93,7 @@ const renames: "renameUser" = contracts["users.renameUser"].name;
 
 - `name` matches `[A-Za-z0-9_-]+`, cannot be `then`, and must be unique within one `ActionHttp.make`. Action names must be unique within the group. MCP tool names must be unique within the group and within each Toolkit or MCP projection that serves it. Duplicates fail at `make`.
 - Group `errors` are appended to each action's own `errors`, so every handler of the group may fail with them. A failure that only the surface produces belongs on the adapter instead (`ActionHttp.make`'s `errors`, `ActionMcp`'s and `ActionToolkit`'s `errors`), not here.
-- `implement` takes a complete record or an Effect producing one. Every action must have a handler; missing keys are compile errors. Additional keys are not dispatched. It takes nothing else.
+- `implement` takes a complete plain record or an Effect producing one. Every action must have a handler; missing keys are compile errors. A handler is an own-property function of the record: an inherited one, such as a class instance's method, does not count. A record that still lacks one at runtime (plain JavaScript, a cast: a missing key, `undefined`, any other non-function, an inherited method) throws at `implement`; a builder's record fails the adapter layer's build. Nothing is served with a handler missing. Handlers are called without a receiver. Additional keys are not dispatched. It takes nothing else.
 - The builder Effect runs once per adapter layer that serves the implementation, in that layer's scope. An implementation served by HTTP and MCP is built twice. Acquire shared state in a Layer you provide to the adapters, not in the builder.
 - Services yielded in the builder are build-time requirements (`RX`). Services yielded in a handler are request-time requirements (`R` of the handler). Adapters keep these separate in their types. Use distinct tags for each kind; never provide a request-identity tag at startup (see [guarantees.md](guarantees.md)).
 - `Implementation` is nominal. Spreading its properties does not produce an implementation. Each `implement` call is a separate binding.
@@ -97,8 +103,9 @@ const renames: "renameUser" = contracts["users.renameUser"].name;
 ### Schema-error policy
 
 - Without a policy, HTTP answers decoding and encoding failures with Effect's native empty 400.
-- With a policy, `map` receives the native `HttpApiSchemaError` (`kind`, `cause`) and returns one of `errors`. HTTP uses that error's `httpApiStatus`, and the error appears in `Http.api`, in clients, and in OpenAPI.
-- `kind` values: `Payload` (input decoding) and `Body` (success encoding). Actions declare no parameters, query, or headers, so no other kind occurs.
+- With a policy, the library picks the answer from the native `HttpApiSchemaError`'s `kind`. Request-side kinds (`Payload`, `Params`, `Headers`, `Query`: the request did not decode) get `invalid`; response-side kinds (`Body`, `ResponseHeaders`: the handler's result did not encode) get `internal`. `make` receives the failure (`kind`, `cause`) and returns its schema's value. HTTP uses that error's `httpApiStatus`, and both errors appear in `Http.api`, in clients, and in OpenAPI.
+- In practice only `Payload` and `Body` occur: actions declare no parameters, query, or headers, and no response headers.
+- `invalid` and `internal` may share one schema; it is declared once.
 - MCP is unaffected. The native `McpServer` answers invalid arguments and unencodable results itself.
 - Policy errors extend the transport contract, not the handler contract. A handler cannot return them.
 - The policy runs only on the server. Client-side codec failures stay `SchemaError`.
@@ -113,6 +120,7 @@ const renames: "renameUser" = contracts["users.renameUser"].name;
 - `Property 'x' is missing in type` at `implement`: the record lacks a handler for action `x`.
 - Handler compiles but returns an error not in `errors`: type error on the handler's error channel. Declare it on the action or the group.
 - `Expected 1 arguments, but got 2` at `implement`: the second options object is gone. Move `before` to the adapter that serves the group.
-- `map` is not typed from `errors` when declared as a standalone constant: annotate its parameter as `HttpApiError.HttpApiSchemaError` (type import from `effect/unstable/httpapi`).
+- `Parameter 'failure' implicitly has an 'any' type` in a standalone policy constant: a `make` that reads the failure is typed only inline. Annotate the parameter as `HttpApiError.HttpApiSchemaError` (type import from `effect/unstable/httpapi`), or annotate the constant as `ActionGroup.SchemaErrorPolicy<typeof Invalid, typeof Internal>`.
+- `Missing handlers for group "<group>": <actions>` thrown at `implement`, or failing the layer build: the handler record has no own-property function for those actions. Add them to the record itself, not to a prototype.
 - A service is resolved once and shared across requests when it should be per request: it was yielded in the builder. Move the `yield*` into the handler.
 - `Duplicate contract group` thrown by `contracts`: two groups share a name, so their keys would collide. Rename one.

package/docs/ActionHttp.md

@@ -13,6 +13,7 @@ Import `@gjermundgaraba/effect-actions/ActionHttp`.
 | `Http.groups`                | The exact bound contracts, in declaration order.                                     |
 | `Http.api`                   | Native Effect `HttpApi` for clients and OpenAPI.                                     |
 | `Http.layer(apps, options?)` | Serve a readonly collection of implementations; omit options when no hook is needed. |
+| `Http.openApi(path?)`        | Serve the OpenAPI document with `GET path`; defaults to `<apiPath>/openapi.json`.    |
 
 Exported types: `Options`, `LayerOptions`, `Http`, `Api`.
 
@@ -22,9 +23,8 @@ Exported types: `Options`, `LayerOptions`, `Http`, `Api`.
 | `make`: `errors`  | Surface error codecs declared on every endpoint; defaults to none.                                                                                          |
 | `layer`: `before` | Effectful hook receiving the selected `Action.Any`, after successful input decoding and before its handler. Failures must belong to the binding's `errors`. |
 
-Layer failures and startup requirements come from the supplied implementations that actually
-serve HTTP actions. Served handlers' and the hook's request services remain router request
-requirements; router/platform services are also required. No request identity is supplied at startup.
+Layer failures and startup requirements come from the supplied implementations. Every
+handler's and the hook's request services remain router request requirements; router/platform services are also required. No request identity is supplied at startup.
 
 Route shape: `POST <apiPath>/<group>/<action>`. Operation ID: `<group>.<action>`.
 
@@ -32,8 +32,7 @@ Route shape: `POST <apiPath>/<group>/<action>`. Operation ID: `<group>.<action>`
 
 ```ts
 import { Layer } from "effect";
-import { HttpRouter, HttpServerResponse } from "effect/unstable/http";
-import { HttpApiScalar, HttpApiSwagger, OpenApi } from "effect/unstable/httpapi";
+import { HttpApiScalar, HttpApiSwagger } from "effect/unstable/httpapi";
 import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
 import { PublicActions, UserActions } from "./contracts.js";
 import { PublicApp, UserApp } from "./handlers.js";
@@ -56,9 +55,9 @@ const routes = Layer.mergeAll(
   Http.layer([UserApp], { before: authorize }).pipe(Layer.provide(authentication.layer)),
 );
 
-// Documents are Effect's own, reading the same contract.
+// Documents are Effect's own, reading the same contract: `GET /api/actions/openapi.json`.
 const documentation = Layer.mergeAll(
-  HttpRouter.add("GET", "/openapi.json", HttpServerResponse.jsonUnsafe(OpenApi.fromApi(Http.api))),
+  Http.openApi(),
   HttpApiSwagger.layer(Http.api, { path: "/docs" }),
   HttpApiScalar.layer(Http.api, { path: "/reference" }),
 );
@@ -70,7 +69,8 @@ Serve with `HttpRouter.serve(layer).pipe(Layer.provide(NodeHttpServer.layer(crea
 
 ### Client
 
-The client is Effect's native grouped `HttpApiClient` over `Http.api`:
+The client is Effect's native grouped `HttpApiClient` over `Http.api`. Code that does not
+run Effects uses the Promise client in [ActionHttpClient.md](ActionHttpClient.md).
 
 ```ts
 import { HttpApiClient } from "effect/unstable/httpapi";
@@ -87,31 +87,33 @@ export const greeting = Effect.gen(function* () {
 
 ## Rules
 
+- HTTP serves every action of every group passed to `make`; an action has no HTTP switch. To keep an action off HTTP, put it in a group left out of `make` and serve that group elsewhere (MCP, Toolkit, CLI).
 - `apiPath` has no default. Group names must be unique within one `make`. Action names need only be unique within their group; equal action names in different groups do not collide.
 - `errors` declares the failures the surface around these endpoints answers with rather than a handler: authentication, authorization, rate limiting, upstream unavailability. They are added to every endpoint's error schemas, so `HttpApiClient`, `ActionCliClient` and the in-memory `Testing.httpClient` decode them as typed failures, and they appear in OpenAPI on every operation. A schema an action already declares is not repeated.
 - Schemas reachable from one endpoint must have distinct `_tag`s: the client decodes a response by trying the schemas declared for its status, and two errors may share a status. Effect unions them per status.
 - `errors` changes only what is declared. Nothing produces them: the middleware that renders those responses must encode a body that matches the schema, or the client sees a decode error again. Handlers cannot fail with them.
-- `Http.layer(apps, options?)` requires each implementation to reference the exact group object passed to `make`; reconstructing an equal-looking group is not sufficient. Each group may occur only once per call. Only supplied implementations are mounted, and a group with no HTTP-enabled actions is not built. Options are optional.
+- `Http.layer(apps, options?)` requires each implementation to reference the exact group object passed to `make`; reconstructing an equal-looking group is not sufficient. Each group may occur only once per call. Only supplied implementations are mounted, and a group without actions is not built. Options are optional.
 - `before` runs after successful native input decoding and before the selected handler. Invalid input skips the hook and handler. A refusal uses the binding's declared error schema and `httpApiStatus`; its services join handler request requirements. Admission that must precede decoding belongs in outer native HTTP middleware.
 - Middleware and the hook are per layer call. Groups that need different middleware or a different policy go in separate `Http.layer` calls, merged with `Layer.mergeAll`.
 - `ActionHttp` sets no response headers of its own. The host owns cache policy; `Authentication.middleware` marks its responses `cache-control: no-store`.
 - A hook refusal and a handler error are plain declared errors: a JSON body and a status, no other headers. Challenge headers such as `WWW-Authenticate` belong to the admission middleware that runs before the router reaches these routes (see [Authentication.md](Authentication.md)), which sets them on its own response.
 - Request-time handler services are `HttpRouter.Request.From<"Requires", R>`. Supply them with router middleware (`Authentication.middleware`, `HttpRouter.middleware`), `HttpRouter.provideRequest`, or the request context. Build-time services are ordinary layer requirements.
 - `Http.api` is a plain `HttpApi`. Anything Effect can do with an `HttpApi` works: `OpenApi.fromApi`, `HttpApiSwagger.layer`, `HttpApiScalar.layer`, `HttpApi.addHttpApi` to combine with other APIs, `HttpApiClient.make`.
+- `Http.openApi(path?)` is `OpenApi.fromApi(Http.api)` as one `GET` route, `<apiPath>/openapi.json` unless a path is given. It documents every bound group, not only the served ones. It is a plain route: middleware provided to its layer covers it, and nothing covers it otherwise.
 - Client calls always take `{ payload }`. No-input actions take `{ payload: {} }`. Pass `null` or `undefined` only when the codec accepts it. There is no flat client.
-- Client effects fail with the declared errors, the group's policy errors, the binding's `errors`, `SchemaError` for local codec failures, and native `HttpClientError`. MCP-only actions are absent from the client.
+- Client effects fail with the declared errors, the group's policy errors, the binding's `errors`, `SchemaError` for local codec failures, and native `HttpClientError`.
 - Add authentication headers with the native `transformClient` option. Use `HttpApiClient.makeWith` for custom error or service channels. Native per-call response modes are available.
 - Wire format without a policy: input failure is an empty 400, success is the encoded body, a declared error is its JSON encoding with its `httpApiStatus`, an encoding failure is an empty 400, a defect is an empty 500. Full table in [guarantees.md](guarantees.md).
 - Each handler runs in a span named `<group>.<action>`, a child of the request span, attributed with `action.group`, `action.name` and `action.access`; its log lines carry the same annotations. The hook, decoding and encoding are outside it, in the request span.
 
 ## Failure modes
 
-- Route returns 404: the implementation was never passed to `Http.layer`, or the action has `http: false`, or the path lacks the group segment.
+- Route returns 404: the implementation was never passed to `Http.layer`, or its group is not bound by `make`, or the path lacks the group segment.
 - Type error listing `HttpRouter.Request.From<"Requires", CurrentActor>` as unsatisfied: a handler yields a request service and no middleware provides it. Wrap that `Http.layer` call with the middleware's `.layer`.
 - Two groups share a name: `make` throws. Rename one.
 - `Implementation of group "x" is not served by this adapter`: `Http.layer` received an implementation whose group was not passed to `ActionHttp.make`. Implement the exact shared group object bound by `make`, or add a genuinely new group to the binding. Matching names and schemas do not establish identity.
 - `Duplicate implementation group: <name>`: a single `Http.layer` call received more than one implementation of the same group. Pass one implementation per group.
-- Client method missing for an action: the action is `http: false`.
+- Client method missing for an action: its group is not bound by `make`.
 - Empty 400 on a valid-looking request: input did not decode. Set a `schemaError` policy on the group to get a typed body, and check `Content-Type: application/json`.
 - 415: wrong or missing content type.
 - `HttpClientError: Decode error (401 POST ...)` from a typed client: the surface answered with a status no endpoint declares. Add that error schema to `ActionHttp.make`'s `errors`.

package/docs/ActionHttpClient.md

@@ -0,0 +1,80 @@
+# ActionHttpClient
+
+A Promise client for an HTTP binding, for code that does not run Effects, such as a browser
+page. It is Effect's native `HttpApiClient` over `fetch`, built once; each call is one request.
+
+## API
+
+Import `@gjermundgaraba/effect-actions/ActionHttpClient`.
+
+| API                       | Purpose                                                               |
+| ------------------------- | --------------------------------------------------------------------- |
+| `promise(http, options?)` | `client.<group>.<action>(input)` for every action of the binding.     |
+| `Options`                 | Where and how requests are sent.                                      |
+| `Client`, `Method`        | The client's type, derived from the binding, and one action's method. |
+
+The options are the native `HttpApiClient.make` options except `transformResponse`, plus `fetch`.
+`transformResponse` may change a call's success, failure or required services, which neither
+the method types nor a Promise can follow; wrap `fetch` or use `transformClient` instead.
+
+| Option            | Meaning                                                                                                                         |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `baseUrl`         | What routes are resolved against, such as `https://api.example.com`. Omitted: relative routes (the page's origin in a browser). |
+| `transformClient` | Wraps the native `HttpClient`. A bearer token: `HttpClient.mapRequest(HttpClientRequest.bearerToken(token))`.                   |
+| `fetch`           | The transport. Defaults to the global `fetch`, looked up on each call.                                                          |
+
+A method takes the action's decoded input and resolves with its decoded success. An action
+whose input may be empty (no `input`, or only optional fields) may be called without an argument.
+
+## Canonical
+
+```ts
+import { HttpClient, HttpClientError, HttpClientRequest } from "effect/unstable/http";
+import * as ActionHttpClient from "@gjermundgaraba/effect-actions/ActionHttpClient";
+import { Http, UserNotFound } from "./contracts.js";
+
+// Promises in, Promises out: for code that does not run Effects, such as a browser page.
+// The options are the native `HttpApiClient.make` options plus `fetch`; a bearer token is
+// a `transformClient`.
+const client = ActionHttpClient.promise(Http, {
+  baseUrl: "http://127.0.0.1:3000",
+  transformClient: HttpClient.mapRequest(HttpClientRequest.bearerToken("alice")),
+});
+
+export const userName = async (id: string): Promise<string> => {
+  try {
+    return (await client.users.getUser({ id })).name;
+  } catch (error) {
+    // A declared error rejects as its own value...
+    if (error instanceof UserNotFound) return "(no such user)";
+
+    // ...and what the contract cannot account for as Effect's own `HttpClientError`.
+    if (HttpClientError.isHttpClientError(error) && error.response === undefined) {
+      return "(server unreachable)";
+    }
+
+    throw error;
+  }
+};
+```
+
+Other headers also go through `transformClient` (`HttpClient.mapRequest(HttpClientRequest.setHeader("x-agent", agent))`).
+Reacting to a response every call may meet (a proxy's 401), or a token read per call, goes through
+`fetch`: `fetch: (input, init) => { const request = new Request(input, init); request.headers.set("authorization", "Bearer " + readToken()); return fetch(request); }`.
+
+## Rules
+
+- A call rejects with exactly what the native client's Effect fails with. Declared errors arrive as their decoded values: the action's own (its group's `errors` included), its group's schema-error policy's, and the binding's surface `errors`. Classify them with `instanceof`, their `_tag`, or `Schema.is`.
+- Anything the contract does not account for rejects with Effect's own error. `HttpClientError`: the server could not be reached (`response` is `undefined`), or answered with a status no schema declares, or with a body that could not be read. `SchemaError`: the input did not encode, or the success body did not decode.
+- The library adds no error type of its own and interprets no status. Which failures mean "signed out" or "try again" is the caller's decision.
+- Nothing is retried. A rejected write may or may not have happened; only a declared error says what the server did.
+- Every action of a bound group has a method. A group without actions has no namespace.
+- The client holds no connections or timers. Making one is synchronous and sends nothing.
+- A method is not an Effect. Code that runs Effects uses `HttpApiClient.make(Http.api)` directly (see [ActionHttp.md](ActionHttp.md)); its methods take `{ payload }`.
+
+## Failure modes
+
+- Rejects with `HttpClientError` whose `reason._tag` is `StatusCodeError` for a 401 or 403: the surface answered with an error the binding does not declare. Add it to `ActionHttp.make`'s `errors`, and have the middleware encode it.
+- Rejects with `HttpClientError` whose `reason._tag` is `InvalidUrlError` outside a browser: `baseUrl` is omitted, and there is no page to resolve relative routes against. Set `baseUrl`.
+- A stubbed global `fetch` is not used: `fetch` was passed as an option, which takes precedence.
+- Property does not exist on the client: the action's group is not bound in this `Http`.

package/docs/ActionMcp.md

@@ -2,7 +2,7 @@
 
 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.
+JSON-RPC on standard I/O for a subprocess. Both speak MCP 2026-07-28 only.
 
 ## API
 
@@ -14,15 +14,19 @@ Import `@gjermundgaraba/effect-actions/ActionMcp`.
 | `layerStdio(apps, options)` | Serve implementations over a subprocess's standard I/O.                       |
 | `Options`, `StdioOptions`   | Configuration for the two transports.                                         |
 
-| Option            | Meaning                                                                                               |
-| ----------------- | ----------------------------------------------------------------------------------------------------- |
-| `name`, `version` | Required native server information.                                                                   |
-| `protocols`       | Required nonempty list of native protocol adapters.                                                   |
-| `path`            | Required HTTP endpoint path; HTTP only, no default.                                                   |
-| `allowedOrigins`  | Optional exact Origin allowlist; HTTP only, not CORS configuration.                                   |
-| `instructions`    | Optional native server instructions.                                                                  |
-| `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. |
+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
@@ -33,7 +37,6 @@ is supplied by the server, not owed by the host.
 
 ```ts
 import { Layer } from "effect";
-import { McpProtocol } from "effect/unstable/ai";
 import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
 import { AuditApp, PublicApp, UserApp } from "./handlers.js";
 import { authentication, authorize, Forbidden } from "./auth.js";
@@ -43,7 +46,6 @@ const allowedOrigins = ["http://localhost:3000"];
 // One endpoint is one route: its middleware covers every tool on it.
 // Tools with different middleware needs get their own endpoint.
 const publicMcp = ActionMcp.layerHttp([PublicApp], {
-  protocols: [McpProtocol.v2026_07_28],
   name: "app-public",
   version: "1.0.0",
   path: "/mcp/public",
@@ -51,7 +53,6 @@ const publicMcp = ActionMcp.layerHttp([PublicApp], {
 });
 
 const mcp = ActionMcp.layerHttp([UserApp, AuditApp], {
-  protocols: [McpProtocol.v2026_07_28],
   name: "app",
   version: "1.0.0",
   path: "/mcp",
@@ -73,7 +74,6 @@ choose its policy for every route it covers.
 
 ```ts
 import { Effect, Layer } from "effect";
-import { McpProtocol } from "effect/unstable/ai";
 import { HttpRouter } from "effect/unstable/http";
 import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
 import { Actions } from "./quickstart.js";
@@ -86,7 +86,6 @@ const mcp = ActionMcp.layerHttp([app], {
   name: "greetings",
   version: "1.0.0",
   path: "/mcp",
-  protocols: [McpProtocol.v2026_07_28],
   allowedOrigins,
 });
 
@@ -114,7 +113,6 @@ export const routes = Layer.mergeAll(
 ```ts
 import { NodeRuntime, NodeStdio } from "@effect/platform-node";
 import { Console, Effect, Layer, Logger, Schema } from "effect";
-import { McpProtocol } from "effect/unstable/ai";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
 import * as ActionGroup from "@gjermundgaraba/effect-actions/ActionGroup";
 import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
@@ -132,7 +130,6 @@ const app = ActionGroup.make({ name: "stdio" }, Status).implement({
 const layer = ActionMcp.layerStdio([app], {
   name: "effect-actions-stdio",
   version: "0.1.0",
-  protocols: [McpProtocol.v2026_07_28],
 }).pipe(Layer.provide(NodeStdio.layer));
 
 // Protocol messages use stdout exclusively. Runtime diagnostics remain on stderr.
@@ -145,18 +142,18 @@ Layer.launch(layer).pipe(
 
 ## Rules
 
-- `protocols` is required and must be a nonempty list of Effect's native `McpProtocol.ProtocolAdapter` values. Effect owns negotiation, revision rejection, and sessions. `[McpProtocol.v2026_07_28]` gives a stateless endpoint that needs no initialize handshake.
+- 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, whatever revision is negotiated.
 - 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.
 - `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.
+- 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: { value: <encoded success> }`. A declared error is an `isError` result whose text content is the error's JSON encoding, the same bytes HTTP sends as the body, and no `structuredContent`.
 - Invalid arguments and unencodable results are answered by the native `McpServer`: an `isError` result with a message for the model. Group `schemaError` policies do not apply.
 - Defects and encoding failures produce the generic `isError` text `Tool execution failed due to an internal server error.`; the cause is logged, not sent.
 - Tool discovery is not filtered by actor. Every caller sees every tool of the endpoint. Authorization happens in `before`.
-- Cancellation is Effect's native RPC interruption.
+- 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.
 - Each endpoint or subprocess owns a fresh native tool registry. That isolates tool names, not application context.
@@ -170,9 +167,9 @@ Layer.launch(layer).pipe(
 - Type error listing `HttpRouter.Request.From<"Requires", ...>`: a handler yields a request service and the endpoint has no middleware providing it. Provide it with `Layer.provide(middleware.layer)` on that `layerHttp`.
 - Public tool requires a token: it shares an endpoint with protected tools. Give it its own path.
 - Client reports a broken transport from a stdio subprocess: something printed to stdout. Set `Logger.LogToStderr` and remove `console.log`.
-- Older MCP client cannot connect: the client expects a revision not listed in `protocols`. Add the adapter for that revision.
+- 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" } }`).
 - 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.
 - 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.
-- Type error on an empty `protocols` array: provide at least one native protocol adapter.
+- `Object literal may only specify known properties, and 'protocols'`: the revision is fixed. Delete the option.
 - 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`.

package/docs/ActionToolkit.md

@@ -51,7 +51,7 @@ With a model: pass `binding.toolkit` as `toolkit` to `LanguageModel.generateText
 
 ## Rules
 
-- Selects MCP-enabled actions only, named by `mcp.name`, with resolved hints. Groups with no selected tools are not built. `make(apps, options?)` accepts a readonly implementation collection; options may be omitted.
+- 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. There is no `{ value }` wrapper. Declared failures are returned as native tool results (`failureMode: "return"`), not raised.
 - `tools.handle(name, encodedInput)` takes encoded arguments and returns an Effect producing a result stream. The handler starts while that stream is constructed, so request services must be provided around the entire `handle(...).pipe(Effect.flatMap(Stream.runCollect))`, not only around the stream.
 - `binding.layer` acquires each implementation once, in the layer's scope. Build-time requirements belong to the whole selected implementation.

package/docs/CONTEXT.md

@@ -5,7 +5,7 @@ use these words with these meanings.
 
 ## Terms
 
-- **Action**: one contract. A name, a description, an input schema, a success schema, declared error schemas, authorization metadata (`access`), and transport metadata (`http`, `mcp`). Holds no behavior. Made by `Action.make`.
+- **Action**: one contract. A name, a description, an input schema, a success schema, declared error schemas, authorization metadata (`access`), and MCP metadata (`mcp`). Holds no behavior. Made by `Action.make`.
 - **Access**: `"read"` or `"write"`, required on every action and kept as a literal. States what the action does to its resource. Authorization metadata read by a pre-handler hook, independent of the MCP `readOnly` hint, which defaults from it.
 - **Group**: a named, ordered set of actions plus group-level errors and an optional schema-error policy. Adapters serve groups, clients are organized by group, and the group name is the OpenAPI tag. Made by `ActionGroup.make`.
 - **Contract**: an action or a group. Pure data; safe to import anywhere, including browsers.
@@ -19,13 +19,13 @@ use these words with these meanings.
 - **Binding**: the value an adapter returns before anything runs. `ActionHttp.make` returns the HTTP binding (`groups`, `api`, `layer`); `ActionToolkit.make` returns the Toolkit binding (`toolkit`, `layer`).
 - **Contract map**: the record `ActionGroup.contracts` returns, keyed `<group>.<action>`, with each action's exact type. The shared identity of an action across routes, tools and commands.
 - **Declared error**: an error schema listed on an action or inherited from its group. Handlers may fail with it. HTTP encodes it with its `httpApiStatus`; MCP returns encoded error text in an `isError` result. Toolkit returns a native failure result, and CLI fails its command Effect without serializing the error.
-- **Schema-error policy**: a group option mapping Effect's `HttpApiSchemaError` (decode or encode failure) to a declared policy error with a status. HTTP only.
+- **Schema-error policy**: a group option answering Effect's `HttpApiSchemaError` with a declared policy error and its status: `invalid` when the request did not decode, `internal` when the handler's result did not encode. The library decides which applies. HTTP only.
 - **Policy error**: an error a schema-error policy may answer with. Part of the transport contract, never returnable by a handler.
 - **Surface error**: an error declared on an adapter binding rather than on an action. Produced by middleware around the surface or by its pre-handler hook, never by a handler; declared so typed callers decode it.
-- **Local-only action**: `http: false` and `mcp: false`. Reachable through `ActionCli` and listed in the catalog.
 - **Tool**: the MCP or Toolkit projection of an MCP-enabled action, named by `mcp.name` and carrying its hints.
 - **Endpoint**: one `ActionMcp.layerHttp` mount. One route, one middleware set, one tool registry.
-- **Document**: the OpenAPI output of `Http.api`, produced by Effect (`OpenApi.fromApi`).
+- **Document**: the OpenAPI output of `Http.api`, produced by Effect (`OpenApi.fromApi`) and served by `Http.openApi`.
+- **Promise client**: `ActionHttpClient.promise(Http)`, the native `HttpApiClient` as one Promise method per action of the binding, for code that does not run Effects. It rejects with what the native client fails with.
 - **Catalog**: the offline JSON description of groups produced by `ActionCatalog.make`, with standalone JSON Schemas for encoded values. Descriptive only.
 - **Identity**: the per-request principal, provided by `Authentication.middleware` under an application-owned tag. Never provided at startup.
 

package/docs/README.md

@@ -9,29 +9,30 @@ Read the card for a module before writing code that uses it. Exported TypeScript
 Package facts that apply everywhere:
 
 - Every module is a subpath import: `import * as Action from "@gjermundgaraba/effect-actions/Action"`. There is no package root.
-- The `effect` peer is pinned to an exact release candidate (`4.0.0-rc.116`). Install the same version.
+- The `effect` peer accepts any 4.0 release candidate from `4.0.0-rc.116` on (`>=4.0.0-rc.116 <4.0.0`). The package is built and tested against `4.0.0-rc.117`.
 - Contracts are pure values. Nothing runs, binds, or acquires services until an adapter layer is built.
 
 ## Pages
 
-| Read                                     | When you need to                                                                       |
-| ---------------------------------------- | -------------------------------------------------------------------------------------- |
-| [setup.md](setup.md)                     | install, pin versions, pick entry points, know what the package does not do            |
-| [Action.md](Action.md)                   | define one contract: input, success, errors, read/write access, HTTP and MCP flags     |
-| [ActionGroup.md](ActionGroup.md)         | group contracts, declare shared errors, bind handlers, map every contract by name      |
-| [ActionHttp.md](ActionHttp.md)           | serve JSON POST routes, declare surface errors and one hook, publish OpenAPI, call it  |
-| [ActionMcp.md](ActionMcp.md)             | serve MCP tools over Streamable HTTP or stdio                                          |
-| [ActionToolkit.md](ActionToolkit.md)     | use actions as a native Effect AI `Toolkit` without a server                           |
-| [ActionCli.md](ActionCli.md)             | run handlers in-process from a terminal command                                        |
-| [ActionCliClient.md](ActionCliClient.md) | call the HTTP API from a terminal command                                              |
-| [ActionCatalog.md](ActionCatalog.md)     | export contracts as an offline JSON document                                           |
-| [Authentication.md](Authentication.md)   | provide a per-request identity, publish RFC 9728 discovery, build bearer challenges    |
-| [Testing.md](Testing.md)                 | call routes in memory, build MCP requests, drive the official MCP client               |
-| [guarantees.md](guarantees.md)           | cross-cutting rules: dependency lifetimes, wire formats, spans, request context, scope |
+| Read                                       | When you need to                                                                       |
+| ------------------------------------------ | -------------------------------------------------------------------------------------- |
+| [setup.md](setup.md)                       | install, pin versions, pick entry points, know what the package does not do            |
+| [Action.md](Action.md)                     | define one contract: input, success, errors, read/write access, HTTP and MCP flags     |
+| [ActionGroup.md](ActionGroup.md)           | group contracts, declare shared errors, bind handlers, map every contract by name      |
+| [ActionHttp.md](ActionHttp.md)             | serve JSON POST routes, declare surface errors and one hook, publish OpenAPI, call it  |
+| [ActionHttpClient.md](ActionHttpClient.md) | call the HTTP API with Promises, from code that does not run Effects                   |
+| [ActionMcp.md](ActionMcp.md)               | serve MCP 2026-07-28 tools over Streamable HTTP or stdio                               |
+| [ActionToolkit.md](ActionToolkit.md)       | use actions as a native Effect AI `Toolkit` without a server                           |
+| [ActionCli.md](ActionCli.md)               | run handlers in-process from a terminal command                                        |
+| [ActionCliClient.md](ActionCliClient.md)   | call the HTTP API from a terminal command                                              |
+| [ActionCatalog.md](ActionCatalog.md)       | export contracts as an offline JSON document                                           |
+| [Authentication.md](Authentication.md)     | provide a per-request identity, publish RFC 9728 discovery, build bearer challenges    |
+| [Testing.md](Testing.md)                   | call routes and tools in memory, build MCP requests, drive the official MCP client     |
+| [guarantees.md](guarantees.md)             | cross-cutting rules: dependency lifetimes, wire formats, spans, request context, scope |
 
 ## Choose an adapter
 
-- Callers speak JSON over HTTP: `ActionHttp`. Clients use Effect's `HttpApiClient` on `Http.api`.
+- Callers speak JSON over HTTP: `ActionHttp`. Clients use Effect's `HttpApiClient` on `Http.api`, or `ActionHttpClient.promise(Http)` where nothing runs Effects.
 - Callers are MCP clients: `ActionMcp.layerHttp` for a hosted endpoint, `ActionMcp.layerStdio` for a subprocess.
 - Callers are an Effect AI program in the same process: `ActionToolkit`.
 - Callers are humans or scripts in a terminal, handlers run locally: `ActionCli`.
@@ -43,7 +44,6 @@ One implementation (`group.implement(...)`) feeds every adapter.
 ## Minimal program
 
 ```ts
-import { McpProtocol } from "effect/unstable/ai";
 import { Effect, Layer, Schema } from "effect";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
 import * as ActionGroup from "@gjermundgaraba/effect-actions/ActionGroup";
@@ -68,7 +68,6 @@ const app = Actions.implement({
 export const routes = Layer.mergeAll(
   Http.layer([app]),
   ActionMcp.layerHttp([app], {
-    protocols: [McpProtocol.v2026_07_28],
     name: "greetings",
     version: "1.0.0",
     path: "/mcp",
@@ -83,6 +82,7 @@ Serve `routes` with `HttpRouter.serve` and a platform server layer. Result: `POS
 Repository directory `examples/` ([on GitHub](https://github.com/gjermundgaraba/effect-actions/tree/main/examples)):
 
 - `quickstart.ts`, `quickstart-client.ts`: the minimal program and its typed client.
+- `promise-client.ts`: the Promise client, with a declared error and an unreachable server.
 - `contracts.ts`, `handlers.ts`, `app.ts`, `server.ts`: an authenticated application with three groups, per-group middleware, two MCP endpoints, OpenAPI and Swagger.
 - `toolkit.ts`, `catalog.ts`, `cli.ts`, `cli-client.ts`, `mcp-stdio.ts`: one file per other projection.
 

package/docs/Testing.md

@@ -12,21 +12,23 @@ Import `@gjermundgaraba/effect-actions/Testing`; official-client helpers are in
 | -------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
 | `Testing.httpClient(api, handler, options?)` | Native grouped `HttpApiClient` over an in-memory web handler; retains client middleware requirements. |
 | `Testing.mcpRequest(options)`                | Build a stateless MCP JSON-RPC `Request`.                                                             |
+| `Testing.mcpCall(handler, options)`          | Call one tool in memory and return its outcome without the wire envelope.                             |
 | `TestingClient.withMcpClient(options, run)`  | Connect the official client, run an asynchronous callback, then close it.                             |
 
 `httpClient` takes native client options; `baseUrl` defaults to `http://localhost`.
 Its exported `Handler` type is a web request to response Promise.
 
-| MCP option                            | Meaning                                                                             |
-| ------------------------------------- | ----------------------------------------------------------------------------------- |
-| `mcpRequest`: `url`, `method`         | Required destination and JSON-RPC method.                                           |
-| `mcpRequest`: `params`, `headers`     | Optional parameters and request headers.                                            |
-| `withMcpClient`: `fetch`, `path`      | Required in-memory request handler and endpoint path.                               |
-| `withMcpClient`: `baseUrl`, `headers` | Optional base URL (default `http://localhost`) and headers.                         |
-| `withMcpClient`: `versionNegotiation` | Optional native client negotiation configuration; omitted means its native default. |
+| MCP option                            | Meaning                                                     |
+| ------------------------------------- | ----------------------------------------------------------- |
+| `mcpRequest`: `url`, `method`         | Required destination and JSON-RPC method.                   |
+| `mcpRequest`: `params`, `headers`     | Optional parameters and request headers.                    |
+| `mcpCall`: `url`, `name`              | Required endpoint URL and tool name (`mcp.name`).           |
+| `mcpCall`: `arguments`, `headers`     | Optional tool arguments (default `{}`) and request headers. |
+| `withMcpClient`: `fetch`, `path`      | Required in-memory request handler and endpoint path.       |
+| `withMcpClient`: `baseUrl`, `headers` | Optional base URL (default `http://localhost`) and headers. |
 
-Exported option/value types: `McpRequestOptions`, `McpRequestParams`, `McpRequestValue`
-from `Testing`, and `McpClientOptions` from `TestingClient`.
+Exported option/value types: `McpRequestOptions`, `McpRequestParams`, `McpRequestValue`,
+`McpCallOptions`, `McpCallResult` from `Testing`, and `McpClientOptions` from `TestingClient`.
 
 ## Canonical
 
@@ -53,13 +55,19 @@ try {
     Testing.mcpRequest({ url: "http://localhost/mcp", method: "tools/list" }),
   );
 
+  // One tool call, answered as `{ isError: false, value: "Hello, Ada!" }`.
+  const called = await Testing.mcpCall(web.handler, {
+    url: "http://localhost/mcp",
+    name: "greet",
+    arguments: { name: "Ada" },
+  });
+
   // The official client uses the same in-memory handler.
-  const result = await TestingClient.withMcpClient(
-    { fetch: web.handler, path: "/mcp", versionNegotiation: { mode: { pin: "2026-07-28" } } },
-    (client) => client.callTool({ name: "greet", arguments: { name: "Ada" } }),
+  const result = await TestingClient.withMcpClient({ fetch: web.handler, path: "/mcp" }, (client) =>
+    client.callTool({ name: "greet", arguments: { name: "Ada" } }),
   );
 
-  console.log({ greeting, listStatus: listed.status, result });
+  console.log({ greeting, listStatus: listed.status, called, result });
 } finally {
   await web.dispose();
 }
@@ -70,14 +78,17 @@ try {
 - `httpClient` is the same `HttpApiClient` consumers use, with its transport replaced by `handler`. Same `{ payload }` calls, same error channel.
 - `mcpRequest` pins protocol version 2026-07-28 in both the header and `_meta`. Caller `params._meta` fields override the defaulted client capabilities and info; the merge is shallow. Application metadata is preserved.
 - `params` accepts what `JSON.stringify` accepts, so tests can send malformed arguments on purpose. `undefined` fields are dropped.
-- `withMcpClient` closes the transport in a `finally` block. `versionNegotiation` is passed to the official client unchanged; for a stateless endpoint pin `2026-07-28`.
-- Add `Authorization` through `headers` in both MCP helpers, or through `transformClient` in `httpClient` options.
+- `mcpCall` sends one `tools/call` through `mcpRequest` and resolves with `{ isError: false, value }`, the success taken from `structuredContent.value`, or `{ isError: true, error }`, the result's error text parsed as JSON. A declared error or a hook refusal is its JSON encoding, the same body HTTP sends; the native server's own messages (invalid arguments, defects) are not JSON and stay text. It reads a JSON or an event-stream response.
+- `mcpCall` throws when the answer is not a tool result: a status other than 200 (an authentication refusal), or a JSON-RPC error (an unknown tool). Use `mcpRequest` to assert on those responses.
+- `withMcpClient` pins the official client to MCP 2026-07-28, the only revision `ActionMcp` serves, and closes the transport in a `finally` block.
+- Add `Authorization` through `headers` in the MCP helpers, or through `transformClient` in `httpClient` options.
 - Direct handler tests can use `app.build` under `Effect.scoped`, but they bypass decoding, encoding, and middleware. Keep at least one adapter-level test per transport.
 
 ## Failure modes
 
 - `@modelcontextprotocol/client` not found: only `TestingClient` needs it. Install the peer in devDependencies, or use `Testing.mcpRequest` instead.
-- Official client fails negotiation against a stateless endpoint: set `versionNegotiation: { mode: { pin: "2026-07-28" } }`.
+- `withMcpClient` rejects its options with `versionNegotiation`: the revision is fixed at 2026-07-28. Delete the option.
+- `MCP tools/call "<name>" answered 401`: the call reached authentication without a credential. Pass `headers: { authorization: "Bearer ..." }`.
 - Handler leaks between tests: `web.dispose()` was not called. Register it with the test runner's cleanup hook.
 - 404 from `httpClient`: the requested route was not mounted, or the path/base URL is wrong. Include `Http.layer([app])` in the served routes.
 - Missing platform-service requirements when constructing the web handler: provide `HttpServer.layerServices` to the routes before `toWebHandler`.