@gjermundgaraba/effect-actions 0.5.0 → 0.6.0

package/README.md

@@ -7,7 +7,6 @@ Effect's own servers and clients underneath.
 ## Looks like this
 
 ```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";
@@ -32,7 +31,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",
@@ -60,6 +58,9 @@ const greeting = Effect.gen(function* () {
 });
 ```
 
+Code that does not run Effects, such as a browser page, gets the same calls as Promises:
+`await ActionHttpClient.promise(Http, { baseUrl }).greetings.greet({ name: "Ada" })`.
+
 ## Why
 
 - Input, success, and errors are declared once. Routes, tools, commands, clients, OpenAPI, and the catalog are derived from that declaration, so they cannot disagree.
@@ -72,10 +73,10 @@ const greeting = Effect.gen(function* () {
 ## Install
 
 ```sh
-pnpm add @gjermundgaraba/effect-actions effect@4.0.0-rc.116
+pnpm add @gjermundgaraba/effect-actions effect@4.0.0-rc.117
 ```
 
-Add `@effect/platform-node@4.0.0-rc.116` to serve from Node. Every module is a subpath import
+Add `@effect/platform-node@4.0.0-rc.117` to serve from Node. Every module is a subpath import
 (`.../Action`, `.../ActionHttp`, ...); there is no package root, so a contracts-only bundle
 never loads a server.
 
@@ -100,8 +101,8 @@ in `node_modules/@gjermundgaraba/effect-actions/docs`) gives the same content.
 
 ## Status
 
-The `effect` peer is pinned to an exact Effect 4 release candidate and moves with it; expect a
-release of this package for each Effect release candidate it adopts. Actions are unary JSON over HTTP and MCP: no streaming, uploads, prompts, or resources.
+The `effect` peer accepts any Effect 4.0 release candidate from `4.0.0-rc.116` on; the package
+is built and tested against the release candidate in its `devDependencies` (see [docs/setup.md](docs/setup.md)). Actions are unary JSON over HTTP and MCP: no streaming, uploads, prompts, or resources.
 Authentication and authorization belong to the application. See [docs/setup.md](docs/setup.md).
 
 ## Acknowledgements

package/dist/ActionCatalog.mjs

@@ -1,4 +1,4 @@
-import { assertDistinct } from "./internal/actions.mjs";
+import { assertDistinct, policyErrors } from "./internal/actions.mjs";
 import { JsonSchema, Schema } from "effect";
 //#region src/ActionCatalog.ts
 /** Describe the JSON wire form; decoding on the server remains authoritative. */
@@ -29,7 +29,7 @@ const make = (...groups) => {
 			input: describe(action.input),
 			success: describe(action.success),
 			errors: action.errors.map(describe),
-			httpSchemaErrors: action.http ? group.schemaError?.errors.map(describe) ?? [] : []
+			httpSchemaErrors: action.http && group.schemaError !== void 0 ? policyErrors(group.schemaError).map(describe) : []
 		})))
 	};
 };

package/dist/ActionCli.mjs

@@ -4,6 +4,10 @@ import { command as command$1 } from "./internal/cli.mjs";
 import { Effect } from "effect";
 import { Command } from "effect/unstable/cli";
 //#region src/ActionCli.ts
+/**
+* Acquire the implementation in a scope of its own, run one action through the hook
+* and its handler, and release it: every local command, selected or grouped.
+*/
 const local = (app, action, before, input) => Effect.scoped(Effect.flatMap(app.build, (handlers) => dispatch(app.group, action, handlers, before)(input)));
 /**
 * Project one explicitly selected local action into a native Effect CLI command.
@@ -15,7 +19,7 @@ const command = (app, name, options) => {
 };
 /** Project every local action below its group namespace with default CLI options. */
 const group = (app, options) => {
-	const commands = app.group.actions.map((action) => command$1(action, (input) => Effect.scoped(Effect.flatMap(app.build, (handlers) => dispatch(app.group, action, handlers, options?.before)(input)))));
+	const commands = app.group.actions.map((action) => command$1(action, (input) => local(app, action, options?.before, input)));
 	return Command.make(options?.name ?? app.group.name).pipe(Command.withSubcommands(commands));
 };
 //#endregion

package/dist/ActionGroup.d.mts

@@ -1,31 +1,35 @@
 import { Action, Action_d_exports, Any as Any$1, Codec, Handler } from "./Action.mjs";
