@gjermundgaraba/effect-actions 0.16.0 → 0.18.0

package/dist/contract/implementation.mjs

@@ -1,5 +1,7 @@
+import { Anyone, assertAuthentication } from "./caller.mjs";
 import { Unauthenticated } from "./errors.mjs";
-import { Anyone, assertAuthentication, assertDistinct, assertOnce, projectedErrors } from "./rules.mjs";
+import { assertDistinct, assertOnce } from "./names.mjs";
+import { projectedErrors } from "./declared.mjs";
 import { Array, Cause, Context, Effect, Exit, Layer, Option, Schema } from "effect";
 //#region src/contract/implementation.ts
 const uniqueKey = () => Math.random().toString(36).slice(2);
@@ -152,13 +154,7 @@ const dispatch = (action, handle, before) => {
 		} else reasons.push(reason);
 		return yield* Effect.failCause(Cause.fromReasons(reasons));
 	});
-	return (input) => {
-		const handled = Effect.withSpan(Effect.annotateLogs(Effect.suspend(() => handle(input)), actionAttributes), action.name, {
-			captureStackTrace: false,
-			attributes: actionAttributes
-		});
-		return Effect.scoped(authentication.pipe(Effect.andThen(authorization), Effect.andThen(handled), Effect.catchCause(declaredOrDefect)));
-	};
+	return (input) => Effect.scoped(authentication.pipe(Effect.andThen(authorization), Effect.andThen(Effect.suspend(() => handle(input))), Effect.catchCause(declaredOrDefect))).pipe(Effect.annotateLogs(actionAttributes), Effect.withSpan(action.name, { attributes: actionAttributes }, { captureStackTrace: false }));
 };
 //#endregion
 export { Implementation, acquire, assertHeld, builders, built, memoized, provideHandlers, select, servingOf, toList };

package/dist/contract/names.mjs

