@gjermundgaraba/effect-actions 0.18.2 → 0.19.0

package/dist/ActionMcp.d.mts

@@ -7,9 +7,9 @@ import { McpSchema, McpServer } from "effect/ai";
 import { HttpRouter } from "effect/http";
 //#region src/mcp/ActionMcp.d.ts
 /**
- * An MCP server, over HTTP or stdio: every native `McpServer.layerStdio` option except
- * `protocols`, the server information, `instructions` and `extensions`, the actions `A` that
- * are its tools, and the native features it serves beside them.
+ * An MCP server, over HTTP or stdio: every native `McpServer.layerStdio` option but `protocols`,
+ * the server information, `instructions` and `extensions` among them, the actions `A` that are
+ * its tools, and the native features it serves beside them.
  */
 export interface Options<E = never, R = never, A extends Any = Any> extends Omit<Parameters<typeof McpServer.layerStdio>[0], "protocols"> {
   /**
@@ -20,7 +20,14 @@ export interface Options<E = never, R = never, A extends Any = Any> extends Omit
   /**
    * Native MCP features served beside the actions' tools, such as `McpServer.resource`,
    * `McpServer.prompt` and `McpServer.toolkit` layers merged into one. They register on this
-   * server's registry; merged beside it instead, they register on another and are not served.
+   * server's registry and run with the services they were built with, and no `authorize` runs for
+   * them.
+   *
+   * **Gotchas**
+   *
+   * - Merged beside the endpoint instead of passed here, they register on another registry and are never served, without an error.
+   * - A service provided to this layer itself is built again for the features alone, so a resource reads another store than the tools write: provide it around the endpoint.
+   * - They never receive a request's services, so they cannot read the caller: content that depends on the caller is an action.
    */
   readonly features?: Layer.Layer<never, E, R> | undefined;
 }
@@ -32,6 +39,21 @@ export interface Options<E = never, R = never, A extends Any = Any> extends Omit
 export interface LayerHttpOptions<E = never, R = never, A extends Any = Any> extends Options<E, R, A>, Omit<Parameters<typeof McpServer.layerHttp>[0], "protocols" | "path" | "allowSessionTermination"> {
   /** The endpoint's route; defaults to `/mcp`. */
   readonly path?: HttpRouter.PathInput;
+  /**
+   * The descriptor the protected tools' contracts name, whose provider, built by
+   * `Authentication.layer`, the routes provide. On an endpoint of protected tools only, every
+   * request authenticates before it is decoded; on a mixed one, anyone may discover the server,
+   * list its tools, cancel, and call a public tool in a 2026-07-28 request, and everything else
+   * authenticates first.
+   *
+   * **Gotchas**
+   *
+   * - A credential a request presents is still verified, on a public tool's call too: an expired or invalid one answers 401, its challenge naming `invalid_token`, on which a client refreshes it or signs in again.
+   * - `tools/list` names every tool, protected ones included: serve public tools on an endpoint of their own if signed-out callers must not see the rest.
+   * - A client of a 2025 revision opens a session, which on an endpoint serving a protected tool only a signed-in caller does: it signs in for every request there, a public tool's call and `tools/list` included.
+   * - Every prompt and resource request needs a credential, listings included: to offer them signed out, serve them on an endpoint without protected tools.
+   * - A handler that sends a notification starts the response, so a refusal after it is an `isError: true` tool result, not the 401 or 403 a client re-authorizes on: refuse in `authorize`.
+   */
   readonly authentication?: Any$1;
   /**
    * Whether MCP 2026-07-28 clients may subscribe, holding a stream open for list changes and
@@ -43,9 +65,10 @@ export interface LayerHttpOptions<E = never, R = never, A extends Any = Any> ext
   /**
    * `true` runs a server per request, as Effect's `McpServer.layerHttpRequestScoped` does, for a
    * host such as Cloudflare Workers where nothing may outlive a request. It speaks MCP 2026-07-28
-   * alone, so a client that opens with `initialize` is refused, and it keeps no session. It has
-   * no subscriptions, so `allowSubscriptions` is ignored, and native `features` send no
-   * list-change notification and cannot use `McpServer.elicit`.
+   * alone, so a client that opens with `initialize` is refused; it keeps no session and takes only
+   * `POST`, a `DELETE` answering 405. It has no subscriptions, so `allowSubscriptions` is ignored,
+   * and native `features` send no list-change notification. `McpServer.elicit` reaches no client
+   * on it, as Effect's `McpServer.layerHttpRequestScoped` says.
    */
   readonly requestScoped?: boolean | undefined;
 }
