@gjermundgaraba/effect-actions 0.7.0 → 0.8.0

package/README.md

@@ -73,10 +73,10 @@ Code that does not run Effects, such as a browser page, gets the same calls as P
 ## Install
 
 ```sh
-pnpm add @gjermundgaraba/effect-actions effect@4.0.0-rc.117
+pnpm add @gjermundgaraba/effect-actions effect@4.0.0-rc.118
 ```
 
-Add `@effect/platform-node@4.0.0-rc.117` to serve from Node. Every module is a subpath import
+Add `@effect/platform-node@4.0.0-rc.118` 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.
 
@@ -101,7 +101,7 @@ in `node_modules/@gjermundgaraba/effect-actions/docs`) gives the same content.
 
 ## Status
 
-The `effect` peer accepts any Effect 4.0 release candidate from `4.0.0-rc.116` on; the package
+The `effect` peer accepts any Effect 4.0 release candidate from `4.0.0-rc.118` 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).
 

package/dist/Action.d.mts

@@ -21,13 +21,22 @@ export interface McpOptions {
   readonly idempotent?: boolean;
   /** `openWorldHint`; defaults to `true`. */
   readonly openWorld?: boolean;
+  /**
+   * A string field of the encoded success that MCP sends as a raw text block rather
+   * than as structured content, such as a document body. Other surfaces serve the
+   * whole success.
+   */
+  readonly text?: string;
 }
+/** The fields `mcp.text` may name: those an encoded success has as a string. */
+type TextFields<Encoded> = Encoded extends object ? { readonly [K in keyof Encoded]-?: Required<Encoded>[K] extends string ? K : never; }[keyof Encoded] & string : never;
 type ResolvedMcp<Name extends string, Mcp extends false | McpOptions | undefined> = Mcp extends false ? false : {
   readonly name: Mcp extends McpOptions ? "name" extends keyof Mcp ? Extract<Mcp["name"], string> extends never ? Name : Extract<Mcp["name"], string> | (undefined extends Mcp["name"] ? Name : never) : Name : Name;
   readonly readOnly: boolean;
   readonly destructive: boolean;
   readonly idempotent: boolean;
   readonly openWorld: boolean;
+  readonly text?: string;
 };
 /** What `make` needs to define an action. */
 export interface Options<Input extends Codec, Output extends Codec, Errors extends ReadonlyArray<Codec>, Acc extends Access = Access, Mcp extends false | McpOptions | undefined = McpOptions | undefined> {
@@ -77,6 +86,10 @@ type McpOf<O extends AnyOptions> = [O] extends [{
  * Define an action contract. Names are `[A-Za-z0-9_-]+`, other than `then`.
  * HTTP serves every action of a group it binds; `mcp: false` hides one from MCP.
  */
-export declare function make<const Name extends string, const O extends AnyOptions>(name: Name, options: O & { readonly [K in Exclude<keyof O, keyof AnyOptions>]: never; }): Action<Name, "input" extends keyof O ? Exclude<O["input"], undefined> : typeof NoInput, O["success"], "errors" extends keyof O ? Exclude<O["errors"], undefined> : [], O["access"], McpOf<O>>;
+export declare function make<const Name extends string, const O extends AnyOptions>(name: Name, options: O & { readonly [K in Exclude<keyof O, keyof AnyOptions>]: never; } & {
+  readonly mcp?: false | (McpOptions & {
+    readonly text?: TextFields<O["success"]["Encoded"]>;
+  }) | undefined;
+}): Action<Name, "input" extends keyof O ? Exclude<O["input"], undefined> : typeof NoInput, O["success"], "errors" extends keyof O ? Exclude<O["errors"], undefined> : [], O["access"], McpOf<O>>;
 //#endregion
 export { Action_d_exports };

package/dist/Action.mjs

@@ -13,7 +13,8 @@ function make(name, options) {
 		readOnly,
 		destructive: options.mcp?.destructive ?? !readOnly,
 		idempotent: options.mcp?.idempotent ?? false,
-		openWorld: options.mcp?.openWorld ?? true
+		openWorld: options.mcp?.openWorld ?? true,
+		...options.mcp?.text === void 0 ? {} : { text: options.mcp.text }
 	};
 	if (mcp !== false && mcp.name.length > 128) throw new Error(`Invalid MCP name: ${mcp.name}`);
 	if (mcp !== false) assertName("MCP name", mcp.name);

package/dist/ActionCatalog.mjs

@@ -1,9 +1,12 @@
 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. */
+/**
+* Describe the JSON wire form closed, as the OpenAPI document does; decoding on the
+* server remains authoritative.
+*/
 const describe = (codec) => {
-	const { schema, definitions } = Schema.toJsonSchemaDocument(codec);
+	const { schema, definitions } = Schema.toJsonSchemaDocument(codec, { onExcessProperty: "error" });
 	return {
 		$schema: JsonSchema.META_SCHEMA_URI_DRAFT_2020_12,
 		...schema,

package/dist/ActionCli.d.mts

@@ -3,7 +3,7 @@ import { Actions } from "./internal/actions.mjs";
 import { HandlerContext, Handlers, HandlersContext, Implementation } from "./internal/implementation.mjs";
 import { Options as Options$1 } from "./internal/cli.mjs";
 import { Effect, Scope } from "effect";
-import { Command } from "effect/unstable/cli";
+import { Command } from "effect/cli";
 //#region src/ActionCli.d.ts
 /**
  * The hook a local command runs before the selected handler. A CLI does not serialize

package/dist/ActionCli.mjs

@@ -2,7 +2,7 @@ import { selectNamed } from "./internal/actions.mjs";
 import { dispatch } from "./internal/implementation.mjs";
 import { command as command$1 } from "./internal/cli.mjs";
 import { Effect } from "effect";
-import { Command } from "effect/unstable/cli";
+import { Command } from "effect/cli";
 //#region src/ActionCli.ts
 /**
 * Acquire the implementation in a scope of its own, run one action through the hook

package/dist/ActionCliClient.d.mts

@@ -3,9 +3,9 @@ import { Actions } from "./internal/actions.mjs";
 import { Options as Options$1 } from "./internal/cli.mjs";
 import { ActionHttp_d_exports, Api, Http } from "./ActionHttp.mjs";
 import { Effect } from "effect";
-import { HttpClient } from "effect/unstable/http";
-import { HttpApi, HttpApiClient, HttpApiEndpoint, HttpApiGroup } from "effect/unstable/httpapi";
-import { Command } from "effect/unstable/cli";
+import { HttpClient } from "effect/http";
+import { HttpApi, HttpApiClient, HttpApiEndpoint, HttpApiGroup } from "effect/http-api";
+import { Command } from "effect/cli";
 //#region src/ActionCliClient.d.ts
 /**
  * What the host configures on Effect's native client: `baseUrl`, `transformClient`,

package/dist/ActionCliClient.mjs

@@ -1,9 +1,9 @@
 import { selectNamed } from "./internal/actions.mjs";
 import { command as command$1 } from "./internal/cli.mjs";
 import { Effect } from "effect";
-import { HttpClient } from "effect/unstable/http";
-import { HttpApiClient } from "effect/unstable/httpapi";
-import { Command } from "effect/unstable/cli";
+import { HttpClient } from "effect/http";
+import { HttpApiClient } from "effect/http-api";
+import { Command } from "effect/cli";
 //#region src/ActionCliClient.ts
 /**
 * The native endpoint builder needs string selectors for a runtime-selected route.

package/dist/ActionGroup.mjs

@@ -16,7 +16,6 @@ function make(options, ...declared) {
 		errors: [...action.errors, ...options.errors ?? []]
 	}));
 	assertDistinct("action", actions.map((action) => action.name));
-	assertDistinct("MCP tool", actions.flatMap((action) => action.mcp === false ? [] : [action.mcp.name]));
 	const group = {
 		name,
 		actions,

package/dist/ActionHttp.d.mts

@@ -2,8 +2,8 @@ import { Action_d_exports, Any, Codec } from "./Action.mjs";
 import { Actions, PolicyError } from "./internal/actions.mjs";
 import { AnyImplementation, BuildContext, BuildError, RequestContext } from "./internal/implementation.mjs";
 import { Effect, Layer, Schema } from "effect";
-import { Etag, HttpPlatform, HttpRouter } from "effect/unstable/http";
-import { HttpApi, HttpApiEndpoint, HttpApiGroup } from "effect/unstable/httpapi";
+import { Etag, HttpPlatform, HttpRouter } from "effect/http";
+import { HttpApi, HttpApiEndpoint, HttpApiGroup } from "effect/http-api";
 import { FileSystem } from "effect/FileSystem";
 import { Path } from "effect/Path";
 declare namespace ActionHttp_d_exports {

package/dist/ActionHttp.mjs

@@ -1,8 +1,8 @@
 import { answerSchemaError, assertDistinct, policyErrors, projectedErrors } from "./internal/actions.mjs";
 import { dispatch } from "./internal/implementation.mjs";
 import { Effect, Layer } from "effect";
-import { HttpRouter, HttpServerResponse } from "effect/unstable/http";
-import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiMiddleware, OpenApi } from "effect/unstable/httpapi";
+import { HttpRouter, HttpServerResponse } from "effect/http";
+import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiMiddleware, OpenApi } from "effect/http-api";
 //#region src/ActionHttp.ts
 const endpoint = (options, group, action) => HttpApiEndpoint.post(action.name, `${options.apiPath}/${group.name}/${action.name}`, {
 	payload: action.input,
@@ -33,7 +33,10 @@ function bind(options, group) {
 }
 function apiOf(groups) {
 	const [first, ...rest] = groups;
-	const empty = HttpApi.make("actions").annotate(HttpApi.ParseOptions, { errors: "all" });
+	const empty = HttpApi.make("actions").annotate(HttpApi.PayloadParseOptions, {
+		errors: "all",
+		onExcessProperty: "error"
+	});
 	return first === void 0 ? empty : empty.add(first, ...rest);
 }
 /**

package/dist/ActionMcp.d.mts

@@ -2,8 +2,8 @@ import { Action_d_exports, Codec } from "./Action.mjs";
 import { AnyImplementation, BuildContext, BuildError, HiddenFromMcp, RequestContext } from "./internal/implementation.mjs";
 import { SurfaceOptions } from "./internal/tools.mjs";
 import { Cause, Layer } from "effect";
-import { HttpRouter } from "effect/unstable/http";
-import { McpSchema, McpServer } from "effect/unstable/ai";
+import { HttpRouter } from "effect/http";
+import { McpSchema, McpServer } from "effect/ai";
 import { Stdio } from "effect/Stdio";
 //#region src/ActionMcp.d.ts
 /**

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

@@ -2,7 +2,7 @@ import { Action_d_exports, Any, Codec } from "./Action.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>;

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,6 +1,6 @@
 import { ClientOptions } from "./internal/fetchClient.mjs";
 import { Schema } from "effect";
-import { HttpApi, HttpApiGroup } from "effect/unstable/httpapi";
+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>;
@@ -10,7 +10,7 @@ export type Handler = (request: Request) => Promise<Response>;
  */
 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>]: 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>>;
+}> 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;
@@ -46,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, whatever its shape) 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;

package/dist/Testing.mjs

@@ -40,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)
@@ -80,9 +80,11 @@ const mcpCall = async (handler, { url, name, headers, arguments: args = {} }) =>
 		};
 	}
 	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

