@gjermundgaraba/effect-actions 0.9.0 → 0.11.0

package/dist/Testing.mjs

@@ -1,91 +1,133 @@
-import { fetchApiClient } from "./internal/fetchClient.mjs";
-import { Option, Predicate, Schema } from "effect";
+import { Refusal } from "./internal/errors.mjs";
+import { assertOnce, projectedErrors } from "./internal/actions.mjs";
+import { inputOf } from "./internal/call.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 { Base64, Sse } from "effect/encoding";
 //#region src/Testing.ts
+function layer(routes) {
+	if (!Layer.isLayer(routes)) return clientOf(routes);
+	return Layer.unwrap(Effect.gen(function* () {
+		const fileSystem = Option.getOrElse(yield* Effect.serviceOption(FileSystem.FileSystem), () => FileSystem.makeNoop({}));
+		const platform = yield* Layer.build(Layer.fresh(Layer.mergeAll(HttpPlatform.layer, Path.layer, Etag.layerWeak).pipe(Layer.provideMerge(Layer.succeed(FileSystem.FileSystem, fileSystem)))));
+		const context = Context.merge(platform, yield* Effect.context());
+		const app = yield* HttpRouter.toHttpEffect(routes).pipe(Effect.provideContext(context));
+		return clientOf(HttpEffect.toWebHandlerWith(context)(app));
+	}));
+}
 /**
-* The native grouped HTTP client, calling `handler` in memory instead of the network.
-* `baseUrl` defaults to `http://localhost`.
+* An answer a client method cannot decode as the action's success or a declared error,
+* such as the native server's message for invalid arguments or an unknown tool. Its message
+* holds the answer.
 */