@@ -61,34 +84,38 @@ type Inferring<D, A extends Any> = [D] extends [undefined] ? [Protected<A>] exte
  * Serve MCP tools over one Streamable HTTP endpoint, speaking MCP 2026-07-28, 2025-11-25 or
  * 2025-06-18, as the client negotiates. A 2026-07-28 request stands alone; a client of a 2025
  * revision opens a session with `initialize`, which holds what it sent there and no identity,
- * and lasts until that client ends it with a DELETE, answered 204, or the process stops. For a
- * serverless host, see `requestScoped`.
- *
- * Protected tools need the `authentication` descriptor their contracts name, and the
- * provider `Authentication.layer` builds from it. On an endpoint of protected tools only,
- * every request authenticates before it is decoded. On a mixed endpoint, anyone may discover
- * the server, list its tools, cancel, and call a public tool in a 2026-07-28 request;
- * everything else authenticates first, a session's every request included, so a protected
- * tool's description is listed to anyone but run only for its caller.
- * On a Bearer endpoint, a protected tool's call refused with `Unauthenticated`, or with
- * `Forbidden` naming scopes, is answered with its HTTP status and challenge, 401 or 403, as MCP
- * authorization requires, unless its response has started; any other failure is a tool result. Claude Code connects with
- * `claude mcp add --transport http <name> <url>`. In a tool call, what middleware provides per request wins over
- * what the endpoint was built with; native `features` read only what they were built with,
- * never a request's. Never provide an identity at startup: a tool call takes its identity
- * only from the request it authenticated.
+ * and lasts until that client ends it with a DELETE, answered 204, or the process stops. Protected
+ * tools need `authentication`; for a serverless host, see `requestScoped`. In a tool call, what
+ * middleware provides per request wins over what the endpoint was built with.
  * Guide: `docs/ActionMcp.md` in this package; in an application: `examples/mcp-tools/`.