@@ -1,5 +1,5 @@
 import { Effect } from "effect";
-import { HttpApi, HttpApiClient, HttpApiGroup } from "effect/unstable/httpapi";
+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]>;

package/dist/internal/fetchClient.mjs

@@ -1,6 +1,6 @@
 import { Effect } from "effect";
-import { FetchHttpClient } from "effect/unstable/http";
-import { HttpApiClient } from "effect/unstable/httpapi";
+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));

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

@@ -21,7 +21,8 @@ Import `@gjermundgaraba/effect-actions/Action`.
 | `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
@@ -72,6 +73,16 @@ export const ListChanges = Action.make("listChanges", {
   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.",
@@ -92,12 +103,13 @@ export const Double = Action.make("double", {
 - 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.
+- 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
 

package/docs/ActionCatalog.md

@@ -12,7 +12,7 @@ Import `@gjermundgaraba/effect-actions/ActionCatalog`.
 | Entry field                          | Meaning                                                             |
 | ------------------------------------ | ------------------------------------------------------------------- |
 | `id`, `group`, `name`, `description` | Stable `<group>.<action>` identity and contract metadata.           |
-| `mcp`                                | Resolved MCP enablement, name and hints.                            |
+| `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. |
@@ -38,7 +38,7 @@ 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.

package/docs/ActionCli.md

@@ -28,7 +28,7 @@ scope. Success output is encoded; failures remain failures of the command Effect
 
 ```ts
 import { Console, Effect, Logger } from "effect";
-import { Command, Flag } from "effect/unstable/cli";
+import { Command, Flag } from "effect/cli";
 import { NodeRuntime, NodeServices } from "@effect/platform-node";
 import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
 import { actors, authorize, CurrentActor } from "./auth.js";

package/docs/ActionCliClient.md

@@ -25,7 +25,7 @@ retain the selected endpoint's client failures and middleware requirements, and
 ## Canonical
 
 ```ts
-import { Command } from "effect/unstable/cli";
+import { Command } from "effect/cli";
 import { Console, Effect, Logger } from "effect";
 import { NodeHttpClient, NodeRuntime, NodeServices } from "@effect/platform-node";
 import * as ActionCliClient from "@gjermundgaraba/effect-actions/ActionCliClient";
