@gjermundgaraba/effect-actions 0.5.0 → 0.6.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 record or an Effect producing one. Every action must have a handler; missing keys are compile errors. A record that still lacks one at runtime (plain JavaScript, a cast) throws at `implement`; a builder's record fails the adapter layer's build. Nothing is served with a handler missing. 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 lacks those actions. Add them.
 - 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`.
 
@@ -32,8 +33,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 +56,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 +70,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";
@@ -98,6 +99,7 @@ export const greeting = Effect.gen(function* () {
 - 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.
 - Add authentication headers with the native `transformClient` option. Use `HttpApiClient.makeWith` for custom error or service channels. Native per-call response modes are available.

package/docs/ActionHttpClient.md

@@ -0,0 +1,73 @@
+# 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 HTTP-served 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.         |
+
+| Option    | Meaning                                                                                                                         |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `baseUrl` | What routes are resolved against, such as `https://api.example.com`. Omitted: relative routes (the page's origin in a browser). |
+| `token`   | Sent as `Authorization: Bearer <token>` with every call.                                                                        |
+| `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 { HttpClientError } 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.
+const client = ActionHttpClient.promise(Http, {
+  baseUrl: "http://127.0.0.1:3000",
+  token: "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, or reacting to a response every call may meet (a proxy's 401), go through
+`fetch`: `fetch: (input, init) => { const request = new Request(input, init); request.headers.set("x-agent", agent); 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.
+- Only HTTP-served actions have methods. An action with `http: false` is absent, and so is a group without HTTP actions.
+- 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 is `http: false`, or its 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,7 +142,7 @@ 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.
 - `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.
@@ -156,7 +153,7 @@ Layer.launch(layer).pipe(
 - 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/CONTEXT.md

@@ -19,13 +19,14 @@ 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 HTTP action, 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`.

package/docs/guarantees.md

@@ -32,7 +32,7 @@ Defaults without a schema-error policy. HTTP is a native `HttpApi`; MCP is a nat
 | Unknown path or method      | 404                                                                                                   | n/a                                                                                                    |
 | Invalid JSON / content type | 400 / 415                                                                                             | n/a                                                                                                    |
 
-- A group `schemaError` policy replaces the empty 400s on HTTP with a declared error and status. It never affects MCP. Details in [ActionGroup.md](ActionGroup.md).
+- A group `schemaError` policy replaces the empty 400s on HTTP with a declared error and status: its `invalid` error for input that does not decode, its `internal` error for output that does not encode. It never affects MCP. Details in [ActionGroup.md](ActionGroup.md).
 - `ActionHttp` sets no headers of its own. The host owns cache and challenge headers; `Authentication.middleware` marks its responses `cache-control: no-store`. Hook refusals and handler failures are ordinary declared error responses.
 - Routes are `POST <apiPath>/<group>/<action>`. Operation IDs are `<group>.<action>`. Effect generates OpenAPI component names and references.
 - `ActionHttp.make`'s `errors` are declared on every endpoint so clients decode the surface's own failures (401, 403, 429, 503). They are produced by middleware or by the binding's hook, never by a handler. `ActionMcp` and `ActionToolkit` declare their own `errors` the same way, joined into every tool's failure schema. Two errors may share an HTTP status; their `_tag`s must differ, because the client decodes a status by trying the schemas declared for it.
@@ -51,9 +51,9 @@ Defaults without a schema-error policy. HTTP is a native `HttpApi`; MCP is a nat
 
 ## MCP transport
 
-- `protocols` is required. Effect owns negotiation, revision rejection, and session lifecycle; the adapter forwards the selection unchanged. `[McpProtocol.v2026_07_28]` is a stateless endpoint.
-- `layerHttp` is single-endpoint Streamable HTTP, never two-endpoint HTTP+SSE, whatever revision is selected.
-- Cancellation is Effect's native RPC interruption.
+- MCP 2026-07-28 is the only revision served, on both transports; there is no option to select another. Effect owns version checks and rejects other revisions. Over HTTP the endpoint is stateless: no initialize handshake and no session.
+- `layerHttp` is single-endpoint Streamable HTTP, never two-endpoint HTTP+SSE.
+- Cancellation is Effect's native RPC interruption. Without an HTTP session, `notifications/cancelled` interrupts nothing over HTTP; a call ends with its request.
 - Each endpoint or subprocess owns a fresh native tool registry. That isolates names, not application context.
 
 ## Scope

package/docs/setup.md

@@ -5,12 +5,12 @@ Install, version pins, entry points, and the boundaries of the package.
 ## Install
 
 ```sh
-pnpm add @gjermundgaraba/effect-actions effect@4.0.0-rc.116
+pnpm add @gjermundgaraba/effect-actions effect@4.0.0-rc.117
 ```
 
 | Need                           | Add                                                   |
 | ------------------------------ | ----------------------------------------------------- |
-| Node HTTP server or stdio host | `@effect/platform-node@4.0.0-rc.116`                  |
+| Node HTTP server or stdio host | `@effect/platform-node@4.0.0-rc.117`                  |
 | `TestingClient.withMcpClient`  | `@modelcontextprotocol/client@^2.0.0` (optional peer) |
 
 Node `^22.12.0 || ^24.0.0 || >=26.0.0`. ESM only.
@@ -23,6 +23,7 @@ There is no package root. Import one module per subpath, as a namespace:
 import * as Action from "@gjermundgaraba/effect-actions/Action";
 import * as ActionGroup from "@gjermundgaraba/effect-actions/ActionGroup";
 import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import * as ActionHttpClient from "@gjermundgaraba/effect-actions/ActionHttpClient";
 import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
 import * as ActionToolkit from "@gjermundgaraba/effect-actions/ActionToolkit";
 import * as ActionCatalog from "@gjermundgaraba/effect-actions/ActionCatalog";
@@ -39,11 +40,11 @@ and `TestingClient` is the only module that imports the optional `@modelcontextp
 peer. Because there is no package root, importing a contract module never pulls in an MCP
 server or the peer.
 
-Companion Effect modules you will import alongside: `effect/unstable/httpapi` (`HttpApiClient`, `OpenApi`, `HttpApiSwagger`, `HttpApiScalar`), `effect/unstable/http` (`HttpRouter`, `HttpServerResponse`, `FetchHttpClient`), `effect/unstable/ai` (`McpProtocol`), `effect/unstable/cli` (`Command`, `Flag`, `Argument`).
+Companion Effect modules you will import alongside: `effect/unstable/httpapi` (`HttpApiClient`, `OpenApi`, `HttpApiSwagger`, `HttpApiScalar`), `effect/unstable/http` (`HttpRouter`, `HttpServerResponse`, `FetchHttpClient`, `HttpClientError`), `effect/unstable/cli` (`Command`, `Flag`, `Argument`).
 
 ## Rules
 
-- Pin `effect` to the exact release candidate the package declares as peer. Mixed rc versions fail at the type level in ways that look like library bugs.
+- Install a single `effect` version within the peer range, and keep every `@effect/*` package on that same release candidate. Mixed rc versions fail at the type level in ways that look like library bugs.
 - Never import from `dist/` paths or from a package root. Only the subpaths above are public.
 - Schemas passed to `Action.make` must be service-free (`Schema.Codec<_, _, never, never>`). Handlers may require services.
 
@@ -52,12 +53,12 @@ Companion Effect modules you will import alongside: `effect/unstable/httpapi` (`
 What the package does, and nothing else:
 
 - HTTP means JSON `POST` endpoints built on Effect's `HttpApi`. It is not Effect RPC.
-- MCP means one native `McpServer` `Tool` per action. There is no MCP SDK runtime dependency.
+- MCP means one native `McpServer` `Tool` per action, over MCP 2026-07-28 only. There is no MCP SDK runtime dependency.
 - Actions are unary: one decoded input, one decoded success or one declared error. No streaming, uploads, prompts, resources, retries, or code-execution sandbox.
 - Authentication and authorization are the application's. The library provides the seams — `Authentication.middleware` for identity, one `before` hook per surface for the authorization rule, `access` for what that rule reads, each surface's `errors` for what a caller can decode — and no token verifier, error types or scopes of its own. Tool discovery is never filtered by actor.
 
 ## Failure modes
 
 - `Cannot find module '@gjermundgaraba/effect-actions'`: there is no root export. Import a subpath.
-- Type errors inside `effect/unstable/*` after install: `effect` version drift. Align to the peer pin.
+- Type errors inside `effect/unstable/*` after install: `effect` version drift. Install one `effect` release candidate within the peer range for every package.
 - `@modelcontextprotocol/client` resolution errors in a server build: something imported `TestingClient`. Only tests should.