@gjermundgaraba/effect-actions 0.5.0 → 0.7.0

package/dist/ActionToolkit.d.mts

@@ -1,16 +1,14 @@
 import { Action_d_exports, Any, Codec } from "./Action.mjs";
-import { AnyImplementation, BuildContext, BuildError, HandlerContext, Implementation } from "./internal/implementation.mjs";
+import { AnyImplementation, BuildContext, BuildError, HandlerContext, HiddenFromMcp, Implementation } from "./internal/implementation.mjs";
 import { SurfaceOptions } from "./internal/tools.mjs";
 import { Layer, Schema } from "effect";
 import { Tool, Toolkit } from "effect/unstable/ai";
 //#region src/ActionToolkit.d.ts
 /** What the in-process caller binds around the implementations it projects. */
 export type Options<Errors extends ReadonlyArray<Codec> = [], R = never> = SurfaceOptions<Errors, R>;
-/** A native tool corresponding to an MCP-enabled action. */
-type NativeTool<A extends Any, E extends Codec, R> = A extends {
-  readonly mcp: {
-    readonly name: infer Name extends string;
-  };
+/** A native tool corresponding to an action MCP may serve, named by its tool metadata. */
+type NativeTool<A extends Any, E extends Codec, R> = Extract<A["mcp"], object> extends {
+  readonly name: infer Name extends string;
 } ? Tool.Tool<Name, {
   readonly parameters: A["input"];
   readonly success: A["success"];
@@ -18,10 +16,11 @@ type NativeTool<A extends Any, E extends Codec, R> = A extends {
   readonly failureMode: "return";
 }, R> : never;
 type HandlersOf<App extends AnyImplementation> = App extends Implementation<any, infer H, any, any> ? H : never;
-/** A tool needs what its handler needs, plus what the binding's `before` hook needs. */
-type ToolForAction<App extends AnyImplementation, A extends Any, E extends Codec, RB> = A extends {
-  readonly mcp: object;
-} ? NativeTool<A, E, HandlerContext<HandlersOf<App>, Extract<A["name"], keyof HandlersOf<App>>> | RB> : never;
+/**
+ * A tool needs what its handler needs, plus what the binding's `before` hook needs. The
+ * rule is `ActionMcp`'s: only an action certainly hidden from MCP has no tool.
+ */
+type ToolForAction<App extends AnyImplementation, A extends Any, E extends Codec, RB> = A extends HiddenFromMcp ? never : NativeTool<A, E, HandlerContext<HandlersOf<App>, Extract<A["name"], keyof HandlersOf<App>>> | RB>;
 type ToolsFor<App extends AnyImplementation, E extends Codec, RB> = App extends AnyImplementation ? ToolForAction<App, App["group"]["actions"][number], E, RB> : never;
 type ToolkitTools<Apps extends ReadonlyArray<AnyImplementation>, E extends Codec, RB> = { readonly [T in ToolsFor<Apps[number], E, RB> as T["name"]]: T; };
 /** Native tools and the layer that binds their action implementations. */
@@ -37,5 +36,5 @@ export interface Binding<Tools extends Record<string, Tool.Any>, E = never, R =
  * Build services are needed to construct `layer`; request services are needed
  * when the resulting toolkit handles a call.
  */
-export declare function make<const Apps extends ReadonlyArray<AnyImplementation>, const Errors extends ReadonlyArray<Codec> = [], RB = never>(apps: readonly [...Apps], options?: Options<Errors, RB>): Binding<ToolkitTools<Apps, Errors[number], RB>, BuildError<Apps[number], "mcp">, BuildContext<Apps[number], "mcp">>;
+export declare function make<const Apps extends ReadonlyArray<AnyImplementation>, const Errors extends ReadonlyArray<Codec> = [], RB = never>(apps: readonly [...Apps], options?: Options<Errors, RB>): Binding<ToolkitTools<Apps, Errors[number], RB>, BuildError<Apps[number], HiddenFromMcp>, BuildContext<Apps[number], HiddenFromMcp>>;
 //#endregion

package/dist/Testing.d.mts

@@ -1,5 +1,6 @@
-import { Effect } from "effect";
-import { HttpApi, HttpApiClient, HttpApiGroup } from "effect/unstable/httpapi";
+import { ClientOptions } from "./internal/fetchClient.mjs";
+import { Schema } from "effect";
+import { HttpApi, HttpApiGroup } from "effect/unstable/httpapi";
 //#region src/Testing.d.ts
 /** A web handler, such as `HttpRouter.toWebHandler(routes).handler`. */
 export type Handler = (request: Request) => Promise<Response>;
@@ -7,9 +8,9 @@ export type Handler = (request: Request) => Promise<Response>;
  * The native grouped HTTP client, calling `handler` in memory instead of the network.
  * `baseUrl` defaults to `http://localhost`.
  */
-export declare const httpClient: <Id extends string, Groups extends HttpApiGroup.Constraint>(api: HttpApi.HttpApi<Id, Groups>, handler: Handler, options?: NonNullable<Parameters<typeof HttpApiClient.make>[1]>) => Effect.Effect<import("effect/Types").Simplify<{ readonly [Group in Extract<Groups, {
+export declare const httpClient: <Id extends string, Groups extends HttpApiGroup.Constraint>(api: HttpApi.HttpApi<Id, Groups>, handler: Handler, options?: ClientOptions) => import("effect/Effect").Effect<import("effect/Types").Simplify<{ readonly [Group in Extract<Groups, {
   readonly topLevel: false;
-}> as HttpApiGroup.Identifier<Group>]: HttpApiClient.Client.GroupByEndpoint<Group, never, never>; } & HttpApiClient.Client.TopLevelMethods<Groups, never, never>>, never, Exclude<import("effect/unstable/httpapi/HttpApiMiddleware").MiddlewareClient<import("effect/unstable/httpapi/HttpApiEndpoint").Middleware<HttpApiGroup.Endpoints<Groups>>>, import("effect/unstable/http/HttpClient").HttpClient>>;
+}> as HttpApiGroup.Identifier<Group>]: import("effect/unstable/httpapi/HttpApiClient").Client.GroupByEndpoint<Group, never, never>; } & import("effect/unstable/httpapi/HttpApiClient").Client.TopLevelMethods<Groups, never, never>>, never, Exclude<Exclude<import("effect/unstable/httpapi/HttpApiMiddleware").MiddlewareClient<import("effect/unstable/httpapi/HttpApiEndpoint").Middleware<HttpApiGroup.Endpoints<Groups>>>, import("effect/unstable/http/HttpClient").HttpClient>, never>>;
 /** A stateless 2026-07-28 request. */
 export interface McpRequestOptions {
   readonly url: string | URL;
@@ -33,4 +34,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, whatever its shape) 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, arguments: args }: McpCallOptions) => Promise<McpCallResult>;
 //#endregion

