@gjermundgaraba/effect-actions 0.4.1 → 0.6.0

package/dist/ActionMcp.d.mts

@@ -1,60 +1,34 @@
-import { Action_d_exports, Any, Codec } from "./Action.mjs";
+import { Action_d_exports, Codec } from "./Action.mjs";
 import { AnyImplementation, BuildContext, BuildError, RequestContext } from "./internal/implementation.mjs";
-import { Cause, Effect, Layer } from "effect";
+import { SurfaceOptions } from "./internal/tools.mjs";
+import { Cause, Layer } from "effect";
 import { HttpRouter } from "effect/unstable/http";
 import { McpSchema, McpServer } from "effect/unstable/ai";
 import { Stdio } from "effect/Stdio";
 //#region src/ActionMcp.d.ts
-/** What every MCP transport binds around the tools it serves. */
-interface SurfaceOptions<Errors extends ReadonlyArray<Codec>, R> {
-  /**
-   * Failures the surface answers with instead of a handler: authorization, rate
-   * limits. Declared on every tool of this transport, so a refusal is returned
-   * as an `isError` result exactly like an action's own error.
-   */
-  readonly errors?: Errors;
-  /**
-   * Runs once per tool call, after the native server has decoded the arguments
-   * and before the selected handler, with the action contract it is about to run.
-   * It fails with this transport's `errors`. Its services are request-time
-   * requirements, like a handler's.
-   */
-  readonly before?: (action: Any) => Effect.Effect<void, Errors[number]["Type"], R>;
-}
-/** One Streamable HTTP MCP endpoint; its fields become the native server info. */
-export interface Options<Errors extends ReadonlyArray<Codec> = [], R = never> extends SurfaceOptions<Errors, R> {
-  readonly name: string;
-  readonly version: string;
-  /** Native protocol adapters to serve; negotiation and sessions are owned by Effect. */
-  readonly protocols: Parameters<typeof McpServer.layerHttp>[0]["protocols"];
-  /** Route of the Streamable HTTP endpoint; no default. */
-  readonly path: HttpRouter.PathInput;
-  /** Browser origins accepted by the native server; passed through to `McpServer.layerHttp`. */
-  readonly allowedOrigins?: ReadonlyArray<string>;
-  readonly instructions?: string;
-}
-/** Server information for an MCP subprocess connected through standard I/O. */
-export interface StdioOptions<Errors extends ReadonlyArray<Codec> = [], R = never> extends SurfaceOptions<Errors, R> {
-  readonly name: string;
-  readonly version: string;
-  /** Native protocol adapters to serve; negotiation is owned by Effect. */
-  readonly protocols: Parameters<typeof McpServer.layerStdio>[0]["protocols"];
-  readonly instructions?: string;
-}
+/**
+ * One Streamable HTTP MCP endpoint: every native `McpServer.layerHttp` option except
+ * `protocols` (server information, `path`, `allowedOrigins`, `instructions`,
+ * `extensions`, ...), plus the surface's `errors` and `before`.
+ */
+export interface Options<Errors extends ReadonlyArray<Codec> = [], R = never> extends Omit<Parameters<typeof McpServer.layerHttp>[0], "protocols">, SurfaceOptions<Errors, R> {}
+/** An MCP subprocess on standard I/O: every native `McpServer.layerStdio` option except `protocols`. */
+export interface StdioOptions<Errors extends ReadonlyArray<Codec> = [], R = never> extends Omit<Parameters<typeof McpServer.layerStdio>[0], "protocols">, SurfaceOptions<Errors, R> {}
 /** The native server supplies its own request context to every tool call. */
-type ToolRequestContext<App, RB> = Exclude<RequestContext<App> | RB, McpSchema.McpRequestContext>;
+type ToolRequestContext<App, RB> = Exclude<RequestContext<App, "mcp"> | RB, McpSchema.McpRequestContext>;
 /**
- * Serve MCP tools over one Streamable HTTP endpoint.
+ * Serve MCP tools over one Streamable HTTP endpoint, speaking MCP 2026-07-28 only.
  *
  * Middleware provided around this layer has the normal HTTP lifetime. Native
  * context capture applies: never provide request-identity tags at startup.
  */