+ *
+ * **Gotchas**
+ *
+ * - A success is `isError: false` with `structuredContent` its JSON and the same JSON as one text block, both `null` for an action without `success`; an `Action.Image` field is left out of `structuredContent` and its text, its block following them, and a success of images alone has no `structuredContent`.
+ * - A declared error is an `isError: true` tool result in a 200 holding its JSON as one text block, with no `structuredContent`; a refusal is answered as `Action.Unauthenticated` and `Action.Forbidden` say.
+ * - Arguments that do not decode never reach the handler: an `isError: true` result in a 200, text `Invalid parameters for tool '<name>': …`, or for a 2025-06-18 client a JSON-RPC error.
+ * - A defect, an undeclared failure, or a success or an error that does not encode is `isError: true`, text `Tool execution failed due to an internal server error.`: the cause goes to the log and to the call's `ErrorReporter`s, never to the client.
+ * - An unknown tool is a JSON-RPC error `-32602` in a 200; a body that is not JSON a JSON-RPC error `-32700` in a 200; a `Content-Type` missing or not JSON an empty 415; another HTTP method an empty 405 with `Allow: POST, DELETE`, `Allow: POST` where `requestScoped`, or the 401 of an endpoint with authentication when signed out.
+ * - A 2025-11-25 or 2025-06-18 client gets `structuredContent` only for a success that is an object: any other success arrives as its text block alone, a string unquoted.
+ * - A client asking for an earlier revision, such as 2025-03-26, is offered 2025-11-25, so a client speaking only that earlier one cannot connect.
+ * - A request body is read whole, however large, and a 2025 session holds what its `initialize` sent until it ends, so an oversized `initialize` costs memory for that long: limit bodies as `ActionHttp.layer` says.
  */
 export declare function layerHttp<const Apps extends Served, const O extends Selection<ActionOf<Member<Apps>>> = {}, E = never, R = never, const D extends Any$1 | undefined = undefined>(implementations: Apps, options: LayerHttpOptions<E, R, ActionOf<Member<Apps>>> & O & NoInfer<Known<O, LayerHttpOptions<E, R, Any>>> & NoInfer<Required<SelectedOf<O, Apps>>> & Matching<NoInfer<SelectedOf<O, Apps>>, NoInfer<D>> & Inferring<D, NoInfer<SelectedOf<O, Apps>>>): Layer.Layer<never, BuildError<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>> | Cause.IllegalArgumentError | E, ServerBuildServices<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>> | HttpRouter.HttpRouter | HttpRouter.Request.From<"Requires", HttpToolRequestContext<RemoteRequest<Member<Apps>, SelectedOf<O, Apps>>>> | ProviderOf<D> | Features<R>>;
 /**
  * Serve MCP tools through newline-delimited JSON-RPC on standard I/O, speaking MCP
  * 2026-07-28, 2025-11-25 or 2025-06-18, as the host negotiates: the whole
  * program of an MCP subprocess, which succeeds once the host closes its side and every call
- * in flight has been answered. A signal interrupts it.
+ * in flight has been answered. A signal interrupts it. Its own Effect logs and `Console` output
+ * go to stderr, since stdout carries the protocol. The host supplies the `Stdio` service, and
+ * provides the identity around `runStdio`; arguments are tool input only and never establish
+ * request identity or authority, and each implementation's `authorize` runs for its protected
+ * actions. Its tool results, and how it answers each revision and an earlier one asked for, are
+ * `layerHttp`'s.
+ *
+ * **Gotchas**
  *
- * Effect logs go to stderr, since stdout carries the protocol. The host supplies the
- * `Stdio` service and the identity. Arguments are tool input only and never establish
- * request identity or authority; each implementation's `authorize` runs for its protected actions.
+ * - A line that is not JSON goes unanswered, with no `-32700` as over HTTP, and the lines after it are still answered.
+ * - The layers provided around it log to stdout, among the protocol's lines: apply `ActionCli.logToStderr` to the program, last, as its JSDoc says.
  */
 export declare function runStdio<const Apps extends Served, const O extends Selection<ActionOf<Member<Apps>>> = {}, E = never, R = never>(implementations: Apps, options: Options<E, R, ActionOf<Member<Apps>>> & O & NoInfer<Known<O, Options<E, R, Any>>>): Effect.Effect<void, BuildError<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>> | Cause.IllegalArgumentError | E, BuildServices<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>> | Stdio.Stdio | ToolRequestContext<ServedRequest<Member<Apps>, SelectedOf<O, Apps>>> | Features<R>>;
 //#endregion

package/dist/ActionMcp.mjs

@@ -1,5 +1,5 @@
 import { Anyone, assertAuthentication } from "./contract/caller.mjs";
-import { assertOnce } from "./contract/names.mjs";
+import { assertOnce, heldOnce } from "./contract/names.mjs";
 import { projectedErrors } from "./contract/declared.mjs";
 import { hintsOf } from "./contract/hints.mjs";
 import { acquire, provideHandlers, select, toList } from "./contract/implementation.mjs";