@@ -51,13 +51,13 @@ Authentication: `connection: { transformClient: HttpClient.mapRequest(HttpClient
 
 - 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 (`--input`, `--input-file`, or `input(parsed)`) is encoded JSON. The command decodes it with the action schema, and the native client re-encodes it with `Http.api`'s closed payload codec.
 - Input syntax (`--input`, `--input-file`, or `parameters`) and output (`render` and its `--json` flag) are exactly as in `ActionCli`.
-- Errors are the client's: declared errors, policy errors, `SchemaError`, and `HttpClientError`.
+- Errors are the client's: declared errors (the binding's `errors` included), policy errors, `SchemaError`, and `HttpClientError`.
 
 ## Failure modes
 
 - 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.
+- `HttpClient` unsatisfied (a type error at `runMain`): provide `NodeHttpClient.layerUndici` (or `FetchHttpClient.layer`) to the runtime.
+- `HttpClientError` with `reason._tag` `InvalidUrlError`: `connection.baseUrl` is absent; it has no default. Connection refused: `baseUrl` points at the wrong host or port.
 - 401 from the server: add `transformClient` to `connection`. The command adds no headers on its own.

package/docs/ActionGroup.md

@@ -31,7 +31,7 @@ builder's requirements.
 import { Effect, Schema } from "effect";
 import * as ActionGroup from "@gjermundgaraba/effect-actions/ActionGroup";
 import { CurrentActor } from "./auth.js";
-import { GetUser, RenameUser, WhoAmI } from "./contracts.js";
+import { Double, GetUser, RenameUser, WhoAmI } from "./contracts.js";
 import { Users } from "./users.js";
 
 class InvalidRequest extends Schema.TaggedError<InvalidRequest>()(
@@ -58,6 +58,8 @@ const schemaError = {
   },
 };
 
+export const MathActions = ActionGroup.make({ name: "math" }, Double);
+
 export const UserActions = ActionGroup.make(
   { name: "users", schemaError },
   GetUser,
@@ -91,10 +93,10 @@ const renames: "renameUser" = contracts["users.renameUser"].name;
 
 ## Rules
 
-- `name` matches `[A-Za-z0-9_-]+`, cannot be `then`, and must be unique within one `ActionHttp.make`. Action names must be unique within the group. MCP tool names must be unique within the group and within each Toolkit or MCP projection that serves it. Duplicates fail at `make`.
+- `name` matches `[A-Za-z0-9_-]+` and cannot be `then`. Action names are unique within the group. Group and MCP tool names are checked where they are served; see [guarantees.md](guarantees.md#namespaces).
 - Group `errors` are appended to each action's own `errors`, so every handler of the group may fail with them. A failure that only the surface produces belongs on the adapter instead (`ActionHttp.make`'s `errors`, `ActionMcp`'s and `ActionToolkit`'s `errors`), not here.
 - `implement` takes a complete plain record or an Effect producing one. Every action must have a handler; missing keys are compile errors. A handler is an own-property function of the record: an inherited one, such as a class instance's method, does not count. A record that still lacks one at runtime (plain JavaScript, a cast: a missing key, `undefined`, any other non-function, an inherited method) throws at `implement`; a builder's record fails the adapter layer's build. Nothing is served with a handler missing. Handlers are called without a receiver. Additional keys are not dispatched. It takes nothing else.
-- The builder Effect runs once per adapter layer that serves the implementation, in that layer's scope. An implementation served by HTTP and MCP is built twice. Acquire shared state in a Layer you provide to the adapters, not in the builder.
+- The builder Effect runs once per adapter layer that serves the implementation, in that layer's scope, and once per invocation under `ActionCli`. An implementation served by HTTP and MCP is built twice. Acquire shared state in a Layer you provide to the adapters, not in the builder.
 - Services yielded in the builder are build-time requirements (`RX`). Services yielded in a handler are request-time requirements (`R` of the handler). Adapters keep these separate in their types. Use distinct tags for each kind; never provide a request-identity tag at startup (see [guarantees.md](guarantees.md)).
 - `Implementation` is nominal. Spreading its properties does not produce an implementation. Each `implement` call is a separate binding.
 - `build` exists for direct handler tests under `Effect.scoped`. It bypasses transport validation and the hook, and is not a substitute for adapter tests. There is no public handler service or Layer.
@@ -109,18 +111,18 @@ const renames: "renameUser" = contracts["users.renameUser"].name;
 - MCP is unaffected. The native `McpServer` answers invalid arguments and unencodable results itself.
 - Policy errors extend the transport contract, not the handler contract. A handler cannot return them.
 - The policy runs only on the server. Client-side codec failures stay `SchemaError`.
-- HTTP decodes with `errors: "all"`, so `cause` carries every issue. Issues never retain the rejected values.
+- HTTP decodes input with `errors: "all"`, so an `invalid` `cause` carries every issue. Issues never retain the rejected values.
 - Groups served by one adapter may have different policies; each action answers with its own group's.
 - Input schema-error policies run before the `before` hook. Invalid input is answered by the policy without invoking the hook or handler.
 - Domain errors, defects, interruptions, and protocol errors are not remapped. An unencodable declared error is a defect. A broken policy error is not recursively remapped.
 
 ## Failure modes
 
-- Throws at `make`: duplicate action name, duplicate MCP tool name, invalid group name.
+- Throws at `make`: `Duplicate action: <name>` or `Invalid action group name: <name>`.
 - `Property 'x' is missing in type` at `implement`: the record lacks a handler for action `x`.
 - Handler compiles but returns an error not in `errors`: type error on the handler's error channel. Declare it on the action or the group.
 - `Expected 1 arguments, but got 2` at `implement`: the second options object is gone. Move `before` to the adapter that serves the group.
-- `Parameter 'failure' implicitly has an 'any' type` in a standalone policy constant: a `make` that reads the failure is typed only inline. Annotate the parameter as `HttpApiError.HttpApiSchemaError` (type import from `effect/unstable/httpapi`), or annotate the constant as `ActionGroup.SchemaErrorPolicy<typeof Invalid, typeof Internal>`.
+- `Parameter 'failure' implicitly has an 'any' type` in a standalone policy constant: a `make` that reads the failure is typed only inline. Annotate the parameter as `HttpApiError.HttpApiSchemaError` (type import from `effect/http-api`), or annotate the constant as `ActionGroup.SchemaErrorPolicy<typeof Invalid, typeof Internal>`.
 - `Missing handlers for group "<group>": <actions>` thrown at `implement`, or failing the layer build: the handler record has no own-property function for those actions. Add them to the record itself, not to a prototype.
 - A service is resolved once and shared across requests when it should be per request: it was yielded in the builder. Move the `yield*` into the handler.
 - `Duplicate contract group` thrown by `contracts`: two groups share a name, so their keys would collide. Rename one.

package/docs/ActionHttp.md

@@ -32,7 +32,7 @@ Route shape: `POST <apiPath>/<group>/<action>`. Operation ID: `<group>.<action>`
 
 ```ts
 import { Layer } from "effect";
-import { HttpApiScalar, HttpApiSwagger } from "effect/unstable/httpapi";
+import { HttpApiScalar, HttpApiSwagger } from "effect/http-api";
 import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
 import { PublicActions, UserActions } from "./contracts.js";
 import { PublicApp, UserApp } from "./handlers.js";
