@gjermundgaraba/effect-actions 0.10.0 → 0.11.0

package/README.md

@@ -78,10 +78,10 @@ const greeting = Effect.gen(function* () {
 ## Install
 
 ```sh
-pnpm add @gjermundgaraba/effect-actions effect@~4.0.0
+pnpm add @gjermundgaraba/effect-actions effect@~4.0.2
 ```
 
-Add `@effect/platform-node@~4.0.0` to serve or run a CLI from Node. Every module is a
+Add `@effect/platform-node@~4.0.2` to serve or run a CLI from Node. Every module is a
 subpath import (`.../Action`, `.../ActionHttp`, ...); there is no package root, so a
 contracts-only bundle never loads a server.
 
@@ -107,9 +107,8 @@ release; in a project that installs the package, point the agent at
 
 ## Status
 
-The `effect` peer is `~4.0.0`, Effect's 4.0.x patches, since the modules the surfaces build on may
-change in a minor release; the package is built and tested against the Effect release in its
-`devDependencies` (see [docs/setup.md](docs/setup.md)). Actions are unary JSON over HTTP and MCP: no streaming, uploads, prompts, or resources.
+The `effect` peer admits the patches of the Effect release the package is tested against, since
+the modules the surfaces build on may change in a minor release (see [docs/setup.md](docs/setup.md#install)). Actions are unary JSON over HTTP and MCP: no streaming, uploads, prompts, or resources.
 Token verification and the authorization rule belong to the application; the library supplies the authentication descriptor and provider, runs the rule, and answers the refusals. See [docs/setup.md](docs/setup.md).
 
 ## Acknowledgements

package/dist/Action.d.mts

@@ -2,9 +2,10 @@ import { Anyone } from "./internal/actions.mjs";
 import { BuiltIn, BuiltIns, Forbidden, InvalidInput, Issue, Refusal, Unauthenticated } from "./internal/errors.mjs";
 import { ActionOf, AnyImplementation, Authorize, BuildError, BuildServices, Holding, Implementation, Known, Member, Offered, OptionalUnless, Protected, RequestOf, SelectedOf, Served, Serving } from "./internal/implementation.mjs";
 import { Call } from "./internal/call.mjs";
+import { Image } from "./internal/media.mjs";
 import { Context, Effect, Layer, Schema, Scope } from "effect";
 declare namespace Action_d_exports {
-  export { Action, Any, AnyImplementation, Anyone, Authorize, BuildError, BuildServices, BuiltIn, Client, ClientOptions, Errors, Forbidden, Handler, Handlers, Implementation, InvalidInput, Issue, Mcp, Options, Refusal, Unauthenticated, allowAll, byName, client, implement, layer, make };
+  export { Action, Any, AnyImplementation, Anyone, Authorize, BuildError, BuildServices, BuiltIn, Client, ClientOptions, Errors, Forbidden, Handler, Handlers, Image, Implementation, InvalidInput, Issue, Mcp, Options, Refusal, Unauthenticated, allowAll, byName, client, implement, layer, make };
 }
 /** Any service-free schema. Only handlers may require services. */
 type Codec = Schema.Codec<unknown, unknown, never, never>;
@@ -298,4 +299,4 @@ export interface ClientOptions<A extends Any> {
  */
 export declare function client<const Apps extends Served, const O extends ClientOptions<ActionOf<Member<Apps>>> = {}>(implementations: Apps, ...options: OptionalUnless<O, ClientOptions<ActionOf<Member<Apps>>> & O & NoInfer<Known<O, ClientOptions<Any>>>>): Effect.Effect<Client<Apps, Offered<O, ActionOf<Member<Apps>>>>, BuildError<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>>, BuildServices<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>> | Scope.Scope>;
 //#endregion
-export { Action_d_exports, type AnyImplementation, Anyone, type Authorize, type BuildError, type BuildServices, BuiltIn, Forbidden, type Implementation, InvalidInput, type Issue, Refusal, Unauthenticated };
+export { Action_d_exports, type AnyImplementation, Anyone, type Authorize, type BuildError, type BuildServices, BuiltIn, Forbidden, Image, type Implementation, InvalidInput, type Issue, Refusal, Unauthenticated };

package/dist/Action.mjs

@@ -2,6 +2,7 @@ import { BuiltIn, Forbidden, InvalidInput, Refusal, Unauthenticated } from "./in
 import { Anyone, assertKnown, assertName, assertOnce, assertOwnTags, errorList, projectedErrors } from "./internal/actions.mjs";
 import { inputOf } from "./internal/call.mjs";
 import { Implementation, builders, built, memoized, select, toList } from "./internal/implementation.mjs";
+import { Image } from "./internal/media.mjs";
 import { Array as Array$1, Cause, Context, Effect, Predicate, Schema } from "effect";
 //#region src/Action.ts
 /**
@@ -130,4 +131,4 @@ function client(served, options) {
 	return Effect.map(built(apps), (bound) => Object.fromEntries(bound.map(([action, run]) => [action.name, methodOf(action, run)])));
 }
 //#endregion
-export { Anyone, BuiltIn, Forbidden, InvalidInput, Refusal, Unauthenticated, allowAll, byName, client, implement, layer, make };
+export { Anyone, BuiltIn, Forbidden, Image, InvalidInput, Refusal, Unauthenticated, allowAll, byName, client, implement, layer, make };

package/dist/ActionMcp.d.mts

@@ -74,8 +74,8 @@ export declare function layerHttp<const Apps extends Served, const O extends Sel
 /**
  * Serve MCP tools through newline-delimited JSON-RPC on standard I/O, speaking MCP
  * 2026-07-28, 2025-11-25 or 2025-06-18, as the host negotiates: the whole
- * program of an MCP subprocess, which succeeds once the host closes its side and the calls in
- * flight, which that interrupts, have stopped. A signal interrupts it.
+ * program of an MCP subprocess, which succeeds once the host closes its side and every call
+ * in flight has been answered. A signal interrupts it.
  *
  * Effect logs go to stderr, since stdout carries the protocol. The host supplies the
  * `Stdio` service and the identity. Arguments are tool input only and never establish

package/dist/ActionMcp.mjs

@@ -1,13 +1,13 @@
 import { Anyone } from "./internal/actions.mjs";
 import { provideHandlers, select, toList } from "./internal/implementation.mjs";
 import { assertAuthentication, promote } from "./internal/authentication.mjs";
-import { httpProtocol } from "./internal/mcp.mjs";
+import { fieldKey, httpProtocol, isMisplaced, liftOf, liftedFrom } from "./internal/mcp.mjs";
 import { recordStepUp } from "./internal/refusal.mjs";
 import { logToStderr } from "./internal/console.mjs";
 import { bindTools } from "./internal/tools.mjs";
-import { Cause, Context, Effect, Exit, Fiber, JsonPointer, Layer, Predicate, Schema } from "effect";
+import { Cause, Context, Effect, ErrorReporter, Exit, Fiber, JsonPointer, Layer, Option, Predicate, References, Result, Schema, Stream } from "effect";
 import { HttpRouter, HttpServerRequest } from "effect/http";
-import { McpProtocol, McpSchema, McpServer, Tool } from "effect/ai";
+import { AiError, McpProtocol, McpSchema, McpServer, Tool, Toolkit } from "effect/ai";
 //#region src/ActionMcp.ts
 /**
 * The revisions served over stdio: 2026-07-28 and the stateful revisions hosts open stdio
@@ -23,8 +23,9 @@ const stdioProtocols = [
 ];
 /**
 * MCP has a JSON-only wire contract. Success is the encoded success as structured content,
-* and its JSON as text; declared failures are returned as JSON text. The native server
-* refuses undeclared arguments and publishes closed input schemas.
+* and its JSON as text, but for its media, each lifted into a block of its own; declared
+* failures are returned as JSON text. The native server refuses undeclared arguments and
+* publishes closed input schemas.
 */
 const projection = {
 	label: "MCP tool",
@@ -33,38 +34,161 @@ const projection = {
 /** Whether a JSON Schema is one the native server takes for a tool's arguments. */
 const isToolJson = Schema.is(McpSchema.ToolJson);
 /**
-* The JSON Schema root of `schema` as the native server lists it for a tool, a `$ref` at its
-* root resolved.
+* The JSON Schema of `schema`, a JSON codec, as the native server lists it for a tool: a
+* `$ref` at its root resolved, as MCP requires an object root, and its definitions as `$defs`.
+* A strict one refuses undeclared keys.
 */
-const rootOf = (schema) => {
-	const document = Schema.toJsonSchemaDocument(Schema.toCodecJson(schema));
+const toolJsonSchema = (schema, strict) => {
+	const document = Schema.toJsonSchemaDocument(schema, { onExcessProperty: strict ? "error" : "ignore" });
 	const [scope, key] = Predicate.isString(document.schema.$ref) ? JsonPointer.parseUriFragment(document.schema.$ref) ?? [] : [];
-	return scope === "$defs" && key !== void 0 ? document.definitions[key] : document.schema;
+	const root = scope === "$defs" && key !== void 0 ? document.definitions[key] : document.schema;
+	return root === void 0 || Object.keys(document.definitions).length === 0 ? root : {
+		...root,
+		$defs: document.definitions
+	};
 };
 /**
-* Refuse, when the server is made, the actions of `apps` whose input is not one object, as the
-* root of a tool's arguments must be, naming every one, reading the JSON Schema the native
+* Refuse, when the server is made, the actions whose input is not one object, as the root of a
+* tool's arguments must be, naming every one, reading the JSON Schema the native
 * server reads: not a union, an array, a scalar, nor `Schema.Struct({})`, which takes any value
 * but `null`, where the native server dies when the layer builds, suggesting
-* `Tool.EmptyParams`.
+* `Tool.EmptyParams`. Then refuse those holding media where no tool lifts it, as each action's
+* `Lift` says.
 */
-const assertShapes = (apps) => {
-	const inputs = apps.flatMap((app) => app.actions).filter((action) => !isToolJson(rootOf(action.input))).map(({ name }) => name);
+const assertShapes = (lifted) => {
+	const inputs = lifted.map(([action]) => action).filter((action) => !isToolJson(toolJsonSchema(Schema.toCodecJson(action.input), true))).map(({ name }) => name);
 	if (inputs.length > 0) throw new Error(`MCP tool input must be one object with keys, such as a struct: ${inputs.join(", ")}`);
+	const misplaced = lifted.filter(([action, lift]) => isMisplaced(action, lift)).map(([{ name }]) => name);
+	if (misplaced.length > 0) throw new Error(`MCP media must be the success or an array of it, or a top-level field of a struct success, one, optional or a required array: ${misplaced.join(", ")}`);
 };
+/**
+* What the native server answers a call that fails other than as its contract declares: a
+* defect, an invalid success or error, or an unknown tool.
+*/
+const internalError = "Tool execution failed due to an internal server error.";
+/** A tool's error result, `text` its one text block. */
+const errorResult = (text) => new McpSchema.CallToolResult({
+	isError: true,
+	content: [{
+		type: "text",
+		text
+	}]
+});
+/** The one text block holding `encoded`'s JSON, none for `undefined`, as the native server sends it. */
+const textOf = (encoded) => encoded === void 0 ? [] : [{
+	type: "text",
+	text: JSON.stringify(encoded)
+}];
+/** The content block a lifted media value is sent as, naming its field where it has one. */
+const blockOf = ({ kind, field, value }) => ({
+	type: kind,
+	data: value.data,
+	mimeType: value.mimeType,
+	...field === void 0 ? {} : { _meta: { [fieldKey]: field } }
+});
+/** Why a tool call's arguments failed to decode, as the native server tells it, if they did. */
+const invalidParameters = (error) => AiError.isAiError(error) && Predicate.isTagged(error.reason, "ToolParameterValidationError") ? error.reason : void 0;
+const omitRequestServices = Context.omit(McpSchema.McpRequestContext, McpSchema.McpServerClient, HttpServerRequest.HttpServerRequest, References.CurrentLogLevel);
+/**
+* Register the tools of `toolkit` on the endpoint's registry, as `McpServer.registerToolkit`
+* does, lifting the media `lifts` finds in a tool's success into blocks of their own. The native
+* registration sends every success as structured content and one JSON text block, and takes
+* no option, so this one follows it: its decode options, failure classification, defect
+* scrubbing and listing, and the request services it leaves out of what it retains. A tool
+* whose action holds no media is registered as the native one would be: a test compares their
+* listings and results, not the services each call runs with.
+*/
+const registerTools = Effect.fnUntraced(function* (toolkit, lifts) {
+	const registry = yield* McpServer.McpServer;
+	const built = yield* toolkit.pipe(Effect.updateContext((context) => Context.merge(context, Context.mergeAll(...Object.values(toolkit.tools).flatMap((tool) => {
+		const key = Context.Service(tool.id);
+		return Option.toArray(Context.getOption(context, key)).map((handler) => Context.make(key, {
+			...handler,
+			context: omitRequestServices(handler.context)
+		}));
+	})))));
+	const services = omitRequestServices(yield* Effect.context());
+	const internalToolError = (cause) => {
+		const failure = Cause.findFail(cause);
+		return Result.isFailure(failure) && !Cause.hasDies(cause) ? Effect.failCause(failure.failure) : Effect.logError(cause).pipe(Effect.andThen(Effect.provideContext(ErrorReporter.report(cause), services)), Effect.as(errorResult(internalError)));
+	};
+	const handleCause = (cause) => {
+		const failure = Cause.findFail(cause);
+		if (Result.isSuccess(failure)) {
+			const { error } = failure.success;
+			const invalid = Context.get(Cause.reasonAnnotations(failure.success), Toolkit.FailureOrigin) === "parameters" ? invalidParameters(error) : void 0;
+			if (invalid !== void 0) return Effect.fail(new McpSchema.InvalidParams({ message: invalid.message }));
+		}
+		return internalToolError(cause);
+	};
+	const registrations = yield* Effect.forEach(Object.entries(built.tools), ([name, tool]) => Effect.gen(function* () {
+		const strict = Tool.getStrictMode(tool) === true;
+		const decodeOptions = {
+			onExcessProperty: strict ? "error" : "ignore",
+			errors: "all"
+		};
+		const lift = lifts.get(name);
+		const media = lift === void 0 || lift.fields.length === 0 ? void 0 : lift;
+		const structured = media === void 0 ? tool.successSchema : media.rest === void 0 ? void 0 : Schema.toCodecJson(media.rest);
+		const outputSchema = structured === void 0 ? void 0 : yield* Schema.decodeUnknownEffect(McpSchema.ToolOutputJson)(toolJsonSchema(structured, false)).pipe(Effect.orDie);
+		const inputSchema = yield* Schema.decodeUnknownEffect(McpSchema.ToolJson)(toolJsonSchema(tool.parametersSchema, strict)).pipe(Effect.orDie);
+		const lifted = new Set(media?.fields.map(({ name }) => name));
+		const succeeded = ({ encodedResult, result }) => {
+			if (media === void 0) return new McpSchema.CallToolResult({
+				isError: false,
+				structuredContent: encodedResult,
+				content: textOf(encodedResult)
+			});
+			const blocks = liftedFrom(media, result).map(blockOf);
+			if (structured === void 0) return new McpSchema.CallToolResult({
+				isError: false,
+				content: blocks
+			});
+			const rest = Predicate.isObject(encodedResult) ? Object.fromEntries(Object.entries(encodedResult).filter(([key]) => !lifted.has(key))) : encodedResult;
+			return new McpSchema.CallToolResult({
+				isError: false,
+				structuredContent: rest,
+				content: [...textOf(rest), ...blocks]
+			});
+		};
+		return {
+			tool: new McpSchema.Tool({
+				name,
+				description: Tool.getDescription(tool),
+				inputSchema,
+				outputSchema,
+				annotations: {
+					...Context.getOption(tool.annotations, Tool.Title).pipe(Option.map((title) => ({ title })), Option.getOrUndefined),
+					readOnlyHint: Context.get(tool.annotations, Tool.Readonly),
+					destructiveHint: Context.get(tool.annotations, Tool.Destructive),
+					idempotentHint: Context.get(tool.annotations, Tool.Idempotent),
+					openWorldHint: Context.get(tool.annotations, Tool.OpenWorld)
+				},
+				_meta: Context.getOrUndefined(tool.annotations, Tool.Meta)
+			}),
+			annotations: tool.annotations,
+			handle: (payload) => built.handle(name, payload ?? {}, void 0, decodeOptions).pipe(Stream.unwrap, Stream.runLast, Effect.flatMap(Effect.fromOption), Effect.flatMap((result) => !result.isFailure ? Effect.succeed(succeeded(result)) : result.failureOrigin === "handler" ? Effect.succeed(new McpSchema.CallToolResult({
+				isError: true,
+				content: textOf(result.encodedResult)
+			})) : Effect.failCause(Cause.annotate(Cause.fail(result.result), Context.make(Toolkit.FailureOrigin, result.failureOrigin ?? "result")))), Effect.catchCause(handleCause), Effect.provideContext(services))
+		};
+	}));
+	for (const registration of registrations) yield* registry.addTool(registration);
+});
 const server = (apps, transport, features = Layer.empty, authentication) => {
 	const binding = bindTools(apps, authentication === void 0 ? projection : {
 		...projection,
 		handler: (run, action) => (input) => action.caller === Anyone ? run(input) : recordStepUp(promote(authentication, run(input)))
 	});
-	assertShapes(apps);
-	const names = new Set(apps.flatMap((app) => app.actions.map(({ name }) => name)));
+	const lifted = apps.flatMap((app) => app.actions.map((action) => [action, liftOf(action.success)]));
+	assertShapes(lifted);
+	const lifts = new Map(lifted.map(([{ name }, lift]) => [name, lift]));
 	const register = Effect.gen(function* () {
 		const registry = yield* McpServer.McpServer;
-		const claimed = registry.tools.flatMap(({ tool }) => names.has(tool.name) ? [tool.name] : []);
+		const claimed = registry.tools.flatMap(({ tool }) => lifts.has(tool.name) ? [tool.name] : []);
 		if (claimed.length > 0) return yield* Effect.die(/* @__PURE__ */ new Error(`Duplicate MCP tool: ${claimed.join(", ")}, claimed by an action and a native feature`));
 		const handlers = yield* Layer.build(binding.layer);
-		yield* McpServer.registerToolkit(binding.toolkit).pipe(Effect.setContext(Context.add(handlers, McpServer.McpServer, registry)));
+		yield* registerTools(binding.toolkit, lifts).pipe(Effect.setContext(Context.add(handlers, McpServer.McpServer, registry)));
 	});
 	return Layer.effectDiscard(register).pipe(Layer.provide(features), Layer.provide(transport), Layer.fresh, provideHandlers(apps));
 };

package/dist/Testing.d.mts

@@ -71,10 +71,12 @@ export type McpClient<Actions extends ReadonlyArray<Any>> = { readonly [A in Act
 /**
  * A client of an MCP endpoint served by `ActionMcp.layerHttp`, one method per action calling
  * its tool with one stateless request, as `ActionHttp.client` calls routes: the input is
- * encoded with the action's schema, and the success decoded from its structured content. A
- * declared error the tool returns, the action's own or a refusal, is its decoded value, and so
- * is a refusal the endpoint's authentication answers with. The argument may be omitted when
- * `{}` is a valid input. Requires the native `HttpClient`, such as the one `layer` provides.
+ * encoded with the action's schema, and the success decoded from its structured content, each
+ * media field from the blocks whose `_meta` names it, and a success that is media, or whose
+ * every field is, from its blocks alone. A declared error the tool returns, the action's own
+ * or a refusal, is its decoded value, and so is a refusal the endpoint's authentication
+ * answers with. The argument may be omitted when `{}` is a valid input. Requires the native
+ * `HttpClient`, such as the one `layer` provides.
  */
 export declare function mcpClient<const Actions extends ReadonlyArray<Any>>(actions: Actions, options?: McpClientOptions): Effect.Effect<McpClient<Actions>, never, HttpClient.HttpClient>;
 /**

package/dist/Testing.mjs

@@ -1,12 +1,12 @@
 import { Refusal } from "./internal/errors.mjs";
 import { assertOnce, projectedErrors } from "./internal/actions.mjs";
 import { inputOf } from "./internal/call.mjs";
-import { defaultPath, statelessRequest } from "./internal/mcp.mjs";
+import { defaultPath, liftOf, statelessRequest } from "./internal/mcp.mjs";
 import { clientOf } from "./internal/memory.mjs";
 import { Context, Effect, FileSystem, Layer, Option, Path, Predicate, Schema, identity } from "effect";
 import { Etag, HttpClient, HttpClientRequest, HttpEffect, HttpPlatform, HttpRouter } from "effect/http";
 import { McpSchema } from "effect/ai";
-import { Sse } from "effect/encoding";
+import { Base64, Sse } from "effect/encoding";
 //#region src/Testing.ts
 function layer(routes) {
 	if (!Layer.isLayer(routes)) return clientOf(routes);
@@ -44,10 +44,41 @@ const replyOf = (response, text) => {
 	}).feed(text);
 	return Option.fromNullishOr(data.flatMap((message) => Option.toArray(decodeReply(message))).at(-1));
 };
+/**
+* The JSON of the media `field` a tool result's blocks hold: those of its kind naming it, or
+* none, for the whole success, in order; an array, or else the one, if any. Surplus blocks for
+* one value stay an array, which its decoding refuses.
+*/
+const mediaOf = ({ name, kind, many }, result) => {
+	const values = result.content.flatMap((block) => block.type === kind && block._meta?.["effect-actions/field"] === name ? [{
+		data: Base64.encode(block.data),
+		mimeType: block.mimeType
+	}] : []);
+	return many || values.length > 1 ? values : values[0];
+};
+/**
+* The encoded success of a tool result lifting the media `lift` finds: the whole success's
+* blocks, or its structured content with each media field taken from its blocks alone, an
+* empty one when nothing else was left.
+*/
+const reassembled = (lift, result) => {
+	const [whole] = lift.fields;
+	if (whole !== void 0 && whole.name === void 0) return mediaOf(whole, result);
+	const { structuredContent = {} } = result;
+	if (!Predicate.isObject(structuredContent)) return structuredContent;
+	const lifted = new Set(lift.fields.map(({ name }) => name));
+	return Object.fromEntries([...Object.entries(structuredContent).filter(([key]) => !lifted.has(key)), ...lift.fields.flatMap((field) => {
+		const value = mediaOf(field, result);
+		return field.name === void 0 || value === void 0 ? [] : [[field.name, value]];
+	})]);
+};
 /** Fail with the value of one of `errors` that `text` holds, or else with `otherwise`. */
 const failWith = (errors, text, otherwise) => Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.toCodecJson(Schema.Union(errors))))(text).pipe(Effect.mapError(() => otherwise), Effect.flatMap(Effect.fail));
-/** The tool call of `action` with `input` on `client`, sending to `url`. */
-const callTool = (client, url, action, input) => {
+/**
+* The tool call of `action`, whose success its tool lifts as `lift` says, with `input` on
+* `client`, sending to `url`.
+*/
+const callTool = (client, url, action, lift, input) => {
 	const { name } = action;
 	const other = (answer) => new McpCallError({ message: `MCP tools/call "${name}" ${answer}` });
 	return Effect.gen(function* () {
@@ -69,8 +100,8 @@ const callTool = (client, url, action, input) => {
 			const error = textOf(result.content.find((block) => block.type === "text")) ?? "";
 			return yield* failWith(projectedErrors(action), error, other(`returned an error: ${error}`));
 		}
-		if (result.structuredContent === void 0) return yield* Effect.fail(other(`returned no structured content: ${text}`));
-		return yield* Schema.decodeUnknownEffect(Schema.toCodecJson(action.success))(result.structuredContent);
+		if (result.structuredContent === void 0 && lift.rest !== void 0) return yield* Effect.fail(other(`returned no structured content: ${text}`));
+		return yield* Schema.decodeUnknownEffect(Schema.toCodecJson(action.success))(reassembled(lift, result));
 	});
 };
 function mcpClient(actions, { url = defaultPath, transformClient = identity } = {}) {
@@ -78,7 +109,8 @@ function mcpClient(actions, { url = defaultPath, transformClient = identity } =
 	return Effect.map(HttpClient.HttpClient, (native) => {
 		const client = transformClient(native);
 		return Object.fromEntries(actions.map((action) => {
-			return [action.name, (...args) => Effect.flatMap(inputOf(action, args), (input) => callTool(client, url, action, input))];
+			const lift = liftOf(action.success);
+			return [action.name, (...args) => Effect.flatMap(inputOf(action, args), (input) => callTool(client, url, action, lift, input))];
 		}));
 	});
 }

package/dist/internal/mcp.d.mts

@@ -1,3 +1,6 @@
+import "./implementation.mjs";
+import "./media.mjs";
+import "../Action.mjs";
 import { Schema } from "effect";
 import { McpProtocol } from "effect/ai";
 //#region src/internal/mcp.d.ts

package/dist/internal/mcp.mjs

@@ -1,4 +1,5 @@
-import { Predicate } from "effect";
+import { Media, isMarked, kindOf } from "./media.mjs";
+import { Predicate, Schema, SchemaAST } from "effect";
 import { McpProtocol } from "effect/ai";
 //#region src/internal/mcp.ts
 /**
@@ -48,5 +49,134 @@ const statelessRequest = (method, params) => {
 		}
 	};
 };
+/** The `_meta` key of a lifted block naming its field. */
+const fieldKey = "effect-actions/field";
+const isMedia = Schema.is(Media);
+const isMediaArray = Schema.is(Schema.Array(Media));
+/** The schema `ast` stands for, a `Schema.suspend` resolved, which only delays its definition. */
+const resolved = (ast) => SchemaAST.isSuspend(ast) ? resolved(ast.thunk()) : ast;
+/** The kind `ast` is, suspended or not. */
+const kindIn = (ast) => kindOf(resolved(ast));
+/**
+* The media `ast` is, one value or an array of them, as a whole success may be: an array without
+* an encoding of its own whose every element is media of one kind, such as `Schema.Array` or
+* `Schema.NonEmptyArray` of it.
+*/
+const wholeOf = (suspended) => {
+	const ast = resolved(suspended);
+	const one = kindOf(ast);
+	if (one !== void 0) return {
+		kind: one,
+		many: false
+	};
+	if (!SchemaAST.isArrays(ast) || ast.encoding !== void 0) return void 0;
+	const [kind, ...others] = new Set([...ast.elements, ...ast.rest].map(kindIn));
+	return kind === void 0 || others.length > 0 ? void 0 : {
+		kind,
+		many: true
+	};
+};
+/**
+* The media a field's `ast` is: one value, which `Schema.optional` or `Schema.optionalKey` may
+* make absent, or an array, which they may not, as no block would tell an absent one from an
+* empty one.
+*/
+const fieldOf = (field) => {
+	const optional = field.context?.isOptional === true;
+	const ast = resolved(field);
+	if (optional && SchemaAST.isUnion(ast) && ast.types.length === 2) {
+		const [value, ...more] = ast.types.filter((member) => !SchemaAST.isUndefined(member));
+		const kind = value === void 0 || more.length > 0 ? void 0 : kindIn(value);
+		return kind === void 0 ? void 0 : {
+			kind,
+			many: false
+		};
+	}
+	const whole = wholeOf(ast);
+	return whole === void 0 || optional && whole.many ? void 0 : whole;
+};
+/**
+* How an MCP tool sends `success`: it lifts the success itself, one value or an array, or the
+* top-level media fields of a struct without an encoding of its own, keyed by strings, and
+* sends the rest of the struct, if any is left.
+*/
+const liftOf = (success) => {
+	const ast = resolved(success.ast);
+	const whole = wholeOf(ast);
+	if (whole !== void 0) return {
+		fields: [{
+			name: void 0,
+			...whole
+		}],
+		rest: void 0
+	};
+	if (!SchemaAST.isObjects(ast) || ast.encoding !== void 0) return {
+		fields: [],
+		rest: success
+	};
+	const fields = ast.propertySignatures.flatMap(({ name, type }) => {
+		const field = fieldOf(type);
+		return field === void 0 ? [] : [{
+			name: String(name),
+			...field
+		}];
+	});
+	if (fields.length === 0) return {
+		fields,
+		rest: success
+	};
+	const names = new Set(fields.map(({ name }) => name));
+	const rest = ast.propertySignatures.filter(({ name }) => !names.has(name));
+	const { identifier: _identifier, ...annotations } = ast.annotations ?? {};
+	return {
+		fields,
+		rest: rest.length === 0 && ast.indexSignatures.length === 0 ? void 0 : Schema.make(new SchemaAST.Objects(rest, ast.indexSignatures, annotations))
+	};
+};
+/** The schemas `ast` is made of, its encoded side included. */
+const partsOf = (ast) => [
+	...SchemaAST.isDeclaration(ast) ? ast.typeParameters : [],
+	...SchemaAST.isArrays(ast) ? [...ast.elements, ...ast.rest] : [],
+	...SchemaAST.isObjects(ast) ? [...ast.propertySignatures, ...ast.indexSignatures].map(({ type }) => type) : [],
+	...SchemaAST.isUnion(ast) ? ast.types : [],
+	...SchemaAST.isSuspend(ast) ? [ast.thunk()] : [],
+	...(ast.encoding ?? []).map(({ to }) => to)
+];
+/** Whether `ast` holds media anywhere, each schema visited once, so a recursive one ends. */
+const holdsMedia = (ast) => {
+	const seen = /* @__PURE__ */ new Set();
+	const pending = [ast];
+	for (let next = pending.pop(); next !== void 0; next = pending.pop()) {
+		if (seen.has(next)) continue;
+		seen.add(next);
+		if (isMarked(next)) return true;
+		pending.push(...partsOf(next));
+	}
+	return false;
+};
+/**
+* Whether `action`, whose success an MCP tool lifts as `lift` says, holds media where no tool
+* lifts it: in its input, in a declared error, or in the rest of its success, such as nested in
+* a field or in a union.
+*/
+const isMisplaced = (action, { rest }) => {
+	return [
+		action.input,
+		...action.error,
+		...rest === void 0 ? [] : [rest]
+	].some(({ ast }) => holdsMedia(ast));
+};
+/**
+* The media `lift` finds in `success`, a decoded value its schema has validated: the whole
+* success's, or each field's, in field order, an array's in its order, none for an absent field.
+*/
+const liftedFrom = (lift, success) => lift.fields.flatMap(({ name, kind, many }) => {
+	const value = name === void 0 ? success : Predicate.hasProperty(success, name) ? success[name] : void 0;
+	return (many ? isMediaArray(value) ? value : [] : isMedia(value) ? [value] : []).map((media) => ({
+		kind,
+		field: name,
+		value: media
+	}));
+});
 //#endregion
-export { defaultPath, httpProtocol, statelessRequest };
+export { defaultPath, fieldKey, httpProtocol, isMisplaced, liftOf, liftedFrom, statelessRequest };

package/dist/internal/media.d.mts

@@ -0,0 +1,8 @@
+import { Schema, SchemaAST } from "effect";
+//#region src/internal/media.d.ts
+/** An image, a media field's schema, as `Action.Image` exports it. */
+export declare const Image: Schema.Struct<{
+  readonly data: Schema.Uint8Array;
+  readonly mimeType: Schema.String;
+}>;
+//#endregion

package/dist/internal/media.mjs

@@ -0,0 +1,26 @@
+import { Schema } from "effect";
+//#region src/internal/media.ts
+/**
+* The annotation marking a media kind's schema, naming the MCP content block a value of it is
+* lifted into: `Action.Image`'s is `"image"`.
+*/
+const mediaKey = "effect-actions/media";
+/** What every media kind holds: bytes, and their MIME type. */
+const Media = Schema.Struct({
+	data: Schema.Uint8Array,
+	mimeType: Schema.String
+});
+/** An image, a media field's schema, as `Action.Image` exports it. */
+const Image = Media.annotate({ [mediaKey]: "image" });
+/**
+* Whether `ast` is marked as media, read from its own annotations: a copy, such as an optional
+* key or one with checks added, keeps them, and so does one with an encoding of its own.
+*/
+const isMarked = (ast) => ast.annotations?.[mediaKey] === "image";
+/**
+* The kind `ast` is, when its values are the media they encode to: marked, without an encoding
+* of its own, which would send its values as something else.
+*/
+const kindOf = (ast) => isMarked(ast) && ast.encoding === void 0 ? "image" : void 0;
+//#endregion
+export { Image, Media, isMarked, kindOf };

package/dist/internal/schema-errors.mjs

@@ -10,11 +10,11 @@ import { HttpApiMiddleware } from "effect/http-api";
 const responseKinds = /* @__PURE__ */ new Set(["Body", "ResponseHeaders"]);
 /**
 * The native middleware answering schema failures: a request that does not decode with
-* `InvalidInput`, the schema's own message and issues, a result that does not encode as a defect,
-* the empty 500 of any other server bug.
+* `InvalidInput`, the schema's own message and issues. A result that does not encode stays the
+* native failure, which Effect answers with an empty 500 and reports.
 */
 var SchemaErrors = class extends HttpApiMiddleware.Service()("effect-actions/http/SchemaErrors", { error: [InvalidInput] }) {};
 /** `SchemaErrors`' server side, built by `ActionHttp.layer` alone, so a client's bundle leaves it out. */
-const schemaErrors = () => HttpApiMiddleware.layerSchemaErrorTransform(SchemaErrors, (failure) => responseKinds.has(failure.kind) ? Effect.die(failure.cause) : Effect.fail(InvalidInput.fromSchemaError(failure.cause)));
+const schemaErrors = () => HttpApiMiddleware.layerSchemaErrorTransform(SchemaErrors, (failure) => Effect.fail(responseKinds.has(failure.kind) ? failure : InvalidInput.fromSchemaError(failure.cause)));
 //#endregion
 export { SchemaErrors, schemaErrors };

package/docs/Action.md

@@ -13,31 +13,32 @@ surface declares and any handler may fail with.
 
 Import `@gjermundgaraba/effect-actions/Action`.
 
-| Export                                          | Purpose                                                                                                       |
-| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
-| `make(name, options)`                           | Define a pure contract; literal names, `readOnly` and `caller` stay typed.                                    |
-| `byName(actions)`                               | A list of actions keyed by name, each its exact contract: `contracts.getUser`.                                |
-| `implement(action, handler, { authorize })`     | Bind one handler, and a protected action's authorizer; returns one `Implementation`.                          |
-| `implement([actions], handlers, { authorize })` | Bind a record of handlers keyed by action name; returns one `Implementation` of all.                          |
-| `implement(actions, builder, options?)`         | Either form, with an Effect that builds the handler or record once per layer graph.                           |
-| `allowAll`                                      | The authorizer without an action-level rule: every authenticated caller may call.                             |
-| `Anyone`                                        | The caller of a public action, `caller: Action.Anyone`: anyone, signed in or not.                             |
-| `layer(implementations)`                        | Their builders as one layer: provided above every surface, each runs once for all.                            |
-| `client(implementations, { actions? })`         | An Effect of a caller running them in process: `client.<action>(input)`.                                      |
-| `InvalidInput`, `Unauthenticated`, `Forbidden`  | Built-in errors: 400, 401, 403, body `{ _tag, message }`, `InvalidInput`'s with `issues`; `message` defaults. |
-| `InvalidInput.fromSchemaError(error)`           | The `InvalidInput` every surface answers a `Schema.SchemaError` with, `issues` given.                         |
-| `Issue`                                         | One of `InvalidInput`'s `issues`: a `path` into the input and a `message`.                                    |
-| `Refusal`                                       | `Unauthenticated \| Forbidden`, schema and type: what authentication or an authorizer refuses with.           |
-| `BuiltIn`                                       | `InvalidInput \| Refusal`, schema and type: what any handler may fail with.                                   |
-| `Errors`                                        | A list of error schemas, as `error` holds it: `<E extends Action.Errors>`.                                    |
-| `Action`, `Any`, `Implementation`               | Concrete and erased contracts, and bound implementations.                                                     |
-| `Client<Apps>`                                  | What `client` gives for the implementations `Apps`, one or a list.                                            |
-| `AnyImplementation`, `AnyImplementation<A>`     | Any implementation, or any of actions `A`, erased: a generic helper's constraint.                             |
-| `BuildServices`, `BuildError`                   | What their builders read and fail with at startup, which a surface serving them owes.                         |
-| `implementation.actions`                        | Its exact contract values, as `Testing.mcpClient(users.actions)` takes them.                                  |
-| `Handler`, `Authorize`                          | Typed handlers, and authorizers `(action) => Effect<void, Refusal, R>`.                                       |
-| `Handlers`                                      | A list's handlers keyed by name, for a builder written apart from `implement`.                                |
-| `Options`, `ClientOptions`, `Mcp`               | What `make` and `client` take, and `make`'s `mcp` options.                                                    |
+| Export                                          | Purpose                                                                                                        |
+| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `make(name, options)`                           | Define a pure contract; literal names, `readOnly` and `caller` stay typed.                                     |
+| `byName(actions)`                               | A list of actions keyed by name, each its exact contract: `contracts.getUser`.                                 |
+| `implement(action, handler, { authorize })`     | Bind one handler, and a protected action's authorizer; returns one `Implementation`.                           |
+| `implement([actions], handlers, { authorize })` | Bind a record of handlers keyed by action name; returns one `Implementation` of all.                           |
+| `implement(actions, builder, options?)`         | Either form, with an Effect that builds the handler or record once per layer graph.                            |
+| `allowAll`                                      | The authorizer without an action-level rule: every authenticated caller may call.                              |
+| `Anyone`                                        | The caller of a public action, `caller: Action.Anyone`: anyone, signed in or not.                              |
+| `layer(implementations)`                        | Their builders as one layer: provided above every surface, each runs once for all.                             |
+| `client(implementations, { actions? })`         | An Effect of a caller running them in process: `client.<action>(input)`.                                       |
+| `Image`                                         | A media field's schema, `{ data: Uint8Array, mimeType: string }`: an image, which MCP sends as an image block. |
+| `InvalidInput`, `Unauthenticated`, `Forbidden`  | Built-in errors: 400, 401, 403, body `{ _tag, message }`, `InvalidInput`'s with `issues`; `message` defaults.  |
+| `InvalidInput.fromSchemaError(error)`           | The `InvalidInput` every surface answers a `Schema.SchemaError` with, `issues` given.                          |
+| `Issue`                                         | One of `InvalidInput`'s `issues`: a `path` into the input and a `message`.                                     |
+| `Refusal`                                       | `Unauthenticated \| Forbidden`, schema and type: what authentication or an authorizer refuses with.            |
+| `BuiltIn`                                       | `InvalidInput \| Refusal`, schema and type: what any handler may fail with.                                    |
+| `Errors`                                        | A list of error schemas, as `error` holds it: `<E extends Action.Errors>`.                                     |
+| `Action`, `Any`, `Implementation`               | Concrete and erased contracts, and bound implementations.                                                      |
+| `Client<Apps>`                                  | What `client` gives for the implementations `Apps`, one or a list.                                             |
+| `AnyImplementation`, `AnyImplementation<A>`     | Any implementation, or any of actions `A`, erased: a generic helper's constraint.                              |
+| `BuildServices`, `BuildError`                   | What their builders read and fail with at startup, which a surface serving them owes.                          |
+| `implementation.actions`                        | Its exact contract values, as `Testing.mcpClient(users.actions)` takes them.                                   |
+| `Handler`, `Authorize`                          | Typed handlers, and authorizers `(action) => Effect<void, Refusal, R>`.                                        |
+| `Handlers`                                      | A list's handlers keyed by name, for a builder written apart from `implement`.                                 |
+| `Options`, `ClientOptions`, `Mcp`               | What `make` and `client` take, and `make`'s `mcp` options.                                                     |
 
 | Option        | Meaning                                                                                        |
 | ------------- | ---------------------------------------------------------------------------------------------- |
@@ -372,6 +373,7 @@ console.log(
 - An `undefined` option takes its default, as an omitted one does. One that may be either is typed as either: with `success: enabled ? Schema.String : undefined`, or the same through a conditional spread, the success is `string | void`. The same holds for `input` and `error`.
 - Options annotated with a wide type, such as `Parameters<typeof Action.make>[1]`, are not checked. Their action's schemas are as wide as what may run, so its success is `unknown`. A constant object spread into the options, as above, keeps its exact types and is checked like inline options.
 - MCP input must be one object with keys, an identified, recursive or suspended root included. Scalar, array or union input is fine for HTTP and for a native Toolkit, but `ActionMcp` refuses it when `layerHttp` or `runStdio` is called, naming the action ([ActionMcp.md](ActionMcp.md#rules)). Success and error schemas may be any shape.
+- `Action.Image` is a media field, an image: `{ data: Uint8Array, mimeType: string }`, `mimeType` such as `image/png`. It goes in the success, as a top-level field of a struct, `success: { screen: Screen, image: Action.Image }`, optional, `Schema.optional(Action.Image)`, or an array, `Schema.Array(Action.Image)` or `Schema.NonEmptyArray(Action.Image)`, or as the whole success, `success: Action.Image`, or an array of it. An MCP tool lifts it into an image block, the content a model reads as an image; every other surface sends it as JSON, the bytes in base64 ([guarantees.md](guarantees.md#wire-behavior)). Anywhere else, nested in a field, in a union or a record, in an optional array field, in a class or an encoded struct, given an encoding of its own, in the input or in an error, the other surfaces still send it as JSON, but `ActionMcp` refuses it when `layerHttp` or `runStdio` is called, naming the actions ([ActionMcp.md](ActionMcp.md#media)): leave such an action out of its `actions`, or move the image to a top-level field.
 - The contract keeps `mcp` as given, `action.mcp`, and defaults none of it. A hint left out is not annotated, so the native default, MCP's, stands: `destructiveHint` `true`, `idempotentHint` `false`, `openWorldHint` `true`; but a read-only action's `destructiveHint` is `false` unless it states one. A stated hint is sent as it is, a read-only action's included, which MCP reads only for a tool that is not read-only. `readOnlyHint` is always `readOnly`. Hints are metadata for the model. They do not enforce authorization, approval, or retries; a native Toolkit's approval is `ActionToolkit.make`'s `needsApproval` option.
 - The built-in errors are declared everywhere ([guarantees.md](guarantees.md#wire-behavior)), and any handler may fail with them without listing them: `InvalidInput` for input that decodes but cannot be served, naming `issues` of its own as the library's do ([guarantees.md](guarantees.md#wire-behavior)), `new Action.InvalidInput({ message, issues: [{ path: ["lines"], message }] })`, so an application declares no second error for bad input; a refusal for a step-up. `make` refuses an `error` entry that encodes with a built-in tag, the built-in itself included, since every surface declares it already and a client could not tell a look-alike apart. Only those classes are built-in errors: a handler or an authorizer failing with an error of the same `_tag` and fields, such as Effect's `HttpApiError.Forbidden` or a `Forbidden` of your own, does not compile, since a built-in error's codec encodes its own class alone.
 - Code that decodes input of its own, such as a header, a route parameter or a file's metadata, answers a failure as the surfaces do with `Action.InvalidInput.fromSchemaError(error)`: the schema's message and its `issues`, `Effect.mapError(Action.InvalidInput.fromSchemaError)` after a `Schema.decodeUnknownEffect`. To place the issues under a field of a larger input, decode the value as that field, `Schema.decodeUnknownEffect(Schema.Struct({ payload: Payload }))({ payload })`, so each issue's `path` starts at it.

package/docs/ActionCli.md

@@ -261,6 +261,7 @@ export const cli = ActionCli.make(cache, { name: "ops" }).pipe(
 - The flags follow the schema: renaming a field renames its flag. `name`, `positional`, `aliases` and `render` give a command its name, its arguments, its short flags and its output, and keep every rule of this page: prefer a derived command wherever they express the syntax. For a syntax they cannot, such as a flag named apart from its field, or a command calling several actions, build the command with native `Command.make`, `Flag` and `Argument`, and call the actions in it through `Action.client`, acquired in its handler, inside `Effect.scoped`, so each invocation builds and releases it ([Action.md](Action.md#clients)), or over HTTP through the binding's `ActionHttp.client`. Calling a handler directly bypasses decoding and the implementation's authorizer.
 - Such a command is the host's own: through `Action.client` the authorizer runs, but the output, failure and logging rules of this page do not apply. It prints what it prints, its logs go where the host's logger writes, and a failure it leaves as it is is the action's own, not a `UserError`, which `runMain` reports on stdout with a stack and without its fields. Map it to Effect CLI's `CliError.UserError`, `new CliError.UserError({ cause, userMessage })`, for `Command.run` to print `userMessage` on stderr.
 - Output is validated and encoded before printing. Default output is JSON. `render(decoded)` gives human output and adds a `--json` flag to that command, which selects JSON again. An action whose `success` is `Schema.Void` prints nothing by default or with `--json`; a custom `render` can still print human output. Rendering cannot bypass validation: a success its schema does not encode is a defect, as on HTTP, and nothing prints it.
+- A media field, `Action.Image`, is printed as JSON, by default and with `--json`: `{ "data": "<base64>", "mimeType": "image/png" }`, as HTTP sends it. A command's `render` receives the decoded success, the image's `data` a `Uint8Array`, and prints the text it returns instead, such as the image's size; it returns text, never bytes.
 - `--json` is a regular flag of the rendered command only. A command without `render` has no such flag: its output is JSON already. Nothing is declared tree-wide, so a host CLI may declare its own `--json`, global or not.
 - Each invocation builds the selected implementation's builder, and its authorizer when an Effect builds it, in a scope of its own and releases them after the call. Only that implementation's builder runs: other implementations passed alongside it, on `command` or `make`, are not built. Domain services and authority come from layers the host provides on the command, `Command.provide(layer)`: built when the command runs, before its input is decoded, so input the action's schema refuses is refused after they are built; `--help` and the parser's errors, such as a missing or unknown flag, never build them. `make`'s aggregate run alone builds them before showing its help, since its own handler shows it, and fails instead if one fails. There is no HTTP fallback.
 - A local command is a local surface: the implementation's `authorize` runs before a protected action's handler, on `command` and on every subcommand of `make`, and the host provides the identity a protected action declares on the command, `Command.provideSync(CurrentActor, actor)`, or `Command.provideEffect(CurrentActor, load)` to read it when an action runs. Its type requires it whether or not the handler or the authorizer reads it.

package/docs/ActionHttp.md

@@ -229,6 +229,7 @@ In a browser, relative routes resolve against the page; elsewhere, give `baseUrl
 - Bindings combine into one host API with the native `addHttpApi` method, `HttpApi.make("app").addHttpApi(Http.api)`, for one document or one native client, only when their prefixes differ and no action name repeats across them. An operation ID is the action name, and a group is keyed by its mount path. Serving several bindings with `layer` has neither limit.
 - Serve the OpenAPI document as a native route: `HttpRouter.add("GET", "/api/openapi.json", HttpServerResponse.jsonUnsafe(OpenApi.fromApi(Http.api)))`. It documents every bound action, not only the served ones. It is a plain route: middleware provided to its layer covers it, and nothing covers it otherwise.
 - A route runs only a request typed as JSON: any other type, or none, is a 415, after authentication on a protected route, as on an MCP endpoint, whatever encoding the input is annotated with, such as `HttpApiSchema.asFormUrlEncoded()`, which `HttpApi` would read and no other surface does. So no request a page on another origin can send without a CORS preflight reaches a handler, whatever credentials, cookies included, it carries; one typed as JSON is preflighted, and the host's CORS policy decides.
+- A media field, `Action.Image`, is JSON in the body: `{ "data": "<base64>", "mimeType": "image/png" }`, as Effect's JSON codec encodes a `Uint8Array`. The OpenAPI document lists `data` as `type: string`, `format: byte`, `contentEncoding: base64`, as Effect's JSON Schema does, and `client` decodes it to a `Uint8Array`. Only MCP lifts it into a block of its own ([ActionMcp.md](ActionMcp.md#media)).
 - Wire format: [guarantees.md](guarantees.md#wire-behavior). Spans and log annotations: [guarantees.md](guarantees.md#observability).
 
 ### Binding errors

package/docs/ActionMcp.md

@@ -136,6 +136,83 @@ ActionMcp.runStdio(status, { name: "effect-actions-stdio", version: "0.1.0" }).p
 );
 ```
 
+### Media
+
+A tool returning an image is an action like the others: an `Action.Image` field of its success
+([Action.md](Action.md#contracts)) is lifted into an image block, the content a model reads as
+an image, and the rest of the success is sent as any success is.
+
+```ts example=mcp-image.ts
+import { Buffer } from "node:buffer";
+import { NodeRuntime, NodeStdio } from "@effect/platform-node";
+import { Effect, Schema } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
+import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
+
+const Screen = Schema.Struct({ id: Schema.Int, title: Schema.String });
+
+class TerminusError extends Schema.TaggedError<TerminusError>()("TerminusError", {
+  message: Schema.String,
+}) {}
+
+// The image is a field of the success. Over MCP it is lifted into an image block, after the
+// JSON text of `{ screen }`, which is also the structured content; elsewhere it is JSON, the
+// bytes in base64.
+const GetScreenImage = Action.make("get_screen_image", {
+  description: "Fetch the rendered image for a listed screen.",
+  input: { screen_id: Schema.Int },
+  success: { screen: Screen, image: Action.Image },
+  error: TerminusError,
+  readOnly: true,
+  caller: Action.Anyone,
+});
+
+// A one-pixel PNG stands in for a rendered screen.
+const pixel = Buffer.from(
+  "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
+  "base64",
+);
+
+const getScreenImage = Action.implement(GetScreenImage, ({ screen_id }) =>
+  screen_id === 1
+    ? Effect.succeed({
+        screen: { id: screen_id, title: "Home" },
+        image: { data: pixel, mimeType: "image/png" },
+      })
+    : Effect.fail(new TerminusError({ message: `No screen ${screen_id}.` })),
+);
+
+// A subprocess MCP server, as mcp-stdio.ts is: launch it from an MCP client.
+ActionMcp.runStdio(getScreenImage, { name: "terminus", version: "0.1.0" }).pipe(
+  Effect.provide(NodeStdio.layer),
+  ActionCli.logToStderr,
+  NodeRuntime.runMain,
+);
+```
+
+`get_screen_image` with `{ "screen_id": 1 }` answers, on every revision, beside the fields the
+native server adds to every result ([Rules](#rules)):
+
+```json
+{
+  "content": [
+    { "type": "text", "text": "{\"screen\":{\"id\":1,\"title\":\"Home\"}}" },
+    {
+      "type": "image",
+      "data": "iVBORw0KGgo...",
+      "mimeType": "image/png",
+      "_meta": { "effect-actions/field": "image" }
+    }
+  ],
+  "structuredContent": { "screen": { "id": 1, "title": "Home" } }
+}
+```
+
+The tool lists the `outputSchema` of `{ screen }`. HTTP, a CLI command and a Toolkit send the
+same success as JSON, the image `{ "data": "<base64>", "mimeType": "image/png" }`
+([guarantees.md](guarantees.md#wire-behavior)).
+
 ### Native features
 
 Effect's own resources, prompts and tools join an endpoint's tools as its `features`, one layer
@@ -181,14 +258,21 @@ satisfy a feature.
 - A handler may yield `McpServer.McpServer`, its endpoint's registry, to send notifications such as progress: the endpoint provides it, and no host owes it. Served on another surface too, where nothing provides it, read it with `Effect.serviceOption`.
 - Every served action's input must be one object with keys, as a tool's arguments are: fields, a struct or a class, identified, recursive or suspended, a record, or a declared type whose JSON Schema is an object. `layerHttp` and `runStdio` read the JSON Schema the native server reads, and throw for any other when they are called, naming the actions: a union, an array, a scalar, or an object without keys such as `Schema.Struct({})`. Omit `input`, or give `{}`, for a tool with no arguments.
 - A tool's `inputSchema` is its input's JSON Schema, on every revision, closed with `additionalProperties: false` where the input declares its fields; a record's lists its value schema there instead. Undeclared arguments are refused on every revision, as invalid arguments.
-- A success is sent as it is. On 2026-07-28, over HTTP and stdio, it is `structuredContent: <encoded success>`, of any JSON type (`null` for an action that returns nothing), and one text block holding the same JSON, and the tool's `outputSchema` describes the encoded success. Stdio's earlier revisions, 2025-11-25 and 2025-06-18, structure less: they carry only an object as `structuredContent`, and list only an object-rooted `outputSchema`. A success they do not structure is text alone: its JSON, or a string success the string itself. 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`.
+- A success without a media field is sent as it is. On 2026-07-28, over HTTP and stdio, it is `structuredContent: <encoded success>`, of any JSON type (`null` for an action that returns nothing), and one text block holding the same JSON, and the tool's `outputSchema` describes the encoded success. Stdio's earlier revisions, 2025-11-25 and 2025-06-18, structure less: they carry only an object as `structuredContent`, and list only an object-rooted `outputSchema`. A success they do not structure is text alone: its JSON, or a string success the string itself. 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`.
+- A media field is lifted out of the result ([Media](#media)): each becomes a content block of its own, after the one text block, in field order: for an `Action.Image`, an `image` block of its `data` in base64 and its `mimeType`. The rest of the success is sent as any success is: `structuredContent` is the encoded success without its media fields, the tool's `outputSchema` describes that, and the text block is its JSON, exactly. The rest is an object, so stdio's 2025 revisions structure it too.
+- An absent optional media field sends no block. An array field sends one block per element, in order.
+- A success that is media, `success: Action.Image`, or whose every field is, sends its blocks alone: no `structuredContent`, no text block, and the tool lists no `outputSchema`. A success that is an array of media, `success: Schema.Array(Action.Image)`, sends one block per element, alone too. Blocks of a success that is media carry no `_meta`, as no field names them.
+- Each block lifted from a field names it in its `_meta`, `{ "effect-actions/field": "image" }`, on every revision, so a client reassembles the success from the structured content and the blocks, as `Testing.mcpClient` does ([Testing.md](Testing.md#rules)). A client that does not know the key ignores it, as MCP's `_meta` is open.
+- Media is lifted only from a top-level field of a struct success (`Schema.Struct` or fields, `Schema.suspend`ed or not), the field bare, `Schema.optional` or `Schema.optionalKey`, or an array, `Schema.Array` or `Schema.NonEmptyArray`, or from a success that is media or such an array. An `Action.Image` anywhere else in an action the endpoint serves is refused when `layerHttp` or `runStdio` is called, naming the actions, as an input that is not one object is: nested in a field, in a union or a record, in an optional array field, whose blocks cannot tell absent from empty, in a `Schema.Class` success or a struct with an encoding of its own, such as `Schema.encodeKeys`, or given an encoding of its own itself, which would send it as something else, in the input or in an error. Only the listed `actions` are checked.
+- A media field's own annotations, such as its `description`, and those of a success that is media, reach no model: the `outputSchema` leaves the field out, a success that is media lists none, and an image block carries no description. Describe the image in the action's `description`.
+- A declared error is unchanged by media: an `isError` result whose text is the error's JSON.
 - On 2026-07-28, over HTTP and over stdio, the native server adds `_meta["io.modelcontextprotocol/serverInfo"]` and `resultType: "complete"` to every result, beside a tool result's own fields (`isError: false` on a success); the earlier revisions stdio speaks add neither. `serverInfo` is the options' `name`, `version`, `description`, `websiteUrl` and `icons`, as given, so a 2026-07-28 result's encoded size is the size of its own fields plus a fixed overhead per endpoint or subprocess.
 - Invalid arguments are answered by the native `McpServer`: from 2025-11-25 on, an `isError` result with a message for the model, such as `Invalid parameters for tool 'greet': Expected string\n  at ["name"]`; on earlier stdio revisions, a JSON-RPC error. HTTP's `InvalidInput` does not apply. A protected tool's call from a caller without a credential that verifies gets the 401 first, before its arguments are decoded, malformed ones included, on a mixed endpoint as on one of protected tools alone.
 - Defects and encoding failures produce the generic `isError` text `Tool execution failed due to an internal server error.`; the cause is logged, not sent.
 - Every caller sees every tool of the endpoint ([guarantees.md](guarantees.md#scope)); authorization happens in each implementation's `authorize`.
 - Cancellation is Effect's native RPC interruption. Over HTTP there is no session, so `notifications/cancelled` interrupts nothing. A tool call ends with its HTTP request, whose lifetime (for example, whether a client disconnect interrupts it) is the host's.
 - Handlers may yield `McpSchema.McpRequestContext` for the client's declared information; the native server supplies it to every tool call, so it is never a router or host requirement.
-- `runStdio` is the subprocess's whole program: it serves until the host closes stdin, then succeeds, so the process exits 0. Closing stdin interrupts every call in flight; `runStdio` succeeds once they have stopped, after any uninterruptible region has completed. An interrupted call gets no result: no answer, or a JSON-RPC error. MCP hosts close stdin to shut a server down; a script piping requests keeps stdin open until it has read every answer. A signal interrupts it, as any program. Provide `Stdio` and its services to it and run it, `NodeRuntime.runMain`.
+- `runStdio` is the subprocess's whole program: it serves until the host closes stdin, then succeeds, so the process exits 0. Closing stdin ends the input, not the calls in flight: each runs to completion and is answered, and `runStdio` succeeds once every answer is written. A script piping requests may close stdin as soon as it has written them. A call that never completes keeps the process running: MCP hosts close stdin to shut a server down, and the MCP specification expects them to send `SIGTERM` when it does not exit in time. A signal interrupts it, as any program. Provide `Stdio` and its services to it and run it, `NodeRuntime.runMain`.
 - stdio is a local surface and takes no `authentication`: the host supplies `Stdio` (`NodeStdio.layer`) and any request-time services explicitly around `runStdio`, the identity of every protected tool included, `Effect.provideService(CurrentActor, actor)`. Each implementation's `authorize` runs for its protected tools. Tool arguments never establish identity.
 - `runStdio` gives its program a `Console` that writes every method through the `error` of the console it runs with, to stderr, since stdout carries the protocol: every console logger, the default one included, `Console.log`, and the counters, timers and group labels Node's console prints on stdout. A counter or a timer prints its label and its count or the milliseconds since it started, a group prints its label without indenting what follows, and `clear` does nothing. Layers provided around `runStdio` run outside its program: apply `ActionCli.logToStderr` last, before `runMain`, as the example does, which moves their default logger to stderr and reports there what `runMain` would report on stdout, a failure of such a layer or a defect, with the exit code `runMain` gives ([ActionCli.md](ActionCli.md#rules)). It does not move their `Console` output or a logger writing through `Console.log`, such as `Logger.consoleJson`; log JSON with `Logger.withConsoleError(Logger.formatJson)` instead. Keep the global `console.log` and other direct writes off stdout.
 - Each endpoint or subprocess owns a fresh native tool registry. That isolates tool names, not application context.
@@ -201,6 +285,7 @@ satisfy a feature.
 ## Failure modes
 
 - `MCP tool input must be one object with keys, such as a struct: <name>, ...` thrown by `layerHttp` or `runStdio`: those actions' input is a union, an array, a scalar, or an object without keys such as `Schema.Struct({})`. Wrap a union in a field, `input: { notification: Schema.Union([Email, Sms]) }`, omit `input` (or give `{}`) for no arguments, or leave the action out of `actions`.
+- `MCP media must be the success or an array of it, or a top-level field of a struct success, one, optional or a required array: <name>, ...` thrown by `layerHttp` or `runStdio`: those actions hold an `Action.Image` a tool cannot lift, nested in a field, in a union or a record, in an optional array field, in a class or an encoded struct, with an encoding of its own, in the input or in an error. Make it a top-level field of a `Schema.Struct` success, the whole success or an array of it, give an optional array field as a required one, empty when absent, or leave the action out of `actions`; the other surfaces send it as JSON.
 - `Type 'CurrentActor' is not assignable to type 'never'` where the server is launched, with `CurrentActor` among the endpoint's startup requirements rather than its `Request<"Requires", ...>`: a feature reads a request service, which it never receives ([native features](#native-features)). Serve that content as an action.
 - A native `McpServer.resource`, `McpServer.prompt` or `McpServer.toolkit` layer merged beside `layerHttp` builds without error and is never served: `resources/list` is empty, `prompts/list` is not found, and `tools/list` lists only the actions. Each endpoint's registry is its own: pass them as its `features`.
 - An MCP client gets an `isError` refusal instead of the 401 or 403 it re-authorizes on: the handler sent a notification before refusing, so the response had already started. Refuse in the implementation's `authorize`, before the handler runs.

package/docs/ActionToolkit.md

@@ -105,6 +105,7 @@ provide it once. So does one of fewer tools, such as an agent's
 
 - Every action of the implementations passed becomes a tool, named after the action, with its `mcp` hints, unless `actions` lists the tools: then only those, each behind its implementation's authorizer and from its builder's one run, and an implementation holding none of them is not built. `make(implementations)` accepts one implementation or a list, such as `[userActions, double]`. The types take only actions of the implementations, and type `toolkit` and `layer`'s build services by the listed actions alone; `needsApproval`'s `call` is typed by every action of the implementations. Options whose `actions` may be absent, such as a value typed `ActionToolkit.Options<A>`, serve every action when it is absent and the listed ones when given, so their types owe what every action owes, and hold only the tools present either way ([guarantees.md](guarantees.md#names)).
 - A result's `result` is the action's decoded success or declared failure, and its `encodedResult` the JSON a model reads, such as `"42"` for a `BigInt`. Declared failures are returned as native tool results (`failureMode: "return"`), not raised.
+- A media field, `Action.Image`, reaches a model as base64 text: the tool's `encodedResult` is the JSON success, `{ "data": "<base64>", "mimeType": "image/png" }` for an image, as HTTP sends it, and Effect's providers send a tool's result to the model as text. The model reads no image from it, and the base64 fills its context. Leave such an action out of `actions` unless the model needs those bytes; over MCP the same action sends an image block ([ActionMcp.md](ActionMcp.md#media)).
 - `tools.handle(name, encodedInput)` takes JSON arguments, as a model sends them: an ISO string for a `Schema.Date`, `null` for an absent `Schema.optional` field. It 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.
 - Builders, calls and identity follow the [dependency lifetimes](guarantees.md#dependency-lifetimes), and authorization the [authorization rules](guarantees.md#authorization): `layer` builds, a call releases what it acquired when it ends, whether a model's turn or `tools.handle` makes it, and identity is supplied at invocation, never when building the layer. A protected tool's call owes its identity in its type; one call without it anyway, as from plain JavaScript, fails with `Unauthenticated` before `authorize` runs. The innermost caller provided wins: a call made under a narrower identity runs as that one.
 - A model loop in a route yields `toolkit` in its implementation's builder, `Action.implement(Chat, Effect.map(toolkit, (tools) => ({ prompt }) => ...), { authorize })`, and passes `tools` to `LanguageModel.generateText`; the route's layer takes the toolkit's `layer`, `ActionHttp.layer(ChatHttp, chat).pipe(Layer.provide(layer))`. That is one build, in the routes' layer graph, shared with every surface serving the same implementations. `Effect.provide(layer)` in the handler builds it for every call unless a surface of the graph serves the same implementations, and `HttpRouter.provideRequest(layer)` once, but in a layer graph of its own: a second build when another surface serves them and has not built them first.
@@ -119,6 +120,7 @@ provide it once. So does one of fewer tools, such as an agent's
 
 ## Failure modes
 
+- A model reads base64 text where an image was meant: a tool's success holds an `Action.Image`, which a Toolkit gives the model as JSON text. Leave the action out of `actions`, or serve it over MCP, which sends an image block.
 - Tool missing from the toolkit: its implementation was not passed to `make`, or `actions` leaves it out.
 - `Listed in actions, but no implementation holds it: <names>` thrown at `make`: those actions are not among the implementations' actions, by identity. `(another contract)` marks one whose name an implementation holds, as a second copy of the contracts module makes. Pass the implementation holding it, or list the contract it implements.
 - A defect when a tool handles a call: no `layer` of its implementation is provided, only one of another implementation with tools of the same names, such as another implementation of the same actions, which the types accept. Provide a `layer` made from the implementations the `toolkit` was made from.

package/docs/CONTEXT.md

@@ -26,3 +26,4 @@ words with these meanings. Module names and Effect's own terms (`HttpApi`, `Tool
 - **Declared error**: an error schema listed in an action's `error`. Its handler may fail with it, a limit such as a rate limit included. HTTP sends its JSON encoding with its `httpApiStatus`, 422 without one; MCP returns the same JSON as an `isError` result; the Toolkit returns it as a failure result; a CLI command prints the same JSON on stderr, failing with Effect CLI's `UserError`, whose `cause` it is.
 - **Built-in errors**: `Action.InvalidInput` (400), `Action.Unauthenticated` (401) and `Action.Forbidden` (403), tagged errors with body `{ _tag, message }` and a default `message`; an `InvalidInput` also lists `issues`, empty when it names none, each an `Action.Issue`: a `path` into the input and a `message`, and a `Forbidden` the OAuth `scopes` a call lacks. The library produces them, and every surface declares them: [guarantees.md](guarantees.md#wire-behavior).
 - **Refusal**: `Action.Refusal`, `Unauthenticated | Forbidden`, a schema and a type, as `Action.BuiltIn` is of every built-in error. What authentication or an authorizer refuses a caller with instead of letting a handler run, and all an authorizer may fail with. A **step-up refusal** is one an OAuth client acts on, `Unauthenticated` or a `Forbidden` naming `scopes`. Its HTTP status, challenge, and the exception for an MCP response that has already started follow the [authorization rules](guarantees.md#authorization).
+- **Media field**: a field of an action's success whose schema is a media kind, `Action.Image`, `{ data: Uint8Array, mimeType: string }`: a top-level field of a struct success, optional or an array, or the whole success or an array of it. An MCP tool **lifts** it out of its result into a content block of its own, an image block, beside the rest of the success; every other surface sends it as JSON, the bytes in base64 ([ActionMcp.md](ActionMcp.md#media)).

package/docs/README.md

@@ -10,7 +10,7 @@ Read the card for a module before writing code that uses it. Exported TypeScript
 Package facts that apply everywhere:
 
 - Every module is a subpath import: `import * as Action from "@gjermundgaraba/effect-actions/Action"`. There is no package root.
-- The `effect` peer is `~4.0.0`: Effect's 4.0.x patches. Effect marks the HTTP, HTTP API, AI and CLI modules the surfaces build on unstable, so a minor release may change them; a later minor is admitted once the package is tested against it. The package is built and tested against `4.0.0`.
+- The `effect` peer admits the patches of the Effect release the package is tested against, and no later minor until a release is tested against it ([setup.md](setup.md#install)).
 - Action contracts are pure values. Defining contracts and implementations runs neither handlers nor builder Effects. Builder services are acquired when a layer is built, an `Action.client` is acquired, or a local CLI command runs; see [dependency lifetimes](guarantees.md#dependency-lifetimes).
 
 ## Pages

package/docs/Testing.md

@@ -144,9 +144,9 @@ Any provider of that descriptor satisfies the routes; nothing else does.
 - A relative URL resolves against `http://localhost`, once any `baseUrl` a client adds is applied, so `ActionHttp.client(Http)` needs no `baseUrl` under `layer`, and one given is kept. Every request on this client is answered by the routes, whatever its host, so the native `HttpApiClient` and a remote `ActionCli` command work in memory too.
 - The client is `layer`'s own: the program's other HTTP clients get none of its requests, and it none of theirs, whether a `FetchHttpClient` is built before or after it or a `FetchHttpClient.Fetch` is provided around the program.
 - `layer(handler)` gives the same client, answered by a web handler the test serves, such as `HttpRouter.toWebHandler(routes.pipe(Layer.provide(HttpServer.layerServices))).handler` shared with tests that send it `Request`s: the routes are built once, by the handler, for every `layer` given it. The web handler needs the routes' platform services, which `HttpServer.layerServices` provides and `layer(routes)` supplies itself. The test owns the handler: `layer` neither builds nor disposes it, so the test calls `dispose` when it is done.
-- A client method sends one stateless `tools/call` for the action's tool, at the protocol version `ActionMcp.layerHttp` serves, 2026-07-28, in both the header and `_meta`. It encodes the input with the action's schema, and decodes the success from `structuredContent`, as `ActionHttp.client` does for a route. It reads a JSON or an event-stream response.
+- A client method sends one stateless `tools/call` for the action's tool, at the protocol version `ActionMcp.layerHttp` serves, 2026-07-28, in both the header and `_meta`. It encodes the input with the action's schema, and decodes the success from `structuredContent`, as `ActionHttp.client` does for a route. A media field it takes only from the blocks whose `_meta` names it, `{ "effect-actions/field": "image" }`, in order, never from the structured content, and a success that is media, or whose every field is, from its blocks alone ([ActionMcp.md](ActionMcp.md#media)): the method succeeds with the success as the handler returned it, the image's `data` a `Uint8Array`, an optional image returned as `undefined` absent, as no block tells the two apart. It reads a JSON or an event-stream response.
 - A declared error, the action's own or a built-in one, is a typed failure of its decoded value: an `isError` result from the tool, or a 401 or 403 from the endpoint's authentication or an authorizer, whose body is the same JSON. Match it with `Effect.catchTag`, exactly as on the HTTP client.
-- Any other answer fails with `McpCallError`, whose `message` holds it: another status, the native server's own text (invalid arguments, a defect), no reply, a result without `structuredContent`, or a JSON-RPC error (an unknown tool). Match it with `Effect.catchTag("McpCallError", ...)`.
+- Any other answer fails with `McpCallError`, whose `message` holds it: another status, the native server's own text (invalid arguments, a defect), no reply, a result without the `structuredContent` its success is sent as, or a JSON-RPC error (an unknown tool). Match it with `Effect.catchTag("McpCallError", ...)`. A success that does not decode, such as one missing the blocks of its media fields, fails with `SchemaError`, as it does from `ActionHttp.client`.
 - The input is typed, so a malformed call cannot be sent through a client method. To assert on a malformed call, another MCP method or the response itself, such as a refusal's status and `WWW-Authenticate` challenge, send `mcpRequest(method, params, options)`.
 - `mcpRequest` is one stateless request as a client method sends it, a native `HttpClientRequest` the test sends itself: with `mcp-name` from `params.uri` for `resources/read` and from `params.name` otherwise, and the client metadata in `_meta`. A `_meta` in `params`, such as a `progressToken`, is merged over the client metadata, and the protocol version is always the request's own.
 - Under `layer`, send it with `HttpClient.execute(Testing.mcpRequest("tools/list"))`, which succeeds with the response whatever its status.

package/docs/guarantees.md

@@ -40,17 +40,17 @@ built-in errors are `Action.InvalidInput` (400), `Action.Unauthenticated` (401)
 `Action.Forbidden` (403), each `{ _tag, message }`; an `InvalidInput` also lists `issues`, empty
 when it names none, and a `Forbidden` may add `scopes`.
 
-| Case                        | HTTP                                                                                                  | MCP                                                                                                                                                                  |
-| --------------------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Input                       | decoded with the schema's JSON codec; failure is **400** `InvalidInput`, `message` the schema issues  | decoded with the schema's JSON codec; failure is an `isError` result from 2025-11-25 on, and a JSON-RPC `InvalidParams` error before                                 |
-| Success                     | the success codec's encoding as the body: `{"id":"1","name":"Ada"}`, `42`                             | `structuredContent: <encoded>` and its JSON as text on 2026-07-28; earlier stdio revisions structure only an object ([ActionMcp.md](ActionMcp.md#rules))             |
-| Declared error              | encoded by its schema with its `httpApiStatus` (unannotated: 422): `{"_tag":"UserNotFound","id":"x"}` | `isError: true`; text content is the same JSON; no `structuredContent`                                                                                               |
-| Authentication              | a protected route without a valid credential: **401** with a challenge, before its body is read       | a request a protected tool's call or a native feature needs: **401** with a challenge, before its body is read ([ActionMcp.md](ActionMcp.md#rules))                  |
-| Authorizer refusal          | its JSON with its status, **401** / **403**, after input decoding; the handler never runs             | the same `isError` result, after arguments are decoded; on a Bearer-authenticated endpoint a protected tool's step-up refusal is **401** / **403**                   |
-| Invalid output encoding     | a defect: empty **500**                                                                               | `isError: true`, text `Tool execution failed due to an internal server error.`; cause logged, not sent                                                               |
-| Defect                      | empty **500**                                                                                         | same generic `isError` result; cause logged, not sent                                                                                                                |
-| Unknown path or method      | 404                                                                                                   | another path: 404, as HTTP; another HTTP method on the endpoint: an empty **405** with `Allow: POST`; an unknown tool: a JSON-RPC `-32602` error, with 200 over HTTP |
-| Invalid JSON / content type | 400 `InvalidInput` / 415 for a missing or non-JSON type, after authentication on a protected route    | over HTTP, a JSON-RPC `Parse error` (`-32700`) with 200 / an empty **415** for a missing or non-JSON type; over stdio, a line that is not JSON goes unanswered       |
+| Case                        | HTTP                                                                                                  | MCP                                                                                                                                                                                                                                            |
+| --------------------------- | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Input                       | decoded with the schema's JSON codec; failure is **400** `InvalidInput`, `message` the schema issues  | decoded with the schema's JSON codec; failure is an `isError` result from 2025-11-25 on, and a JSON-RPC `InvalidParams` error before                                                                                                           |
+| Success                     | the success codec's encoding as the body: `{"id":"1","name":"Ada"}`, `42`                             | `structuredContent: <encoded>` and its JSON as text on 2026-07-28; earlier stdio revisions structure only an object ([ActionMcp.md](ActionMcp.md#rules)); a media field is lifted into a block of its own ([ActionMcp.md](ActionMcp.md#media)) |
+| Declared error              | encoded by its schema with its `httpApiStatus` (unannotated: 422): `{"_tag":"UserNotFound","id":"x"}` | `isError: true`; text content is the same JSON; no `structuredContent`                                                                                                                                                                         |
+| Authentication              | a protected route without a valid credential: **401** with a challenge, before its body is read       | a request a protected tool's call or a native feature needs: **401** with a challenge, before its body is read ([ActionMcp.md](ActionMcp.md#rules))                                                                                            |
+| Authorizer refusal          | its JSON with its status, **401** / **403**, after input decoding; the handler never runs             | the same `isError` result, after arguments are decoded; on a Bearer-authenticated endpoint a protected tool's step-up refusal is **401** / **403**                                                                                             |
+| Invalid output encoding     | an empty **500**, reported to `ErrorReporter`s                                                        | `isError: true`, text `Tool execution failed due to an internal server error.`; cause logged, not sent                                                                                                                                         |
+| Defect                      | empty **500**                                                                                         | same generic `isError` result; cause logged, not sent                                                                                                                                                                                          |
+| Unknown path or method      | 404                                                                                                   | another path: 404, as HTTP; another HTTP method on the endpoint: an empty **405** with `Allow: POST`; an unknown tool: a JSON-RPC `-32602` error, with 200 over HTTP                                                                           |
+| Invalid JSON / content type | 400 `InvalidInput` / 415 for a missing or non-JSON type, after authentication on a protected route    | over HTTP, a JSON-RPC `Parse error` (`-32700`) with 200 / an empty **415** for a missing or non-JSON type; over stdio, a line that is not JSON goes unanswered                                                                                 |
 
 - The HTTP surfaces set no header of their own; handler failures are ordinary declared error responses. On a route a Bearer descriptor authenticates, a `Forbidden` naming scopes carries `WWW-Authenticate: Bearer error="insufficient_scope", scope="..."`.
 - Authentication marks every response to a request it authenticates, on a protected HTTP route, an MCP endpoint naming a descriptor or a route of the host's own under `Authentication.protect`, `Cache-Control: no-store`, unless its route states its own caching, such as `private, max-age=31536000, immutable` for a content-addressed download. A covered route stating its own says `private` unless its answer is the same for every caller: a credential a proxy forwards is invisible to a cache in front of that proxy, which may store the answer and serve it to anyone. A failure that enclosing middleware serializes always gets `no-store`, whatever caching it states. An MCP endpoint's answer to a request it does not authenticate, discovery, its listing or a public tool's call without a credential, gets none, as a public HTTP route's does: it reads no credential. It gives every 401 among them without a challenge its scheme's, where the scheme has one, whether authentication, the authorizer or a handler answers it, a failure that enclosing middleware serializes included. As a protected resource, it names its metadata URL in every challenge, and a 401's names `scopesRequired`, and `invalid_token` when the request presented credentials ([Authentication.md](Authentication.md#rules)).
@@ -62,7 +62,8 @@ when it names none, and a `Forbidden` may add `scopes`.
 - HTTP refuses undeclared input fields, nested ones too, as the OpenAPI document's `additionalProperties: false` says: the request is a 400 `InvalidInput` naming the field's path. A client drops them when it encodes, since TypeScript lets a wider value through. A record accepts every key its key schema does. A CLI command refuses them too, with an `InvalidInput`, in `--input` and in a flag's JSON. A Toolkit drops them, as Effect decodes a model's tool call. An action without input, `input: {}` given or not, accepts only `{}`, on every surface; over HTTP, an empty JSON body is a 400. MCP tools are strict (`Tool.Strict`): undeclared arguments are invalid arguments, an `isError` result from 2025-11-25 on and a JSON-RPC `InvalidParams` error on earlier stdio revisions. An input that declares its fields publishes `additionalProperties: false` in its schema over HTTP and on MCP ([ActionMcp.md](ActionMcp.md#rules)).
 - An `InvalidInput` for input that does not decode lists `issues`, one `{ path, message }` per issue its `message` describes: `path` holds the keys and indexes from the input's root, `["lines", 1, "count"]`, a symbol key as its string form, `Symbol(name)`, and is empty for the input as a whole. Over HTTP a wrong or missing top-level literal field is such an issue, reported as the whole expected shape. A handler failing with `InvalidInput` may give `issues` of its own, sent as written, and `issues: []` without them: the field is always sent, and the OpenAPI document requires it. MCP's and a Toolkit's native answers have a message only.
 - A message for input that does not decode says what the schema expects and, where Effect's decoder reports one, each issue's path, as does each of an `InvalidInput`'s `issues`; never a value sent, on every surface: `InvalidInput` over HTTP, from a CLI command and from `Action.client`, MCP's invalid-arguments result, a Toolkit's `ToolParameterValidationError`. A path names each key it passes through, an undeclared key and a record's keys included, so a record keyed by an email or a token names it. Effect CLI's own parser, which reads a flag before the schema decodes it, names a rejected choice, an unknown flag or an unexpected argument as typed. A schema's own `message` annotation, or a filter's message, is sent as written, so never put the input in one. Declare a secret `Schema.Redacted`, so what a handler logs of its decoded input prints `<redacted>`; a tool call's span holds it all the same ([observability](#observability)).
-- A CLI command prints the success's encoding on stdout, and a failure on stderr as the JSON HTTP sends: the action's declared error, a binding's, a built-in one, `InvalidInput` included. A success that does not encode is a defect there too, which the command does not print ([ActionCli.md](ActionCli.md#rules)).
+- A media field, `Action.Image`, is JSON on every surface but MCP: `{ "data": "<base64>", "mimeType": "image/png" }`, the bytes in base64, as Effect's JSON codec encodes a `Uint8Array`. HTTP sends it so, a CLI command prints it so, a Toolkit gives it so to a model, and `Action.client` passes it through that codec. Only an MCP tool lifts it, into an image block beside the rest of the success ([ActionMcp.md](ActionMcp.md#media)).
+- A CLI command prints the success's encoding on stdout, and a failure on stderr as the JSON HTTP sends: the action's declared error, a binding's, a built-in one, `InvalidInput` included. A success that does not encode is a defect there, which the command does not print ([ActionCli.md](ActionCli.md#rules)).
 - An `Action.client` call passes its input, its success and its failure through their JSON codecs, encoded then decoded, as HTTP carries them, so its handler and its caller get what a remote call's would. A success or a failure that does not pass, an error its action does not declare included, is a defect, as it is an empty 500 over HTTP ([Action.md](Action.md#clients)).
 - A failure an action does not declare, which the types refuse but plain JavaScript or a cast lets through, is answered by each surface its own way: `Action.client` dies with a defect, HTTP answers an empty 500, MCP its internal-error tool result, `Tool execution failed due to an internal server error.`, a local CLI command fails with `UserError` whose `cause` is that failure, and a Toolkit call fails with an `AiError`, `Failed to encode result`. Declare every error a handler may fail with.
 

package/docs/setup.md

@@ -5,12 +5,17 @@ Installation, version pins, entry points, a minimal program, and package boundar
 ## Install
 
 ```sh
-pnpm add @gjermundgaraba/effect-actions effect@~4.0.0
+pnpm add @gjermundgaraba/effect-actions effect@~4.0.2
 ```
 
 | Need                                | Add                            |
 | ----------------------------------- | ------------------------------ |
-| Node HTTP server, stdio host or CLI | `@effect/platform-node@~4.0.0` |
+| Node HTTP server, stdio host or CLI | `@effect/platform-node@~4.0.2` |
+
+The `effect` peer admits the patches of the Effect release the package is built and tested
+against, and no later minor: Effect marks the HTTP, HTTP API, AI and CLI modules the surfaces build
+on unstable, so a minor release may change them. A release of this package admits a later minor
+once it is tested against it.
 
 Node `^22.12.0 || ^24.0.0 || >=26.0.0`. TypeScript 7 or newer; earlier versions are not
 supported. ESM only.
@@ -95,7 +100,7 @@ the browser example in [ActionMcp.md](ActionMcp.md#cross-origin-browsers).
 
 `Action`, `ActionHttp` and `Authentication`, and every module they import, import Effect through three
 specifiers alone: `effect`, `effect/http` and `effect/http-api`. A page that loads Effect from
-an import map rather than its bundle maps those three. A map pointing at Effect 4.0.0's
+an import map rather than its bundle maps those three. A map pointing at Effect's
 published files maps `effect/Cause`, `effect/Effect`, `effect/Exit` and `effect/Function` too,
 to the same files the `effect` barrel loads, as Effect's own `Runtime` module imports them by
 name; a build or CDN that resolves Effect's own imports needs only the three.
@@ -122,7 +127,7 @@ What the package does and does not do: [guarantees.md](guarantees.md#scope).
 - A browser build fails with `Could not resolve "node:…"`, or warns `Module "node:…" has been externalized for browser compatibility`: the page imports a module that also holds server code, such as a contract beside its `Action.implement`, or an authentication descriptor beside its `Authentication.layer` verifier. Move the contracts, their identities, the descriptor and the binding to modules that import no server code.
 - A page that loads Effect from an import map still bundles a second copy of Effect, or of some of its modules: a module of the page imports an Effect specifier the map does not serve, such as `effect/Schema`. Serve `effect`, `effect/http` and `effect/http-api`, all `Action`, `ActionHttp` and `Authentication` import, and import Effect through them in the page's own modules too.
 - A page loading Effect from an import map fails before its modules run, with `Failed to resolve module specifier "effect/Cause"` in Chromium: the map points at Effect's published files and lacks a specifier Effect imports itself. Map `effect/Cause`, `effect/Effect`, `effect/Exit` and `effect/Function` to the same files, or serve Effect from a build that resolves its own imports.
-- Type errors inside `effect/*` modules after install: `effect` version drift. Install one `effect` 4.0.x release for every package.
-- An unmet peer warning for `effect@~4.0.0`, such as `found 4.1.0`: the installed Effect is a later minor than this release has been tested against. Install `effect` 4.0.x, with every `@effect/*` package on the same release, until a release of this package admits that minor.
+- Type errors inside `effect/*` modules after install: `effect` version drift. Install one `effect` release, in the peer range, for every package.
+- An unmet peer warning for `effect`, such as `found 4.1.0`: the installed Effect is outside the releases this one is tested against. Install the `effect` range [Install](#install) names, with every `@effect/*` package on the same release.
 - `Cannot find module 'effect/unstable/http'` (or `…/httpapi`, `…/cli`, `…/ai`): Effect `4.0.0-rc.118` moved these modules to `effect/http`, `effect/http-api`, `effect/cli` and `effect/ai`. Import the new paths.
-- `Cannot find module 'effect/http'` (or `effect/http-api`, `effect/cli`, `effect/ai`), or at run time `Cannot find module '…/node_modules/effect/dist/http-api.js'` (or `http.js`, `ai.js`, `cli.js`): `effect` is a release candidate older than `4.0.0-rc.118`, which moved these modules out of `effect/unstable/*`. Install `effect` 4.0.0 or later.
+- `Cannot find module 'effect/http'` (or `effect/http-api`, `effect/cli`, `effect/ai`), or at run time `Cannot find module '…/node_modules/effect/dist/http-api.js'` (or `http.js`, `ai.js`, `cli.js`): `effect` is a release candidate older than `4.0.0-rc.118`, which moved these modules out of `effect/unstable/*`. Install the `effect` range [Install](#install) names.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjermundgaraba/effect-actions",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Define Effect action contracts once and project them onto HTTP, MCP, native Toolkits, and CLIs.",
   "homepage": "https://github.com/gjermundgaraba/effect-actions#readme",
   "bugs": {
@@ -31,19 +31,19 @@
     "access": "public"
   },
   "devDependencies": {
-    "@effect/platform-node": "4.0.0",
-    "@effect/vitest": "4.0.0",
-    "@modelcontextprotocol/client": "2.0.0",
-    "@types/node": "26.6.2",
-    "effect": "4.0.0",
+    "@effect/platform-node": "4.0.2",
+    "@effect/vitest": "4.0.2",
+    "@modelcontextprotocol/client": "2.3.1",
+    "@types/node": "26.6.4",
+    "effect": "4.0.2",
     "tsx": "4.23.15",
     "typescript": "7.0.2",
-    "vite": "npm:@voidzero-dev/vite-plus-core@1.0.0",
-    "vite-plus": "1.0.0",
-    "vitest": "5.0.1"
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.1.0",
+    "vite-plus": "1.1.0",
+    "vitest": "5.0.3"
   },
   "peerDependencies": {
-    "effect": "~4.0.0"
+    "effect": "~4.0.2"
   },
   "devEngines": {
     "packageManager": {