package/dist/Testing.mjs

@@ -1,15 +1,14 @@
-import { Effect, Layer, Predicate } from "effect";
-import { FetchHttpClient } from "effect/unstable/http";
-import { HttpApiClient } from "effect/unstable/httpapi";
+import { fetchApiClient } from "./internal/fetchClient.mjs";
+import { Option, Predicate, Schema } from "effect";
 //#region src/Testing.ts
 /**
 * The native grouped HTTP client, calling `handler` in memory instead of the network.
 * `baseUrl` defaults to `http://localhost`.
 */
-const httpClient = (api, handler, options) => HttpApiClient.make(api, {
+const httpClient = (api, handler, options) => fetchApiClient(api, (input, init) => handler(new Request(input, init)), {
 	baseUrl: "http://localhost",
 	...options
-}).pipe(Effect.provide(FetchHttpClient.layer.pipe(Layer.provide(Layer.succeed(FetchHttpClient.Fetch, (input, init) => handler(new Request(input, init)))))));
+});
 /** Build one stateless 2026-07-28 JSON-RPC request, with client metadata defaulted. */
 const mcpRequest = ({ url, method, params = {}, headers: init }) => {
 	const headers = new Headers(init);
@@ -38,5 +37,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, arguments: args = {} }) => {
+	const response = await handler(mcpRequest({
+		url,
+		method: "tools/call",
+		params: {
+			name,
+			arguments: args
+		},
+		...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/fetchClient.d.mts

@@ -0,0 +1,6 @@
+import { Effect } from "effect";
+import { HttpApi, HttpApiClient, HttpApiGroup } from "effect/unstable/httpapi";
+//#region src/internal/fetchClient.d.ts
+/** The native `HttpApiClient.make` options: `baseUrl`, `transformClient`, `transformResponse`. */
+export type ClientOptions = NonNullable<Parameters<typeof HttpApiClient.make>[1]>;
+//#endregion

package/dist/internal/fetchClient.mjs

@@ -0,0 +1,8 @@
+import { Effect } from "effect";
+import { FetchHttpClient } from "effect/unstable/http";
+import { HttpApiClient } from "effect/unstable/httpapi";
+//#region src/internal/fetchClient.ts
+/** The native grouped `HttpApiClient` of `api`, sending every request through `fetch`. */
+const fetchApiClient = (api, fetch, options) => HttpApiClient.make(api, options).pipe(Effect.provide(FetchHttpClient.layer), Effect.provideService(FetchHttpClient.Fetch, fetch));
+//#endregion
+export { fetchApiClient };

package/dist/internal/implementation.d.mts

@@ -30,21 +30,20 @@ export declare class Implementation<G extends Actions, H, EX, RX> {
 }
 /** Any nominal implementation of `G`, with its record and channels erased. */
 export type AnyImplementation<G extends Actions = Actions> = Implementation<G, any, any, any>;
-/** The transports that serve a subset of a group's actions, by the contract flag that hides an action. */
-export type Transport = "http" | "mcp";
+/** What hides an action from MCP and Toolkit types: an `mcp` type of exactly `false`. The one rule both use. */
+export type HiddenFromMcp = {
+  readonly mcp: false;
+};
 /**
- * Names of the actions of `G` that `T` may serve. Only an action hidden by a
- * literal `false` is excluded; a flag decided at runtime keeps its requirements.
+ * Names of the actions of `G` a surface serves: all of them, less those matching
+ * `Hidden`. An action whose `mcp` may be `false` at runtime does not match, so it keeps
+ * its requirements.
  */
-export type ServedNames<G extends Actions, T extends Transport> = Exclude<G["actions"][number], T extends "http" ? {
-  readonly http: false;
-} : {
-  readonly mcp: false;
-}>["name"];
-/** Per-request requirements of the handlers `T` can invoke, or of a union of implementations. */
-export type RequestContext<App, T extends Transport> = App extends Implementation<infer G, infer H, any, any> ? { readonly [K in Extract<ServedNames<G, T>, keyof H>]: HandlerContext<H, K>; }[Extract<ServedNames<G, T>, keyof H>] : never;
-/** Handler-acquisition failures of the implementations `T` acquires, or of a union of them. */
-export type BuildError<App, T extends Transport> = App extends Implementation<infer G, any, infer EX, any> ? [ServedNames<G, T>] extends [never] ? never : EX : never;
-/** Handler-acquisition requirements of the implementations `T` acquires, or of a union of them. */
-export type BuildContext<App, T extends Transport> = App extends Implementation<infer G, any, any, infer RX> ? [ServedNames<G, T>] extends [never] ? never : RX : never;
+type ServedNames<G extends Actions, Hidden> = Exclude<G["actions"][number], Hidden>["name"];
+/** Per-request requirements of the handlers a surface can invoke, or of a union of implementations. */
+export type RequestContext<App, Hidden = never> = App extends Implementation<infer G, infer H, any, any> ? { readonly [K in Extract<ServedNames<G, Hidden>, keyof H>]: HandlerContext<H, K>; }[Extract<ServedNames<G, Hidden>, keyof H>] : never;
+/** Handler-acquisition failures of the implementations a surface acquires, or of a union of them. */
+export type BuildError<App, Hidden = never> = App extends Implementation<infer G, any, infer EX, any> ? [ServedNames<G, Hidden>] extends [never] ? never : EX : never;
+/** Handler-acquisition requirements of the implementations a surface acquires, or of a union of them. */
+export type BuildContext<App, Hidden = never> = App extends Implementation<infer G, any, any, infer RX> ? [ServedNames<G, Hidden>] extends [never] ? never : RX : never;
 //#endregion

package/dist/internal/implementation.mjs

@@ -1,4 +1,4 @@
-import { Effect } from "effect";
+import { Effect, Predicate } from "effect";
 //#region src/internal/implementation.ts
 /**
 * An acquired handler record for a group.
@@ -22,15 +22,16 @@ 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.
 */
 const dispatch = (group, action, handlers, before) => {
-	const handle = handlers[action.name];
-	if (handle === void 0) throw new Error(`Missing handler: ${action.name}`);
+	const handle = Object.hasOwn(handlers, action.name) ? handlers[action.name] : void 0;
+	if (!Predicate.isFunction(handle)) throw new Error(`No handler for ${group.name}.${action.name}`);
 	const attributes = {
 		"action.group": group.name,
 		"action.name": action.name,

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 }));
 };
 /**

package/docs/Action.md

@@ -7,18 +7,17 @@ metadata. An action holds no behavior; handlers are bound by `ActionGroup.implem
 
 Import `@gjermundgaraba/effect-actions/Action`.
 
-| Export                                     | Purpose                                                                            |
-| ------------------------------------------ | ---------------------------------------------------------------------------------- |
-| `make(name, options)`                      | Define a pure contract; literal names, access and transport exclusions stay typed. |
-| `Action`, `Any`, `Options`                 | Concrete contracts, erased contracts and construction options.                     |
-| `Codec`, `Handler`, `Access`, `McpOptions` | Service-free codecs, typed handlers, read/write classification and tool metadata.  |
+| Export                                     | Purpose                                                                           |
+| ------------------------------------------ | --------------------------------------------------------------------------------- |
+| `make(name, options)`                      | Define a pure contract; literal names, access and MCP exclusion stay typed.       |
+| `Action`, `Any`, `Options`                 | Concrete contracts, erased contracts and construction options.                    |
+| `Codec`, `Handler`, `Access`, `McpOptions` | Service-free codecs, typed handlers, read/write classification and tool metadata. |
 
 | Option                             | Meaning                                                                      |
 | ---------------------------------- | ---------------------------------------------------------------------------- |
 | `description`, `success`, `access` | Required description, success codec and `"read"` / `"write"` classification. |
 | `input`                            | Optional codec; omission means an empty object.                              |
 | `errors`                           | Declared error codecs; defaults to none.                                     |
-| `http`                             | Defaults to enabled; `false` removes routes and client methods.              |
 | `mcp`                              | Defaults to enabled; `false` removes tools, otherwise accepts `McpOptions`.  |
 
 MCP options: `name` defaults to the action name; `readOnly` to `access === "read"`;
@@ -65,12 +64,11 @@ export const WhoAmI = Action.make("whoAmI", {
   access: "read",
 });
 
-// MCP-only: no HTTP route, no client method.
+// A tool only: its group is left out of the HTTP binding (see ActionHttp.md).
 export const ListChanges = Action.make("listChanges", {
   description: "List renames in your tenant, oldest first.",
   success: Schema.Struct({ changes: Schema.Array(Schema.String) }),
   access: "read",
-  http: false,
   mcp: { name: "list_changes" },
 });
 
@@ -90,8 +88,10 @@ export const Double = Action.make("double", {
 - `errors` is a list of schemas, default none. Each keeps its own `httpApiStatus` annotation; an unannotated error is served as HTTP 500. Group-level `errors` are appended to every action of the group (see [ActionGroup.md](ActionGroup.md)).
 - A handler may fail only with the declared errors. Anything else is a defect.
 - `access` is `"read"` or `"write"` and is required. `make` also checks it at runtime, so a caller the compiler never sees cannot define an action no rule classifies. It stays a literal on the action, so a rule may switch on it at the type level. It is authorization metadata for a surface's `before` hook (see [guarantees.md](guarantees.md)); the library itself authorizes nothing. Its only built-in uses are default MCP hints and span/log annotations; adapters never enforce an authorization rule from it.
-- `access` is independent of `mcp`. A local-only action (`mcp: false`) still has one, and an action may set `access: "write"` with `mcp: { readOnly: true }` if the tool hint should say something else. Derive authorization from `access`, never from a tool hint.
-- Both transports are on by default. `http: false` removes the route and the client method. `mcp: false` removes the tool. Both `false` makes a local-only action, reachable through `ActionCli` only.
+- `access` is independent of `mcp`. An action hidden from MCP (`mcp: false`) still has one, and an action may set `access: "write"` with `mcp: { readOnly: true }` if the tool hint should say something else. Derive authorization from `access`, never from a tool hint.
+- An action has no HTTP switch. HTTP serves every action of every group it binds; to keep an action off HTTP, put it in a group the HTTP binding leaves out. `ActionCli` runs any action locally.
+- `mcp: false` removes the tool. The action's type is hidden from MCP only when the options' type has a required `mcp: false`, such as a literal `mcp: false` in the object passed to `make`. Options that may serve it type it as served, so MCP layers keep its handler's requirements: a conditional spread of `{ mcp: false }`, `false | undefined`, a flag-driven value such as `enabled ? {} : false`, or an `Options` value whose `mcp` is optional.
+- `make` accepts only the keys `Options` declares. An unknown key, such as a stale `http`, is a compile error.
 - MCP input must have an object-root JSON Schema, an identified or recursive root included. Scalar or array input is fine for HTTP and for a native Toolkit, but the native MCP server refuses it when an `ActionMcp` layer is built. Success and error schemas may be any shape.
 - `mcp.name` is the tool name, matches `[A-Za-z0-9_-]+` except `then`, is at most 128 characters, unique within the group and within any Toolkit or MCP projection that serves the group. Default is the action name.
 - Hint defaults: `readOnly: access === "read"`, `destructive: !readOnly`, `idempotent: false`, `openWorld: true`. Hints are metadata for the model. They do not enforce authorization, approval, or retries.
@@ -105,4 +105,5 @@ export const Double = Action.make("double", {
 - Type error `Effect<..., X, ...> is not assignable` in `implement`: the handler fails with an undeclared error `X`. Add it to `errors` or handle it.
 - Handler receives a string where a number was expected: the schema is `Schema.String`, not a transforming codec such as `Schema.FiniteFromString`.
 - `Property 'access' is missing` at `make`: every action declares `"read"` or `"write"`. There is no default.
+- `Type 'false' is not assignable to type 'never'` on `http` at `make`: the option is gone. Delete it; to keep the action off HTTP, move it to a group the HTTP binding leaves out.
 - A tool shows `readOnlyHint: false` for a read: the action sets `mcp: { readOnly: false }` explicitly, which wins over `access`.

package/docs/ActionCatalog.md

@@ -7,15 +7,15 @@ Built from contracts alone: no implementation, service or server is involved.
 
 Import `@gjermundgaraba/effect-actions/ActionCatalog`.
 
-`make(...groups)` returns `Catalog`: `version: "3"` and an ordered `actions` array of `Entry`.
+`make(...groups)` returns `Catalog`: `version: "4"` and an ordered `actions` array of `Entry`.
 
-| Entry field                          | Meaning                                                                      |
-| ------------------------------------ | ---------------------------------------------------------------------------- |
-| `id`, `group`, `name`, `description` | Stable `<group>.<action>` identity and contract metadata.                    |
-| `http`, `mcp`                        | HTTP enablement and resolved MCP enablement/name/hints.                      |
-| `input`, `success`                   | Standalone draft 2020-12 JSON Schema objects, not wrappers.                  |
-| `errors`                             | JSON Schema objects for own and inherited group errors.                      |
-| `httpSchemaErrors`                   | JSON Schema objects for HTTP policy errors; empty for HTTP-disabled actions. |
+| Entry field                          | Meaning                                                             |
+| ------------------------------------ | ------------------------------------------------------------------- |
+| `id`, `group`, `name`, `description` | Stable `<group>.<action>` identity and contract metadata.           |
+| `mcp`                                | Resolved MCP enablement, name and hints.                            |
+| `input`, `success`                   | Standalone draft 2020-12 JSON Schema objects, not wrappers.         |
+| `errors`                             | JSON Schema objects for own and inherited group errors.             |
+| `httpSchemaErrors`                   | JSON Schema objects for HTTP policy errors; empty without a policy. |
 
 Exported types are `Catalog` and `Entry`.
 
@@ -43,7 +43,7 @@ Console.log(
 - Each schema root includes its own `$schema` and, where needed, `$defs`. Equal identifiers across entries or fields cannot replace each other; recursive references resolve locally.
 - The catalog contains JSON Schema only. Use Effect's `SchemaRepresentation` directly when native schema persistence or revival is needed.
 - `errors` includes group-level errors. HTTP schema-policy errors are separate in `httpSchemaErrors`. Surface errors belong to bindings and are not listed.
-- `access` is omitted; read it from the contract when needed. Local-only actions are included. Presence grants no authorization or proof that an endpoint is mounted; the host decides what to publish.
+- `access` is omitted; read it from the contract when needed. Actions hidden from MCP are included. Presence grants no authorization or proof that an endpoint is mounted; the host decides what to publish.
 - No search, catalog HTTP endpoint, or TypeScript code generation is provided.
 
 ## Failure modes

package/docs/ActionCli.md

@@ -1,17 +1,17 @@
 # ActionCli
 
 Native Effect CLI commands that run handlers in-process. The host provides every service;
-nothing is fetched over HTTP.
+nothing is fetched over HTTP. Any action runs locally, whether or not HTTP or MCP serves it.
 
 ## API
 
 Import `@gjermundgaraba/effect-actions/ActionCli`.
 
-| API                            | Purpose                                                           |
-| ------------------------------ | ----------------------------------------------------------------- |
-| `command(app, name, options?)` | One selected action as a native Effect `Command`.                 |
-| `group(app, options?)`         | Every action under a group command, including local-only actions. |
-| `Options`, `GroupOptions`      | Configuration for single and aggregate commands.                  |
+| API                            | Purpose                                           |
+| ------------------------------ | ------------------------------------------------- |
+| `command(app, name, options?)` | One selected action as a native Effect `Command`. |
+| `group(app, options?)`         | Every action under a group command.               |
+| `Options`, `GroupOptions`      | Configuration for single and aggregate commands.  |
 
 | Option                | Meaning                                                                                                      |
 | --------------------- | ------------------------------------------------------------------------------------------------------------ |
@@ -56,7 +56,7 @@ Command.runWith(command, { version: "0.1.0" })(process.argv.slice(2)).pipe(
 
 ## Rules
 
-- `command(app, name)` selects one action by name from the bound group; the name is checked at the type level. `group(app)` puts every action under the group command, including actions with `http: false` and `mcp: false`.
+- `command(app, name)` selects one action by name from the bound group; the name is checked at the type level. `group(app)` puts every action under the group command, including actions with `mcp: false` and groups no HTTP binding serves.
 - Default syntax is `--input '<json>'` or `--input-file <path>` carrying the entire encoded input: nested objects, arrays, scalars. The file is read and JSON-parsed by the native `Flag.FileSchema`. Both are decoded by the native parser; if both are given, the file is used. Omitting both decodes `{}` separately on every invocation; result identity follows the codec's behavior. An action that requires input then fails with a `SchemaError`, exactly as a `parameters` command's mapped input does.
 - `parameters` and `input` are supplied together or not at all. With them, the command has explicit native flags and arguments and neither `--input` nor `--input-file`, so its syntax does not change when the schema changes.
 - `input(parsed)` returns encoded JSON. The action schema decodes it before dispatch; a mismatch is a `SchemaError` at runtime. Action fields are never turned into flags automatically.

package/docs/ActionCliClient.md

@@ -9,8 +9,8 @@ Import `@gjermundgaraba/effect-actions/ActionCliClient`.
 
 | API                                              | Purpose                                                                    |
 | ------------------------------------------------ | -------------------------------------------------------------------------- |
-| `command(http, groupName, actionName, options?)` | Call one HTTP-enabled action through a native Effect `Command`.            |
-| `group(http, groupName, options?)`               | Every HTTP-enabled action of a bound group under one command.              |
+| `command(http, groupName, actionName, options?)` | Call one action of the binding through a native Effect `Command`.          |
+| `group(http, groupName, options?)`               | Every action of a bound group under one command.                           |
 | `Options`, `GroupOptions`, `Connection`          | Single/aggregate command configuration and native HTTP connection options. |
 
 Single-command options: `name`, `render`, paired `parameters`/`input`, and `connection`.
@@ -49,7 +49,7 @@ Authentication: `connection: { transformClient: HttpClient.mapRequest(HttpClient
 
 ## Rules
 
-- Selectors resolve from `http.groups` only. `groupName` must be a bound group; `actionName` must be an action of that group with `http: true`. Runtime guards reject dynamically supplied strings that the types would not accept.
+- Selectors resolve from `http.groups` only. `groupName` must be a bound group; `actionName` must be an action of that group. Runtime guards reject dynamically supplied strings that the types would not accept.
 - The host provides `HttpClient` and its configuration. Endpoint selection, credentials, and storage are the host's; nothing is inferred from action arguments.
 - Input is decoded by the action schema before dispatch, then passed to the native client at its normal codec boundary. Do not pre-encode values.
 - Input syntax (`--input`, `--input-file`, or `parameters`) and output (`render` and its `--json` flag) are exactly as in `ActionCli`.
@@ -57,7 +57,7 @@ Authentication: `connection: { transformClient: HttpClient.mapRequest(HttpClient
 
 ## Failure modes
 
-- Type error on `actionName`: the action is `http: false`, or the group is not bound in this `Http`.
+- Type error on `actionName`: the action is not in that group, or the group is not bound in this `Http`.
 - `HttpClient` missing at runtime: provide `NodeHttpClient.layerUndici` (or `FetchHttpClient.layer`) to the runtime.
 - Connection refused: `connection.baseUrl` is absent or wrong. It has no default.
 - 401 from the server: add `transformClient` to `connection`. The command adds no headers on its own.