-import { Actions, SchemaErrorPolicy } from "./internal/actions.mjs";
+import { Actions, SchemaErrorAnswer, SchemaErrorPolicy } from "./internal/actions.mjs";
 import { Implementation } from "./internal/implementation.mjs";
 import { Effect, Scope, Types } from "effect";
 declare namespace ActionGroup_d_exports {
-  export { Any, Contracts, Group, Implementation, Options, SchemaErrorPolicy, contracts, make };
+  export { Any, Contracts, Group, Implementation, Options, SchemaErrorAnswer, SchemaErrorPolicy, contracts, make };
 }
 type HandlersFrom<Actions extends ReadonlyArray<Any$1>> = { readonly [A in Actions[number] as A["name"]]: Handler<A, any>; };
 /** Group-level errors join each action's own, so a shared set is declared once. */
 type WithErrors<Actions extends ReadonlyArray<Any$1>, Errors extends ReadonlyArray<Codec>> = { readonly [K in keyof Actions]: Actions[K] extends Action<infer Name, infer Input, infer Output, infer Own, infer Access, infer Http, infer Mcp> ? Action<Name, Input, Output, readonly [...Own, ...Errors], Access, Http, Mcp> : never; };
 /** What `make` needs to define a group. */
-export interface Options<Name extends string, Errors extends ReadonlyArray<Codec>, PolicyErrors extends ReadonlyArray<Codec>> {
+export interface Options<Name extends string, Errors extends ReadonlyArray<Codec>, Invalid extends Codec = never, Internal extends Codec = never> {
   /** The `HttpApiGroup` identifier, and so the OpenAPI tag and operation-ID prefix. */
   readonly name: Name;
   /** Failures every action of the group may have, added to each action's own. */
   readonly errors?: Errors;
-  /** How HTTP answers failed decoding or encoding of these actions; MCP keeps its native answers. */
-  readonly schemaError?: SchemaErrorPolicy<PolicyErrors>;
+  /**
+   * How HTTP answers a request that fails decoding (`invalid`) and a result that fails
+   * encoding (`internal`); without one, both are Effect's empty 400. MCP keeps its
+   * native answers.
+   */
+  readonly schemaError?: SchemaErrorPolicy<Invalid, Internal>;
 }
 /** A named set of action contracts: what adapters serve and what `implement` binds. */
-export interface Group<Name extends string, Actions$1 extends ReadonlyArray<Any$1>, PolicyErrors extends ReadonlyArray<Codec> = ReadonlyArray<Codec>> extends Actions<Name, Actions$1, PolicyErrors> {
+export interface Group<Name extends string, Actions$1 extends ReadonlyArray<Any$1>, PolicyError extends Codec = Codec> extends Actions<Name, Actions$1, PolicyError> {
   /** Bind every handler at once, resolving build-time services once per adapter layer. */
-  readonly implement: <H extends HandlersFrom<Actions$1>, EX = never, RX = never>(build: H | Effect.Effect<H, EX, RX>) => Implementation<Group<Name, Actions$1, PolicyErrors>, H, NoInfer<EX>, NoInfer<Exclude<RX, Scope.Scope>>>;
+  readonly implement: <H extends HandlersFrom<Actions$1>, EX = never, RX = never>(build: H | Effect.Effect<H, EX, RX>) => Implementation<Group<Name, Actions$1, PolicyError>, H, NoInfer<EX>, NoInfer<Exclude<RX, Scope.Scope>>>;
 }
 /** Any group, with its actions and error schemas erased. */
-export type Any = Group<string, ReadonlyArray<Any$1>, ReadonlyArray<Codec>>;
+export type Any = Group<string, ReadonlyArray<Any$1>, Codec>;
 /** Define a group. Invalid or duplicate action and MCP names fail here, at definition time. */
-export declare function make<const Name extends string, const Actions extends ReadonlyArray<Any$1>, const Errors extends ReadonlyArray<Codec> = [], const PolicyErrors extends ReadonlyArray<Codec> = []>(options: Options<Name, Errors, PolicyErrors>, ...actions: Actions): Group<Name, WithErrors<Actions, Errors>, PolicyErrors>;
+export declare function make<const Name extends string, const Actions extends ReadonlyArray<Any$1>, const Errors extends ReadonlyArray<Codec> = [], Invalid extends Codec = never, Internal extends Codec = never>(options: Options<Name, Errors, Invalid, Internal>, ...actions: Actions): Group<Name, WithErrors<Actions, Errors>, Invalid | Internal>;
 /** `G extends unknown` distributes, so each group maps only its own actions. */
 type PerGroup<G extends Actions> = G extends unknown ? { readonly [A in G["actions"][number] as `${G["name"]}.${A["name"]}`]: A; } : never;
 /** Every action of `Groups`, keyed `<group>.<action>`: the per-group maps merged into one. */
@@ -37,4 +41,4 @@ export type Contracts<Groups extends ReadonlyArray<Actions>> = Types.UnionToInte
  */
 export declare function contracts<const Groups extends ReadonlyArray<Actions>>(...groups: Groups): Contracts<Groups>;
 //#endregion
-export { ActionGroup_d_exports, type Implementation, type SchemaErrorPolicy };
+export { ActionGroup_d_exports, type Implementation, type SchemaErrorAnswer, type SchemaErrorPolicy };

package/dist/ActionGroup.mjs

@@ -2,6 +2,17 @@ import { assertDistinct, assertName } from "./internal/actions.mjs";
 import { Implementation } from "./internal/implementation.mjs";
 import { Effect } from "effect";
 //#region src/ActionGroup.ts
+/**
+* The types require every handler, but a record built in plain JavaScript or through a
+* cast may still lack one, or hold `undefined` under its key. It fails before anything is served rather than on the
+* first request for the missing action.
+*/
+const assertHandlers = (group, handlers) => {
+	const bound = new Map(Object.entries(handlers));
+	const missing = group.actions.filter((action) => bound.get(action.name) === void 0);
+	if (missing.length > 0) throw new Error(`Missing handlers for group "${group.name}": ${missing.map((action) => action.name).join(", ")}`);
+	return handlers;
+};
 function make(options, ...declared) {
 	const { name } = options;
 	assertName("action group name", name);
@@ -16,7 +27,7 @@ function make(options, ...declared) {
 		actions,
 		schemaError: options.schemaError,
 		implement: (build) => {
-			const built = Effect.isEffect(build) ? build : Effect.succeed(build);
+			const built = Effect.isEffect(build) ? Effect.map(build, (handlers) => assertHandlers(group, handlers)) : Effect.succeed(assertHandlers(group, build));
 			return Implementation.make(group, built);
 		}
 	};

package/dist/ActionHttp.d.mts

@@ -48,6 +48,12 @@ export interface Http<Groups extends ReadonlyArray<Actions>, Errors extends Read
    * services are unions over precisely those apps and that hook.
    */
   readonly layer: <const Apps extends ReadonlyArray<AnyImplementation<Groups[number]>>, RB = never>(apps: readonly [...Apps], options?: LayerOptions<Errors, RB>) => Layer.Layer<never, BuildError<Apps[number], "http">, BuildContext<Apps[number], "http"> | HttpRouter.HttpRouter | HttpRouter.Request.From<"Requires", RequestContext<Apps[number], "http"> | RB> | Etag.Generator | FileSystem | HttpPlatform.HttpPlatform | Path>;
+  /**
+   * Serve the OpenAPI document of `api` with `GET path`, by default
+   * `<apiPath>/openapi.json`. It is a plain route: middleware provided to this layer
+   * covers it, and none is applied otherwise.
+   */
+  readonly openApi: (path?: HttpRouter.PathInput) => Layer.Layer<never, never, HttpRouter.HttpRouter>;
 }
 /**
  * Bind the contract-level configuration once. Every route is `POST

package/dist/ActionHttp.mjs

@@ -1,7 +1,7 @@
-import { assertDistinct, projectedErrors } from "./internal/actions.mjs";
+import { answerSchemaError, assertDistinct, policyErrors, projectedErrors } from "./internal/actions.mjs";
 import { dispatch } from "./internal/implementation.mjs";
 import { Effect, Layer } from "effect";
-import "effect/unstable/http";
+import { HttpRouter, HttpServerResponse } from "effect/unstable/http";
 import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiMiddleware, OpenApi } from "effect/unstable/httpapi";
 //#region src/ActionHttp.ts
 const httpActions = (group) => group.actions.filter((action) => action.http);
@@ -12,10 +12,10 @@ const endpoint = (options, group, action) => HttpApiEndpoint.post(action.name, `
 }).annotate(OpenApi.Description, action.description);
 /** The native middleware declares the policy's errors on every endpoint it wraps. */
 const schemaErrorMiddleware = (name, policy) => {
-	class SchemaErrors extends HttpApiMiddleware.Service()(`effect-actions/http/SchemaErrors/${name}`, { error: policy.errors }) {}
+	class SchemaErrors extends HttpApiMiddleware.Service()(`effect-actions/http/SchemaErrors/${name}`, { error: policyErrors(policy) }) {}
 	return {
 		SchemaErrors,
-		layer: HttpApiMiddleware.layerSchemaErrorTransform(SchemaErrors, (failure) => Effect.fail(policy.map(failure)))
+		layer: HttpApiMiddleware.layerSchemaErrorTransform(SchemaErrors, (failure) => Effect.fail(answerSchemaError(policy, failure)))
 	};
 };
 function bind(options, group) {
@@ -49,7 +49,10 @@ const erasedHandlers = (handlers) => {
 };
 /** Register one group's handlers. Handler erasure is limited to native dynamic endpoint registration. */
 const groupHandlers = (api, app, middleware, before) => {
-	const entries = (record) => Object.fromEntries(httpActions(app.group).map((action) => [action.name, (request) => dispatch(app.group, action, record, before)(request.payload)]));
+	const entries = (record) => Object.fromEntries(httpActions(app.group).map((action) => {
+		const run = dispatch(app.group, action, record, before);
+		return [action.name, (request) => run(request.payload)];
+	}));
 	return Layer.unwrap(Effect.map(app.build, (record) => HttpApiBuilder.group(api, app.group.name, (builder) => builder.handleAll(entries(erasedHandlers(record)))))).pipe(Layer.provide(middleware));
 };
 function make(options, ...groups) {
@@ -72,10 +75,13 @@ function make(options, ...groups) {
 		const [first, ...rest] = served.map(({ app, middleware }) => groupHandlers(api, app, middleware, layerOptions.before));
 		return first === void 0 ? HttpApiBuilder.layer(api) : HttpApiBuilder.layer(api).pipe(Layer.provide([first, ...rest]));
 	};
+	const api = apiOf([...bound.values()].map(({ native }) => native));
+	const openApi = (path = `${options.apiPath}/openapi.json`) => HttpRouter.add("GET", path, HttpServerResponse.jsonUnsafe(OpenApi.fromApi(api)));
 	return {
 		groups,
-		api: apiOf([...bound.values()].map(({ native }) => native)),
-		layer
+		api,
+		layer,
+		openApi
 	};
 }
 //#endregion

package/dist/ActionHttpClient.d.mts

@@ -0,0 +1,45 @@
+import { Action_d_exports, Any, Codec } from "./Action.mjs";
+import { Actions } from "./internal/actions.mjs";
+import { ServedNames } from "./internal/implementation.mjs";
+import { ActionHttp_d_exports, Http } from "./ActionHttp.mjs";
+//#region src/ActionHttpClient.d.ts
+/** Where and how a Promise client sends its requests. */
+export interface Options {
+  /**
+   * What the binding's routes are resolved against, such as `https://api.example.com`.
+   * Omitted, routes stay relative, which a browser resolves against the page's origin.
+   */
+  readonly baseUrl?: string | URL;
+  /** Sent as `Authorization: Bearer <token>` with every call. */
+  readonly token?: string;
+  /**
+   * The transport. Defaults to the global `fetch`, looked up per call. Wrap it to add
+   * headers or to observe responses, such as a proxy's 401.
+   */
+  readonly fetch?: typeof globalThis.fetch;
+}
+/** The HTTP-served actions of `G`: an action with a literal `http: false` has no method. */
+type HttpAction<G extends Actions> = Extract<G["actions"][number], {
+  readonly name: ServedNames<G, "http">;
+}>;
+/**
+ * One action as a Promise of its decoded success. An action whose input may be empty,
+ * such as one declared without `input`, may be called without an argument.
+ */
+export type Method<A extends Any> = {} extends A["input"]["Type"] ? (input?: A["input"]["Type"]) => Promise<A["success"]["Type"]> : (input: A["input"]["Type"]) => Promise<A["success"]["Type"]>;
+/** Every HTTP-served action of the binding, as `client.<group>.<action>(input)`. */
+export type Client<Groups extends ReadonlyArray<Actions>> = { readonly [G in Groups[number] as [HttpAction<G>] extends [never] ? never : G["name"]]: { readonly [A in HttpAction<G> as A["name"]]: Method<A>; }; };
+/**
+ * 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, and
+ * each call runs one request: nothing is retried.
+ *
+ * A call resolves with the action's decoded success. It rejects with what the native
+ * client fails with: a declared error value (the action's, its group's schema-error
+ * policy's, or the binding's surface `errors`), a native `HttpClientError` when the
+ * server could not be reached or answered with a status or body the contract does not
+ * declare, or a `SchemaError` when the input does not encode or the success does not
+ * decode.
+ */
+export declare function promise<const Groups extends ReadonlyArray<Actions>, const Errors extends ReadonlyArray<Codec>>(http: Http<Groups, Errors>, options?: Options): Client<Groups>;
+//#endregion

package/dist/ActionHttpClient.mjs

@@ -0,0 +1,24 @@
+import { Effect } from "effect";
+import { FetchHttpClient, HttpClient, HttpClientRequest } from "effect/unstable/http";
+import { HttpApiClient } from "effect/unstable/httpapi";
+//#region src/ActionHttpClient.ts
+function promise(http, { baseUrl, token, fetch } = {}) {
+	const send = fetch ?? ((input, init) => globalThis.fetch(input, init));
+	const native = Effect.runSync(HttpApiClient.make(http.api, {
+		baseUrl,
+		transformClient: token === void 0 ? void 0 : HttpClient.mapRequest(HttpClientRequest.bearerToken(token))
+	}).pipe(Effect.provide(FetchHttpClient.layer), Effect.provideService(FetchHttpClient.Fetch, send)));
+	return Object.fromEntries(http.groups.flatMap((group) => {
+		const endpoints = native[group.name];
+		if (endpoints === void 0) return [];
+		const methods = group.actions.flatMap((action) => {
+			const endpoint = endpoints[action.name];
+			if (endpoint === void 0) return [];
+			const method = (input) => Effect.runPromise(endpoint({ payload: input ?? {} }));
+			return [[action.name, method]];
+		});
+		return [[group.name, Object.fromEntries(methods)]];
+	}));
+}
+//#endregion
+export { promise };

package/dist/ActionMcp.d.mts

@@ -6,37 +6,26 @@ import { HttpRouter } from "effect/unstable/http";
 import { McpSchema, McpServer } from "effect/unstable/ai";
 import { Stdio } from "effect/Stdio";
 //#region src/ActionMcp.d.ts
-/** One Streamable HTTP MCP endpoint; its fields become the native server info. */
-export interface Options<Errors extends ReadonlyArray<Codec> = [], R = never> extends SurfaceOptions<Errors, R> {
-  readonly name: string;
-  readonly version: string;
-  /** Native protocol adapters to serve; negotiation and sessions are owned by Effect. */
-  readonly protocols: Parameters<typeof McpServer.layerHttp>[0]["protocols"];
-  /** Route of the Streamable HTTP endpoint; no default. */
-  readonly path: HttpRouter.PathInput;
-  /** Browser origins accepted by the native server; passed through to `McpServer.layerHttp`. */
-  readonly allowedOrigins?: ReadonlyArray<string>;
-  readonly instructions?: string;
-}
-/** Server information for an MCP subprocess connected through standard I/O. */
-export interface StdioOptions<Errors extends ReadonlyArray<Codec> = [], R = never> extends SurfaceOptions<Errors, R> {
-  readonly name: string;
-  readonly version: string;
-  /** Native protocol adapters to serve; negotiation is owned by Effect. */
-  readonly protocols: Parameters<typeof McpServer.layerStdio>[0]["protocols"];
-  readonly instructions?: string;
-}
+/**
+ * One Streamable HTTP MCP endpoint: every native `McpServer.layerHttp` option except
+ * `protocols` (server information, `path`, `allowedOrigins`, `instructions`,
+ * `extensions`, ...), plus the surface's `errors` and `before`.
+ */
+export interface Options<Errors extends ReadonlyArray<Codec> = [], R = never> extends Omit<Parameters<typeof McpServer.layerHttp>[0], "protocols">, SurfaceOptions<Errors, R> {}
+/** An MCP subprocess on standard I/O: every native `McpServer.layerStdio` option except `protocols`. */
+export interface StdioOptions<Errors extends ReadonlyArray<Codec> = [], R = never> extends Omit<Parameters<typeof McpServer.layerStdio>[0], "protocols">, SurfaceOptions<Errors, R> {}
 /** The native server supplies its own request context to every tool call. */
 type ToolRequestContext<App, RB> = Exclude<RequestContext<App, "mcp"> | RB, McpSchema.McpRequestContext>;
 /**
- * Serve MCP tools over one Streamable HTTP endpoint.
+ * Serve MCP tools over one Streamable HTTP endpoint, speaking MCP 2026-07-28 only.
  *
  * Middleware provided around this layer has the normal HTTP lifetime. Native
  * context capture applies: never provide request-identity tags at startup.
  */
 export declare function layerHttp<const Apps extends ReadonlyArray<AnyImplementation>, const Errors extends ReadonlyArray<Codec> = [], RB = never>(apps: readonly [...Apps], options: Options<Errors, RB>): Layer.Layer<never, BuildError<Apps[number], "mcp"> | Cause.IllegalArgumentError, BuildContext<Apps[number], "mcp"> | HttpRouter.HttpRouter | HttpRouter.Request.From<"Requires", ToolRequestContext<Apps[number], RB>>>;
 /**
- * Serve MCP tools through newline-delimited JSON-RPC on standard I/O.
+ * Serve MCP tools through newline-delimited JSON-RPC on standard I/O, speaking MCP
+ * 2026-07-28 only.
  *
  * The host supplies the `Stdio` service. Arguments are tool input only and
  * never establish request identity or authority.

package/dist/ActionMcp.mjs

@@ -1,8 +1,13 @@
 import "./internal/implementation.mjs";
 import { bindTools } from "./internal/tools.mjs";
 import { Layer } from "effect";
-import { McpServer } from "effect/unstable/ai";
+import { McpProtocol, McpServer } from "effect/unstable/ai";
 //#region src/ActionMcp.ts
+/**
+* The one protocol revision served. 2026-07-28 is stateless over HTTP: no
+* initialize handshake and no session, so every request stands alone.
+*/
+const protocols = [McpProtocol.v2026_07_28];
 const registration = (apps, options) => {
 	const binding = bindTools(apps, "mcp", options);
 	return Layer.effectDiscard(McpServer.registerToolkit(binding.toolkit)).pipe(Layer.provide(binding.layer));
@@ -10,16 +15,15 @@ const registration = (apps, options) => {
 const server = (apps, options, transport) => registration(apps, options).pipe(Layer.provide(transport), Layer.fresh);
 function layerHttp(apps, options) {
 	return server(apps, options, McpServer.layerHttp({
-		name: options.name,
-		version: options.version,
-		instructions: options.instructions,
-		path: options.path,
-		protocols: options.protocols,
-		allowedOrigins: options.allowedOrigins
+		...options,
+		protocols
 	}));
 }
 function layerStdio(apps, options) {
-	return server(apps, options, McpServer.layerStdio(options));
+	return server(apps, options, McpServer.layerStdio({
+		...options,
+		protocols
+	}));
 }
 //#endregion
 export { layerHttp, layerStdio };

package/dist/Testing.d.mts

@@ -1,4 +1,4 @@
-import { Effect } from "effect";
+import { Effect, Schema } from "effect";
 import { HttpApi, HttpApiClient, HttpApiGroup } from "effect/unstable/httpapi";
 //#region src/Testing.d.ts
 /** A web handler, such as `HttpRouter.toWebHandler(routes).handler`. */
@@ -33,4 +33,34 @@ export interface McpRequestParams {
 }
 /** Build one stateless 2026-07-28 JSON-RPC request, with client metadata defaulted. */
 export declare const mcpRequest: ({ url, method, params, headers: init }: McpRequestOptions) => Request;
+/** One `tools/call` for `mcpCall`: the endpoint, the tool and its arguments. */
+export interface McpCallOptions {
+  readonly url: string | URL;
+  /** The tool name, `mcp.name` of its action. */
+  readonly name: string;
+  /** Defaults to `{}`. Like `params`, it may be malformed on purpose. */
+  readonly arguments?: {
+    readonly [key: string]: McpRequestValue;
+  };
+  readonly headers?: ConstructorParameters<typeof Headers>[0];
+}
+/**
+ * A tool call's outcome with the library's wire envelope removed: the success from
+ * `structuredContent.value`, or the error text of an `isError` result, parsed as JSON
+ * when it is JSON (a declared error) and kept as the text otherwise (the native
+ * server's own message, such as for invalid arguments).
+ */
+export type McpCallResult = {
+  readonly isError: false;
+  readonly value: Schema.Json;
+} | {
+  readonly isError: true;
+  readonly error: Schema.Json;
+};
+/**
+ * Call one tool through `handler` with a stateless 2026-07-28 request and return its
+ * outcome. A response that is not an HTTP 200 carrying a tool result, such as an
+ * authentication refusal or a JSON-RPC error, throws; use `mcpRequest` to inspect one.
+ */
+export declare const mcpCall: (handler: Handler, { url, name, headers, ...options }: McpCallOptions) => Promise<McpCallResult>;
 //#endregion

package/dist/Testing.mjs

@@ -1,4 +1,4 @@
-import { Effect, Layer, Predicate } from "effect";
+import { Effect, Layer, Option, Predicate, Schema } from "effect";
 import { FetchHttpClient } from "effect/unstable/http";
 import { HttpApiClient } from "effect/unstable/httpapi";
 //#region src/Testing.ts
@@ -38,5 +38,53 @@ const mcpRequest = ({ url, method, params = {}, headers: init }) => {
 		})
 	});
 };
+/** The JSON-RPC response to a `tools/call`: a tool result or a protocol error. */
+const ToolReply = Schema.Union([Schema.Struct({ result: Schema.Struct({
+	isError: Schema.optionalKey(Schema.Boolean),
+	structuredContent: Schema.optionalKey(Schema.Struct({ value: Schema.Json })),
+	content: Schema.Array(Schema.Struct({
+		type: Schema.String,
+		text: Schema.optionalKey(Schema.String)
+	}))
+}) }), Schema.Struct({ error: Schema.Struct({
+	code: Schema.Finite,
+	message: Schema.String
+}) })]);
+const decodeReply = Schema.decodeUnknownOption(Schema.fromJsonString(ToolReply));
+const parseJson = Schema.decodeUnknownOption(Schema.fromJsonString(Schema.Json));
+/**
+* Call one tool through `handler` with a stateless 2026-07-28 request and return its
+* outcome. A response that is not an HTTP 200 carrying a tool result, such as an
+* authentication refusal or a JSON-RPC error, throws; use `mcpRequest` to inspect one.
+*/
+const mcpCall = async (handler, { url, name, headers, ...options }) => {
+	const response = await handler(mcpRequest({
+		url,
+		method: "tools/call",
+		params: {
+			name,
+			arguments: options.arguments ?? {}
+		},
+		...headers === void 0 ? {} : { headers }
+	}));
+	const body = await response.text();
+	if (response.status !== 200) throw new Error(`MCP tools/call "${name}" answered ${response.status}: ${body}`);
+	const reply = body.split("\n").map((line) => line.replace(/^data:/, "").trim()).flatMap((line) => Option.toArray(decodeReply(line))).at(-1);
+	if (reply === void 0) throw new Error(`MCP tools/call "${name}" had no reply: ${body}`);
+	if ("error" in reply) throw new Error(`MCP tools/call "${name}" failed with ${reply.error.code}: ${reply.error.message}`);
+	const { result } = reply;
+	if (result.isError === true) {
+		const text = result.content.find((content) => content.type === "text")?.text ?? "";
+		return {
+			isError: true,
+			error: Option.getOrElse(parseJson(text), () => text)
+		};
+	}
+	if (result.structuredContent === void 0) throw new Error(`MCP tools/call "${name}" returned no structured content: ${body}`);
+	return {
+		isError: false,
+		value: result.structuredContent.value
+	};
+};
 //#endregion
-export { httpClient, mcpRequest };
+export { httpClient, mcpCall, mcpRequest };

package/dist/TestingClient.d.mts

@@ -1,16 +1,17 @@
-import { Client, ClientOptions } from "@modelcontextprotocol/client";
+import { Client } from "@modelcontextprotocol/client";
 //#region src/TestingClient.d.ts
 /** How `withMcpClient` connects the official client. */
 export interface McpClientOptions {
   /** A web handler, such as `HttpRouter.toWebHandler(routes).handler`. */
   readonly fetch: (request: Request) => Promise<Response>;
   readonly path: string;
-  /** Passed directly to the official client; omitted options use its native default. */
-  readonly versionNegotiation?: ClientOptions["versionNegotiation"];
   /** Defaults to `http://localhost`. */
   readonly baseUrl?: string | URL;
   readonly headers?: ConstructorParameters<typeof Headers>[0];
 }
-/** Connect an official client and always close its transport after the callback. */
-export declare const withMcpClient: <A>({ fetch, path, baseUrl, headers, versionNegotiation }: McpClientOptions, run: (client: Client) => Promise<A>) => Promise<A>;
+/**
+ * Connect an official client pinned to MCP 2026-07-28, the revision `ActionMcp`
+ * serves, and always close its transport after the callback.
+ */
+export declare const withMcpClient: <A>({ fetch, path, baseUrl, headers }: McpClientOptions, run: (client: Client) => Promise<A>) => Promise<A>;
 //#endregion

package/dist/TestingClient.mjs

@@ -1,11 +1,14 @@
 import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
 //#region src/TestingClient.ts
-/** Connect an official client and always close its transport after the callback. */
-const withMcpClient = async ({ fetch, path, baseUrl = "http://localhost", headers, versionNegotiation }, run) => {
+/**
+* Connect an official client pinned to MCP 2026-07-28, the revision `ActionMcp`
+* serves, and always close its transport after the callback.
+*/
+const withMcpClient = async ({ fetch, path, baseUrl = "http://localhost", headers }, run) => {
 	const client = new Client({
 		name: "test",
 		version: "0"
-	}, versionNegotiation === void 0 ? {} : { versionNegotiation });
+	}, { versionNegotiation: { mode: { pin: "2026-07-28" } } });
 	try {
 		const transportOptions = { fetch: (input, init) => fetch(new Request(input, init)) };
 		if (headers !== void 0) transportOptions.requestInit = { headers };

package/dist/internal/actions.d.mts

@@ -1,18 +1,29 @@
 import { Action_d_exports, Any, Codec } from "../Action.mjs";
 import { HttpApiError } from "effect/unstable/httpapi";
 //#region src/internal/actions.d.ts
-/** Pure HTTP policy for native schema decoding and encoding failures. */
-export interface SchemaErrorPolicy<Errors extends ReadonlyArray<Codec>> {
-  readonly errors: Errors;
-  readonly map: (failure: HttpApiError.HttpApiSchemaError) => NoInfer<Errors[number]["Type"]>;
+/** One side of a schema-error policy: the error it answers with, and how to make it. */
+export interface SchemaErrorAnswer<E extends Codec> {
+  /** A declared error schema; its `httpApiStatus` is the HTTP status of the answer. */
+  readonly schema: E;
+  readonly make: (failure: HttpApiError.HttpApiSchemaError) => NoInfer<E["Type"]>;
+}
+/**
+ * Pure HTTP policy for native schema failures, split by whose fault they are. The
+ * library owns the split, so every group draws it the same way.
+ */
+export interface SchemaErrorPolicy<Invalid extends Codec = Codec, Internal extends Codec = Codec> {
+  /** The request did not decode: its payload, or its params, headers or query. */
+  readonly invalid: SchemaErrorAnswer<Invalid>;
+  /** The handler's result did not encode: its body or its response headers. */
+  readonly internal: SchemaErrorAnswer<Internal>;
 }
 /** The contract half of a group: what adapters and clients need, without `implement`. */
-export interface Actions<Name extends string = string, A extends ReadonlyArray<Any> = ReadonlyArray<Any>, PolicyErrors extends ReadonlyArray<Codec> = ReadonlyArray<Codec>> {
+export interface Actions<Name extends string = string, A extends ReadonlyArray<Any> = ReadonlyArray<Any>, PolicyError extends Codec = Codec> {
   readonly name: Name;
   readonly actions: A;
   /** How HTTP answers failed decoding or encoding; native behavior without one. MCP is unaffected. */
-  readonly schemaError: SchemaErrorPolicy<PolicyErrors> | undefined;
+  readonly schemaError: SchemaErrorPolicy<PolicyError, PolicyError> | undefined;
 }
 /** The errors a group's policy may answer with, by lookup rather than a conditional type. */
-export type PolicyError<G extends Actions> = NonNullable<G["schemaError"]>["errors"][number];
+export type PolicyError<G extends Actions> = NonNullable<G["schemaError"]>[keyof SchemaErrorPolicy]["schema"];
 //#endregion

package/dist/internal/actions.mjs

@@ -1,4 +1,14 @@
 //#region src/internal/actions.ts
+/** Each distinct error a policy may answer with, invalid first. */
+const policyErrors = (policy) => [.../* @__PURE__ */ new Set([policy.invalid.schema, policy.internal.schema])];
+/**
+* `HttpApiBuilder` reports these kinds while encoding the handler's answer, after the
+* handler ran; every other kind (`Payload`, `Params`, `Headers`, `Query`) comes from
+* decoding the request before it.
+*/
+const responseKinds = /* @__PURE__ */ new Set(["Body", "ResponseHeaders"]);
+/** The policy's answer to one native failure: `internal` for the response side, else `invalid`. */
+const answerSchemaError = (policy, failure) => responseKinds.has(failure.kind) ? policy.internal.make(failure) : policy.invalid.make(failure);
 /**
 * An action's own failures plus the ones its surface answers with, which is what
 * a projection of that action declares. A schema the action already declares is
@@ -28,4 +38,4 @@ const assertDistinct = (what, names) => {
 	}
 };
 //#endregion
-export { assertDistinct, assertName, projectedErrors, selectNamed };
+export { answerSchemaError, assertDistinct, assertName, policyErrors, projectedErrors, selectNamed };

package/dist/internal/implementation.mjs

@@ -22,8 +22,9 @@ var Implementation = class Implementation {
 	}
 };
 /**
-* Select and invoke a handler after an adapter has selected a concrete action.
-* The surface's pre-handler hook runs first, outside the action's span, so a
+* Select the handler of a concrete action, once, when an adapter binds its acquired
+* record; `implement` has already refused a record without it. The returned function
+* invokes it: the surface's pre-handler hook runs first, outside the action's span, so a
 * refusal is attributed to the surface rather than to a handler that never ran.
 * `R` remains in the returned effect so transport layers cannot erase required
 * per-request services while assembling routes.

package/dist/internal/tools.mjs

@@ -47,7 +47,7 @@ const project = (projection, entry, options) => {
 	return tool.annotate(Tool.Strict, true);
 };
 const handler = (projection, app, action, handlers, before) => {
-	const run = (input) => dispatch(app.group, action, handlers, before)(input);
+	const run = dispatch(app.group, action, handlers, before);
 	return projection === "native" ? run : (input) => Effect.map(run(input), (value) => ({ value }));
 };
 /**