@gjermundgaraba/effect-actions 0.6.0 → 0.8.0

package/dist/ActionMcp.mjs

@@ -1,16 +1,85 @@
 import "./internal/implementation.mjs";
-import { bindTools } from "./internal/tools.mjs";
-import { Layer } from "effect";
-import { McpProtocol, McpServer } from "effect/unstable/ai";
+import { TextField, bindTools } from "./internal/tools.mjs";
+import { Context, Effect, Layer, Option, Predicate, Schema } from "effect";
+import { McpProtocol, McpSchema, McpServer } from "effect/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];
+/** The parts of a listed output schema a text field is removed from. */
+const decodeOutput = Schema.decodeUnknownOption(Schema.Struct({
+	properties: Schema.Record(Schema.String, Schema.Json),
+	required: Schema.optionalKey(Schema.Array(Schema.String))
+}));
+/** A JSON value that is an object: neither null, a scalar nor an array. */
+const isJsonObject = (value) => Predicate.isObject(value);
+/** Split a JSON object into one field and the rest. */
+const detach = (value, field) => {
+	const { [field]: detached, ...rest } = value;
+	return {
+		detached,
+		rest
+	};
+};
+/**
+* The listed output schema without the text field. Only a top-level property can be
+* detached; anything else fails the layer build rather than publish a schema the
+* structured content would not satisfy.
+*/
+const outputWithout = (tool, field) => {
+	const { properties: _, required: __, ...output } = tool.outputSchema ?? {};
+	const listed = Option.getOrUndefined(decodeOutput(tool.outputSchema));
+	if (listed === void 0 || !Object.hasOwn(listed.properties, field)) return Effect.die(`MCP tool '${tool.name}' cannot send '${field}' as text: it is not a top-level property of its success`);
+	const required = (listed.required ?? []).filter((key) => key !== field);
+	return Effect.succeed({
+		...output,
+		properties: detach(listed.properties, field).rest,
+		...required.length === 0 ? {} : { required }
+	});
+};
+/**
+* A successful result with a string text field sent once, raw, before the structured
+* rest and its JSON copy. Any other result, such as a failure or a success without
+* the field, is the native one.
+*/
+const textResult = (result, field) => {
+	const structured = result.structuredContent;
+	if (result.isError === true || !isJsonObject(structured)) return result;
+	const { detached, rest } = detach(structured, field);
+	if (!Predicate.isString(detached)) return result;
+	return new McpSchema.CallToolResult({
+		...result,
+		structuredContent: rest,
+		content: [{
+			type: "text",
+			text: detached
+		}, {
+			type: "text",
+			text: JSON.stringify(rest)
+		}]
+	});
+};
+/** A native registration whose success sends `field` as text. */
+const withText = (registration, field) => Effect.map(outputWithout(registration.tool, field), (outputSchema) => ({
+	...registration,
+	tool: new McpSchema.Tool({
+		...registration.tool,
+		outputSchema
+	}),
+	handle: (payload) => Effect.map(registration.handle(payload), (result) => Predicate.isTagged(result, "InputRequired") ? result : textResult(result, field))
+}));
 const registration = (apps, options) => {
 	const binding = bindTools(apps, "mcp", options);
-	return Layer.effectDiscard(McpServer.registerToolkit(binding.toolkit)).pipe(Layer.provide(binding.layer));
+	const registered = McpServer.registerToolkit(binding.toolkit).pipe(Effect.updateService(McpServer.McpServer, (server) => ({
+		...server,
+		addTool: (tool) => {
+			const field = Context.get(tool.annotations, TextField);
+			return field === void 0 ? server.addTool(tool) : Effect.flatMap(withText(tool, field), server.addTool);
+		}
+	})));
+	return Layer.effectDiscard(registered).pipe(Layer.provide(binding.layer));
 };
 const server = (apps, options, transport) => registration(apps, options).pipe(Layer.provide(transport), Layer.fresh);
 function layerHttp(apps, options) {

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";
+import { Tool, Toolkit } from "effect/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/ActionToolkit.mjs

@@ -1,7 +1,7 @@
 import "./internal/implementation.mjs";
 import { bindTools } from "./internal/tools.mjs";
 import "effect";
-import "effect/unstable/ai";
+import "effect/ai";
 //#region src/ActionToolkit.ts
 function make(apps, options = {}) {
 	return bindTools(apps, "native", options);

package/dist/Authentication.d.mts

@@ -1,5 +1,5 @@
 import { Context, Effect } from "effect";
-import { HttpRouter, HttpServerResponse } from "effect/unstable/http";
+import { HttpRouter, HttpServerResponse } from "effect/http";
 import { NonEmptyReadonlyArray } from "effect/Array";
 //#region src/Authentication.d.ts
 /**

package/dist/Authentication.mjs

@@ -1,5 +1,5 @@
 import { Effect } from "effect";
-import { HttpEffect, HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
+import { HttpEffect, HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/http";
 //#region src/Authentication.ts
 /**
 * Authenticate each request and provide its identity to the downstream handler.

package/dist/Testing.d.mts

@@ -1,5 +1,6 @@
-import { Effect, Schema } 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/http-api";
 //#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/http-api/HttpApiClient").Client.GroupByEndpoint<Group, never, never>; } & import("effect/http-api/HttpApiClient").Client.TopLevelMethods<Groups, never, never>>, never, Exclude<Exclude<import("effect/http-api/HttpApiMiddleware").MiddlewareClient<import("effect/http-api/HttpApiEndpoint").Middleware<HttpApiGroup.Endpoints<Groups>>>, import("effect/http/HttpClient").HttpClient>, never>>;
 /** A stateless 2026-07-28 request. */
 export interface McpRequestOptions {
   readonly url: string | URL;
@@ -45,14 +46,15 @@ export interface McpCallOptions {
   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).
+ * A tool call's outcome: the success from `structuredContent`, with the text an action's
+ * `mcp.text` field sent before it; 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 text?: string;
 } | {
   readonly isError: true;
   readonly error: Schema.Json;
@@ -62,5 +64,5 @@ export type McpCallResult = {
  * 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>;
+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, Option, Predicate, Schema } 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);
@@ -41,7 +40,7 @@ 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 })),
+	structuredContent: Schema.optionalKey(Schema.Json),
 	content: Schema.Array(Schema.Struct({
 		type: Schema.String,
 		text: Schema.optionalKey(Schema.String)
@@ -57,13 +56,13 @@ const parseJson = Schema.decodeUnknownOption(Schema.fromJsonString(Schema.Json))
 * 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 mcpCall = async (handler, { url, name, headers, arguments: args = {} }) => {
 	const response = await handler(mcpRequest({
 		url,
 		method: "tools/call",
 		params: {
 			name,
-			arguments: options.arguments ?? {}
+			arguments: args
 		},
 		...headers === void 0 ? {} : { headers }
 	}));
@@ -81,9 +80,11 @@ const mcpCall = async (handler, { url, name, headers, ...options }) => {
 		};
 	}
 	if (result.structuredContent === void 0) throw new Error(`MCP tools/call "${name}" returned no structured content: ${body}`);
+	const [text] = result.content.length > 1 ? result.content : [];
 	return {
 		isError: false,
-		value: result.structuredContent.value
+		value: result.structuredContent,
+		...text?.text === void 0 ? {} : { text: text.text }
 	};
 };
 //#endregion

package/dist/internal/actions.d.mts

@@ -1,5 +1,5 @@
 import { Action_d_exports, Any, Codec } from "../Action.mjs";
-import { HttpApiError } from "effect/unstable/httpapi";
+import { HttpApiError } from "effect/http-api";
 //#region src/internal/actions.d.ts
 /** One side of a schema-error policy: the error it answers with, and how to make it. */
 export interface SchemaErrorAnswer<E extends Codec> {

package/dist/internal/cli.d.mts

@@ -1,6 +1,6 @@
 import "../Action.mjs";
 import { Effect, Schema } from "effect";
-import { Command } from "effect/unstable/cli";
+import { Command } from "effect/cli";
 //#region src/internal/cli.d.ts
 /** Options shared by the local and HTTP command projections. */
 interface CommonOptions<Output> {

package/dist/internal/cli.mjs

@@ -1,5 +1,5 @@
 import { Console, Effect, Option, Schema } from "effect";
-import { Command, Flag } from "effect/unstable/cli";
+import { Command, Flag } from "effect/cli";
 //#region src/internal/cli.ts
 const isParametersOptions = (options) => options?.parameters !== void 0;
 /**

package/dist/internal/fetchClient.d.mts

@@ -0,0 +1,6 @@
+import { Effect } from "effect";
+import { HttpApi, HttpApiClient, HttpApiGroup } from "effect/http-api";
+//#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/http";
+import { HttpApiClient } from "effect/http-api";
+//#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.
@@ -30,8 +30,8 @@ var Implementation = class Implementation {
 * 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.d.mts

@@ -1,7 +1,7 @@
 import { Action_d_exports, Any, Codec } from "../Action.mjs";
 import "./implementation.mjs";
-import { Effect, Layer } from "effect";
-import { Tool, Toolkit } from "effect/unstable/ai";
+import { Context, Effect, Layer } from "effect";
+import { Tool, Toolkit } from "effect/ai";
 //#region src/internal/tools.d.ts
 /** What a tool surface binds around the implementations it projects. */
 export interface SurfaceOptions<Errors extends ReadonlyArray<Codec>, R> {

package/dist/internal/tools.mjs

@@ -1,8 +1,14 @@
 import { assertDistinct, projectedErrors } from "./actions.mjs";
 import { dispatch } from "./implementation.mjs";
-import { Effect, Schema } from "effect";
-import { Tool, Toolkit } from "effect/unstable/ai";
+import { Context, Effect, Schema } from "effect";
+import { Tool, Toolkit } from "effect/ai";
 //#region src/internal/tools.ts
+/**
+* The success field an MCP tool sends as a raw text block, from `mcp.text`. The native
+* server reads a tool's annotations when it registers the tool, so `ActionMcp` finds
+* it there.
+*/
+const TextField = Context.Reference("@gjermundgaraba/effect-actions/TextField", { defaultValue: () => void 0 });
 const isToolAction = (action) => action.mcp !== false;
 /** Only tool-enabled groups are acquired; each implementation appears once. */
 const toolApps = (apps) => apps.flatMap((app) => {
@@ -30,30 +36,26 @@ const nativeTool = (action, errors) => annotate(Tool.make(action.mcp.name, {
 	failureMode: "return"
 }), action.mcp);
 /**
-* MCP has a JSON-only wire contract. Success uses its documented `{ value }`
-* structured-content envelope; declared failures are returned as JSON text.
+* MCP has a JSON-only wire contract. Success is the encoded success as structured
+* content; declared failures are returned as JSON text.
 */
 const mcpTool = (action, errors) => annotate(Tool.make(action.mcp.name, {
 	description: action.description,
 	parameters: Schema.toCodecJson(action.input),
-	success: Schema.toCodecJson(Schema.Struct({ value: action.success })),
+	success: Schema.toCodecJson(action.success),
 	failure: Schema.toCodecJson(Schema.Union(errors)),
 	failureMode: "return"
-}), action.mcp);
+}), action.mcp).annotate(TextField, action.mcp.text);
 const project = (projection, entry, options) => {
 	const errors = projectedErrors(entry.action, options.errors);
 	const tool = projection === "native" ? nativeTool(entry.action, errors) : mcpTool(entry.action, errors);
 	if (projection === "native") return tool;
 	return tool.annotate(Tool.Strict, true);
 };
-const handler = (projection, app, action, handlers, before) => {
-	const run = dispatch(app.group, action, handlers, before);
-	return projection === "native" ? run : (input) => Effect.map(run(input), (value) => ({ value }));
-};
 /**
 * Project MCP-enabled actions and acquire their handlers exactly once per adapter layer.
-* Native and MCP differ only in tool codecs and the MCP success envelope; selection,
-* scoped acquisition, dispatch and native Toolkit binding stay identical.
+* Native and MCP differ only in tool codecs; selection, scoped acquisition, dispatch
+* and native Toolkit binding stay identical.
 */
 const bindTools = (apps, projection, options) => {
 	const served = toolApps(apps);
@@ -64,9 +66,9 @@ const bindTools = (apps, projection, options) => {
 		toolkit,
 		layer: toolkit.toLayer(Effect.map(Effect.forEach(served, ({ app, actions }) => Effect.map(app.build, (handlers) => {
 			const record = handlers;
-			return actions.map((action) => [action.mcp.name, handler(projection, app, action, record, options.before)]);
+			return actions.map((action) => [action.mcp.name, dispatch(app.group, action, record, options.before)]);
 		})), (built) => Object.fromEntries(built.flat())))
 	};
 };
 //#endregion
-export { bindTools };
+export { TextField, bindTools };

package/docs/Action.md

@@ -7,22 +7,22 @@ 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"`;
-`destructive` to `!readOnly`; `idempotent` to `false`; `openWorld` to `true`.
+`destructive` to `!readOnly`; `idempotent` to `false`; `openWorld` to `true`. `text` has no
+default; it names the success's text field.
 Handlers receive decoded input and return decoded success, failing only with declared errors.
 
 ## Canonical
@@ -65,15 +65,24 @@ 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" },
 });
 
+// MCP sends `markdown` once, raw, then the rest as structured content.
+// Every other surface serves the whole page.
+export const ReadPage = Action.make("readPage", {
+  description: "Read one page of a document as Markdown.",
+  input: Schema.Struct({ url: Schema.String }),
+  success: Schema.Struct({ markdown: Schema.String, next: Schema.optionalKey(Schema.String) }),
+  access: "read",
+  mcp: { name: "read_page", text: "markdown" },
+});
+
 // Input decoding is the schema's: "21" on the wire, 21 in the handler.
 export const Double = Action.make("double", {
   description: "Double a finite number supplied as a string.",
@@ -90,14 +99,17 @@ 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.
-- 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.
+- `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. `Schema.Struct({})` is not an object root either: omit `input` for no arguments. 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 each Toolkit or MCP projection that serves it. Default is the action name.
+- `mcp.text` names a string field of the encoded success, the text field; it may be optional. `make` refuses a field that is not a string. Building the MCP layer refuses a field that is not a top-level property of the success's JSON Schema, such as one of a union of structs. It changes only the MCP result (see [ActionMcp.md](ActionMcp.md)).
 - 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.
 - Schemas must be service-free. Put service access in the handler.
 - The group name, not the action, is the OpenAPI tag and operation-ID prefix: `<group>.<action>`.
-- HTTP strips undeclared input fields. MCP tools are strict (`Tool.Strict`): undeclared arguments are an invalid-arguments result and input schemas publish `additionalProperties: false`. HTTP is not strict, and cannot be made strict without a hack: Effect merges one `HttpApi.ParseOptions` per endpoint and uses it for payload decoding _and_ error encoding, so `onExcessProperty: "error"` also rejects a `TaggedError` instance's own `message` and `stack`, turning a declared 409 into an empty 500. Making the payload schema itself strict would require wrapping it in an open schema, which erases its OpenAPI shape. Declare the fields you accept and treat extra HTTP fields as ignored.
+- Input is closed: HTTP, MCP and typed clients refuse fields `input` does not declare. Details in [guarantees.md](guarantees.md).
 
 ## Failure modes
 
@@ -105,4 +117,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, hints and text field.                |
+| `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`.
 
@@ -38,12 +38,12 @@ Console.log(
 - Takes groups, not implementations. Nothing is acquired or started.
 - Group names must be unique. Entries preserve group declaration order, then action declaration order.
 - `id` is the stable `<group>.<action>` identity, equal to the HTTP operation ID.
-- Schemas describe encoded action values through native `Schema.toJsonSchemaDocument`, which lowers to the JSON codec first. A `Date` is a string, an `Option` a tagged union, a `bigint` a string of digits. These are action values, not MCP's `{ value }` envelope or deployment URLs.
+- Schemas describe encoded action values through native `Schema.toJsonSchemaDocument`, which lowers to the JSON codec first. Objects are closed (`additionalProperties: false`), as in the OpenAPI document. A `Date` is a string, an `Option` a tagged union, a `bigint` a string of digits. These are whole action values, as HTTP sends them, not MCP's split of a text field or deployment URLs.
 - JSON Schema does not preserve arbitrary Effect transformations or filters. Checks on the decoded side of a transformation, such as `FiniteFromString.check(isGreaterThan(0))`, are not described. The server's decode remains authoritative.
 - 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