-const httpClient = (api, handler, options) => fetchApiClient(api, (input, init) => handler(new Request(input, init)), {
-	baseUrl: "http://localhost",
-	...options
-});
-/** Build one stateless 2026-07-28 JSON-RPC request, with client metadata defaulted. */
-const mcpRequest = ({ url, method, params = {}, headers: init }) => {
-	const headers = new Headers(init);
-	headers.set("content-type", "application/json");
-	headers.set("accept", "application/json, text/event-stream");
-	headers.set("mcp-protocol-version", "2026-07-28");
-	headers.set("mcp-method", method);
-	if (Predicate.isString(params.name)) headers.set("mcp-name", params.name);
-	return new Request(url, {
-		method: "POST",
-		headers,
-		body: JSON.stringify({
-			jsonrpc: "2.0",
-			id: 1,
-			method,
-			params: {
-				...params,
-				_meta: Object.assign({
-					"io.modelcontextprotocol/clientCapabilities": {},
-					"io.modelcontextprotocol/clientInfo": {
-						name: "test",
-						version: "0"
-					}
-				}, params._meta, { "io.modelcontextprotocol/protocolVersion": "2026-07-28" })
-			}
-		})
-	});
-};
-/** 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.Json),
-	content: Schema.Array(Schema.Struct({
-		type: Schema.String,
-		text: Schema.optionalKey(Schema.String)
-	}))
-}) }), Schema.Struct({ error: Schema.Struct({
+var McpCallError = class extends Schema.TaggedError()("McpCallError", { message: Schema.String }) {};
+/** The text of a block, none of a block of another kind. */
+const textOf = (block) => block?.type === "text" ? block.text : void 0;
+/** The JSON-RPC response to a `tools/call`: the native tool result, or a protocol error. */
+const ToolReply = Schema.Union([Schema.Struct({ result: McpSchema.CallToolResult }), 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.
+* The reply in a response: its body when it is one JSON message, or the last reply among an
+* event stream's events, which notifications may precede.
+*/
+const replyOf = (response, text) => {
+	if (!(response.headers["content-type"] ?? "").startsWith("text/event-stream")) return decodeReply(text);
+	const data = [];
+	Sse.makeParser((event) => {
+		if (Predicate.isTagged(event, "Event")) data.push(event.data);
+	}).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 mcpCall = async (handler, { url, name, headers, arguments: args = {} }) => {
-	const response = await handler(mcpRequest({
-		url,
-		method: "tools/call",
-		params: {
+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`, 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* () {
+		const encoded = yield* Schema.encodeEffect(Schema.toCodecJson(action.input))(input);
+		const response = yield* client.execute(mcpRequest("tools/call", {
 			name,
-			arguments: args
-		},
-		...headers === void 0 ? {} : { headers }
-	}));
-	const body = await response.text();
-	if (response.status !== 200) throw new Error(`MCP tools/call "${name}" answered ${response.status}: ${body}`);
-	const reply = body.split("\n").map((line) => line.replace(/^data:/, "").trim()).flatMap((line) => Option.toArray(decodeReply(line))).at(-1);
-	if (reply === void 0) throw new Error(`MCP tools/call "${name}" had no reply: ${body}`);
-	if ("error" in reply) throw new Error(`MCP tools/call "${name}" failed with ${reply.error.code}: ${reply.error.message}`);
-	const { result } = reply;
-	if (result.isError === true) {
-		const text = result.content.find((content) => content.type === "text")?.text ?? "";
-		return {
-			isError: true,
-			error: Option.getOrElse(parseJson(text), () => text)
-		};
-	}
-	if (result.structuredContent === void 0) throw new Error(`MCP tools/call "${name}" returned no structured content: ${body}`);
-	const [text] = result.content.length > 1 ? result.content : [];
-	return {
-		isError: false,
-		value: result.structuredContent,
-		...text?.text === void 0 ? {} : { text: text.text }
-	};
+			arguments: encoded
+		}, { url }));
+		const text = yield* response.text;
+		if (response.status !== 200) return yield* failWith(Refusal.members, text, other(`answered ${response.status}: ${text}`));
+		const reply = replyOf(response, text);
+		if (Option.isNone(reply)) return yield* Effect.fail(other(`had no reply: ${text}`));
+		if ("error" in reply.value) {
+			const { code, message } = reply.value.error;
+			return yield* Effect.fail(other(`failed with ${code}: ${message}`));
+		}
+		const { result } = reply.value;
+		if (result.isError === true) {
+			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 && 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 } = {}) {
+	assertOnce("action", actions);
+	return Effect.map(HttpClient.HttpClient, (native) => {
+		const client = transformClient(native);
+		return Object.fromEntries(actions.map((action) => {
+			const lift = liftOf(action.success);
+			return [action.name, (...args) => Effect.flatMap(inputOf(action, args), (input) => callTool(client, url, action, lift, input))];
+		}));
+	});
+}
+/**
+* One stateless MCP request of `method` with `params`, as `ActionMcp.layerHttp` serves it,
+* as the native request value: the JSON-RPC envelope, the 2026-07-28 headers, `mcp-name` from
+* `params.uri` for `resources/read` and `params.name` otherwise, and the client metadata in
+* `_meta` are filled in, under any `_meta` given, such as a `progressToken`; the protocol
+* version is always the request's own. The test sends it: `HttpClient.execute` answers the
+* response as the endpoint sent it, whatever its status, and `HttpClientRequest.toWebResult`
+* gives the web `Request` a web handler or `fetch` takes, once `url` is absolute. It is for a test
+* asserting on what `mcpClient` decodes away, such as `tools/list`, a refusal's challenge, or
+* a call its types would not send.
+*/
+const mcpRequest = (method, params = {}, { headers = {}, url = defaultPath } = {}) => {
+	const { headers: routing, body } = statelessRequest(method, params);
+	return HttpClientRequest.post(url).pipe(HttpClientRequest.setHeaders(headers), HttpClientRequest.setHeaders(routing), HttpClientRequest.bodyJsonUnsafe(body));
 };
 //#endregion
-export { httpClient, mcpCall, mcpRequest };
+export { McpCallError, layer, mcpClient, mcpRequest };

package/dist/internal/actions.d.mts

@@ -1,29 +1,9 @@
-import { Action_d_exports, Any, Codec } from "../Action.mjs";
-import { HttpApiError } from "effect/http-api";
+import "../Action.mjs";
+import { SchemaAST } from "effect";
 //#region src/internal/actions.d.ts
-/** One side of a schema-error policy: the error it answers with, and how to make it. */
-export interface SchemaErrorAnswer<E extends Codec> {
-  /** 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.
+ * The caller of a public action: anyone, signed in or not. Registered globally, so two copies
+ * of the package agree on it, as they agree on a name.
  */
-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>, 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<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"]>[keyof SchemaErrorPolicy]["schema"];
+export declare const Anyone: unique symbol;
 //#endregion

package/dist/internal/actions.mjs

@@ -1,41 +1,89 @@
+import { builtIns, statuses } from "./errors.mjs";
+import { Predicate, Schema, SchemaAST } from "effect";
 //#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.
+* The list an `error` option stands for: one schema, a list as given, or none, as
+* `HttpApiEndpoint` takes 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);
+const errorList = (error) => error === void 0 ? [] : Schema.isSchema(error) ? [error] : error;
 /**
-* 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.
+* What a projection of an action declares: the built-in errors, the action's own, and any
+* its surface adds, such as a binding's. The built-ins come first, since a failure encodes
+* and decodes with the first schema that accepts it, and they are classes, which accept
+* only their own instances: a loose schema of the action's never captures one. A schema
+* listed twice is not repeated.
 */
-const projectedErrors = (action, surface) => [.../* @__PURE__ */ new Set([...action.errors, ...surface ?? []])];
-const validName = /^[A-Za-z0-9_-]+$/;
+const projectedErrors = (action, surface = []) => [.../* @__PURE__ */ new Set([
+	...builtIns,
+	...action.error,
+	...surface
+])];
+/**
+* The caller of a public action: anyone, signed in or not. Registered globally, so two copies
+* of the package agree on it, as they agree on a name.
+*/
+const Anyone = Symbol.for("@gjermundgaraba/effect-actions/Anyone");
+const validName = /^[A-Za-z0-9_-]{1,128}$/;
 /** 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>`.
+* Names are checked by whoever owns them: an implementation, a binding, a CLI, or the MCP
+* tools. `claimantOf` says who claims a name, so a clash between two claimants names both.
 */
-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();
-	for (const name of names) {
-		if (seen.has(name)) throw new Error(`Duplicate ${what}: ${name}`);
-		seen.add(name);
+const assertDistinct = (what, items, nameOf, claimantOf = nameOf) => {
+	const seen = /* @__PURE__ */ new Map();
+	for (const item of items) {
+		const name = nameOf(item);
+		const claimant = claimantOf(item);
+		const other = seen.get(name);
+		if (other !== void 0) {
+			const by = other === claimant ? "" : `, claimed by ${other} and ${claimant}`;
+			throw new Error(`Duplicate ${what}: ${name}${by}`);
+		}
+		seen.set(name, claimant);
 	}
 };
+/** Refuse an action name `actions` hold twice. */
+const assertOnce = (what, actions) => assertDistinct(what, actions, (action) => action.name);
+/**
+* Refuse a key of options keyed by action name, such as handlers, tools or commands, that no
+* action of `names` has, so a stale option cannot outlive its action.
+*/
+const assertKnown = (what, keys, names) => {
+	const unknown = keys.filter((key) => !names.includes(key));
+	if (unknown.length > 0) throw new Error(`Unknown ${what}: ${unknown.join(", ")}`);
+};
+/** `ast` with any suspension at its top resolved, as a recursive schema's is. */
+const unsuspended = (ast) => SchemaAST.isSuspend(ast) ? unsuspended(ast.thunk()) : ast;
+/** The members of a union, nested and suspended ones included, or the one type otherwise. */
+const members = (ast) => {
+	const resolved = unsuspended(ast);
+	return SchemaAST.isUnion(resolved) ? resolved.types.flatMap(members) : [resolved];
+};
+/**
+* The values a literal or an enum accepts, or `undefined` for any other type, which has no
+* fixed set.
+*/
+const literalValues = (ast) => SchemaAST.isLiteral(ast) ? [ast.literal] : SchemaAST.isEnum(ast) ? ast.enums.map(([, value]) => value) : [void 0];
+/**
+* The `_tag`s a schema's encoding carries: each member's of a union, every value of a union of
+* literals or of an enum, and a suspended schema's, as a recursive error is written.
+*/
+const tagsOf = (ast) => members(SchemaAST.toEncoded(ast)).flatMap((member) => {
+	const tag = SchemaAST.isObjects(member) ? member.propertySignatures.find((property) => property.name === "_tag")?.type : void 0;
+	return tag === void 0 ? [] : members(tag).flatMap(literalValues).filter(Predicate.isString);
+});
+/**
+* Refuse an error that encodes with a built-in error's `_tag`, the built-in itself included:
+* every endpoint and tool declares the built-in errors already, a client decoding the answer
+* could not tell a look-alike from them, and a look-alike of a refusal would step up. Checked
+* where the action or the binding is made, so every surface and client of it may rely on it.
+*/
+const assertOwnTags = (what, errors) => {
+	const tag = errors.flatMap((error) => tagsOf(error.ast)).find((tag) => Object.hasOwn(statuses, tag));
+	if (tag !== void 0) throw new Error(`${what}: error _tag "${tag}" is built in, and declared on every surface`);
+};
 //#endregion
-export { answerSchemaError, assertDistinct, assertName, policyErrors, projectedErrors, selectNamed };
+export { Anyone, assertDistinct, assertKnown, assertName, assertOnce, assertOwnTags, errorList, literalValues, members, projectedErrors, unsuspended };

package/dist/internal/authentication.d.mts

@@ -0,0 +1,102 @@
+import { Anyone } from "./actions.mjs";
+import { Refusal } from "./errors.mjs";
+import { Protected, ServedRequest, Serving } from "./implementation.mjs";
+import { Action_d_exports, Any as Any$1, Errors } from "../Action.mjs";
+import { Context, Effect } from "effect";
+import { HttpRouter, HttpServerResponse } from "effect/http";
+import { HttpApiMiddleware, HttpApiSecurity } from "effect/http-api";
+//#region src/internal/authentication.d.ts
+/** One native security scheme: Bearer unless a descriptor names another. */
+export type Security = HttpApiSecurity.HttpApiSecurity;
+/** What a native scheme decodes: a `Redacted` token or key, or Basic credentials. */
+export type Credential = HttpApiSecurity.HttpApiSecurity.Type<Security>;
+/** The provider of a descriptor's verifier: a type of its own, apart from the actor. */
+export interface Provider<I, Name extends string = string> {
+  readonly "~effect-actions/Authentication": I;
+  readonly "~effect-actions/Authentication/Name": Name;
+}
+/**
+ * The native security middleware a descriptor's protected endpoints carry, which provides
+ * the identity: an identifier of its own, which no `Authentication.layer` provides, so only
+ * `ActionHttp.layer` satisfies it, from the provider.
+ */
+export interface SecurityMiddleware<I, Name extends string = string> {
+  readonly "~effect-actions/Authentication/Security": Name;
+  readonly "~effect/http-api/HttpApiMiddleware": {
+    readonly provides: I;
+    readonly requires: never;
+    readonly error: never;
+    readonly clientError: never;
+    readonly requiredForClient: false;
+  };
+}
+type Response = Effect.Effect<HttpServerResponse.HttpServerResponse, unknown, unknown>;
+interface Runtime$1 {
+  /** The descriptor the provider was built from, the one a binding naming it must hold. */
+  readonly descriptor: unknown;
+  /** The native security middleware's implementation, keyed by its scheme. */
+  readonly middleware: Readonly<Record<string, (route: Response, options: {
+    readonly credential: Credential;
+  }) => Response>>;
+  /**
+   * A protected HTTP route as it leaves the layer's middleware, a step-up refusal it fails with
+   * answered with its challenge under Bearer; as it is under another scheme.
+   */
+  readonly stepUp: HttpApiMiddleware.HttpApiMiddleware<never, never, never>;
+  readonly http: <E, R>(route: Effect.Effect<HttpServerResponse.HttpServerResponse, E, R>, optional: boolean) => Effect.Effect<HttpServerResponse.HttpServerResponse, E, R | HttpRouter.Provided>;
+  /**
+   * A route of the host's own: the request is decoded here, the route gets the identity
+   * itself, and a refusal it fails with is answered as an action route's.
+   */
+  readonly route: <E, R>(route: Effect.Effect<HttpServerResponse.HttpServerResponse, E, R>) => Effect.Effect<HttpServerResponse.HttpServerResponse, Exclude<E, Refusal>, HttpRouter.Provided>;
+}
+/**
+ * What `Authentication.make` declares: its name, the identity it authenticates, its scheme,
+ * and what its verifier may fail with besides a refusal. The `~` keys are the library's own
+ * wiring, which no host composes.
+ */
+export interface Descriptor<I, A, S extends Security, Name extends string = string, E extends Errors = readonly []> {
+  readonly name: Name;
+  readonly identity: Context.Key<I, A>;
+  readonly security: S;
+  /**
+   * What its verifier may fail with besides a refusal, as a list: every protected endpoint
+   * declares it, and every remote surface sends it with its status.
+   */
+  readonly error: E;
+  readonly "~provider": Context.Key<Provider<I, Name>, Runtime$1>;
+  readonly "~middleware": Context.Key<SecurityMiddleware<I, Name>, unknown>;
+  /** An MCP request's verified identity, which a protected tool's call promotes. */
+  readonly "~verified": Context.Key<never, unknown>;
+}
+export type Any = Descriptor<unknown, unknown, Security, string, Errors>;
+export type Identity<A extends Any$1> = [A] extends [never] ? never : A["caller"] extends Context.Key<infer I, unknown> ? I : never;
+/**
+ * The identity a descriptor for `A` must authenticate: `unknown` for an erased action, whose
+ * key is known only at run time, where `assertAuthentication` checks it.
+ */
+type Covered<A extends Any$1> = Exclude<A["caller"], typeof Anyone> extends Context.Key<infer I, unknown> ? I : never;
+export type Required<A extends Any$1> = [Protected<A>] extends [never] ? {
+  readonly authentication?: Any;
+} : {
+  readonly authentication: Descriptor<Covered<Protected<A>>, unknown, Security, string, Errors>;
+};
+export type ProviderOf<D> = D extends Descriptor<infer I, unknown, Security, infer Name, Errors> ? Provider<I, Name> : never;
+/** All protected actions on a surface use the descriptor's single identity key. */
+export type Matching<A extends Any$1, D> = unknown extends Covered<Protected<A>> ? unknown : [Exclude<Covered<Protected<A>>, D extends Descriptor<infer I, unknown, Security, string, Errors> ? I : never>] extends [never] ? unknown : {
+  readonly "Authentication descriptor does not cover every protected action": never;
+};
+/** Keep public requirements separate, without rescanning all handlers for every action. */
+export type RemoteRequest<App, A extends Any$1> = ServedRequest<App, Extract<A, {
+  readonly caller: typeof Anyone;
+}>> | Exclude<ServedRequest<App, Protected<A>>, Identity<Protected<A>>>;
+/**
+ * What a call of `A` under the descriptor `D` may fail with from its verifier: the errors `D`
+ * declares, for a protected action; none for a public one, which nothing verifies.
+ */
+export type VerifierError<A extends Any$1, D> = A["caller"] extends typeof Anyone ? never : D extends {
+  readonly error: infer E extends Errors;
+} ? E[number] : never;
+export type ServedProvider<App, A extends Any$1, D> = [Protected<Serving<App, A>>] extends [never] ? never : ProviderOf<D>;
+//#endregion
+export { Runtime$1 as Runtime };

package/dist/internal/authentication.mjs

@@ -0,0 +1,11 @@
+import { Unauthenticated } from "./errors.mjs";
+import { Anyone } from "./actions.mjs";
+import { Effect, Option } from "effect";
+//#region src/internal/authentication.ts
+const assertAuthentication = (actions, auth) => {
+	for (const action of actions) if (action.caller !== Anyone && (auth === void 0 || action.caller.key !== auth.identity.key)) throw new Error(`Protected action '${action.name}' requires its matching authentication descriptor`);
+};
+/** Remote promotion happens at tool entry, before shared dispatch, never in local calls. */
+const promote = (auth, run) => Effect.flatMap(Effect.serviceOption(auth["~verified"]), (actor) => Option.isSome(actor) ? Effect.provideService(run, auth.identity, actor.value) : Effect.fail(new Unauthenticated()));
+//#endregion
+export { assertAuthentication, promote };

package/dist/internal/call.d.mts

@@ -0,0 +1,12 @@
+import "./implementation.mjs";
+import { Action_d_exports, Any } from "../Action.mjs";
+import { Effect, Schema } from "effect";
+//#region src/internal/call.d.ts
+/**
+ * A call of `A` answering `R`. It may leave its input out when `{}` is a valid encoded input,
+ * such as for an action declared without `input` or one whose every field has a decoding
+ * default, and then sends the input `{}` decodes to. Every client shares this rule:
+ * `ActionHttp.client`, `Testing.mcpClient` and `Action.client`.
+ */
+export type Call<A extends Any, R> = {} extends A["input"]["Encoded"] ? (...input: [] | [input: A["input"]["Type"]]) => R : (input: A["input"]["Type"]) => R;
+//#endregion

package/dist/internal/call.mjs

@@ -0,0 +1,12 @@
+import { Effect, Schema } from "effect";
+//#region src/internal/call.ts
+/**
+* The input a method of `action` sends for the arguments it was called with: a given
+* argument as given, and none as the input `{}` decodes to, as a server decodes the `{}` it
+* receives. `Call` allows none only when `{}` is a valid encoded input, which is what this
+* decodes; decoding makes it one of the input's own values, such as an instance of an input
+* class, or fills its defaults.
+*/
+const inputOf = (action, args) => args.length === 0 ? Schema.decodeUnknownEffect(Schema.toCodecJson(action.input))({}) : Effect.succeed(args[0]);
+//#endregion
+export { inputOf };

package/dist/internal/cli.d.mts

@@ -1,29 +1,43 @@
-import "../Action.mjs";
-import { Effect, Schema } from "effect";
-import { Command } from "effect/cli";
+import "./errors.mjs";
+import { Action_d_exports, Any } from "../Action.mjs";
+import { Effect, Runtime, Types } from "effect";
+import { CliError, Command } from "effect/cli";
 //#region src/internal/cli.d.ts
-/** Options shared by the local and HTTP command projections. */
-interface CommonOptions<Output> {
-  /** Override the command name. The action name is used by default. */
+/**
+ * The fields of `A`'s input that may be positional: the named top-level fields of a struct
+ * or class input, as encoded. None for any other input, a record or a union included.
+ */
+export type Field<A extends Any> = A["input"]["Encoded"] extends (infer E) ? true extends Types.IsUnion<E> ? never : E extends ReadonlyArray<unknown> ? never : E extends object ? string extends keyof E ? never : Extract<keyof E, string> : never : never;
+/** How one command is named, takes its input and prints its result. */
+export interface Options<A extends Any> {
+  /** Override the command name. The action name, in kebab case, is used by default. */
   readonly name?: string;
   /** 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`. */
-export interface JsonOptions<Output> extends CommonOptions<Output> {
-  readonly parameters?: never;
-  readonly input?: never;
-}
-/** Supply native CLI parameters and map their parsed values to canonical action JSON. */
-export interface ParametersOptions<Output, Parameters extends Command.Command.Config> extends CommonOptions<Output> {
-  /** 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.InferValue<Parameters>) => Schema.Json;
+  readonly render?: (output: A["success"]["Type"]) => string;
+  /**
+   * Input fields taken as positional arguments instead of flags, in this order. An
+   * optional field is an optional argument, so it follows every required one.
+   */
+  readonly positional?: ReadonlyArray<Field<A>>;
+  /**
+   * A short name per input field's flag, such as `{ limit: "n" }` for `-n`, given as
+   * `Param.withAlias` takes it.
+   */
+  readonly aliases?: { readonly [K in Field<A>]?: string; };
 }
 /**
- * A command either accepts whole JSON input or has explicit native CLI parameters.
- * The latter intentionally has no implicit `--input` mode.
+ * What a command fails with when its action fails: Effect CLI's own error for a handler's
+ * failure, which `Command.run` prints on stderr and marks reported, so `runMain` does not
+ * print it again. Its `cause` is the action's failure. The process exits with the cause's
+ * `Runtime.errorExitCode`, 1 by default.
  */
-export type Options<Output, Parameters extends Command.Command.Config = never> = JsonOptions<Output> | ParametersOptions<Output, Parameters>;
+export declare class UserError<out E = unknown> extends CliError.UserError {
+  readonly cause: E;
+  /**
+   * The action's failure, as Effect names an error's nested one, so the native
+   * `Effect.catchReason("UserError", "UserNotFound", f)` and `catchReasons` match it by tag.
+   */
+  get reason(): E;
+  get [Runtime.errorExitCode](): number;
+}
 //#endregion