@gjermundgaraba/effect-actions 0.17.0 → 0.18.0

package/README.md

@@ -72,7 +72,9 @@ implementation is also:
 ```ts
 const { toolkit, layer } = ActionToolkit.make(greeting); // native Effect AI Toolkit and its handler layer
 const cli = ActionCli.make(greeting, { name: "greetings" }); // greetings greet --name Ada
-const remote = ActionCli.remoteCommand(Http, Greet, { client: { baseUrl } }); // greet --name Ada, over HTTP
+const remote = ActionCli.remoteCommand(Http, Greet, {
+  client: ActionHttp.client(Http, { baseUrl }),
+}); // greet --name Ada, over HTTP
 const local = Action.client(greeting); // the HTTP client's methods, in process
 const rpc = ActionRpc.layer(ActionRpc.make([Greet]), greeting); // Effect RPC, on the protocol the host provides
 ```

package/dist/ActionCli.d.mts

@@ -1,14 +1,13 @@
 import { BuiltIn } from "./contract/errors.mjs";
 import { ActionOf, BuildError, BuildServices, Holding, Known, Member, RequestOf, Selected, SelectedOf, Selection, Served } from "./contract/implementation.mjs";
 import { Any } from "./Action.mjs";
-import { VerifierError } from "./authentication/provider.mjs";
 import { Declaring } from "./contract/declared.mjs";
 import { Options, UserError } from "./cli/commands.mjs";
-import { AnyHttp, Options as Options$2 } from "./http/client.mjs";
+import { AnyHttp, Client } from "./http/client.mjs";
 import "./ActionHttp.mjs";