@@ -0,0 +1,25 @@
+//#region src/contract/names.ts
+const validName = /^[A-Za-z0-9_-]{1,128}$/;
+const assertName = (what, name) => {
+	if (!validName.test(name) || name === "then") throw new Error(`Invalid ${what}: ${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);
+	}
+};
+const assertOnce = (what, actions) => assertDistinct(what, actions, (action) => action.name);
+const assertKnown = (what, keys, names) => {
+	const unknown = keys.filter((key) => !names.includes(key));
+	if (unknown.length > 0) throw new Error(`Unknown ${what}: ${unknown.join(", ")}`);
+};
+//#endregion
+export { assertDistinct, assertKnown, assertName, assertOnce };

package/dist/contract/status.mjs

@@ -0,0 +1,18 @@
+import { unsuspended } from "./ast.mjs";
+import { Schema, SchemaAST } from "effect";
+//#region src/contract/status.ts
+const httpApiStatusOf = SchemaAST.resolveAt("httpApiStatus");
+const statusThroughSuspensions = (ast) => httpApiStatusOf(ast) ?? (SchemaAST.isSuspend(ast) ? statusThroughSuspensions(ast.thunk()) : void 0);
+/**
+* `error` as an endpoint declares it: each member of a union without a status of its own apart,
+* each with its status, 422 without one.
+*/
+const declared = (error) => {
+	const status = statusThroughSuspensions(error.ast);
+	if (status !== void 0) return [httpApiStatusOf(error.ast) === void 0 ? error.annotate({ httpApiStatus: status }) : error];
+	const resolved = unsuspended(error.ast);
+	if (SchemaAST.isUnion(resolved) && resolved.checks === void 0 && resolved.encoding === void 0) return resolved.types.flatMap((member) => declared(Schema.make(member)));
+	return [error.annotate({ httpApiStatus: 422 })];
+};
+//#endregion
+export { declared, httpApiStatusOf };

package/dist/http/client.d.mts

@@ -1,17 +1,25 @@
 import { BuiltIns } from "../contract/errors.mjs";
 import { Call } from "../contract/call.mjs";
-import { Action_d_exports, Any, Errors } from "../Action.mjs";
+import { Any, Errors } from "../Action.mjs";
 import { Any as Any$1, VerifierError } from "../authentication/provider.mjs";
 import { Effect, Schema } from "effect";
 import { HttpClient, HttpClientError } from "effect/http";
 import { HttpApi, HttpApiClient } from "effect/http-api";
 //#region src/http/client.d.ts
 /**
- * The native `HttpApiClient.make` options except `transformResponse`: `baseUrl` and
- * `transformClient`. `transformResponse` may change a call's success, failure or
- * services, which the method types cannot follow.
+ * The native `HttpApiClient.make` options except `transformResponse`, which may change a call's
+ * success, failure or services the method types cannot follow: `baseUrl`, and `transformClient`,
+ * which may return a client failing with `E` or requiring `R` of its own, as
+ * `HttpApiClient.makeWith` takes one.
  */
-export type Options = Omit<NonNullable<Parameters<typeof HttpApiClient.make>[1]>, "transformResponse">;
+export interface Options<E = HttpClientError.HttpClientError, R = never> extends Pick<NonNullable<Parameters<typeof HttpApiClient.make>[1]>, "baseUrl"> {
+  /**
+   * Wraps the native `HttpClient` the calls send with: a bearer token is
+   * `HttpClient.mapRequest(HttpClientRequest.bearerToken(token))`. A method also fails with what
+   * the returned client fails with beyond an `HttpClientError`, and requires what it requires.
+   */
+  readonly transformClient?: ((client: HttpClient.HttpClient) => HttpClient.HttpClient.With<E, R>) | undefined;
+}
 type BindingError = Errors[number];
 /**
  * What one call of `A` fails with: a declared error value (the action's own, one `E` of the
@@ -20,7 +28,7 @@ type BindingError = Errors[number];
  * the success does not decode. Input that does not encode is `InvalidInput`, and nothing is sent.
  */
 export type MethodError<A extends Any, E extends BindingError = never> = A["error"][number]["Type"] | E["Type"] | BuiltIns["Type"] | HttpClientError.HttpClientError | Schema.SchemaError;
-type Method<A extends Any, E extends BindingError> = Call<A, Effect.Effect<A["success"]["Type"], MethodError<A, E>>>;
+type Method<A extends Any, E extends BindingError, CE, CR> = Call<A, Effect.Effect<A["success"]["Type"], MethodError<A, E> | CE, CR>>;
 /**
  * Any HTTP binding, with its actions erased: what `layer` and `client` read. The API is a native
  * constraint here because native groups are invariant in their endpoints; `actions` carries the
@@ -35,7 +43,9 @@ export interface AnyHttp {
 }
 /**
  * Every action of the binding `H`, as `client.<action>(input)`: a protected one may also fail
- * with what its descriptor's verifier declares.
+ * with what its descriptor's verifier declares. Each call also fails with `E` and requires `R`,
+ * what its `transformClient` adds.
  */
-export type Client<H extends AnyHttp> = { readonly [A in H["actions"][number] as A["name"]]: Method<A, H["error"][number] | VerifierError<A, H["authentication"]>>; };
-//#endregion
+export type Client<H extends AnyHttp, E = never, R = never> = { readonly [A in H["actions"][number] as A["name"]]: Method<A, H["error"][number] | VerifierError<A, H["authentication"]>, E, R>; };
+//#endregion
+export {};

package/dist/http/client.mjs

@@ -1,8 +1,12 @@
 import { checked } from "../contract/call.mjs";
 import { Effect } from "effect";
+import { HttpClient } from "effect/http";
 import { HttpApiClient } from "effect/http-api";
 //#region src/http/client.ts
-const methods = (http, options = {}) => Effect.map(HttpApiClient.make(http.api, options), (client) => {
+const methodsWith = (http, httpClient, baseUrl) => Effect.map(HttpApiClient.makeWith(http.api, {
+	baseUrl,
+	httpClient
+}), (client) => {
 	const native = client;
 	return Object.fromEntries(http.actions.map((action) => {
 		const method = native[action.name];
@@ -10,5 +14,6 @@ const methods = (http, options = {}) => Effect.map(HttpApiClient.make(http.api,
 		return [action.name, checked(action, (payload) => method({ payload }))];
 	}));
 });
+const methods = (http, { baseUrl, transformClient } = {}) => Effect.flatMap(HttpClient.HttpClient, (native) => transformClient === void 0 ? methodsWith(http, native, baseUrl) : methodsWith(http, transformClient(native), baseUrl));
 //#endregion
 export { methods };

package/dist/mcp/client.d.mts

@@ -1,6 +1,6 @@
 import { BuiltIn } from "../contract/errors.mjs";
 import { Call } from "../contract/call.mjs";
-import { Action_d_exports, Any } from "../Action.mjs";
+import { Any } from "../Action.mjs";
 import { Any as Any$1, VerifierError } from "../authentication/provider.mjs";
 import { Effect, Schema } from "effect";
 import { Headers, HttpClient, HttpClientError, HttpClientRequest } from "effect/http";
@@ -16,8 +16,11 @@ export interface Params {
   };
   readonly [key: string]: Schema.Json | undefined;
 }
-/** Where `client` sends, through what client, and what the endpoint's authentication declares. */
-export interface ClientOptions<D extends Any$1 | undefined = Any$1 | undefined> {
+/**
+ * Where `client` sends, through what client, and what the endpoint's authentication declares: the
+ * client `transformClient` returns may fail with `E` and require `R`.
+ */
+export interface ClientOptions<D extends Any$1 | undefined = Any$1 | undefined, E = HttpClientError.HttpClientError, R = never> {
   /**
    * The endpoint, resolved by the `HttpClient`: relative under `Testing.layer`. Defaults to `/mcp`,
    * the default `layerHttp` path.
@@ -27,7 +30,7 @@ export interface ClientOptions<D extends Any$1 | undefined = Any$1 | undefined>
    * Wraps the native `HttpClient`, as `ActionHttp.client` takes it: a bearer token is
    * `HttpClient.mapRequest(HttpClientRequest.bearerToken(token))`.
    */
-  readonly transformClient?: (client: HttpClient.HttpClient) => HttpClient.HttpClient;
+  readonly transformClient?: (client: HttpClient.HttpClient) => HttpClient.HttpClient.With<E, R>;
   /**
    * The endpoint's descriptor, as `layerHttp` takes it: an error its verifier declares, the
    * endpoint's HTTP answer for a protected tool, is then that error's decoded value, as over
@@ -45,20 +48,55 @@ export interface RequestOptions {
   readonly url?: string;
   readonly headers?: Headers.Input;
 }
+declare const StatusError_base: Schema.Class<StatusError, Schema.TaggedStruct<"StatusError", {
+  readonly status: Schema.Int;
+  readonly body: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** The endpoint answered with an HTTP status other than 200, and a body no declared error decodes. */
+declare class StatusError extends StatusError_base {}
+declare const ProtocolError_base: Schema.Class<ProtocolError, Schema.TaggedStruct<"ProtocolError", {
+  readonly code: Schema.Finite;
+  readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * The endpoint answered with a JSON-RPC error, such as the native server's for invalid arguments
+ * or an unknown tool.
+ */
+declare class ProtocolError extends ProtocolError_base {}
+declare const NoReply_base: Schema.Class<NoReply, Schema.TaggedStruct<"NoReply", {
+  readonly body: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** The endpoint answered 200 without a JSON-RPC reply to read, as JSON or as an event stream. */
+declare class NoReply extends NoReply_base {}
+declare const UndeclaredError_base: Schema.Class<UndeclaredError, Schema.TaggedStruct<"UndeclaredError", {
+  readonly text: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** The tool returned an error whose text decodes as none of the action's declared errors. */
+declare class UndeclaredError extends UndeclaredError_base {}
+declare const NoStructuredContent_base: Schema.Class<NoStructuredContent, Schema.TaggedStruct<"NoStructuredContent", {
+  readonly body: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** The tool returned a result without the structured content its action's success needs. */
+declare class NoStructuredContent extends NoStructuredContent_base {}
 declare const McpCallError_base: Schema.Class<McpCallError, Schema.TaggedStruct<"McpCallError", {
+  readonly tool: Schema.String;
+  readonly reason: Schema.Union<readonly [typeof StatusError, typeof ProtocolError, typeof NoReply, typeof UndeclaredError, typeof NoStructuredContent]>;
   readonly message: Schema.String;
 }>, import("effect/Cause").YieldableError>;
 /**
- * An answer a client method cannot read as the action's success or a declared error, such as
- * the native server's message for invalid arguments or an unknown tool, or a result without
- * its structured content. Its message holds the answer. Structured content that does not
- * decode as the success is a `SchemaError` instead, and a request that fails an
- * `HttpClientError`.
+ * An answer a client method cannot read as the action's success or a declared error: `reason`
+ * says which, with what the endpoint sent, so a caller branches on it with
+ * `Effect.catchReason("McpCallError", "StatusError", ...)`. `message` names the tool and the
+ * reason. Structured content that does not decode as the success is a `SchemaError` instead,
+ * and a request that fails an `HttpClientError`.
  */
 export declare class McpCallError extends McpCallError_base {}
 type CallError<A extends Any, D> = A["error"][number]["Type"] | VerifierError<A, D>["Type"] | BuiltIn | Schema.SchemaError | HttpClientError.HttpClientError | McpCallError;
-/** Every action of `Actions` as `client.<action>(input)`, calling its tool. */
-export type Client<Actions extends ReadonlyArray<Any>, D = undefined> = { readonly [A in Actions[number] as A["name"]]: Call<A, Effect.Effect<A["success"]["Type"], CallError<A, D>>>; };
+/**
+ * Every action of `Actions` as `client.<action>(input)`, calling its tool. Each call also fails
+ * with `E` and requires `R`, what its `transformClient` adds.
+ */
+export type Client<Actions extends ReadonlyArray<Any>, D = undefined, E = never, R = never> = { readonly [A in Actions[number] as A["name"]]: Call<A, Effect.Effect<A["success"]["Type"], CallError<A, D> | E, R>>; };
 /**
  * A client of an MCP endpoint served by `layerHttp`, one method per action calling
  * its tool with one stateless request, as `ActionHttp.client` calls routes: the input is
@@ -71,6 +109,7 @@ export type Client<Actions extends ReadonlyArray<Any>, D = undefined> = { readon
  * native `HttpClient`, such as the one `Testing.layer` provides.
  */
 export declare function client<const Actions extends ReadonlyArray<Any>, D extends Any$1 | undefined = undefined>(actions: Actions, options?: ClientOptions<D>): Effect.Effect<Client<Actions, D>, never, HttpClient.HttpClient>;
+export declare function client<const Actions extends ReadonlyArray<Any>, E, R, D extends Any$1 | undefined = undefined>(actions: Actions, options: ClientOptions<D, E, R>): Effect.Effect<Client<Actions, D, E, R>, never, HttpClient.HttpClient>;
 /**
  * One stateless MCP request of `method` with `params`, as `layerHttp` serves it,
  * as the native request value: the JSON-RPC envelope, the 2026-07-28 headers (`Accept`,
@@ -84,4 +123,5 @@ export declare function client<const Actions extends ReadonlyArray<Any>, D exten
  * a call its types would not send.
  */
 export declare const request: (method: string, params?: Params, { headers, url }?: RequestOptions) => HttpClientRequest.HttpClientRequest;
-//#endregion
+//#endregion
+export {};

package/dist/mcp/client.mjs

@@ -1,8 +1,10 @@
+import { Anyone } from "../contract/caller.mjs";
 import { Refusal } from "../contract/errors.mjs";
-import { Anyone, assertOnce, projectedErrors } from "../contract/rules.mjs";
+import { assertOnce } from "../contract/names.mjs";
+import { projectedErrors } from "../contract/declared.mjs";
 import { checked } from "../contract/call.mjs";
 import { defaultPath, httpProtocol, liftOf, unliftedFrom } from "./protocol.mjs";
-import { Effect, Option, Predicate, Schema, identity } from "effect";
+import { Effect, Match, Option, Predicate, Schema } from "effect";
 import { McpSchema } from "effect/ai";
 import { HttpClient, HttpClientRequest } from "effect/http";
 import { Sse } from "effect/encoding";
@@ -42,14 +44,56 @@ const statelessRequest = (method, params) => {
 		}
 	};
 };
+/** The endpoint answered with an HTTP status other than 200, and a body no declared error decodes. */
+var StatusError = class extends Schema.TaggedError()("StatusError", {
+	status: Schema.Int,
+	body: Schema.String
+}) {};
 /**
-* An answer a client method cannot read as the action's success or a declared error, such as
-* the native server's message for invalid arguments or an unknown tool, or a result without
-* its structured content. Its message holds the answer. Structured content that does not
-* decode as the success is a `SchemaError` instead, and a request that fails an
-* `HttpClientError`.
+* The endpoint answered with a JSON-RPC error, such as the native server's for invalid arguments
+* or an unknown tool.
 */
-var McpCallError = class extends Schema.TaggedError()("McpCallError", { message: Schema.String }) {};
+var ProtocolError = class extends Schema.TaggedError()("ProtocolError", {
+	code: Schema.Finite,
+	message: Schema.String
+}) {};
+/** The endpoint answered 200 without a JSON-RPC reply to read, as JSON or as an event stream. */
+var NoReply = class extends Schema.TaggedError()("NoReply", { body: Schema.String }) {};
+/** The tool returned an error whose text decodes as none of the action's declared errors. */
+var UndeclaredError = class extends Schema.TaggedError()("UndeclaredError", { text: Schema.String }) {};
+/** The tool returned a result without the structured content its action's success needs. */
+var NoStructuredContent = class extends Schema.TaggedError()("NoStructuredContent", { body: Schema.String }) {};
+const Reason = Schema.Union([
+	StatusError,
+	ProtocolError,
+	NoReply,
+	UndeclaredError,
+	NoStructuredContent
+]);
+const sentenceOf = Match.typeTags()({
+	StatusError: ({ status, body }) => `answered ${status}: ${body}`,
+	ProtocolError: ({ code, message }) => `failed with ${code}: ${message}`,
+	NoReply: ({ body }) => `had no reply: ${body}`,
+	UndeclaredError: ({ text }) => `returned an error: ${text}`,
+	NoStructuredContent: ({ body }) => `returned no structured content: ${body}`
+});
+/**
+* An answer a client method cannot read as the action's success or a declared error: `reason`
+* says which, with what the endpoint sent, so a caller branches on it with
+* `Effect.catchReason("McpCallError", "StatusError", ...)`. `message` names the tool and the
+* reason. Structured content that does not decode as the success is a `SchemaError` instead,
+* and a request that fails an `HttpClientError`.
+*/
+var McpCallError = class extends Schema.TaggedError()("McpCallError", {
+	tool: Schema.String,
+	reason: Reason,
+	message: Schema.String
+}) {};
+const callError = (tool, reason) => new McpCallError({
+	tool,
+	reason,
+	message: `MCP tools/call "${tool}" ${sentenceOf(reason)}`
+});
 const textOf = (block) => block?.type === "text" ? block.text : void 0;
 const ToolCallReply = Schema.Union([Schema.Struct({ result: McpSchema.CallToolResult }), Schema.Struct({ error: Schema.Struct({
 	code: Schema.Finite,
@@ -67,7 +111,6 @@ const replyOf = (response, text) => {
 const failWith = (errors, text, otherwise) => Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.toCodecJson(Schema.Union(errors))))(text).pipe(Effect.mapError(() => otherwise), Effect.flatMap(Effect.fail));
 const callTool = (client, url, action, lift, refusedWith, 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(request("tools/call", {
@@ -75,26 +118,26 @@ const callTool = (client, url, action, lift, refusedWith, input) => {
 			arguments: encoded
 		}, { url }));
 		const text = yield* response.text;
-		if (response.status !== 200) return yield* failWith(refusedWith, text, other(`answered ${response.status}: ${text}`));
+		if (response.status !== 200) return yield* failWith(refusedWith, text, callError(name, new StatusError({
+			status: response.status,
+			body: 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}`));
-		}
+		if (Option.isNone(reply)) return yield* Effect.fail(callError(name, new NoReply({ body: text })));
+		if ("error" in reply.value) return yield* Effect.fail(callError(name, new ProtocolError(reply.value.error)));
 		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}`));
+			return yield* failWith(projectedErrors(action), error, callError(name, new UndeclaredError({ text: error })));
 		}
-		if (result.structuredContent === void 0 && lift.rest !== void 0) return yield* Effect.fail(other(`returned no structured content: ${text}`));
+		if (result.structuredContent === void 0 && lift.rest !== void 0) return yield* Effect.fail(callError(name, new NoStructuredContent({ body: text })));
 		return yield* Schema.decodeUnknownEffect(Schema.toCodecJson(action.success))(unliftedFrom(lift, result));
 	});
 };
-function client(actions, { url = defaultPath, transformClient = identity, authentication } = {}) {
+function client(actions, { url = defaultPath, transformClient, authentication } = {}) {
 	assertOnce("action", actions);
 	return Effect.map(HttpClient.HttpClient, (native) => {
-		const http = transformClient(native);
+		const http = transformClient === void 0 ? native : transformClient(native);
 		return Object.fromEntries(actions.map((action) => {
 			const lift = liftOf(action.success);
 			const refusedWith = [...Refusal.members, ...action.caller === Anyone ? [] : authentication?.error ?? []];

package/dist/mcp/protocol.mjs

@@ -1,4 +1,4 @@
-import { unsuspended } from "../contract/rules.mjs";
+import { unsuspended } from "../contract/ast.mjs";
 import { Media, isMarked, kindOf } from "../contract/media.mjs";
 import { Predicate, Schema, SchemaAST } from "effect";
 import { McpProtocol } from "effect/ai";

package/docs/Action.md

@@ -158,11 +158,25 @@ and the whole builder above [notes-service/src/notes/handlers.ts](../examples/no
 - **Pass the builder to `implement` itself.** Through `.pipe(...)` or a wrapper such as
   `Effect.withSpan(builder, name)`, an `Effect.fn` handler it returns takes an `any` input. A
   builder written apart returns its record `satisfies Action.Handlers<typeof actions>`.
-- **Leave a handler's `Effect.fn` unnamed**: each handler already runs in a span named after its
-  action, and its log lines carry `action.name` and `action.read_only`.
+- **Leave a handler's `Effect.fn` unnamed** unless you need handler-only timing: each action
+  already has a span ([Observe calls](#observe-calls)).
 - **Calling the function you passed to `implement` skips authorization.** Call the
   implementation through [`Action.client`](Action-in-process.md#call-actions-in-process).
 
+## Observe calls
+
+The span named after an action includes authorization, handler execution and call cleanup.
+Its exit reflects the final dispatch outcome; the span and its logs carry `action.name` and
+`action.read_only`.
+
+Transport credential verification, input decoding and response encoding run outside this span.
+A request rejected by verification or decoding has no action span; response encoding can fail
+after the action span succeeds.
+
+Add a named handler span to measure handler time alone. The named authorizer in
+[notes-service/src/identity/authorize.ts](../examples/notes-service/src/identity/authorize.ts)
+similarly measures authorization as a child of the action span.
+
 ## Authorize calls
 
 An implementation holding a protected action states `{ authorize }`: a function of the called
@@ -233,5 +247,5 @@ failure compiles. What each surface answers is in [guarantees.md](guarantees.md#
   or `Forbidden`. Passed on, it is this server's own refusal: a caller whose token is valid is
   told to sign in again. Map it to an error the action declares, or to a defect.
 - **Map that client's `HttpClientError` and `SchemaError` to one declared error a caller can
-  act on** ([mcp-tools/src/printers/farm.ts](../examples/mcp-tools/src/printers/farm.ts)). As
+  act on** ([mcp-tools/src/platform/print-farm.ts](../examples/mcp-tools/src/platform/print-farm.ts)). As
   defects, a model reads only a generic text.

package/docs/ActionCli-failures.md

@@ -63,7 +63,10 @@ The tasks are in [ActionCli.md](ActionCli.md).
   `client`. To choose by a condition, build a command from each:
   `remotely ? ActionCli.remote(Http, options) : ActionCli.make(users, options)`.
 - `Type 'HttpClient' is not assignable to type 'never'` in the pipe that runs a remote command:
-  provide `NodeHttpClient.layerUndici` (or `FetchHttpClient.layer`).
+  provide `NodeHttpClient.layerUndici` (or `FetchHttpClient.layer`). Another service named there
+  is what its `client` requires: provide it too.
+- An argument of type `Binding<…>` not assignable at `remote` or `remoteCommand`, beside a
+  `client`: the client is another binding's. Make it with `ActionHttp.client` of this one.
 - A local command requires an identity service no handler yields: its action is protected, and
   requires the identity its contract declares. Provide it on the command
   ([Name the caller](ActionCli.md#name-the-caller)); do not make the contract public to satisfy
@@ -79,20 +82,18 @@ The tasks are in [ActionCli.md](ActionCli.md).
 - `--help` or a mistyped flag connects to a database, or fails reading config: services provided
   around `Command.run` are built before parsing. Provide them on the command,
   `Command.provide(layer)`.
-- `ERROR (#n): ConfigError: SchemaError(Expected string at ["NOTES_TOKEN"])` from a public
-  command, exit 1, on stdout, or on stderr under `logToStderr`: the client provided on the
-  command requires a token, and a failure of what a command is provided is `runMain`'s report,
-  not the command's JSON. Read the token with `Config.option` and add the header only when it is
-  there. Where every command needs it, keep it required and map the failure, in the Effect that
-  provides the client, to `new CliError.UserError({ cause, userMessage })`:
+- `ConfigError: …` or another error's `Tag: message` on stderr from a remote command, a public
+  one too: its `client` failed, as when a required token is not set. Read an optional one with
+  `Config.option` and add the header only when it is there. Where every command needs it, map
+  the failure to a tagged error whose `message` says what to do:
   [notes-service/src/commands.ts](../examples/notes-service/src/commands.ts).
 - `HttpClientError` whose `reason._tag` is `InvalidUrlError`, from a remote command: its client
   has no `baseUrl` and prepends no URL.
 - 401 `Unauthenticated` from a remote command: a remote command adds no headers of its own. Add
-  credentials in `client`'s `transformClient`, or on the `HttpClient` the command is provided.
+  credentials in its client's `transformClient`.
 - Another command's request goes to the API's URL, or carries its token: an `HttpClient`
   configured around the whole program rewrites every request the program makes. Configure it in
-  the `client` option, or provide it on the remote command alone.
+  the `client` option.
 - A report with a stack on stdout, `ERROR (#1): ...`, instead of JSON on stderr: a defect, or a
   failure of a layer the host provides, which `runMain` reports. Fix the defect; apply
   `ActionCli.logToStderr` to keep such reports off stdout.

package/docs/ActionCli.md

@@ -36,10 +36,10 @@ Import `@gjermundgaraba/effect-actions/ActionCli`.
 | `make`, `remote`: `actions`              | The actions that are subcommands; default: every one.                           |
 | `make`, `remote`: `commands`             | Each subcommand's `command` options, by action name: `{ getNote: { render } }`. |
 | `make`, `remote`: `subcommands`          | Commands of your own beside the derived ones: `[exportNotes]`.                  |
-| `remoteCommand`, `remote`: `client`      | The `ActionHttp.client` options, `baseUrl` and `transformClient`.               |
+| `remoteCommand`, `remote`: `client`      | The client its commands call: `ActionHttp.client(Http, { baseUrl })`.           |
 
-Exported types: `Options<A>`, `RemoteOptions<A>`, `CommandOptions<A>`, `RemoteCommandOptions<A>`,
-and `UserError<E>`, a type only: what a command fails with when its action fails with `E`.
+Exported types: `Options<A>` of `make` and `remote`, `CommandOptions<A>` of `command` and
+`remoteCommand`, and `UserError<E>`, a type only: what a command fails with when its action fails with `E`.
 
 ## Run actions as local commands
 
@@ -47,7 +47,7 @@ Pass implementations to `make`, and provide the services and the caller on the c
 
 ```ts
 const assistant = ActionCli.make([tasks, identity], { name: "assistant" }).pipe(
-  Command.provide(Layer.mergeAll(TaskStore.layerFile, Permissions.layerMemory)),
+  Command.provide(Layer.mergeAll(tasksFile, Permissions.layerMemory)),
   Command.provideSync(CurrentCaller, operator),
 );
 ```
@@ -81,21 +81,22 @@ Run it with Effect's own `Command.run`:
 Pass the HTTP binding to `remote`. The program imports the binding alone, never a handler; each
 command calls its action through the binding's `ActionHttp.client` method
 ([ActionHttp.md](ActionHttp.md#call-the-api-from-effect)) and fails as that method does. The host
-provides `HttpClient` (`NodeHttpClient.layerUndici`) and says where the server is:
-[notes-service/src/commands.ts](../examples/notes-service/src/commands.ts) and
-[notes-service/src/cli.ts](../examples/notes-service/src/cli.ts).
+provides `HttpClient` (`NodeHttpClient.layerUndici`) in
+[notes-service/src/cli.ts](../examples/notes-service/src/cli.ts); the client says where the
+server is in [notes-service/src/commands.ts](../examples/notes-service/src/commands.ts).
 [kitchen-sink/src/cli.ts](../examples/kitchen-sink/src/cli.ts) adds a tenant header and uses
 every command option.
 
-- **Choose where the connection comes from.** A fixed URL or token goes in the `client` option:
-  `client: { baseUrl, transformClient: HttpClient.mapRequest(HttpClientRequest.bearerToken(token)) }`.
-  One read from `Config` configures the `HttpClient` provided on the command, with
-  `Command.provideEffect(HttpClient.HttpClient, …)` as `notes-service/src/cli.ts` does, so
-  `--help` needs neither. A command of your own in `subcommands` calls through the same client.
-- **Configure the client on the command, never around the program.** Around the program it
-  rewrites every request the program makes, an absolute URL too, and sends each one the token.
-- **A token every command needs is required, its failure mapped to a `CliError.UserError`**, or a
-  missing one prints a raw `ConfigError` log line: `connection` in
+- **The connection is the `client` option**, an Effect of the binding's client run each time a
+  command runs: `client: ActionHttp.client(Http, { baseUrl, transformClient })`. One reading
+  `Config` is an `Effect.gen` returning `yield* ActionHttp.client(…)`, so `--help` reads nothing.
+  Its failures and its methods' are the command's, printed as `Tag: message`, a
+  `CliError.UserError` as its `userMessage`; what they require, the host provides. Credentials go in `transformClient`
+  ([ActionHttp.md](ActionHttp.md#call-the-api-from-effect)).
+- **Never transform the `HttpClient` around the program**: it rewrites every request the program
+  makes, an absolute URL too, and sends each one the token.
+- **A token every command needs is required, its failure mapped to a tagged error whose `message`
+  says what to do**, or a missing one prints as `ConfigError: …`: `api` in
   [notes-service/src/commands.ts](../examples/notes-service/src/commands.ts). Where a public
   command must answer signed out, read it with `Config.option` and add the header when it is
   there: [kitchen-sink/src/cli.ts](../examples/kitchen-sink/src/cli.ts).
@@ -156,15 +157,15 @@ in `subcommands`: `notes export <file>` takes `Argument.String("file")`
 ([notes-service/src/commands.ts](../examples/notes-service/src/commands.ts)):
 
 ```ts
-const notes = ActionCli.remote(Http, { name: "notes", subcommands: [exportNotes] });
+const notes = ActionCli.remote(Http, { name: "notes", client: api, subcommands: [exportNotes] });
 ```
 
 - **Never pipe `Command.withSubcommands` onto `make` or `remote`.** It replaces the derived
   commands, which then answer with the usage text.
-- **Call the actions through a client**, in the command's own handler: `ActionHttp.client`, which
-  needs no scope and uses the `HttpClient` provided on the aggregate, or `Action.client`, acquired
-  inside `Effect.scoped` ([Action-in-process.md](Action-in-process.md#call-actions-in-process)).
-  `authorize` still runs. The `client` option reaches the derived commands alone.
+- **Call the actions through a client**, in the command's own handler: `yield* api`, the Effect
+  the aggregate's `client` is, which needs no scope, or `Action.client`, acquired inside
+  `Effect.scoped` ([Action-in-process.md](Action-in-process.md#call-actions-in-process)).
+  `authorize` still runs.
 - **Its output is what it prints**, with `Console.log`: the output rules below are a derived
   command's. **Pipe its whole Effect through `ActionCli.toUserError(Http)`**, the binding its
   client is made from, HTTP or RPC, or `toUserError([GetNote])` over `Action.client`, to fail as a derived command does: a declared

package/docs/ActionHttp-failures.md

@@ -53,6 +53,12 @@ The tasks are in [ActionHttp.md](ActionHttp.md).
   the binding's `error`, given inline so its type is certain, or move the check to the handlers
   and declare the error on their actions.
 
+- `No overload matches this call` at `client`, naming `Options<unknown, unknown>`: options built
+  before the call hold the generic `HttpClient.mapRequestEffect(authorize)`, whose failures the
+  call cannot infer, or a helper types them as `Parameters<typeof ActionHttp.client>[1]`. Write
+  the transform as `(client) => HttpClient.mapRequestEffect(client, authorize)`, and type such
+  options as `ActionHttp.ClientOptions<E, R>`.
+
 ## Requests
 
 - A route answers without credentials: its contract is `caller: Action.Anyone`.

package/docs/ActionHttp.md

@@ -36,7 +36,7 @@ Exported types: `Binding`; `Any`, any binding; `Client<typeof Http>`, a client's
 | `layer`: `actions`          | The bound actions it serves: `[GetUser]`. Defaults to every one the implementations hold.         |
 | `layer`: `middleware`       | Native `HttpApiMiddleware` around every route it serves, the first innermost.                     |
 | `client`: `baseUrl`         | What routes resolve against: `https://api.example.com`. Omitted: relative ones, a page's origin.  |
-| `client`: `transformClient` | Wraps the native `HttpClient`: `HttpClient.mapRequest(HttpClientRequest.bearerToken(token))`.     |
+| `client`: `transformClient` | Wraps the native `HttpClient`: a token, or a sign-in per request, whose failures each call adds.  |
 | `fetchClient`: `fetch`      | Its `fetch`, beside `client`'s options. Omitted: the global `fetch`, looked up on every call.     |
 
 Each action is served at `POST <prefix>/<action>`, a `readOnly` one too. One without `success`
@@ -185,9 +185,12 @@ Files: [quickstart/src/client.ts](../examples/quickstart/src/client.ts),
 [kitchen-sink/src/seed.ts](../examples/kitchen-sink/src/seed.ts) (`baseUrl` from `Config`,
 headers, errors by tag).
 
-- Outside a browser, set `baseUrl`. A token or any other header goes through `transformClient`.
-  Where no client is built by hand, as under `ActionCli.remote`, transform the `HttpClient`
-  itself (`connection` in [notes-service/src/commands.ts](../examples/notes-service/src/commands.ts)).
+- Outside a browser, set `baseUrl`. A token or any other header goes through `transformClient`:
+  `HttpClient.mapRequest(HttpClientRequest.bearerToken(token))`. A credential read or refreshed
+  as each request is sent, which may fail, is
+  `(client) => HttpClient.mapRequestEffect(client, authorize)`: each call then also fails with
+  `authorize`'s own errors, as they are, and requires its services. `ActionMcp.client` takes the
+  same transform, and `ActionCli.remote` the client itself as its `client`.
 - Leave the argument out when `{}` is a valid input. A given argument is the decoded input, so
   it states a defaulted field.
 - A declared error is a typed failure, as its decoded value: the action's own, the binding's,
@@ -215,6 +218,8 @@ with `Effect.runPromise`. Files:
 - A page on another origin passes `baseUrl`, and the server must allow that origin with
   `HttpRouter.cors`
   ([kitchen-sink/src/request-policy.ts](../examples/kitchen-sink/src/request-policy.ts), `cors`).
+- A `transformClient` requiring a service, such as the session's token, makes each call require
+  it: provide it on the call before `Effect.runPromise`.
 - An unhandled declared error rejects the promise as its decoded value, so
   `error instanceof Action.Unauthenticated` works in a `catch`. Handle an expected one by its tag
   before `Effect.runPromise`.

package/docs/ActionMcp.md

@@ -21,7 +21,7 @@ Import `@gjermundgaraba/effect-actions/ActionMcp`.
 | `LayerHttpOptions`                    | Type of `layerHttp`'s options: `Options` and HTTP's own.    |
 | `client(actions, options?)`           | An Effect of a client calling each action's tool.           |
 | `request(method, params?, options?)`  | One MCP request, as the native `HttpClientRequest` to send. |
-| `McpCallError`                        | A client method's failure for an answer it cannot decode.   |
+| `McpCallError`                        | A client method's undecodable answer, by tagged `reason`.   |
 
 `implementations` is one implementation or a list.
 
@@ -44,7 +44,7 @@ options. Its `protocols` and `allowSessionTermination` are not options.
 
 `client` takes `url`, default `/mcp`, `transformClient`, and the endpoint's `authentication`, so an
 error its verifier declares decodes; `request` takes `url` and `headers`.
-Types: `Client<Actions, D>`, `ClientOptions`, `RequestOptions`, `Params`.
+Types: `Client<Actions, D, E, R>`, `ClientOptions`, `RequestOptions`, `Params`.
 
 ## Serve tools over HTTP
 
@@ -140,7 +140,7 @@ tool's read-only hint, and the contract's `mcp` option holds its `title`, its ot
   field's `description`, annotated before the check: after a custom one it is lost too.
 - A declared error reaches the model as an `isError` result whose text is the error's JSON. Write
   its `message` for the model, which acts on it:
-  [mcp-tools/src/printers/farm.ts](../examples/mcp-tools/src/printers/farm.ts). Every other case:
+  [mcp-tools/src/platform/print-farm.ts](../examples/mcp-tools/src/platform/print-farm.ts). Every other case:
   [guarantees.md](guarantees.md#wire-behavior).
 - `actions` lists the tools, and only listed actions must suit MCP:
   [kitchen-sink/src/Actions.ts](../examples/kitchen-sink/src/Actions.ts). Leave out an action a