@@ -26,9 +26,9 @@ const toolJsonSchema = (schema, strict) => {
 };
 const assertToolShapes = (lifted) => {
 	const inputs = lifted.map(([action]) => action).filter((action) => !isToolArgumentsSchema(toolJsonSchema(Schema.toCodecJson(action.input), true))).map(({ name }) => name);
-	if (inputs.length > 0) throw new Error(`MCP tool input must be one object with keys, such as a struct: ${inputs.join(", ")}`);
+	if (inputs.length > 0) throw new Error(`MCP tool input must be one object with keys, such as a struct: ${inputs.join(", ")} (wrap a union, an array or a scalar in a field, omit input for no arguments, or leave the action out of actions)`);
 	const misplaced = lifted.filter(([action, lift]) => isMisplaced(action, lift)).map(([{ name }]) => name);
-	if (misplaced.length > 0) throw new Error(`MCP media must be the success or an array of it, or a top-level field of a struct success, one, optional or a required array: ${misplaced.join(", ")}`);
+	if (misplaced.length > 0) throw new Error(`MCP media must be the success or an array of it, or a top-level field of a struct success, one, optional or a required array: ${misplaced.join(", ")} (make the image such a field, or give an optional array as a required one, empty when absent; an image in input or an error is not served over MCP, so leave that action out of actions)`);
 };
 const nativeInternalErrorText = "Tool execution failed due to an internal server error.";
 const textErrorResult = (text) => new McpSchema.CallToolResult({
@@ -118,13 +118,13 @@ const registerTools = Effect.fnUntraced(function* (apps, authentication) {
 	}
 });
 const server = (apps, transport, features = Layer.empty, authentication) => {
-	assertOnce("MCP tool", apps.flatMap((app) => app.actions));
+	assertOnce("MCP tool", apps.flatMap((app) => app.actions), heldOnce);
 	const lifted = apps.flatMap((app) => app.actions.map((action) => [action, liftOf(action.success)]));
 	assertToolShapes(lifted);
 	const names = new Set(lifted.map(([{ name }]) => name));
 	const register = Effect.gen(function* () {
 		const namesClaimedByFeatures = (yield* McpServer.McpServer).tools.flatMap(({ tool }) => names.has(tool.name) ? [tool.name] : []);
-		if (namesClaimedByFeatures.length > 0) return yield* Effect.die(/* @__PURE__ */ new Error(`Duplicate MCP tool: ${namesClaimedByFeatures.join(", ")}, claimed by an action and a native feature`));
+		if (namesClaimedByFeatures.length > 0) return yield* Effect.die(/* @__PURE__ */ new Error(`Duplicate MCP tool: ${namesClaimedByFeatures.join(", ")}, claimed by an action and a native feature (rename the native tool, or leave the action out of actions)`));
 		yield* registerTools(apps, authentication);
 	});
 	return Layer.effectDiscard(register).pipe(Layer.provide(features), Layer.provide(transport), Layer.fresh, provideHandlers(apps));

package/dist/ActionRpc.d.mts

@@ -18,6 +18,7 @@ type RpcOf<A extends Any$1, E extends Errors, D> = A extends Any$1 ? Rpc.Rpc<A["
  * this package, serves the same; `layer` serves it and `client` calls it.
  */
 export interface Binding<Actions extends ReadonlyArray<Any$1>, E extends Errors = [], D extends Any$2 | undefined = undefined> {
+  /** The descriptor authenticating its protected actions, or `undefined` when it names none. */
   readonly authentication: D;
   /** The exact actions bound to this binding. */
   readonly actions: Actions;
@@ -41,8 +42,15 @@ export interface Any {
 }
 /** Contract-level configuration shared by servers and clients. */
 export interface Options<E extends Errors = Errors> {
-  /** Layer middleware's errors, which every rpc declares: one schema, or a list. */
+  /**
+   * What the layer's `middleware` fails with, which every rpc declares so clients decode it:
+   * one schema, or a list.
+   */
   readonly error?: E | E[number];
+  /**
+   * `Authentication.make(...)` of the protected actions' identity, which authenticates each of
+   * their messages: required when the binding holds a protected action, and of its identity.
+   */
   readonly authentication?: Any$2;
 }
 /**
@@ -77,48 +85,50 @@ type RpcLayer<B extends Any, Apps extends Served, M extends Middleware, A extend
 export interface LayerOptions<M extends Middleware = [], A extends Any$1 = never> {
   /**
    * The actions it serves, among the binding's actions the implementations hold: `[GetUser]`.
-   * Defaults to every one of them. A layer whose middleware requires the identity lists
-   * protected actions only.
+   * Defaults to every one of them.
    */
   readonly actions?: ReadonlyArray<A> | undefined;
   /**
-   * Native rpc middleware every served rpc runs, the first innermost: inside the
-   * authentication of a protected rpc, outside its decoding. Server-only: the binding's group,
-   * which clients use, carries none. A middleware requiring the identity needs a layer
-   * serving only protected actions.
+   * Native rpc middleware every served rpc runs on each message, the first innermost: inside
+   * the authentication of a protected rpc, so none provides what a verifier reads, and outside
+   * its decoding, so it also sees input that does not decode. Server-only: the binding's group,
+   * which clients use, carries none.
+   *
+   * **Gotchas**
+   *
+   * - A middleware requiring the identity leaves it owed on a layer serving a public action: bind the protected actions apart, or read the identity with `Effect.serviceOption`, which a public rpc's call lacks.
+   * - A middleware provides a service only to those listed before it and the handlers, and only in a list written in place as a tuple: listed earlier, or in an array-typed list, it leaves the service owed.
+   * - Router middleware around the layer runs once per WebSocket, at its upgrade, so its value holds for the whole connection: what differs per message needs a listed middleware.
    */
   readonly middleware?: M;
 }
 /**
  * Serve the binding's actions among `implementations` with Effect's own `RpcServer`, or those
- * its `actions` lists, as `ActionHttp.layer` selects them. The host provides the protocol,
- * such as `RpcServer.layerProtocolWebsocket` or `layerProtocolHttp` and its JSON serialization:
- * the layer refuses to build under a protocol that does not speak JSON. A protected rpc
- * authenticates each message from its headers with the binding's descriptor, outermost; then
- * the layer's `middleware` runs, then the input is decoded, a failure answering `InvalidInput`,
- * then the implementation's `authorize` and the handler, as on every surface.
+ * its `actions` lists, as `ActionHttp.layer` selects them, under the protocol and JSON
+ * serialization the host provides. Each message of a protected rpc authenticates from its own
+ * headers with the binding's descriptor; then the listed `middleware` runs, the input decodes,
+ * and the implementation's `authorize` and the handler run, as on every surface. The layer
+ * fails as the builders do and needs at startup what they need; per request it owes, as router
+ * request markers, what the authorizers and handlers read until its `middleware` provides it,
+ * or, over a router-mounted protocol, the route's request context.
+ * A protected action's identity comes from its authentication alone.
  *
- * The server serves its own copy of the binding's group, whose payloads, successes and errors
- * are the actions' JSON and which carries no native middleware: the protocol decodes a payload before
- * any middleware runs, and answers one that does not decode with a defect, so each handler
- * runs the authentication and the middleware itself, then decodes the input. A defect is
- * logged with its cause, reported to the call's `ErrorReporter`s, and answered as its
- * request's generic failure, never failing the connection's other calls; a declared failure is
- * the caller's answer, and not reported.
+ * **Gotchas**
  *
- * The layer fails as the builders do, needs at startup what they need, and per request what
- * each implementation's authorization and the handlers of the actions it serves need, as
- * router request markers, until its `middleware` provides them: over a router-mounted
- * protocol, the route's request context does too. The identity of a protected action is
- * provided by its authentication alone.
+ * - Provide the protocol to this layer, inside what `HttpRouter.serve` serves: `RpcServer.layerProtocolWebsocket` and `layerProtocolHttp` add their route to that router, and provided around `HttpRouter.serve` they leave `HttpRouter` owed.
+ * - An rpc the layer does not serve ends its call with `Unknown request tag`, as does every rpc of a second `ActionRpc.layer` given the same protocol, which never receives a message: serve a protocol's rpcs from one layer, or give the second a protocol on another path.
+ * - A declared error, or `InvalidInput` for input that does not decode, is the call's typed failure; a refusal is answered as `Action.Unauthenticated` and `Action.Forbidden` say; the socket stays open, so a token may expire under it and a client handles `Unauthenticated` itself.
+ * - A defect, an undeclared failure, a middleware that throws, or a success or an error that does not encode ends that call with an `Error` whose message is `Internal server error`, its cause logged and reported to the call's `ErrorReporter`s; the connection's other calls go on.
+ * - An `ErrorReporter` is given only what ends a call with `Internal server error`, never a declared failure, a refusal or `InvalidInput`, unlike `ActionHttp.layer`'s `Info`: an alert counting declared failures counts none from rpcs.
+ * - An rpc's credential is read from its headers alone: an API key `in: "query"` never reaches authentication.
+ * - Over a protocol with no router, such as `RpcServer.layerProtocolSocketServer` or `layerProtocolStdio`, there is no HTTP request or route: a provider publishing a `protectedResource` leaves `HttpRouter` owed, and a verifier yielding a request service leaves it owed.
  */
 export declare function layer<const B extends Any, const Apps extends Served>(binding: B, implementations: Apps): RpcLayer<B, Apps, []>;
 export declare function layer<const B extends Any, const Apps extends Served, const O extends LayerOptions<Middleware, B["actions"][number]>>(binding: B, implementations: Apps, options: O & ServerOnly<MiddlewareOf<O, Middleware>, B["error"]> & NoInfer<Known<O, LayerOptions<Middleware>>>): RpcLayer<B, Apps, MiddlewareOf<O, Middleware>, Selected<O, B["actions"][number]>>;
 /**
  * What one call of an action `A` fails with, beside the binding's errors `E`: its declared and
- * built-in errors, and Effect's own `RpcClientError`. Input that does not encode is
- * `InvalidInput`, and nothing is sent; an answer that does not decode is a defect, as the
- * native client makes it.
+ * built-in errors, and Effect's own `RpcClientError` when the server could not be reached. An
+ * answer that does not decode is a defect, as the native client makes it.
  */
 export type MethodError<A extends Any$1, E extends BindingError = never> = A["error"][number]["Type"] | E["Type"] | BuiltIns["Type"] | RpcClientError.RpcClientError;
 type Method<A extends Any$1, E extends BindingError> = Call<A, Effect.Effect<A["success"]["Type"], MethodError<A, E>>>;
@@ -135,14 +145,17 @@ export type Client<B extends Any> = { readonly [A in B["actions"][number] as A["
 export type ClientOptions = Omit<NonNullable<Parameters<typeof RpcClient.make>[1]>, "flatten">;
 /**
  * Effect's native `RpcClient` for a binding, one method per action taking the action's input
- * directly: `client.greet({ name })`, as `ActionHttp.client`'s. The argument may be omitted
- * when `{}` is a valid input. Requires the native client `Protocol` and a `Scope`, as
- * `RpcClient.make` does; headers set with `RpcClient.withHeaders` around a call go with its
- * message. The native client itself stays available: `RpcClient.make(Rpc.group)`.
+ * directly: `client.greet({ name })`, as `ActionHttp.client`'s, the argument omitted when `{}`
+ * is a valid input, each call failing with its `MethodError`. Requires the native client
+ * `Protocol` and a `Scope`, as `RpcClient.make` does; headers set with `RpcClient.withHeaders`
+ * around a call go with its message. The native client stays available:
+ * `RpcClient.make(Rpc.group)`.
+ *
+ * **Gotchas**
  *
- * A call fails with a declared error value (the action's own, the binding's, a built-in
- * `InvalidInput`, `Unauthenticated` or `Forbidden`, or on a protected rpc its descriptor's),
- * or with Effect's own `RpcClientError` when the server could not be reached.
+ * - It drops undeclared input fields as it encodes, and fails with `InvalidInput`, sending nothing, for an input that does not encode.
+ * - A browser WebSocket cannot set an `Authorization` header on its upgrade, so under Bearer a protected call without its own token fails with `Unauthenticated`, `A bearer token is required.`: send the token on each call with `RpcClient.withHeaders`.
+ * - The socket belongs to the Layer providing the protocol, not to the `Scope` around the client: provided around one call, it opens a socket for that call alone.
  */
 export declare function client<const B extends Any>(binding: B, options?: ClientOptions): Effect.Effect<Client<B>, never, RpcClient.Protocol | Scope.Scope>;
 //#endregion

package/dist/ActionRpc.mjs

@@ -93,7 +93,7 @@ function client(binding, options) {
 		const native = client;
 		return Object.fromEntries(binding.actions.map((action) => {
 			const method = native[action.name];
-			if (method === void 0) throw new Error(`No client method for ${action.name}`);
+			if (method === void 0) throw new Error(`No client method for ${action.name} (use the binding \`ActionRpc.make\` returned, whose group holds this action's rpc)`);
 			return [action.name, checked(action, (payload) => method(payload))];
 		}));
 	});

package/dist/ActionToolkit.d.mts

@@ -17,6 +17,12 @@ type ToolFor<App, Listed extends Any> = App extends unknown ? Serving<App, Liste
  * implementations: the `layer` of a `make` call serves the tools it selected in any `toolkit`
  * of the same implementations, while two implementations never run each other's handlers,
  * even with tools of one name.
+ *
+ * **Gotchas**
+ *
+ * - Two `make` calls of one implementation share their handlers: their `layer`s, given different startup services and provided together, serve both toolkits with one of them; use separate implementations for separate services.
+ * - Another implementation's `layer` with tools of the same names type-checks, and the first call dies with Effect's `Cannot read properties of undefined (reading 'context')`: provide the `layer` the same `make` returned.
+ * - `handle(name, arguments)` on `yield* toolkit` takes the JSON a model sends; its handler starts when `handle` runs, so the caller is provided around the whole `handle(...).pipe(Effect.flatMap(Stream.runCollect))`, never around the stream alone.
  */
 export interface Tools<T extends Record<string, Tool.Any>, E, R> {
   /**
@@ -28,7 +34,7 @@ export interface Tools<T extends Record<string, Tool.Any>, E, R> {
 }
 /**
  * One call of a tool, as `needsApproval` receives it: its action's name, the action, and
- * the call's decoded input. Checking `name` narrows the other two to that action's.
+ * the call's decoded input.
  */
 export type ToolCall<A extends Any = Any> = A extends Any ? {
   readonly name: A["name"];
@@ -39,28 +45,38 @@ export type ToolCall<A extends Any = Any> = A extends Any ? {
 export interface Options<A extends Any> {
   /**
    * The actions that are tools, among the implementations' actions: `[GetUser, RenameUser]`.
-   * Each keeps its implementation's authorization and builder. Defaults to every action of them.
+   * Each keeps its implementation's authorization and builder. Defaults to every action of them,
+   * one added to an implementation later included.
    */
   readonly actions?: ReadonlyArray<A> | undefined;
   /**
    * Whether a model's call needs approval before it runs: a boolean, or an Effect of one, for
    * each call, with Effect's native approval context. `LanguageModel` asks for approval
-   * instead of calling the tool when it is `true`. The Effect runs in the caller's context and
-   * requires nothing, so it reads the caller with `Effect.serviceOption`. Defaults to none.
+   * instead of calling the tool when it is `true`, and when the Effect fails, so a policy that
+   * cannot be read asks; a defect, a throw included, ends the turn as Effect's own does. The
+   * Effect runs in the caller's context and requires nothing, so it reads the caller with
+   * `Effect.serviceOption`. Defaults to none.
+   *
+   * **Gotchas**
+   *
+   * - `call` ranges over every action of the implementations, whatever `actions` lists: check `call.name` to narrow `action` and `input`.
+   * - Approval authorizes nothing, which stays `authorize`'s, and only a model's turn asks for it: `handle` and `ActionMcp` never do.
    */
-  readonly needsApproval?: (call: ToolCall<A>, context: Tool.NeedsApprovalContext) => boolean | Effect.Effect<boolean>;
+  readonly needsApproval?: (call: ToolCall<A>, context: Tool.NeedsApprovalContext) => boolean | Effect.Effect<boolean, unknown>;
 }
 /**
  * Project implementations into Effect's native AI toolkit: one tool per action, keyed by its
  * name, of the listed `actions` or, without them, of every action of the implementations.
- *
- * Unlike MCP, calls return the action's native success/failure values directly.
- * Build services are needed to construct `layer`; request services are needed
- * when the resulting toolkit handles a call, the identity an implementation's `authorize`
- * reads included: the caller provides it. `needsApproval` marks the calls a model must have
- * approved; it authorizes nothing, which stays `authorize`'s.
- * Guide: `docs/ActionToolkit.md` in this package; a loop served behind a route, with approval:
+ * Startup services build `layer`; request services, the identity `authorize` reads included,
+ * are provided around each turn or call the toolkit handles. Guide: `docs/ActionToolkit.md` in
+ * this package; a loop served behind a route, with approval:
  * `examples/kitchen-sink/src/assistant/`.
+ *
+ * **Gotchas**
+ *
+ * - A success is a result with `isFailure: false`, `result` the value and `encodedResult` its JSON; a declared error a result with `isFailure: true` and `result` the error, which the model reads, never a raised failure; a refusal as `Action.Unauthenticated` and `Action.Forbidden` say.
+ * - Arguments that do not decode are a result with `isFailure: true` whose `result` is an `AiError` with `reason` a `ToolParameterValidationError`, never `InvalidInput`, and neither `authorize` nor the handler runs; undeclared arguments are dropped and the call runs.
+ * - A defect, or a failure the action's errors reject, is the call's defect; a success or an error that does not encode fails the call with an `AiError`, `Failed to encode result for tool …`.
  */
 export declare function make<const Apps extends Served, const O extends Options<ActionOf<Member<Apps>>> = {}>(implementations: Apps, ...options: OptionalUnless<O, Options<ActionOf<Member<Apps>>> & O & NoInfer<Known<O, Options<Any>>>>): Tools<{ readonly [T in ToolFor<Member<Apps>, Offered<O, ActionOf<Member<Apps>>>> as T["name"]]: T; }, BuildError<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>>, BuildServices<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>>>;
 /** A tool call a model asked to have approved, which no answer has resolved yet. */
@@ -70,7 +86,10 @@ export interface Approval {
   readonly toolCallId: string;
   /** The tool's name, the action's. */
   readonly name: string;
-  /** The call's arguments as the model sent them: show them as JSON. */
+  /**
+   * The call's arguments as the model sent them: show them as JSON, and decode them with
+   * `Schema.toCodecJson(<action>.input)`, the tool's parameters, only where you read a field.
+   */
   readonly params: unknown;
 }
 /**

package/dist/ActionToolkit.mjs

@@ -1,4 +1,4 @@
-import { assertOnce } from "./contract/names.mjs";
+import { assertOnce, heldOnce } from "./contract/names.mjs";
 import { projectedErrors } from "./contract/declared.mjs";
 import { hintsOf } from "./contract/hints.mjs";
 import { Implementation, acquire, provideHandlers, select, toList } from "./contract/implementation.mjs";
@@ -22,12 +22,15 @@ const jsonToolOf = (action) => Tool.make(action.name, {
 function make(apps, options) {
 	const served = select(toList(apps), options?.actions);
 	const needsApproval = options?.needsApproval;
-	assertOnce("tool", served.flatMap((app) => app.actions));
-	const toolOf = (action, app) => Object.assign(needsApproval === void 0 ? jsonToolOf(action) : jsonToolOf(action).setNeedsApproval((input, context) => needsApproval({
-		name: action.name,
-		action,
-		input
-	}, context)), { id: `${Implementation.runKey(app)}/${action.name}` });
+	assertOnce("tool", served.flatMap((app) => app.actions), heldOnce);
+	const toolOf = (action, app) => Object.assign(needsApproval === void 0 ? jsonToolOf(action) : jsonToolOf(action).setNeedsApproval((input, context) => {
+		const decided = needsApproval({
+			name: action.name,
+			action,
+			input
+		}, context);
+		return Effect.isEffect(decided) ? Effect.catch(decided, () => Effect.succeed(true)) : decided;
+	}), { id: `${Implementation.runKey(app)}/${action.name}` });
 	const toolkit = Toolkit.make(...served.flatMap((app) => app.actions.map((action) => annotateFromContract(toolOf(action, app), action))));
 	return {
 		toolkit,