-import { Effect, Schema } from "effect";
-import { HttpClient, HttpClientError } from "effect/http";
-import { Command } from "effect/cli";
+import { Effect } from "effect";
+import { HttpClient } from "effect/http";
+import { CliError, Command } from "effect/cli";
 //#region src/cli/ActionCli.d.ts
 interface AnyBinding extends Declaring {
   readonly actions: ReadonlyArray<Any>;
@@ -24,7 +23,7 @@ interface AnyBinding extends Declaring {
  * `Effect.tapError(() => Console.error(…))`: a `UserError` wrapped around the result would
  * replace its JSON.
  */
-export declare const toUserError: (calls: AnyBinding | ReadonlyArray<Any>) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, UserError<Exclude<E, import("effect/cli/CliError").CliError>> | Exclude<E, Exclude<E, import("effect/cli/CliError").CliError>>, R>;
+export declare const toUserError: (calls: AnyBinding | ReadonlyArray<Any>) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, UserError<Exclude<E, CliError.CliError>> | Exclude<E, Exclude<E, CliError.CliError>>, R>;
 /**
  * An aggregate command of the actions `A`: its name, the actions that are its subcommands,
  * and their options.
@@ -69,39 +68,28 @@ type Local<App, A extends Any> = Effect.Effect<A["success"]["Type"], A["error"][
  * as JSON when it is not a struct. The flag of an array of strings or numbers is repeated for each value, a boolean
  * field is a switch, `--no-<name>` sending `false` as a required one left out does, and a field's `description` is its flag's help. It needs what the authorization, its handler and its builder
  * need; the host provides the identity. It prints the result on stdout; a failure is a
- * `UserError`, which `Command.run` prints on stderr. `remoteCommand` calls a server instead.
+ * `UserError`, or an Effect CLI error as it is, such as a builder's `CliError.UserError`, which
+ * `Command.run` prints on stderr. `remoteCommand` calls a server instead.
  */
-export declare function command<const Apps extends Served, A extends ActionOf<Member<Apps>>, const O = {}>(implementations: Apps, action: A, options?: O & NoInfer<Options<A>> & NoInfer<Known<O, Options<Any>>>): Command.Command<string, never, {}, UserError<Effect.Error<Local<Owning<Member<Apps>, A>, A>>>, Effect.Services<Local<Owning<Member<Apps>, A>, A>>>;
+export declare function command<const Apps extends Served, A extends ActionOf<Member<Apps>>, const O = {}>(implementations: Apps, action: A, options?: O & NoInfer<Options<A>> & NoInfer<Known<O, Options<Any>>>): Command.Command<string, never, {}, Failing<Effect.Error<Local<Owning<Member<Apps>, A>, A>>>, Effect.Services<Local<Owning<Member<Apps>, A>, A>>>;
 /**
  * Project one action of an HTTP binding into a native Effect CLI command, derived as `command`
- * derives it, that calls the action over HTTP through its `ActionHttp.client` method, made with
- * the `client` options on the host's `HttpClient`, and fails as the method does. It runs
- * nothing locally.
+ * derives it, that calls the action through `client`'s method and fails as the method does, or
+ * as the Effect building the client does. `client` is an Effect of the binding's client, such as
+ * `ActionHttp.client(Http, { baseUrl })`, run each time the command runs; omitted, it is
+ * `ActionHttp.client(binding)` on the host's `HttpClient`. It runs nothing locally.
  */
-export declare function remoteCommand<const H extends AnyHttp, A extends H["actions"][number], const O = {}>(binding: H, action: A, options?: O & NoInfer<RemoteCommandOptions<A>> & NoInfer<Known<O, RemoteCommandOptions<Any>>>): Command.Command<string, never, {}, HttpUserError<H, A>, HttpClient.HttpClient>;
-/** A remote command's options, its action `A`. */
-export type RemoteCommandOptions<A extends Any = Any> = Options<A> & {
-  /**
-   * Its client's options, as `ActionHttp.client` takes them: `baseUrl`, and
-   * `transformClient` for credentials. They reach this command's requests alone.
-   */
-  readonly client?: Options$2;
-};
-/** A remote aggregate command's options, its actions `A`. */
-export type RemoteOptions<A extends Any = Any> = Options$1<A> & {
-  /**
-   * Every subcommand's client options, as `ActionHttp.client` takes them: `baseUrl`, and
-   * `transformClient` for credentials. They reach this aggregate's requests alone. A URL or a
-   * token read from `Config` goes instead into the `HttpClient` provided on the command, with
-   * `Command.provideEffect(HttpClient.HttpClient, …)`: it is read when a command runs, so
-   * `--help` needs neither, and a command of your own in `subcommands` calls through it too.
-   * A required one that is not set fails that Effect with a `ConfigError`, which is no
-   * command's failure and prints as a crash line: map the read,
-   * `Effect.mapError((cause) => new CliError.UserError({ cause, userMessage: "TOKEN is not set" }))`.
-   */
-  readonly client?: Options$2;
+export declare function remoteCommand<const H extends AnyHttp, A extends H["actions"][number], const O = {}, C extends ClientOf<H> | undefined = undefined>(binding: H, action: A, options?: O & NoInfer<Options<A>> & NoInfer<Known<O, RemoteKeys<Options<Any>>>> & {
+  readonly client?: C;
+}): Command.Command<string, never, {}, Failing<CallFailure<H, C, A>>, CallServices<C, A>>;
+type ClientOf<H extends AnyHttp> = Effect.Effect<Client<H, unknown, unknown>, unknown, unknown>;
+type RemoteKeys<Keys> = Keys & {
+  readonly client?: unknown;
 };
-type HttpUserError<H extends AnyHttp, A extends Any> = UserError<A["error"][number]["Type"] | H["error"][number]["Type"] | VerifierError<A, H["authentication"]>["Type"] | BuiltIn | HttpClientError.HttpClientError | Schema.SchemaError>;
+type Failing<F> = UserError<Exclude<F, CliError.CliError>> | Extract<F, CliError.CliError>;
+type Called<M, A extends Any> = A extends unknown ? A["name"] extends keyof M ? M[A["name"]] extends ((...input: never) => infer Call) ? Call : never : never : never;
+type CallFailure<H extends AnyHttp, C, A extends Any> = C extends Effect.Effect<infer M, infer CE, unknown> ? CE | Effect.Error<Called<M, A>> : Effect.Error<Called<Client<H>, A>>;
+type CallServices<C, A extends Any> = C extends Effect.Effect<infer M, unknown, infer CR> ? CR | Effect.Services<Called<M, A>> : HttpClient.HttpClient;
 /**
  * Project every implemented action as a subcommand of one aggregate command, each named after
  * its action in kebab case and run in process. `commands` gives a subcommand the options
@@ -113,16 +101,17 @@ type HttpUserError<H extends AnyHttp, A extends Any> = UserError<A["error"][numb
  */
 export declare function make<const Apps extends Served, const O extends Selection<ActionOf<Member<Apps>>> = {}, const Own extends Subcommands = []>(implementations: Apps, options: O & NoInfer<Options$1<ActionOf<Member<Apps>>>> & NoInfer<KnownOptions<O, Options$1, ActionOf<Member<Apps>>>> & {
   readonly subcommands?: Own | undefined;
-}): Command.Command<string, {}, {}, UserError<Effect.Error<Local<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>>>> | Command.Error<OwnCommand<Own>>, Effect.Services<Local<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>>> | Command.Services<OwnCommand<Own>>>;
+}): Command.Command<string, {}, {}, Failing<Effect.Error<Local<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>>>> | Command.Error<OwnCommand<Own>>, Effect.Services<Local<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>>> | Command.Services<OwnCommand<Own>>>;
 /**
  * Project every action of an HTTP binding as a subcommand of one aggregate command, derived as
- * `make` derives it, each calling its action over HTTP. `client` configures every derived
- * subcommand's client; `commands` gives one the options `command` takes; `subcommands` adds
- * commands of your own.
+ * `make` derives it, each calling its action through `client`'s method, as `remoteCommand`
+ * does. `commands` gives one the options `command` takes; `subcommands` adds commands of your
+ * own, which call through the same client by yielding the Effect given as `client`.
  */
-export declare function remote<const H extends AnyHttp, const O extends Selection<H["actions"][number]> = {}, const Own extends Subcommands = []>(binding: H, options: O & NoInfer<RemoteOptions<H["actions"][number]>> & NoInfer<KnownOptions<O, RemoteOptions<Any>, H["actions"][number]>> & {
+export declare function remote<const H extends AnyHttp, const O extends Selection<H["actions"][number]> = {}, const Own extends Subcommands = [], C extends ClientOf<H> | undefined = undefined>(binding: H, options: O & NoInfer<Options$1<H["actions"][number]>> & NoInfer<KnownOptions<O, RemoteKeys<Options$1<Any>>, H["actions"][number]>> & {
+  readonly client?: C;
   readonly subcommands?: Own | undefined;
-}): Command.Command<string, {}, {}, HttpUserError<H, Selected<O, H["actions"][number]>> | Command.Error<OwnCommand<Own>>, HttpClient.HttpClient | Command.Services<OwnCommand<Own>>>;
+}): Command.Command<string, {}, {}, Failing<CallFailure<H, C, Selected<O, H["actions"][number]>>> | Command.Error<OwnCommand<Own>>, CallServices<C, Selected<O, H["actions"][number]>> | Command.Services<OwnCommand<Own>>>;
 /**
  * A program whose stdout carries only its results, such as a CLI feeding scripts or an MCP
  * subprocess, applied last, before `NodeRuntime.runMain`: the default logger of every layer

package/dist/ActionCli.mjs

@@ -17,7 +17,7 @@ import { Command } from "effect/cli";
 * `Effect.tapError(() => Console.error(…))`: a `UserError` wrapped around the result would
 * replace its JSON.
 */
-const toUserError = (calls) => "actions" in calls ? failingAsDerived(calls.actions, (action) => bindingErrors(action, calls)) : failingAsDerived(calls, (action) => projectedErrors(action));
+const toUserError = (calls) => "actions" in calls ? failingAsDerived(calls.actions.flatMap((action) => bindingErrors(action, calls))) : failingAsDerived(calls.flatMap((action) => projectedErrors(action)));
 const runWithBuildOfItsOwn = (app, action, input) => {
 	const thisActionOnly = Implementation.share([action], app);
 	return Effect.flatMap(acquire([thisActionOnly]), (bound) => {
@@ -37,7 +37,7 @@ const inProcess = (apps, action, options) => {
 };
 const overHttp = (binding, action, options, client$1) => {
 	if (!binding.actions.includes(action)) throw new Error(`Action "${action.name}" is not in this HTTP binding`);
-	return command$1(action, (input) => Effect.flatMap(client(binding, client$1), (methods) => {
+	return command$1(action, (input) => Effect.flatMap(client$1 ?? client(binding), (methods) => {
 		const method = methods[action.name];
 		if (method === void 0) throw new Error(`No client method for ${action.name}`);
 		return method(input);
@@ -69,17 +69,12 @@ const checkedCommandsOf = (commands, actions) => {
 * as JSON when it is not a struct. The flag of an array of strings or numbers is repeated for each value, a boolean
 * field is a switch, `--no-<name>` sending `false` as a required one left out does, and a field's `description` is its flag's help. It needs what the authorization, its handler and its builder
 * need; the host provides the identity. It prints the result on stdout; a failure is a
-* `UserError`, which `Command.run` prints on stderr. `remoteCommand` calls a server instead.
+* `UserError`, or an Effect CLI error as it is, such as a builder's `CliError.UserError`, which
+* `Command.run` prints on stderr. `remoteCommand` calls a server instead.
 */
 function command(implementations, action, options) {
 	return inProcess(toList(implementations), action, options);
 }
-/**
-* Project one action of an HTTP binding into a native Effect CLI command, derived as `command`
-* derives it, that calls the action over HTTP through its `ActionHttp.client` method, made with
-* the `client` options on the host's `HttpClient`, and fails as the method does. It runs
-* nothing locally.
-*/
 function remoteCommand(binding, action, options) {
 	const { client, ...syntax } = options ?? {};
 	return overHttp(binding, action, options === void 0 ? void 0 : syntax, client);
@@ -99,12 +94,6 @@ function make(implementations, options) {
 	const served = select(apps, options.actions);
 	return aggregateCommand(options.name, served.flatMap((app) => app.actions), commands, options.subcommands ?? [], (action, syntax) => inProcess(served, action, syntax));
 }
-/**
-* Project every action of an HTTP binding as a subcommand of one aggregate command, derived as
-* `make` derives it, each calling its action over HTTP. `client` configures every derived
-* subcommand's client; `commands` gives one the options `command` takes; `subcommands` adds
-* commands of your own.
-*/
 function remote(binding, options) {
 	const listed = options.actions;
 	if (listed !== void 0) assertHeld("the binding does not hold it", listed, binding.actions);

package/dist/ActionHttp.d.mts

@@ -6,11 +6,11 @@ import { Any as Any$1, DescriptorOf, Identity, Matching, PublicOnly, RemoteReque
 import { Certain, ErrorsOf } from "./contract/declared.mjs";
 import { AnyHttp, Client, MethodError, Options } from "./http/client.mjs";
 import { Context, Effect, FileSystem, Layer, Path, Schema, Types } from "effect";
-import { Etag, HttpClient, HttpPlatform, HttpRouter } from "effect/http";
+import { Etag, HttpClient, HttpClientError, HttpPlatform, HttpRouter } from "effect/http";
 import { HttpApi, HttpApiEndpoint, HttpApiGroup, HttpApiMiddleware } from "effect/http-api";
 //#region src/http/ActionHttp.d.ts
 /** What `fetchClient` takes: `client`'s options, and the `fetch` its calls send with. */
-export interface FetchClientOptions extends Options {
+export interface FetchClientOptions<E = HttpClientError.HttpClientError, R = never> extends Options<E, R> {
   /**
    * What each call sends with. Omitted: the global `fetch`, looked up on every call, so one
    * installed after the client is built, such as a test's stub, is used.
@@ -116,18 +116,21 @@ export declare function layer<const H extends AnyHttp, const Apps extends Served
  * `InvalidInput`, `Unauthenticated` or `Forbidden`), a native `HttpClientError` when the
  * server could not be reached or answered with a status or body the contract does not
  * declare, or a `SchemaError` when the success does not decode. An input that does not encode
- * fails with `InvalidInput`, and nothing is sent.
+ * fails with `InvalidInput`, and nothing is sent. A call also fails with what the client
+ * `transformClient` returns fails with, as it is, and requires what that client requires.
  */
 export declare function client<const H extends AnyHttp>(binding: H, options?: Options): Effect.Effect<Client<H>, never, HttpClient.HttpClient>;
+export declare function client<const H extends AnyHttp, E, R>(binding: H, options: Options<E, R>): Effect.Effect<Client<H, E, R>, never, HttpClient.HttpClient>;
 /**
  * `client` built once over `fetch`, for code that holds a client outside an Effect, such as
- * a browser app: its methods are the same Effects and require nothing, so each call runs
- * alone, as `Effect.runPromise(api.greet({ name }))`. The options are `client`'s, and
- * `fetch`.
+ * a browser app: its methods are the same Effects, which require only what `transformClient`
+ * requires, so a call without one runs alone, as `Effect.runPromise(api.greet({ name }))`. The
+ * options are `client`'s, and `fetch`.
  *
  * Each call sends with `options.fetch`, or with the global `fetch` as it is when the call
  * runs.
  */
 export declare function fetchClient<const H extends AnyHttp>(binding: H, options?: FetchClientOptions): Client<H>;
+export declare function fetchClient<const H extends AnyHttp, E, R>(binding: H, options: FetchClientOptions<E, R>): Client<H, E, R>;
 //#endregion
 export { type AnyHttp as Any, type Client, type Options as ClientOptions, type MethodError, Options$1 as Options };

package/dist/cli/commands.d.mts

@@ -1,6 +1,6 @@
 import "../contract/errors.mjs";
 import { Any } from "../Action.mjs";
-import { Effect, Runtime, Types } from "effect";
+import { Effect, Option, Runtime, Types } from "effect";
 import { CliError, Command } from "effect/cli";
 //#region src/cli/commands.d.ts
 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;

package/dist/cli/commands.mjs

@@ -206,8 +206,8 @@ const userErrorOf = (errors) => {
 		userMessage
 	}))));
 };
-const failingAsDerived = (actions, errorsOf) => {
-	const failure = userErrorOf([...new Set(actions.flatMap(errorsOf))]);
+const failingAsDerived = (errors) => {
+	const failure = userErrorOf([...new Set(errors)]);
 	return (self) => Effect.catchIf(self, (error) => !CliError.isCliError(error), failure);
 };
 const unreadableStdinField = (field, message) => new InvalidInput({
@@ -274,7 +274,7 @@ const command = (action, execute, options, errors) => {
 	const name = options?.name ?? kebab(action.name);
 	const render = options?.render;
 	const { flags, positional, decode, stdinHelp } = inputConfig(action, options?.positional ?? [], options?.aliases ?? {}, options?.stdin);
-	const failure = userErrorOf(errors);
+	const failing = failingAsDerived(errors);
 	assertDistinct("flag", [
 		...Object.keys(flags).map((field) => [`--${kebab(field)}`, `field ${field}`]),
 		...render === void 0 ? [] : [["--json", "render's --json"]],
@@ -285,7 +285,7 @@ const command = (action, execute, options, errors) => {
 		...input,
 		...Object.fromEntries(positional.map(({ field }, index) => [field, values[index] ?? Option.none()]))
 	});
-	const run = (parsed, rendered) => decode(parsed).pipe(Effect.flatMap(execute), Effect.catch(failure), Effect.flatMap((value) => printedOutput(action, value, rendered)), withStderrConsole, Effect.flatMap(Option.match({
+	const run = (parsed, rendered) => decode(parsed).pipe(Effect.flatMap(execute), failing, Effect.flatMap((value) => printedOutput(action, value, rendered)), withStderrConsole, Effect.flatMap(Option.match({
 		onNone: () => Effect.void,
 		onSome: Console.log
 	})));

package/dist/http/client.d.mts

@@ -7,11 +7,19 @@ 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,8 +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"]>>; };
+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

@@ -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
@@ -89,8 +92,11 @@ declare const McpCallError_base: Schema.Class<McpCallError, Schema.TaggedStruct<
  */
 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
@@ -103,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`,

package/dist/mcp/client.mjs

@@ -4,7 +4,7 @@ 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, Match, 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";
@@ -134,10 +134,10 @@ const callTool = (client, url, action, lift, refusedWith, input) => {
 		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/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
 
@@ -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

@@ -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
 

package/examples/kitchen-sink/src/cli.ts

@@ -3,6 +3,7 @@ import { Config, Effect, flow, Option } from "effect";
 import { Command } from "effect/cli";
 import { HttpClient, HttpClientRequest } from "effect/http";
 import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
 import { Http } from "./Api.js";
 
 // Entrypoint: `node --import tsx examples/kitchen-sink/src/cli.ts list-issues`.
@@ -41,27 +42,24 @@ const tracker = ActionCli.remote(Http, {
         `${attachment.name}: ${image.mimeType}, ${image.data.byteLength} bytes`,
     },
   },
-}).pipe(
-  // The connection is read from `Config` when a command runs, so `--help` needs none of it.
-  // It is provided on this command, so it reaches these commands' requests and no others.
-  // The token and the workspace are optional: `tracker get-status` is public and needs neither,
-  // and any other command without them gets the server's 401.
-  Command.provideEffect(
-    HttpClient.HttpClient,
-    Effect.gen(function* () {
-      const url = yield* Config.String("TRACKER_URL").pipe(
-        Config.withDefault("http://127.0.0.1:3000"),
-      );
+  // The connection, read from `Config` when a command runs, so `--help` needs none of it. It is
+  // these commands' client, so it reaches their requests and no others. The token and the
+  // workspace are optional: `tracker get-status` is public and needs neither, and any other
+  // command without them gets the server's 401.
+  client: Effect.gen(function* () {
+    const baseUrl = yield* Config.String("TRACKER_URL").pipe(
+      Config.withDefault("http://127.0.0.1:3000"),
+    );
 
-      const token = yield* Config.option(Config.Redacted("TRACKER_TOKEN"));
-      const workspace = yield* Config.option(Config.String("TRACKER_WORKSPACE"));
+    const token = yield* Config.option(Config.Redacted("TRACKER_TOKEN"));
+    const workspace = yield* Config.option(Config.String("TRACKER_WORKSPACE"));
 
-      const unchanged = (request: HttpClientRequest.HttpClientRequest) => request;
+    const unchanged = (request: HttpClientRequest.HttpClientRequest) => request;
 
-      return HttpClient.mapRequest(
-        yield* HttpClient.HttpClient,
+    return yield* ActionHttp.client(Http, {
+      baseUrl,
+      transformClient: HttpClient.mapRequest(
         flow(
-          HttpClientRequest.prependUrl(url),
           Option.match(token, {
             onNone: () => unchanged,
             onSome: (value) => HttpClientRequest.bearerToken(value),
@@ -71,10 +69,10 @@ const tracker = ActionCli.remote(Http, {
             onSome: (slug) => HttpClientRequest.setHeader("x-workspace", slug),
           }),
         ),
-      );
-    }),
-  ),
-);
+      ),
+    });
+  }),
+});
 
 // A result is printed on stdout. A failure goes to stderr, under an `ERROR` heading, as the JSON
 // HTTP sends, such as `{"_tag":"IssueNotFound","id":"ACME-9"}`, and the command exits 1.

package/examples/notes-service/README.md

@@ -104,7 +104,7 @@ src/
 ├── worker.ts          entrypoint: a fetch handler for a serverless host
 ├── stdio.ts           entrypoint: MCP for a local agent
 ├── commands.ts        the commands calling the server, one written by hand, and their connection
-├── cli.ts             entrypoint: the commands, given that connection
+├── cli.ts             entrypoint: the commands
 └── browser.ts         client module: promises for a web page
 test/
 ├── notes/             in process, with Action.client
@@ -144,7 +144,7 @@ test/
 | A CLI derived from the binding: an argument, a field on stdin | `src/commands.ts`                |
 | A command written by hand beside the derived ones             | `src/commands.ts`                |
 | A bulk import as one action, its command reading a file       | `src/notes/`, `src/commands.ts`  |
-| The CLI's connection, read from config when a command runs    | `src/commands.ts`, `src/cli.ts`  |
+| The CLI's connection, read from config when a command runs    | `src/commands.ts`                |
 | A missing token as one message, not a `ConfigError` report    | `src/commands.ts`                |
 | A promise client handling each declared error by its tag      | `src/browser.ts`                 |
 | Testing handlers and authorization with no transport          | `test/notes/notes.test.ts`       |

package/examples/notes-service/src/cli.ts

@@ -1,21 +1,15 @@
 import { NodeHttpClient, NodeRuntime, NodeServices } from "@effect/platform-node";
 import { Effect } from "effect";
 import { Command } from "effect/cli";
-import { HttpClient } from "effect/http";
 import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
-import { commands, connection } from "./commands.js";
+import { commands } from "./commands.js";
 
 // Entrypoint: `node --import tsx examples/notes-service/src/cli.ts list-notes`.
-// The commands of commands.ts, connected to a server.
-const notes = commands.pipe(
-  // Provided on the command, never around `Command.run`: the URL and the token are then read
-  // when a command runs, so `--help` and a mistyped flag need neither.
-  Command.provideEffect(HttpClient.HttpClient, connection),
-);
+// The commands of commands.ts, which read where the server is and the token when one runs.
 
 // A result is printed on stdout. A failure goes to stderr, under an `ERROR` heading, as the JSON
 // HTTP sends, such as `{"_tag":"NoteNotFound","id":"9"}`, and the command exits 1.
-Command.run(notes, { version: "1.0.0" }).pipe(
+Command.run(commands, { version: "1.0.0" }).pipe(
   Effect.provide([NodeHttpClient.layerUndici, NodeServices.layer]),
   ActionCli.logToStderr,
   NodeRuntime.runMain,

package/examples/notes-service/src/commands.ts

@@ -1,10 +1,44 @@
-import { Config, Console, Effect, FileSystem, flow } from "effect";
+import { Config, Console, Effect, FileSystem, Schema } from "effect";
 import { Argument, CliError, Command } from "effect/cli";
 import { HttpClient, HttpClientRequest } from "effect/http";
 import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
 import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
 import { Http } from "./Api.js";
 
+// What a command fails with when no token is configured: a tagged error of the CLI's own, printed
+// on stderr as `MissingToken: <message>` under an `ERROR` heading, and exit 1.
+class MissingToken extends Schema.TaggedError<MissingToken>()("MissingToken", {
+  message: Schema.String,
+}) {}
+
+// The binding's typed client, connected to where the server is and as who is calling, both read
+// from config. It is an Effect, not a client: every command here, the derived ones and your own,
+// runs it when it runs, so `--help` and a mistyped flag read nothing. It reaches these commands'
+// requests and no others.
+const api = Effect.gen(function* () {
+  const baseUrl = yield* Config.String("NOTES_URL").pipe(
+    Config.withDefault("http://127.0.0.1:3000"),
+  );
+
+  // Required, since every command but `get-status` is refused without one. Left as it is, a
+  // missing token prints as `ConfigError: …`; mapped, it prints the message, which says what to
+  // do. A CLI whose public commands must answer signed out reads the token with `Config.option`
+  // instead and adds the header when it is there.
+  const token = yield* Config.Redacted("NOTES_TOKEN").pipe(
+    Effect.mapError(
+      () =>
+        new MissingToken({
+          message: "NOTES_TOKEN is not set. Set it to your token: export NOTES_TOKEN=<your token>",
+        }),
+    ),
+  );
+
+  return yield* ActionHttp.client(Http, {
+    baseUrl,
+    transformClient: HttpClient.mapRequest(HttpClientRequest.bearerToken(token)),
+  });
+});
+
 // The file's format: each note a `# ` title line, a blank line and its body, the notes apart by
 // a blank line. A body line that starts as a title would is written with a backslash before it,
 // as Markdown escapes one, and `import` takes it off, so every note reads back as it was.
@@ -15,14 +49,14 @@ const unescape = (body: string) => body.replaceAll(/^\\(?=\\*# )/gmu, "");
 // A command of your own, for what no single action does: this one calls two and writes a file.
 // It is a native Effect CLI command, so its syntax and its output are what you write: `notes
 // export notes.md` takes its argument from `Argument`, as a flag would come from `Flag`. It
-// calls the server through the binding's typed client, on the `HttpClient` the derived commands
-// use, and writes with the `FileSystem` every Effect CLI command has.
+// calls the server through `api`, the client the derived commands call, and writes with the
+// `FileSystem` every Effect CLI command has.
 const exportNotes = Command.make(
   "export",
   { file: Argument.String("file").pipe(Argument.withDescription("The Markdown file to write.")) },
   ({ file }) =>
     Effect.gen(function* () {
-      const client = yield* ActionHttp.client(Http);
+      const client = yield* api;
       const files = yield* FileSystem.FileSystem;
       const { notes } = yield* client.listNotes();
       const whole = yield* Effect.forEach(notes, ({ id }) => client.getNote({ id }));
@@ -63,7 +97,7 @@ const importNotes = Command.make(
   },
   ({ text }) =>
     Effect.gen(function* () {
-      const client = yield* ActionHttp.client(Http);
+      const client = yield* api;
 
       if (text === "") return yield* Console.log("Created 0 notes");
 
@@ -93,6 +127,7 @@ const importNotes = Command.make(
 // it: test/commands.test.ts.
 export const commands = ActionCli.remote(Http, {
   name: "notes",
+  client: api,
   commands: {
     // `notes create-note --title Draft < draft.md`: the body is piped in, not a flag.
     createNote: { stdin: "body" },
@@ -104,34 +139,3 @@ export const commands = ActionCli.remote(Http, {
   // go here.
   subcommands: [exportNotes, importNotes],
 });
-
-// Where the server is and who is calling, read from config: the `HttpClient` every command
-// above calls with. It is an Effect, not a value, so that cli.ts provides it on the commands
-// and it runs when one of them does.
-export const connection = Effect.gen(function* () {
-  const url = yield* Config.String("NOTES_URL").pipe(Config.withDefault("http://127.0.0.1:3000"));
-
-  // Required, since every command but `get-status` is refused without one. A failure of what a
-  // command is provided is no action's error: left as it is, a missing token is reported as a
-  // crash, the log line `ERROR (#n): ConfigError: SchemaError(Expected string at
-  // ["NOTES_TOKEN"])`. Mapped to a `UserError`, it is printed as any failure of a command is:
-  // the message under an `ERROR` heading on stderr, and exit 1. `userMessage` is all that is
-  // printed, never `cause`: what the user needs from the cause goes into the message. A CLI
-  // whose public commands must answer signed out reads the token with `Config.option` instead
-  // and adds the header when it is there.
-  const token = yield* Config.Redacted("NOTES_TOKEN").pipe(
-    Effect.mapError(
-      (cause) =>
-        new CliError.UserError({
-          cause,
-          userMessage:
-            "NOTES_TOKEN is not set. Set it to your token: export NOTES_TOKEN=<your token>",
-        }),
-    ),
-  );
-
-  return HttpClient.mapRequest(
-    yield* HttpClient.HttpClient,
-    flow(HttpClientRequest.prependUrl(url), HttpClientRequest.bearerToken(token)),
-  );
-});

package/examples/notes-service/test/commands.test.ts

@@ -16,7 +16,7 @@ import { TestConsole } from "effect/testing";
 import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
 import * as Testing from "@gjermundgaraba/effect-actions/Testing";
 import { Http } from "../src/Api.js";
-import { commands, connection } from "../src/commands.js";
+import { commands } from "../src/commands.js";
 import { ImportNotes, Note, NoteNotFound } from "../src/notes/Notes.js";
 import { NoteStore } from "../src/notes/store.js";
 import { routes } from "../src/routes.js";
@@ -26,17 +26,16 @@ import { routes } from "../src/routes.js";
 // service a builder yields is provided here too (routes.test.ts).
 const served = Testing.layer(routes).pipe(Layer.provide(NoteStore.layerMemory));
 
-// Effect's own runner, given arguments instead of the process's. The console of `it.effect`
-// keeps every line printed, so a run returns the lines it added.
-const run = (token: string, args: ReadonlyArray<string>, stdin = "") =>
+// Effect's own runner, given arguments instead of the process's, and what the commands read from
+// the environment as a Layer, so the test decides whether a token is configured, whatever the
+// shell holds. The console of `it.effect` keeps every line printed, so a run returns the lines
+// it added.
+const connected = (environment: Record<string, string>, args: ReadonlyArray<string>, stdin = "") =>
   Effect.gen(function* () {
     const before = (yield* TestConsole.logLines).length;
 
     yield* Command.runWith(commands, { version: "0" })(args).pipe(
-      Effect.updateService(
-        HttpClient.HttpClient,
-        HttpClient.mapRequest(HttpClientRequest.bearerToken(token)),
-      ),
+      Effect.provide(ConfigProvider.layer(ConfigProvider.fromEnvRecord(environment))),
       Effect.provide(Stdio.layerTest({ stdin: Stream.make(new TextEncoder().encode(stdin)) })),
       Effect.provide(NodeServices.layer),
     );
@@ -44,15 +43,9 @@ const run = (token: string, args: ReadonlyArray<string>, stdin = "") =>
     return (yield* TestConsole.logLines).slice(before);
   });
 
-// The commands as cli.ts connects them, with what it reads from the environment given as a
-// Layer, so the test decides whether a token is configured, whatever the shell holds.
-const connected = (environment: Record<string, string>, args: ReadonlyArray<string>) =>
-  Command.runWith(commands.pipe(Command.provideEffect(HttpClient.HttpClient, connection)), {
-    version: "0",
-  })(args).pipe(
-    Effect.provide(ConfigProvider.layer(ConfigProvider.fromEnvRecord(environment))),
-    Effect.provide(NodeServices.layer),
-  );
+// A run as the caller `token` names.
+const run = (token: string, args: ReadonlyArray<string>, stdin = "") =>
+  connected({ NOTES_TOKEN: token }, args, stdin);
 
 const fitsAFile = (text: string) =>
   new TextDecoder().decode(new TextEncoder().encode(text)) === text;
@@ -270,9 +263,10 @@ describe("the commands", () => {
       const refused = yield* Effect.flip(connected({}, ["list-notes"]));
 
       expect(refused).toBeInstanceOf(CliError.UserError);
+      expect(refused).toHaveProperty("cause._tag", "MissingToken");
       expect(refused).toHaveProperty(
         "userMessage",
-        "NOTES_TOKEN is not set. Set it to your token: export NOTES_TOKEN=<your token>",
+        "MissingToken: NOTES_TOKEN is not set. Set it to your token: export NOTES_TOKEN=<your token>",
       );
 
       // What a person sees: that message, once, on stderr, and no report of a `ConfigError`.
@@ -280,7 +274,7 @@ describe("the commands", () => {
         expect.stringContaining("NOTES_TOKEN is not set."),
       ]);
 
-      // The token is read when a command runs, so its help needs none.
+      // The token is read when a command runs, so help needs none.
       yield* connected({}, ["list-notes", "--help"]);
 
       expect(yield* TestConsole.logLines).toHaveLength(2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjermundgaraba/effect-actions",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Define Effect action contracts once and project them onto HTTP, MCP, Effect RPC, native Toolkits, and CLIs.",
   "keywords": [
     "ai-agents",