-export declare function layerHttp<const Apps extends ReadonlyArray<AnyImplementation>, const Errors extends ReadonlyArray<Codec> = [], RB = never>(options: Options<Errors, RB>, ...apps: Apps): Layer.Layer<never, BuildError<Apps[number]> | Cause.IllegalArgumentError, BuildContext<Apps[number]> | HttpRouter.HttpRouter | HttpRouter.Request.From<"Requires", ToolRequestContext<Apps[number], RB>>>;
+export declare function layerHttp<const Apps extends ReadonlyArray<AnyImplementation>, const Errors extends ReadonlyArray<Codec> = [], RB = never>(apps: readonly [...Apps], options: Options<Errors, RB>): Layer.Layer<never, BuildError<Apps[number], "mcp"> | Cause.IllegalArgumentError, BuildContext<Apps[number], "mcp"> | HttpRouter.HttpRouter | HttpRouter.Request.From<"Requires", ToolRequestContext<Apps[number], RB>>>;
 /**
- * Serve MCP tools through newline-delimited JSON-RPC on standard I/O.
+ * Serve MCP tools through newline-delimited JSON-RPC on standard I/O, speaking MCP
+ * 2026-07-28 only.
  *
  * The host supplies the `Stdio` service. Arguments are tool input only and
  * never establish request identity or authority.
  */
-export declare function layerStdio<const Apps extends ReadonlyArray<AnyImplementation>, const Errors extends ReadonlyArray<Codec> = [], RB = never>(options: StdioOptions<Errors, RB>, ...apps: Apps): Layer.Layer<never, BuildError<Apps[number]> | Cause.IllegalArgumentError, BuildContext<Apps[number]> | Stdio | ToolRequestContext<Apps[number], RB>>;
+export declare function layerStdio<const Apps extends ReadonlyArray<AnyImplementation>, const Errors extends ReadonlyArray<Codec> = [], RB = never>(apps: readonly [...Apps], options: StdioOptions<Errors, RB>): Layer.Layer<never, BuildError<Apps[number], "mcp"> | Cause.IllegalArgumentError, BuildContext<Apps[number], "mcp"> | Stdio | ToolRequestContext<Apps[number], RB>>;
 //#endregion

package/dist/ActionMcp.mjs

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

package/dist/ActionToolkit.d.mts

@@ -1,23 +1,11 @@
 import { Action_d_exports, Any, Codec } from "./Action.mjs";
 import { AnyImplementation, BuildContext, BuildError, HandlerContext, Implementation } from "./internal/implementation.mjs";
-import { Effect, Layer, Schema } from "effect";
+import { SurfaceOptions } from "./internal/tools.mjs";
+import { Layer, Schema } from "effect";
 import { Tool, Toolkit } from "effect/unstable/ai";
 //#region src/ActionToolkit.d.ts