@@ -73,9 +73,9 @@ The client is Effect's native grouped `HttpApiClient` over `Http.api`. Code that
 run Effects uses the Promise client in [ActionHttpClient.md](ActionHttpClient.md).
 
 ```ts
-import { HttpApiClient } from "effect/unstable/httpapi";
+import { HttpApiClient } from "effect/http-api";
 import { Effect } from "effect";
-import { FetchHttpClient } from "effect/unstable/http";
+import { FetchHttpClient } from "effect/http";
 import { Http } from "./quickstart.js";
 
 export const greeting = Effect.gen(function* () {
@@ -98,10 +98,10 @@ export const greeting = Effect.gen(function* () {
 - `ActionHttp` sets no response headers of its own. The host owns cache policy; `Authentication.middleware` marks its responses `cache-control: no-store`.
 - A hook refusal and a handler error are plain declared errors: a JSON body and a status, no other headers. Challenge headers such as `WWW-Authenticate` belong to the admission middleware that runs before the router reaches these routes (see [Authentication.md](Authentication.md)), which sets them on its own response.
 - Request-time handler services are `HttpRouter.Request.From<"Requires", R>`. Supply them with router middleware (`Authentication.middleware`, `HttpRouter.middleware`), `HttpRouter.provideRequest`, or the request context. Build-time services are ordinary layer requirements.
-- `Http.api` is a plain `HttpApi`. Anything Effect can do with an `HttpApi` works: `OpenApi.fromApi`, `HttpApiSwagger.layer`, `HttpApiScalar.layer`, `HttpApi.addHttpApi` to combine with other APIs, `HttpApiClient.make`.
+- `Http.api` is a plain `HttpApi`. Anything Effect can do with an `HttpApi` works: `OpenApi.fromApi`, `HttpApiSwagger.layer`, `HttpApiScalar.layer`, `Http.api.addHttpApi(other)` to combine with other APIs, `HttpApiClient.make`.
 - `Http.openApi(path?)` is `OpenApi.fromApi(Http.api)` as one `GET` route, `<apiPath>/openapi.json` unless a path is given. It documents every bound group, not only the served ones. It is a plain route: middleware provided to its layer covers it, and nothing covers it otherwise.
 - Client calls always take `{ payload }`. No-input actions take `{ payload: {} }`. Pass `null` or `undefined` only when the codec accepts it. There is no flat client.
-- Client effects fail with the declared errors, the group's policy errors, the binding's `errors`, `SchemaError` for local codec failures, and native `HttpClientError`.
+- Client effects fail with the declared errors, the group's policy errors, the binding's `errors`, `SchemaError` for local codec failures (including an undeclared input field, before sending), and native `HttpClientError`.
 - Add authentication headers with the native `transformClient` option. Use `HttpApiClient.makeWith` for custom error or service channels. Native per-call response modes are available.
 - Wire format without a policy: input failure is an empty 400, success is the encoded body, a declared error is its JSON encoding with its `httpApiStatus`, an encoding failure is an empty 400, a defect is an empty 500. Full table in [guarantees.md](guarantees.md).
 - Each handler runs in a span named `<group>.<action>`, a child of the request span, attributed with `action.group`, `action.name` and `action.access`; its log lines carry the same annotations. The hook, decoding and encoding are outside it, in the request span.
@@ -114,8 +114,8 @@ export const greeting = Effect.gen(function* () {
 - `Implementation of group "x" is not served by this adapter`: `Http.layer` received an implementation whose group was not passed to `ActionHttp.make`. Implement the exact shared group object bound by `make`, or add a genuinely new group to the binding. Matching names and schemas do not establish identity.
 - `Duplicate implementation group: <name>`: a single `Http.layer` call received more than one implementation of the same group. Pass one implementation per group.
 - Client method missing for an action: its group is not bound by `make`.
-- Empty 400 on a valid-looking request: input did not decode. Set a `schemaError` policy on the group to get a typed body, and check `Content-Type: application/json`.
-- 415: wrong or missing content type.
+- Empty 400 on a valid-looking request: input did not decode, or it carries a field the action does not declare. Set a `schemaError` policy on the group to get a typed body.
+- 415 `Unsupported content-type: <type>`: a content type other than `application/json`. A missing `Content-Type` is read as JSON.
 - `HttpClientError: Decode error (401 POST ...)` from a typed client: the surface answered with a status no endpoint declares. Add that error schema to `ActionHttp.make`'s `errors`.
 - A surface error decodes as the wrong type: two schemas that share a status also share a `_tag`. Give them distinct tags.
 - The hook's services appear as unsatisfied `HttpRouter.Request.From<"Requires", ...>`: the hook yields an identity tag and this `Http.layer` call has no middleware providing it. Wrap that call with the middleware's `.layer`.

package/docs/ActionHttpClient.md

@@ -29,7 +29,7 @@ whose input may be empty (no `input`, or only optional fields) may be called wit
 ## Canonical
 
 ```ts
-import { HttpClient, HttpClientError, HttpClientRequest } from "effect/unstable/http";
+import { HttpClient, HttpClientError, HttpClientRequest } from "effect/http";
 import * as ActionHttpClient from "@gjermundgaraba/effect-actions/ActionHttpClient";
 import { Http, UserNotFound } from "./contracts.js";
 