-/** What `make` binds around the implementations it projects. */
-export interface Options<Errors extends ReadonlyArray<Codec> = [], R = never> {
-  /**
-   * Failures the caller answers with instead of a handler: authorization, rate
-   * limits. Declared on every tool, so a refusal is returned as a tool failure
-   * exactly like an action's own error.
-   */
-  readonly errors?: Errors;
-  /**
-   * Runs once per tool call, before the selected handler, with the action contract
-   * it is about to run. It fails with this binding's `errors`. Its services join
-   * each tool's request requirements, like a handler's.
-   */
-  readonly before?: (action: Any) => Effect.Effect<void, Errors[number]["Type"], R>;
-}
+/** What the in-process caller binds around the implementations it projects. */
+export type Options<Errors extends ReadonlyArray<Codec> = [], R = never> = SurfaceOptions<Errors, R>;
 /** A native tool corresponding to an MCP-enabled action. */
 type NativeTool<A extends Any, E extends Codec, R> = A extends {
   readonly mcp: {
@@ -49,5 +37,5 @@ export interface Binding<Tools extends Record<string, Tool.Any>, E = never, R =
  * Build services are needed to construct `layer`; request services are needed
  * when the resulting toolkit handles a call.
  */
-export declare function make<const Apps extends ReadonlyArray<AnyImplementation>, const Errors extends ReadonlyArray<Codec> = [], RB = never>(options: Options<Errors, RB>, ...apps: Apps): Binding<ToolkitTools<Apps, Errors[number], RB>, BuildError<Apps[number]>, BuildContext<Apps[number]>>;
+export declare function make<const Apps extends ReadonlyArray<AnyImplementation>, const Errors extends ReadonlyArray<Codec> = [], RB = never>(apps: readonly [...Apps], options?: Options<Errors, RB>): Binding<ToolkitTools<Apps, Errors[number], RB>, BuildError<Apps[number], "mcp">, BuildContext<Apps[number], "mcp">>;
 //#endregion

package/dist/ActionToolkit.mjs

@@ -3,13 +3,8 @@ import { bindTools } from "./internal/tools.mjs";
 import "effect";
 import "effect/unstable/ai";
 //#region src/ActionToolkit.ts
-function make(options, ...apps) {
-	const before = options.before;
-	const toolOptions = {
-		errors: options.errors,
-		before
-	};
-	return bindTools(apps, "native", toolOptions);
+function make(apps, options = {}) {
+	return bindTools(apps, "native", options);
 }
 //#endregion
 export { make };

package/dist/Testing.d.mts

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

package/dist/Testing.mjs

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

package/dist/TestingClient.d.mts

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

package/dist/TestingClient.mjs

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

package/dist/internal/actions.d.mts

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

package/dist/internal/actions.mjs

@@ -1,15 +1,34 @@
 //#region src/internal/actions.ts
+/** Each distinct error a policy may answer with, invalid first. */
+const policyErrors = (policy) => [.../* @__PURE__ */ new Set([policy.invalid.schema, policy.internal.schema])];
+/**
+* `HttpApiBuilder` reports these kinds while encoding the handler's answer, after the
+* handler ran; every other kind (`Payload`, `Params`, `Headers`, `Query`) comes from
+* decoding the request before it.
+*/
+const responseKinds = /* @__PURE__ */ new Set(["Body", "ResponseHeaders"]);
+/** The policy's answer to one native failure: `internal` for the response side, else `invalid`. */
+const answerSchemaError = (policy, failure) => responseKinds.has(failure.kind) ? policy.internal.make(failure) : policy.invalid.make(failure);
 /**
 * An action's own failures plus the ones its surface answers with, which is what
 * a projection of that action declares. A schema the action already declares is
 * not repeated.
 */
-const projectedErrors = (action, surface) => [...action.errors, ...(surface ?? []).filter((error) => !action.errors.includes(error))];
+const projectedErrors = (action, surface) => [.../* @__PURE__ */ new Set([...action.errors, ...surface ?? []])];
 const validName = /^[A-Za-z0-9_-]+$/;
 /** Names become path segments, OpenAPI identifiers and client method keys. */
 const assertName = (what, name) => {
 	if (!validName.test(name) || name === "then") throw new Error(`Invalid ${what}: ${name}`);
 };
+/**
+* The one item of `items` named `name`, narrowed to that contract. A caller passes
+* a literal name, so a miss is a programming error reported as `Unknown <what>`.
+*/
+const selectNamed = (items, name, what) => {
+	const item = items.find((candidate) => candidate.name === name);
+	if (item === void 0) throw new Error(`Unknown ${what}`);
+	return item;
+};
 /** Each namespace is checked by whoever owns it: a group, the routes, or the MCP tools. */
 const assertDistinct = (what, names) => {
 	const seen = /* @__PURE__ */ new Set();
@@ -19,4 +38,4 @@ const assertDistinct = (what, names) => {
 	}
 };
 //#endregion
-export { assertDistinct, assertName, projectedErrors };
+export { answerSchemaError, assertDistinct, assertName, policyErrors, projectedErrors, selectNamed };

package/dist/internal/cli.d.mts

@@ -6,7 +6,7 @@ import { Command } from "effect/unstable/cli";
 interface CommonOptions<Output> {
   /** Override the command name. The action name is used by default. */
   readonly name?: string;
-  /** Human output. JSON remains available with `--json`. */
+  /** Human output. Adds a `--json` flag to the command that selects JSON instead. */
   readonly render?: (output: Output) => string;
 }
 /** The default projection accepts a whole canonical JSON input with `--input`. */
@@ -19,7 +19,7 @@ export interface ParametersOptions<Output, Parameters extends Command.Command.Co
   /** Native Effect CLI flags and arguments. */
   readonly parameters: Parameters;
   /** Maps native parsed parameters to the action's canonical JSON input. */
-  readonly input: (parsed: Command.Command.Config.Infer<Parameters>) => Schema.Json;
+  readonly input: (parsed: Command.Command.Config.InferValue<Parameters>) => Schema.Json;
 }
 /**
  * A command either accepts whole JSON input or has explicit native CLI parameters.

package/dist/internal/cli.mjs

@@ -2,31 +2,45 @@ import { Console, Effect, Option, Schema } from "effect";
 import { Command, Flag } from "effect/unstable/cli";
 //#region src/internal/cli.ts
 const isParametersOptions = (options) => options?.parameters !== void 0;
-const jsonOutput = Flag.Boolean("json").pipe(Flag.optional, Flag.withDescription("Print machine-readable JSON"));
-const output = (action, execute, input, render, useJson) => Effect.gen(function* () {
+/**
+* A command with a renderer takes `--json` as a flag of its own, so nothing is
+* claimed tree-wide and a host's `--json`, global or not, is never contested.
+* Without a renderer the output is JSON already and there is no flag.
+*/
+const jsonFlag = Flag.Boolean("json").pipe(Flag.withDefault(false), Flag.withDescription("Print machine-readable JSON"));
+const output = (action, execute, input, render) => Effect.gen(function* () {
 	const value = yield* execute(input);
 	const encoded = yield* Schema.encodeEffect(Schema.toCodecJson(action.success))(value);
-	const text = render !== void 0 && !useJson ? render(value) : JSON.stringify(encoded, null, 2);
-	yield* Console.log(text);
+	yield* Console.log(render === void 0 ? JSON.stringify(encoded, null, 2) : render(value));
 });
-const defaultCommand = (action, execute, options) => {
-	const input = Flag.String("input").pipe(Flag.withDefault("{}"), Flag.withSchema(Schema.fromJsonString(Schema.toCodecJson(action.input))), Flag.withDescription("Whole canonical action input as JSON"));
-	const config = options?.render === void 0 ? { input } : {
-		input,
-		output: { json: jsonOutput }
-	};
-	return Command.make(options?.name ?? action.name, config, (parsed) => Effect.gen(function* () {
-		const useJson = "output" in parsed && Option.isSome(parsed.output.json) && parsed.output.json.value === true;
-		return yield* output(action, execute, parsed.input, options?.render, useJson);
-	})).pipe(Command.withDescription(action.description));
+/**
+* One native command. The action's own parameters are one nested config, so the
+* flag added for a renderer never meets them in one record.
+*/
+const make = (action, execute, options, config, decode) => {
+	const name = options?.name ?? action.name;
+	const render = options?.render;
+	return (render === void 0 ? Command.make(name, { parameters: config }, ({ parameters }) => Effect.flatMap(decode(parameters), (input) => output(action, execute, input, void 0))) : Command.make(name, {
+		parameters: config,
+		json: jsonFlag
+	}, ({ parameters, json }) => Effect.flatMap(decode(parameters), (input) => output(action, execute, input, json ? void 0 : render)))).pipe(Command.withDescription(action.description));
 };
-const parametersCommand = (action, execute, options) => {
-	if (options.render === void 0) return Command.make(options.name ?? action.name, options.parameters, (parsed) => Effect.flatMap(Schema.decodeUnknownEffect(Schema.toCodecJson(action.input))(options.input(parsed)), (input) => output(action, execute, input, void 0, true))).pipe(Command.withDescription(action.description));
-	return Command.make(options.name ?? action.name, {
-		parameters: options.parameters,
-		output: { json: jsonOutput }
-	}, (parsed) => Effect.flatMap(Schema.decodeUnknownEffect(Schema.toCodecJson(action.input))(options.input(parsed.parameters)), (input) => output(action, execute, input, options.render, Option.isSome(parsed.output.json) && parsed.output.json.value === true))).pipe(Command.withDescription(action.description));
+/**
+* The whole encoded input, inline or from a file. The native parser decodes both,
+* so an invalid value is rendered with the command's help wherever it came from.
+*/
+const inputFlags = (codec) => ({
+	input: Flag.String("input").pipe(Flag.withSchema(Schema.fromJsonString(codec)), Flag.optional, Flag.withDescription("Whole canonical action input as JSON")),
+	inputFile: Flag.FileSchema("input-file", codec, { format: "json" }).pipe(Flag.optional, Flag.withDescription("File containing the whole canonical action input as JSON"))
+});
+const defaultCommand = (action, execute, options) => {
+	const codec = Schema.toCodecJson(action.input);
+	return make(action, execute, options, inputFlags(codec), (parsed) => Option.match(Option.orElse(parsed.inputFile, () => parsed.input), {
+		onNone: () => Schema.decodeUnknownEffect(codec)({}),
+		onSome: Effect.succeed
+	}));
 };
+const parametersCommand = (action, execute, options) => make(action, execute, options, options.parameters, (parsed) => Schema.decodeUnknownEffect(Schema.toCodecJson(action.input))(options.input(parsed)));
 /** Build one native command around an action-bound operation. */
 const command = (action, execute, options) => {
 	if (isParametersOptions(options)) return parametersCommand(action, execute, options);

package/dist/internal/implementation.d.mts

@@ -30,10 +30,21 @@ export declare class Implementation<G extends Actions, H, EX, RX> {
 }
 /** Any nominal implementation of `G`, with its record and channels erased. */
 export type AnyImplementation<G extends Actions = Actions> = Implementation<G, any, any, any>;
-/** Per-request requirements of one implementation, or of a union of them. */
-export type RequestContext<App> = App extends Implementation<any, infer H, any, any> ? HandlersContext<H> : never;
-/** Handler-acquisition failures of one implementation, or of a union of them. */
-export type BuildError<App> = App extends Implementation<any, any, infer EX, any> ? EX : never;
-/** Handler-acquisition requirements of one implementation, or of a union of them. */
-export type BuildContext<App> = App extends Implementation<any, any, any, infer RX> ? RX : never;
+/** The transports that serve a subset of a group's actions, by the contract flag that hides an action. */
+export type Transport = "http" | "mcp";
+/**
+ * Names of the actions of `G` that `T` may serve. Only an action hidden by a
+ * literal `false` is excluded; a flag decided at runtime keeps its requirements.
+ */
+export type ServedNames<G extends Actions, T extends Transport> = Exclude<G["actions"][number], T extends "http" ? {
+  readonly http: false;
+} : {
+  readonly mcp: false;
+}>["name"];
+/** Per-request requirements of the handlers `T` can invoke, or of a union of implementations. */
+export type RequestContext<App, T extends Transport> = App extends Implementation<infer G, infer H, any, any> ? { readonly [K in Extract<ServedNames<G, T>, keyof H>]: HandlerContext<H, K>; }[Extract<ServedNames<G, T>, keyof H>] : never;
+/** Handler-acquisition failures of the implementations `T` acquires, or of a union of them. */
+export type BuildError<App, T extends Transport> = App extends Implementation<infer G, any, infer EX, any> ? [ServedNames<G, T>] extends [never] ? never : EX : never;
+/** Handler-acquisition requirements of the implementations `T` acquires, or of a union of them. */
+export type BuildContext<App, T extends Transport> = App extends Implementation<infer G, any, any, infer RX> ? [ServedNames<G, T>] extends [never] ? never : RX : never;
 //#endregion

package/dist/internal/implementation.mjs

@@ -22,8 +22,9 @@ var Implementation = class Implementation {
 	}
 };
 /**
-* Select and invoke a handler after an adapter has selected a concrete action.
-* The surface's pre-handler hook runs first, outside the action's span, so a
+* Select the handler of a concrete action, once, when an adapter binds its acquired
+* record; `implement` has already refused a record without it. The returned function
+* invokes it: the surface's pre-handler hook runs first, outside the action's span, so a
 * refusal is attributed to the surface rather than to a handler that never ran.
 * `R` remains in the returned effect so transport layers cannot erase required
 * per-request services while assembling routes.
@@ -31,8 +32,16 @@ var Implementation = class Implementation {
 const dispatch = (group, action, handlers, before) => {
 	const handle = handlers[action.name];
 	if (handle === void 0) throw new Error(`Missing handler: ${action.name}`);
+	const attributes = {
+		"action.group": group.name,
+		"action.name": action.name,
+		"action.access": action.access
+	};
 	return (input) => {
-		const handled = Effect.withSpan(Effect.suspend(() => handle(input)), `${group.name}.${action.name}`, { captureStackTrace: false });
+		const handled = Effect.withSpan(Effect.annotateLogs(Effect.suspend(() => handle(input)), attributes), `${group.name}.${action.name}`, {
+			captureStackTrace: false,
+			attributes
+		});
 		return before === void 0 ? handled : Effect.flatMap(before(action), () => handled);
 	};
 };

package/dist/internal/tools.d.mts

@@ -0,0 +1,22 @@
+import { Action_d_exports, Any, Codec } from "../Action.mjs";
+import "./implementation.mjs";
+import { Effect, Layer } from "effect";
+import { Tool, Toolkit } from "effect/unstable/ai";
+//#region src/internal/tools.d.ts
+/** What a tool surface binds around the implementations it projects. */
+export interface SurfaceOptions<Errors extends ReadonlyArray<Codec>, R> {
+  /**
+   * Failures the surface answers with instead of a handler: authorization, rate
+   * limits. Declared on every tool, so a refusal is returned exactly like an
+   * action's own error.
+   */
+  readonly errors?: Errors;
+  /**
+   * Runs once per tool call, after the arguments are decoded and before the
+   * selected handler, with the action contract it is about to run. It fails with
+   * this surface's `errors`. Its services are request-time requirements, like a
+   * handler's.
+   */
+  readonly before?: (action: Any) => Effect.Effect<void, Errors[number]["Type"], R>;
+}
+//#endregion