@@ -65,7 +65,7 @@ Reacting to a response every call may meet (a proxy's 401), or a token read per
 ## Rules
 
 - A call rejects with exactly what the native client's Effect fails with. Declared errors arrive as their decoded values: the action's own (its group's `errors` included), its group's schema-error policy's, and the binding's surface `errors`. Classify them with `instanceof`, their `_tag`, or `Schema.is`.
-- Anything the contract does not account for rejects with Effect's own error. `HttpClientError`: the server could not be reached (`response` is `undefined`), or answered with a status no schema declares, or with a body that could not be read. `SchemaError`: the input did not encode, or the success body did not decode.
+- Anything the contract does not account for rejects with Effect's own error. `HttpClientError`: the server could not be reached (`response` is `undefined`), or answered with a status no schema declares, or with a body that could not be read. `SchemaError`: the input did not encode (including a field the action does not declare; nothing is sent), or the success body did not decode.
 - The library adds no error type of its own and interprets no status. Which failures mean "signed out" or "try again" is the caller's decision.
 - Nothing is retried. A rejected write may or may not have happened; only a declared error says what the server did.
 - Every action of a bound group has a method. A group without actions has no namespace.
@@ -74,7 +74,7 @@ Reacting to a response every call may meet (a proxy's 401), or a token read per
 
 ## Failure modes
 
-- Rejects with `HttpClientError` whose `reason._tag` is `StatusCodeError` for a 401 or 403: the surface answered with an error the binding does not declare. Add it to `ActionHttp.make`'s `errors`, and have the middleware encode it.
+- Rejects with `HttpClientError` whose `reason._tag` is `DecodeError` (`Decode error (401 POST ...)`) for a 401 or 403: the surface answered with an error the binding does not declare. Add it to `ActionHttp.make`'s `errors`, and have the middleware encode it.
 - Rejects with `HttpClientError` whose `reason._tag` is `InvalidUrlError` outside a browser: `baseUrl` is omitted, and there is no page to resolve relative routes against. Set `baseUrl`.
 - A stubbed global `fetch` is not used: `fetch` was passed as an option, which takes precedence.
 - Property does not exist on the client: the action's group is not bound in this `Http`.

package/docs/ActionMcp.md

@@ -74,7 +74,7 @@ choose its policy for every route it covers.
 
 ```ts
 import { Effect, Layer } from "effect";
-import { HttpRouter } from "effect/unstable/http";
+import { HttpRouter } from "effect/http";
 import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
 import { Actions } from "./quickstart.js";
 
@@ -143,13 +143,15 @@ Layer.launch(layer).pipe(
 ## Rules
 
 - Both transports serve MCP 2026-07-28 and no other revision; there is no `protocols` option. Over HTTP the endpoint is stateless: no initialize handshake, no session, and every request stands alone. Effect owns version checks and rejects any other revision. Stdio has no sessions, so it could serve an older host, but it refuses one deliberately, for uniformity: a client that works over one transport works over the other.
-- `path` has no default. `layerHttp` uses the single-endpoint Streamable HTTP transport, never the two-endpoint HTTP+SSE form, whatever revision is negotiated.
+- `path` has no default. `layerHttp` uses the single-endpoint Streamable HTTP transport, never the two-endpoint HTTP+SSE form.
 - Requests reaching the native MCP handler with an `Origin` header receive **403** unless that exact origin is listed in `allowedOrigins`. Requests without `Origin` pass this check. Authentication middleware wrapping the endpoint runs first and may reject the request before native Origin validation; the allowlist does not protect authentication from untrusted-origin requests.
 - `allowedOrigins` is an Origin allowlist, not CORS configuration. Cross-origin browser clients also need outer CORS middleware or a proxy to handle preflight and add response headers. Without it, an allowed-origin `OPTIONS` request receives **405** and even a successful `POST` has no `Access-Control-Allow-Origin`. Keep preflight outside authentication and apply CORS headers to refusals too.
 - An endpoint is one route. Middleware provided to `layerHttp` covers all of its tools. To serve tools under different middleware, mount them on different paths with separate `layerHttp` calls.
 - Only MCP-enabled actions become tools, under `mcp.name` with the resolved hints. A group with no tools is not built. The layer's types drop an action's requirements only when its type is certainly hidden (a literal `mcp: false`, see [Action.md](Action.md)); an `mcp` that may be `false` at runtime keeps them.
 - Every MCP-enabled action must have object-root input; the native server refuses anything else when the layer is built. Omit `input` for a tool with no arguments.
-- Success is `structuredContent: { value: <encoded success> }`. A declared error is an `isError` result whose text content is the error's JSON encoding, the same bytes HTTP sends as the body, and no `structuredContent`.
+- Success is `structuredContent: <encoded success>`, of any JSON type, and one text block holding the same JSON, as the specification recommends. The tool's `outputSchema` describes the encoded success. A declared error is an `isError` result whose text content is the error's JSON encoding, the same bytes HTTP sends as the body, and no `structuredContent`.
+- With a text field (`mcp.text`), a success is `content: [<field>, <JSON of the rest>]` and `structuredContent: <the rest>`. The field is sent once, verbatim, and is left out of `structuredContent` and of the listed `outputSchema`. Use it for a body the model should read raw, such as a page of Markdown: in structured content it would be JSON-escaped, and sent twice. The field must be a top-level property of the success's JSON Schema. A success without the field as a string, such as one that omits an optional field, is sent whole.
+- Besides `content`, `structuredContent` and `isError: false`, the server adds `_meta["io.modelcontextprotocol/serverInfo"]` and `resultType: "complete"` to every result. `serverInfo` is the layer's `name`, `version`, `description`, `websiteUrl` and `icons`, as given, so a result's encoded size is the size of its own fields plus a fixed overhead per endpoint, the same over HTTP and stdio.
 - Invalid arguments and unencodable results are answered by the native `McpServer`: an `isError` result with a message for the model. Group `schemaError` policies do not apply.
 - Defects and encoding failures produce the generic `isError` text `Tool execution failed due to an internal server error.`; the cause is logged, not sent.
 - Tool discovery is not filtered by actor. Every caller sees every tool of the endpoint. Authorization happens in `before`.
@@ -163,7 +165,7 @@ Layer.launch(layer).pipe(
 ## Failure modes
 
 - Layer build dies while registering tools, with a defect whose `SchemaError` message says `Expected "object"` or `Missing key`: an MCP-enabled action has scalar, array, or empty-struct input, which the native server refuses. It is not in the layer's error channel, so it cannot be caught by tag. Wrap the input in a struct with at least one field, omit `input` for no arguments, or set `mcp: false`.
-- `Duplicate MCP tool: <name>` thrown at the `layerHttp` or `layerStdio` call: two apps on one endpoint expose the same tool name. Rename with `mcp.name` or split the endpoint.
+- `Duplicate MCP tool: <name>` thrown at the `layerHttp` or `layerStdio` call: two actions on one endpoint expose the same tool name. Rename with `mcp.name` or split the endpoint.
 - Type error listing `HttpRouter.Request.From<"Requires", ...>`: a handler yields a request service and the endpoint has no middleware providing it. Provide it with `Layer.provide(middleware.layer)` on that `layerHttp`.
 - Public tool requires a token: it shares an endpoint with protected tools. Give it its own path.
 - Client reports a broken transport from a stdio subprocess: something printed to stdout. Set `Logger.LogToStderr` and remove `console.log`.
@@ -172,4 +174,5 @@ Layer.launch(layer).pipe(
 - A disallowed Origin receives 401 instead: wrapping authentication rejected it before the native Origin check. Put any required pre-authentication Host/Origin policy in outer host middleware.
 - Browser calls fail despite an allowed Origin: configure CORS outside authentication and the MCP handler (see the browser example above). The native allowlist alone neither handles preflight nor adds CORS response headers.
 - `Object literal may only specify known properties, and 'protocols'`: the revision is fixed. Delete the option.
+- Layer build dies with `MCP tool '<name>' cannot send '<field>' as text: it is not a top-level property of its success`: the success's JSON Schema has no such top-level property, as for a union of structs. Make the success one struct.
 - A refusal arrives as a generic internal-error result: the hook failed with an error this transport does not declare, which is a defect. Add its schema to `errors`.

package/docs/ActionToolkit.md

@@ -52,7 +52,7 @@ With a model: pass `binding.toolkit` as `toolkit` to `LanguageModel.generateText
 ## Rules
 
 - Selects MCP-enabled actions only, named by `mcp.name`, with resolved hints. Groups with no selected tools are not built. The toolkit's type follows `ActionMcp`'s rule: only an action whose `mcp` type is exactly `false` has no tool; one whose `mcp` may be `false` at runtime is typed as a tool with its handler's requirements. `make(apps, options?)` accepts a readonly implementation collection; options may be omitted.
-- Successes are the action's native values. There is no `{ value }` wrapper. Declared failures are returned as native tool results (`failureMode: "return"`), not raised.
+- Successes are the action's native values, whole: `mcp.text` does not apply. Declared failures are returned as native tool results (`failureMode: "return"`), not raised.
 - `tools.handle(name, encodedInput)` takes encoded arguments and returns an Effect producing a result stream. The handler starts while that stream is constructed, so request services must be provided around the entire `handle(...).pipe(Effect.flatMap(Stream.runCollect))`, not only around the stream.
 - `binding.layer` acquires each implementation once, in the layer's scope. Build-time requirements belong to the whole selected implementation.
 - Each tool carries only its own handler's request requirements, plus the hook's, not those of sibling or disabled tools.
@@ -65,7 +65,7 @@ With a model: pass `binding.toolkit` as `toolkit` to `LanguageModel.generateText
 
 - Tool missing from the toolkit: the action has `mcp: false`. The Toolkit selects by MCP enablement.
 - Type error on `before`'s error channel: it fails with an error this binding does not declare. Add its schema to `errors`.
-- `Duplicate MCP tool: <name>` thrown at `make`: two apps expose the same tool name. Rename with `mcp.name`.
-- `Service not found` for a request tag at call time: it was provided only to the stream, or only to the layer. Provide it around the whole call effect.
+- `Duplicate MCP tool: <name>` thrown at `make`: two selected actions expose the same tool name. Rename with `mcp.name`.
+- `Service not found` for a request tag at call time: it was provided only to the stream. Provide it around the whole call effect. Providing it to `binding.layer` does not fail: the startup value is captured and served to every call (see [guarantees.md](guarantees.md)).
+- A returned failure that is an `AiError` with reason `ToolParameterValidationError`, not a declared error: the arguments did not decode. The hook and the handler did not run.
 - Type error on `binding.layer` requirements: a build-time service is missing. Provide its Layer before `binding.layer`.
-- Result is `{ value: ... }` when a plain value was expected: you are reading an MCP response, not a Toolkit result. The Toolkit never wraps.

package/docs/Authentication.md

@@ -29,7 +29,7 @@ to routes requiring that identity.
 
 ```ts
 import { Context, Effect, Layer, Option, Schema } from "effect";
-import { HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
+import { HttpServerRequest, HttpServerResponse } from "effect/http";
 import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
 
 interface Actor {
@@ -84,7 +84,7 @@ export const routes = Layer.mergeAll(
 - Downstream action errors are handled by their transport. They are never serialized as authentication failures.
 - Use distinct tags for startup capabilities and request identities. Never provide `CurrentActor` or any identity or tenant tag in a startup layer or root context. Native context capture can let a startup value shadow the request value or satisfy a missing one, and the adapters add no isolation boundary. Types track that the tag is required, not where its value came from.
 - `protectedResource` publishes what it is given. The deployment must ensure `resource` and `authorizationServers` are valid OAuth URLs (HTTPS, or loopback HTTP in development).
-- Discovery is served at `/.well-known/oauth-protected-resource` followed by the resource's path and query, for `GET` and `HEAD`, matching that literal path and query. Other requests fall through to the host router. Mount `discovery.layer` outside the authenticated layers. Caching policy is the host's.
+- Discovery is served at `/.well-known/oauth-protected-resource` followed by the resource's path and query, for `GET` and `HEAD`, matching that literal path and query. Other requests fall through to the host router. `discovery.layer` is global router middleware: it answers before any route middleware, so authentication never covers it. Caching policy is the host's.
 - `challenge()` quotes and escapes parameter values; it never rejects them. Name only the scopes needed for the request in `scope`; `scopesSupported` advertises the full set in metadata.
 - Tool discovery is never filtered by actor. Authorization belongs in each surface's `before` hook, which runs with the action contract in hand; write the rule against `action.access` rather than repeating a check in each handler.
 - A response this middleware renders is not part of any endpoint's contract. Declare its schema in `ActionHttp.make`'s `errors` so typed clients decode the 401 instead of reporting a decode error ([ActionHttp.md](ActionHttp.md)).
@@ -94,6 +94,5 @@ export const routes = Layer.mergeAll(
 - Handler sees a stale or wrong actor: an identity tag was provided at startup. Remove it from every startup layer; provide it only through the middleware.
 - Type error `HttpRouter.Request.From<"Requires", CurrentActor>` unsatisfied: the layer serving that implementation was not wrapped with `authentication.layer`.
 - Discovery returns 404: the request path does not match `resource`'s path and query exactly, or `discovery.layer` is not merged into the served layer.
-- Discovery requires a token: `discovery.layer` was placed under the authentication middleware. Mount it separately.
 - 401 response lacks `WWW-Authenticate`: the host's failure response did not set it. Use `discovery.challenge(...)` in its headers.
 - A typed client reports `Decode error (401 ...)` instead of the failure schema: the response this middleware renders is not declared. Add it to `ActionHttp.make`'s `errors`.

package/docs/CONTEXT.md

@@ -16,13 +16,14 @@ use these words with these meanings.
 - **Build-time requirement**: a service yielded in the builder. Resolved when an adapter layer is built.
 - **Request-time requirement**: a service yielded inside a handler. Supplied per invocation: by router middleware for HTTP-hosted adapters, by the host for Toolkit, CLI, and stdio.
 - **Adapter** (also **projection**): a module that maps implementations or contracts onto one surface: `ActionHttp`, `ActionMcp`, `ActionToolkit`, `ActionCli`, `ActionCliClient`, `ActionCatalog`. Each adapter reads only what it serves and validates only its own namespace.
-- **Binding**: the value an adapter returns before anything runs. `ActionHttp.make` returns the HTTP binding (`groups`, `api`, `layer`); `ActionToolkit.make` returns the Toolkit binding (`toolkit`, `layer`).
+- **Binding**: the value an adapter returns before anything runs. `ActionHttp.make` returns the HTTP binding (`groups`, `api`, `layer`, `openApi`); `ActionToolkit.make` returns the Toolkit binding (`toolkit`, `layer`).
 - **Contract map**: the record `ActionGroup.contracts` returns, keyed `<group>.<action>`, with each action's exact type. The shared identity of an action across routes, tools and commands.
 - **Declared error**: an error schema listed on an action or inherited from its group. Handlers may fail with it. HTTP encodes it with its `httpApiStatus`; MCP returns encoded error text in an `isError` result. Toolkit returns a native failure result, and CLI fails its command Effect without serializing the error.
 - **Schema-error policy**: a group option answering Effect's `HttpApiSchemaError` with a declared policy error and its status: `invalid` when the request did not decode, `internal` when the handler's result did not encode. The library decides which applies. HTTP only.
 - **Policy error**: an error a schema-error policy may answer with. Part of the transport contract, never returnable by a handler.
 - **Surface error**: an error declared on an adapter binding rather than on an action. Produced by middleware around the surface or by its pre-handler hook, never by a handler; declared so typed callers decode it.
 - **Tool**: the MCP or Toolkit projection of an MCP-enabled action, named by `mcp.name` and carrying its hints.
+- **Text field**: the string field of an action's encoded success that `mcp.text` names. When a success has it, MCP sends it once, raw, as a text block, and leaves it out of the structured content. Every other surface serves the whole success.
 - **Endpoint**: one `ActionMcp.layerHttp` mount. One route, one middleware set, one tool registry.
 - **Document**: the OpenAPI output of `Http.api`, produced by Effect (`OpenApi.fromApi`) and served by `Http.openApi`.
 - **Promise client**: `ActionHttpClient.promise(Http)`, the native `HttpApiClient` as one Promise method per action of the binding, for code that does not run Effects. It rejects with what the native client fails with.
@@ -31,10 +32,10 @@ use these words with these meanings.
 
 ## Seams
 
-- `src/Action.ts` and `src/ActionGroup.ts` are contracts. They import nothing transport-specific and know nothing about HTTP, MCP, or the CLI.
+- `src/Action.ts` and `src/ActionGroup.ts` are contracts. They import no transport runtime. They carry only transport metadata (`mcp`, `httpApiStatus`, the HTTP schema-error policy).
 - `src/internal/actions.ts` and `src/internal/implementation.ts` hold the shared shapes adapters consume: the contract half of a group, the schema-error policy, and the nominal `Implementation` class. Everything under `src/internal` is not public API; the public modules re-export the types consumers need.
 - Each adapter owns its own mapping from contracts to its surface and never reaches into another adapter. HTTP does not know about tool names; MCP does not know about routes.
-- Adapters build on Effect's own servers and clients: `HttpApi` for HTTP, `McpServer` for MCP, `Toolkit` for the AI toolkit, `Command` for the CLI. The library adds no protocol runtime and defines no application error types.
+- Adapters build on Effect's own servers and clients: `HttpApi` for HTTP, `McpServer` for MCP, `Toolkit` for the AI toolkit, `Command` for the CLI. The library adds no protocol runtime.
 - Authentication is router middleware plus discovery metadata. Verification, login, and consent stay in the application. Authorization is the application's pre-handler hook, bound to each surface, which the library runs but never writes.
 - `Testing` depends only on `effect`. `TestingClient` is the single module that loads the optional MCP client peer.
 - Docs: `README.md` is the pitch for humans. `docs/` is the reference for agents, one card per module. `skills/effect-actions` is a copy of `docs/`, with this vocabulary included. `CONTRIBUTING.md` and `AGENTS.md` are for maintainers.

package/docs/README.md

@@ -1,15 +1,16 @@
 # effect-actions reference
 
-Reference for `@gjermundgaraba/effect-actions`, written for coding agents. Every page is a
+Reference for `@gjermundgaraba/effect-actions`, written for coding agents. Every module page is a
 card with the same sections: **API** (inventory and options), **Canonical** (the one right way to write
 it), **Rules** (must and never), **Failure modes** (what you see when it is wrong, and the fix).
+[setup.md](setup.md), [guarantees.md](guarantees.md), and [CONTEXT.md](CONTEXT.md) are cross-cutting pages with their own structure.
 Read the card for a module before writing code that uses it. Exported TypeScript declarations are the exact signature reference. Vocabulary is defined in
 [CONTEXT.md](CONTEXT.md); the pages use those terms exactly.
 
 Package facts that apply everywhere:
 
 - Every module is a subpath import: `import * as Action from "@gjermundgaraba/effect-actions/Action"`. There is no package root.
-- The `effect` peer accepts any 4.0 release candidate from `4.0.0-rc.116` on (`>=4.0.0-rc.116 <4.0.0`). The package is built and tested against `4.0.0-rc.117`.
+- The `effect` peer accepts any 4.0 release candidate from `4.0.0-rc.118` on (`>=4.0.0-rc.118 <4.0.0`). The package is built and tested against `4.0.0-rc.118`.
 - Contracts are pure values. Nothing runs, binds, or acquires services until an adapter layer is built.
 
 ## Pages
@@ -83,9 +84,8 @@ Repository directory `examples/` ([on GitHub](https://github.com/gjermundgaraba/
 
 - `quickstart.ts`, `quickstart-client.ts`: the minimal program and its typed client.
 - `promise-client.ts`: the Promise client, with a declared error and an unreachable server.
-- `contracts.ts`, `handlers.ts`, `app.ts`, `server.ts`: an authenticated application with three groups, per-group middleware, two MCP endpoints, OpenAPI and Swagger.
+- `contracts.ts`, `auth.ts`, `users.ts`, `handlers.ts`, `app.ts`, `server.ts`, `client.ts`: an authenticated application with three groups, per-group middleware, two MCP endpoints, OpenAPI and Swagger.
 - `toolkit.ts`, `catalog.ts`, `cli.ts`, `cli-client.ts`, `mcp-stdio.ts`: one file per other projection.
-
 - `mcp-browser.ts`: a stateless MCP endpoint with a separate browser CORS policy.
 - `toolkit-authorized.ts`: native Toolkit invocation with authorization and correctly scoped identity.
 - `testing.ts`: in-memory HTTP and MCP calls with cleanup.

package/docs/Testing.md

@@ -16,7 +16,7 @@ Import `@gjermundgaraba/effect-actions/Testing`; official-client helpers are in
 | `TestingClient.withMcpClient(options, run)`  | Connect the official client, run an asynchronous callback, then close it.                             |
 
 `httpClient` takes native client options; `baseUrl` defaults to `http://localhost`.
-Its exported `Handler` type is a web request to response Promise.
+Its exported `Handler` type is a web request to response Promise, not an action handler.
 
 | MCP option                            | Meaning                                                     |
 | ------------------------------------- | ----------------------------------------------------------- |
@@ -34,7 +34,7 @@ Exported option/value types: `McpRequestOptions`, `McpRequestParams`, `McpReques
 
 ```ts
 import { Effect, Layer } from "effect";
-import { HttpRouter, HttpServer } from "effect/unstable/http";
+import { HttpRouter, HttpServer } from "effect/http";
 import * as Testing from "@gjermundgaraba/effect-actions/Testing";
 import * as TestingClient from "@gjermundgaraba/effect-actions/TestingClient";
 import { Http, routes } from "./quickstart.js";
@@ -78,17 +78,20 @@ try {
 - `httpClient` is the same `HttpApiClient` consumers use, with its transport replaced by `handler`. Same `{ payload }` calls, same error channel.
 - `mcpRequest` pins protocol version 2026-07-28 in both the header and `_meta`. Caller `params._meta` fields override the defaulted client capabilities and info; the merge is shallow. Application metadata is preserved.
 - `params` accepts what `JSON.stringify` accepts, so tests can send malformed arguments on purpose. `undefined` fields are dropped.
-- `mcpCall` sends one `tools/call` through `mcpRequest` and resolves with `{ isError: false, value }`, the success taken from `structuredContent.value`, or `{ isError: true, error }`, the result's error text parsed as JSON. A declared error or a hook refusal is its JSON encoding, the same body HTTP sends; the native server's own messages (invalid arguments, defects) are not JSON and stay text. It reads a JSON or an event-stream response.
+- `mcpCall` sends one `tools/call` through `mcpRequest` and resolves with `{ isError: false, value }`, the success taken from `structuredContent`, with `text` holding the text field when a success with `mcp.text` sent one, or `{ isError: true, error }`, the result's error text parsed as JSON. A declared error or a hook refusal is its JSON encoding, the same body HTTP sends; the native server's own messages (invalid arguments, defects) are not JSON and stay text. It reads a JSON or an event-stream response.
+- To assert on a result's exact bytes, such as a size bound, send `mcpRequest` through the handler and parse the reply: `JSON.stringify` of the parsed message reproduces the message the server wrote, so `JSON.stringify(message.result)` is the result as encoded.
 - `mcpCall` throws when the answer is not a tool result: a status other than 200 (an authentication refusal), or a JSON-RPC error (an unknown tool). Use `mcpRequest` to assert on those responses.
 - `withMcpClient` pins the official client to MCP 2026-07-28, the only revision `ActionMcp` serves, and closes the transport in a `finally` block.
 - Add `Authorization` through `headers` in the MCP helpers, or through `transformClient` in `httpClient` options.
-- Direct handler tests can use `app.build` under `Effect.scoped`, but they bypass decoding, encoding, and middleware. Keep at least one adapter-level test per transport.
+- Direct handler tests can use `app.build` under `Effect.scoped`, but they bypass decoding, encoding, middleware, and the `before` hook. Keep at least one adapter-level test per transport.
 
 ## Failure modes
 
 - `@modelcontextprotocol/client` not found: only `TestingClient` needs it. Install the peer in devDependencies, or use `Testing.mcpRequest` instead.
-- `withMcpClient` rejects its options with `versionNegotiation`: the revision is fixed at 2026-07-28. Delete the option.
+- Type error on `versionNegotiation` in `withMcpClient` options: the revision is fixed at 2026-07-28. Delete the option.
 - `MCP tools/call "<name>" answered 401`: the call reached authentication without a credential. Pass `headers: { authorization: "Bearer ..." }`.
+- `MCP tools/call "<name>" failed with <code>: <message>`: a JSON-RPC error, such as an unknown tool. Assert on it with `mcpRequest`.
+- `MCP tools/call "<name>" had no reply` or `returned no structured content`: the response was not a tool result. Inspect it with `mcpRequest`.
 - Handler leaks between tests: `web.dispose()` was not called. Register it with the test runner's cleanup hook.
 - 404 from `httpClient`: the requested route was not mounted, or the path/base URL is wrong. Include `Http.layer([app])` in the served routes.
 - Missing platform-service requirements when constructing the web handler: provide `HttpServer.layerServices` to the routes before `toWebHandler`.

package/docs/guarantees.md

@@ -24,7 +24,7 @@ Defaults without a schema-error policy. HTTP is a native `HttpApi`; MCP is a nat
 | Case                        | HTTP                                                                                                  | MCP                                                                                                    |
 | --------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
 | Input                       | decoded with the schema's JSON codec; failure is an empty **400**                                     | decoded with the schema's JSON codec; failure is `InvalidParams`, presented as an `isError` result     |
-| Success                     | the success codec's encoding as the body: `{"id":"1","name":"Ada"}`, `42`                             | `structuredContent: { value: <encoded> }`                                                              |
+| Success                     | the success codec's encoding as the body: `{"id":"1","name":"Ada"}`, `42`                             | `structuredContent: <encoded>`, and its JSON as text content; a text field is sent as text instead     |
 | Declared error              | encoded by its schema with its `httpApiStatus` (unannotated: 500): `{"_tag":"UserNotFound","id":"x"}` | `isError: true`; text content is the same JSON; no `structuredContent`                                 |
 | Pre-handler hook failure    | the same, using the hook's error schema, after input decoding; the handler never runs                 | the same `isError` result, after arguments are decoded; the handler never runs                         |
 | Invalid output encoding     | empty **400** (`HttpApiSchemaError`)                                                                  | `isError: true`, text `Tool execution failed due to an internal server error.`; cause logged, not sent |
@@ -32,15 +32,16 @@ Defaults without a schema-error policy. HTTP is a native `HttpApi`; MCP is a nat
 | Unknown path or method      | 404                                                                                                   | n/a                                                                                                    |
 | Invalid JSON / content type | 400 / 415                                                                                             | n/a                                                                                                    |
 
+- `mcp.text` changes only the MCP success result. HTTP, OpenAPI, typed clients, the Toolkit, the CLI and its client, and the catalog serve and describe the whole success. A text field's other outcomes are answered as in this table.
 - A group `schemaError` policy replaces the empty 400s on HTTP with a declared error and status: its `invalid` error for input that does not decode, its `internal` error for output that does not encode. It never affects MCP. Details in [ActionGroup.md](ActionGroup.md).
 - `ActionHttp` sets no headers of its own. The host owns cache and challenge headers; `Authentication.middleware` marks its responses `cache-control: no-store`. Hook refusals and handler failures are ordinary declared error responses.
 - Routes are `POST <apiPath>/<group>/<action>`. Operation IDs are `<group>.<action>`. Effect generates OpenAPI component names and references.
 - `ActionHttp.make`'s `errors` are declared on every endpoint so clients decode the surface's own failures (401, 403, 429, 503). They are produced by middleware or by the binding's hook, never by a handler. `ActionMcp` and `ActionToolkit` declare their own `errors` the same way, joined into every tool's failure schema. Two errors may share an HTTP status; their `_tag`s must differ, because the client decodes a status by trying the schemas declared for it.
-- 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. Both transports publish `additionalProperties: false` for input (so does the catalog) and refuse undeclared fields: over HTTP an extra field is an input failure (an empty 400, or the group's `schemaError` `invalid` answer); an MCP tool (`Tool.Strict`) returns an invalid-arguments result. Typed HTTP clients encode input from `Http.api` and fail with `SchemaError` on an undeclared field, before sending. The native Toolkit, `ActionCli` and `ActionCliClient` decode input locally with default options, which drop an undeclared field instead of refusing it.
 
 ## Namespaces
 
-- Group names are unique within one `ActionHttp.make`. Action names are unique within a group. MCP tool names are unique within a group and within each Toolkit or MCP projection that serves it.
+- Group names are unique within one `ActionHttp.make`. Action names are unique within a group. MCP tool names are unique within each Toolkit or MCP projection that serves them; a group does not check them.
 - Adapters validate only the namespace they serve. HTTP does not check tool names; MCP does not check route names.
 - Each adapter builds only what it serves. HTTP serves every action of a group it binds, so `Http.layer` builds every implementation it is given (except a group without actions); a group with no tools is not built by MCP or Toolkit.
 

package/docs/setup.md

@@ -5,12 +5,12 @@ Install, version pins, entry points, and the boundaries of the package.
 ## Install
 
 ```sh
-pnpm add @gjermundgaraba/effect-actions effect@4.0.0-rc.117
+pnpm add @gjermundgaraba/effect-actions effect@4.0.0-rc.118
 ```
 
 | Need                           | Add                                                   |
 | ------------------------------ | ----------------------------------------------------- |
-| Node HTTP server or stdio host | `@effect/platform-node@4.0.0-rc.117`                  |
+| Node HTTP server or stdio host | `@effect/platform-node@4.0.0-rc.118`                  |
 | `TestingClient.withMcpClient`  | `@modelcontextprotocol/client@^2.0.0` (optional peer) |
 
 Node `^22.12.0 || ^24.0.0 || >=26.0.0`. ESM only.
@@ -35,12 +35,12 @@ import * as TestingClient from "@gjermundgaraba/effect-actions/TestingClient";
 ```
 
 Every module imports from the `effect` package only, with two exceptions worth knowing when
-bundling: `ActionMcp` and `ActionToolkit` are the only modules that import `effect/unstable/ai`,
+bundling: `ActionMcp` and `ActionToolkit` are the only modules that import `effect/ai`,
 and `TestingClient` is the only module that imports the optional `@modelcontextprotocol/client`
 peer. Because there is no package root, importing a contract module never pulls in an MCP
 server or the peer.
 
-Companion Effect modules you will import alongside: `effect/unstable/httpapi` (`HttpApiClient`, `OpenApi`, `HttpApiSwagger`, `HttpApiScalar`), `effect/unstable/http` (`HttpRouter`, `HttpServerResponse`, `FetchHttpClient`, `HttpClientError`), `effect/unstable/cli` (`Command`, `Flag`, `Argument`).
+Companion Effect modules you will import alongside: `effect/http-api` (`HttpApiClient`, `OpenApi`, `HttpApiSwagger`, `HttpApiScalar`), `effect/http` (`HttpRouter`, `HttpServerResponse`, `FetchHttpClient`, `HttpClientError`), `effect/cli` (`Command`, `Flag`, `Argument`).
 
 ## Rules
 
@@ -60,5 +60,6 @@ What the package does, and nothing else:
 ## Failure modes
 
 - `Cannot find module '@gjermundgaraba/effect-actions'`: there is no root export. Import a subpath.
-- Type errors inside `effect/unstable/*` after install: `effect` version drift. Install one `effect` release candidate within the peer range for every package.
+- Type errors inside `effect/*` modules after install: `effect` version drift. Install one `effect` release candidate within the peer range for every package.
+- `Cannot find module 'effect/http'` (or `effect/http-api`, `effect/cli`, `effect/ai`): `effect` is older than `4.0.0-rc.118`, which moved these modules out of `effect/unstable/*`. Install a release candidate within the peer range, and import from the new paths.
 - `@modelcontextprotocol/client` resolution errors in a server build: something imported `TestingClient`. Only tests should.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjermundgaraba/effect-actions",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Define Effect action contracts once and project them onto HTTP, MCP, native Toolkits, catalogs, and CLIs.",
   "homepage": "https://github.com/gjermundgaraba/effect-actions#readme",
   "bugs": {
@@ -35,18 +35,18 @@
     "access": "public"
   },
   "devDependencies": {
-    "@effect/platform-node": "4.0.0-rc.117",
+    "@effect/platform-node": "4.0.0-rc.118",
     "@modelcontextprotocol/client": "2.0.0",
     "@types/node": "26.6.2",
-    "effect": "4.0.0-rc.117",
+    "effect": "4.0.0-rc.118",
     "tsx": "4.23.15",
     "typescript": "7.0.2",
-    "vite": "npm:@voidzero-dev/vite-plus-core@0.3.3",
-    "vite-plus": "0.3.3"
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.0.0",
+    "vite-plus": "1.0.0"
   },
   "peerDependencies": {
     "@modelcontextprotocol/client": "^2.0.0",
-    "effect": ">=4.0.0-rc.116 <4.0.0"
+    "effect": ">=4.0.0-rc.118 <4.0.0"
   },
   "peerDependenciesMeta": {
     "@modelcontextprotocol/client": {
@@ -58,6 +58,11 @@
       "name": "pnpm",
       "version": "12.5.1",
       "onFail": "download"
+    },
+    "runtime": {
+      "name": "node",
+      "version": "^22.18.0 || ^24.11.0 || >=26.0.0",
+      "onFail": "error"
     }
   },
   "engines": {