@gjermundgaraba/effect-actions 0.12.0 → 0.14.0

package/README.md

@@ -5,8 +5,8 @@ native Toolkit, and run it from a CLI. Same schemas, same handler, Effect's own
 underneath.
 
 **If you are a coding agent**, start at [docs/README.md](docs/README.md), not here, and read
-one page per tool call: pages read together are cut. It routes every task, protecting an
-action and limiting request bodies included, to its page and its example.
+one page per tool call, again alone if its output says it was truncated. It routes every task,
+protecting an action and limiting request bodies included, to its page and its example.
 
 ## Looks like this
 
@@ -100,11 +100,11 @@ const greeting = Effect.gen(function* () {
 ## Install
 
 ```sh
-pnpm add @gjermundgaraba/effect-actions effect@~4.0.2
+pnpm add @gjermundgaraba/effect-actions effect@~4.0.4
 ```
 
 It needs TypeScript 7 or newer and is ESM only
-([docs/setup.md](docs/setup.md#install)). Add `@effect/platform-node@~4.0.2` to serve or run a CLI from Node. Every module is a
+([docs/setup.md](docs/setup.md#install)). Add `@effect/platform-node@~4.0.4` to serve or run a CLI from Node. Every module is a
 subpath import (`.../Action`, `.../ActionHttp`, ...); there is no package root, so a
 contracts-only bundle never loads a server.
 

package/dist/Action.d.mts

@@ -24,7 +24,9 @@ export interface Mcp {
   readonly title?: string | undefined;
   /**
    * `annotations.destructiveHint`, meaningful for a write only. Left out, a write is listed as
-   * destructive, MCP's default: state `false` for one that only adds or updates.
+   * destructive, MCP's default: state `false` for one that only adds, MCP's "only additive
+   * updates". One that replaces, removes or interrupts, such as an edit or a restart, stays
+   * destructive.
    */
   readonly destructiveHint?: boolean | undefined;
   /** `annotations.idempotentHint`, meaningful for a write only. */

package/dist/ActionToolkit.d.mts

@@ -2,7 +2,7 @@ import { BuiltIns } from "./contract/errors.mjs";
 import { ActionOf, BuildError, BuildServices, Holding, Known, Member, Offered, OptionalUnless, RequestOf, SelectedOf, Served, Serving } from "./contract/implementation.mjs";
 import { Action_d_exports, Any } from "./Action.mjs";
 import { Effect, Layer, Schema } from "effect";
-import { Tool, Toolkit } from "effect/ai";
+import { Prompt, Tool, Toolkit } from "effect/ai";
 //#region src/toolkit/ActionToolkit.d.ts
 type NativeTool<A extends Any, R> = Tool.Tool<A["name"], {
   readonly parameters: Schema.toCodecJson<A["input"]>;
@@ -63,4 +63,26 @@ export interface Options<A extends Any> {
  * `examples/kitchen-sink/src/assistant/`.
  */
 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. */
+export interface Approval {
+  /** What a `tool-approval-response` names to answer it. */
+  readonly approvalId: string;
+  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. */
+  readonly params: unknown;
+}
+/**
+ * The approval requests still open in a conversation's history, such as a `Chat`'s, in the
+ * order they were asked: those with neither an answer nor a tool result. An answer recorded
+ * without a result, as a `streamText` turn that failed while its call ran leaves it, is not
+ * open: the next turn acts on it unasked, and another answer would run the call twice. A turn's
+ * response lists only the requests that turn made, and the answering turn's none, so read every
+ * open one here. Each names the call an answer would run, found as Effect finds it: the last
+ * request with its `approvalId`, listed where it was asked, and the last call with its id.
+ * Guide: `docs/ActionToolkit.md` in this package; in an application:
+ * `examples/kitchen-sink/src/assistant/handlers.ts`.
+ */
+export declare const openApprovals: ({ content: messages }: Prompt.Prompt) => ReadonlyArray<Approval>;
 //#endregion

package/dist/ActionToolkit.mjs

@@ -17,5 +17,32 @@ function make(apps, options) {
 		layer: layer.pipe(provideHandlers(served))
 	};
 }
+/**
+* The approval requests still open in a conversation's history, such as a `Chat`'s, in the
+* order they were asked: those with neither an answer nor a tool result. An answer recorded
+* without a result, as a `streamText` turn that failed while its call ran leaves it, is not
+* open: the next turn acts on it unasked, and another answer would run the call twice. A turn's
+* response lists only the requests that turn made, and the answering turn's none, so read every
+* open one here. Each names the call an answer would run, found as Effect finds it: the last
+* request with its `approvalId`, listed where it was asked, and the last call with its id.
+* Guide: `docs/ActionToolkit.md` in this package; in an application:
+* `examples/kitchen-sink/src/assistant/handlers.ts`.
+*/
+const openApprovals = ({ content: messages }) => {
+	const said = messages.flatMap((message) => message.role === "assistant" ? message.content : []);
+	const told = messages.flatMap((message) => message.role === "tool" ? message.content : []);
+	const answered = new Set(told.flatMap((part) => part.type === "tool-approval-response" ? [part.approvalId] : []));
+	const ran = new Set(told.flatMap((part) => part.type === "tool-result" ? [part.id] : []));
+	const calls = new Map(said.flatMap((part) => part.type === "tool-call" ? [[part.id, part]] : []));
+	return said.filter((part) => part.type === "tool-approval-request").filter(({ approvalId }, place, all) => all.findLastIndex((later) => later.approvalId === approvalId) === place).flatMap(({ approvalId, toolCallId }) => {
+		const call = calls.get(toolCallId);
+		return call === void 0 || answered.has(approvalId) || ran.has(toolCallId) ? [] : [{
+			approvalId,
+			toolCallId,
+			name: call.name,
+			params: call.params
+		}];
+	});
+};
 //#endregion
-export { make };
+export { make, openApprovals };

package/dist/Testing.d.mts

@@ -21,7 +21,8 @@ export declare function layer(handler: (request: Request) => Promise<Response>):
  * it to `ActionHttp.client` and to `mcpClient`. The routes are built with this layer and
  * released with its scope, without request logs: only the cause of a defect, of a result that
  * does not encode or of a failure a route of your own leaves unhandled is logged, as an error,
- * where a server's request logger would show it. What they still require is this layer's, as
+ * where a server's request logger would show it, on the process console even under `it.effect`
+ * and its `TestConsole`. What they still require is this layer's, as
  * under `HttpRouter.serve`: a builder's services, and a per-request service no middleware of
  * theirs provides, including one a global middleware reads. The routes keep their real
  * authentication: a client sends its caller's credential. Provided around it, the test
@@ -32,6 +33,7 @@ export declare function layer(handler: (request: Request) => Promise<Response>):
  * The client is the layer's own: the program's other HTTP clients get none of its requests,
  * and it none of theirs.
  * Guide: `docs/Testing.md` in this package; in an application: `examples/notes-service/test/`.
+ * A type error at `it.effect`, such as one naming `Scope`: `docs/Testing-failures.md`.
  */
 export declare function layer<A, E, R>(routes: Layer.Layer<A, E, R>): Layer.Layer<HttpClient.HttpClient, E, Exclude<HttpRouter.Request.Without<R> | HttpRouter.Request.Only<"Requires", R> | HttpRouter.Request.Only<"GlobalRequires", R>, Served>>;
 /** Where `mcpClient` sends, and through what client. */

package/dist/Testing.mjs

@@ -3,7 +3,7 @@ import { assertOnce, projectedErrors } from "./contract/rules.mjs";
 import { checked } from "./contract/call.mjs";
 import { defaultPath, liftOf, statelessRequest } from "./mcp/protocol.mjs";
 import { clientOf } from "./testing/memory.mjs";
-import { Cause, Context, Effect, ErrorReporter, FileSystem, Layer, Option, Path, Predicate, Schema, identity } from "effect";
+import { Cause, Console, Context, Effect, ErrorReporter, FileSystem, Layer, Option, Path, Predicate, Schema, identity } from "effect";
 import { McpSchema } from "effect/ai";
 import { Etag, HttpClient, HttpClientRequest, HttpEffect, HttpPlatform, HttpRouter } from "effect/http";
 import { Base64, Sse } from "effect/encoding";
@@ -15,7 +15,7 @@ function layer(routes) {
 		const platform = yield* Layer.build(Layer.fresh(Layer.mergeAll(HttpPlatform.layer, Path.layer, Etag.layerWeak).pipe(Layer.provideMerge(Layer.succeed(FileSystem.FileSystem, fileSystem)))));
 		const context = Context.merge(platform, yield* Effect.context());
 		const app = yield* HttpRouter.toHttpEffect(routes).pipe(Effect.provideContext(context));
-		return clientOf(HttpEffect.toWebHandlerWith(context)(Effect.tapCause(app, (cause) => isReported(cause) ? Effect.logError(cause) : Effect.void)));
+		return clientOf(HttpEffect.toWebHandlerWith(context)(Effect.tapCause(app, (cause) => isReported(cause) ? Effect.logError(cause).pipe(Effect.provideService(Console.Console, globalThis.console)) : Effect.void)));
 	}));
 }
 const isReported = (cause) => cause.reasons.some((reason) => Cause.isFailReason(reason) && !ErrorReporter.isIgnored(reason.error) || Cause.isDieReason(reason) && !ErrorReporter.isIgnored(reason.defect));

package/dist/mcp/protocol.d.mts

@@ -6,7 +6,8 @@ import { McpProtocol } from "effect/ai";
 //#region src/mcp/protocol.d.ts
 /**
  * An MCP request's parameters, as `Testing.mcpRequest` takes them: JSON, with any `_meta`, leaving
- * out an `undefined` one, as a caller may.
+ * out an `undefined` one, as a caller may. A helper passing on whole params types them as this,
+ * and a tool's `arguments` as `Schema.Json`, never `unknown`.
  */
 export interface Params {
   readonly _meta?: {

package/docs/Action.md

@@ -3,8 +3,9 @@
 `Action.make` defines an action, and `Action.implement` binds handlers and an authorizer to
 contracts: every surface takes the implementation it returns, or a list of them.
 
-Read this page alone, in one tool call: pages read together are cut. When something fails,
-search [Action-failures.md](Action-failures.md). Reading order: [README.md](README.md).
+Read this page alone, in one tool call; if its output says it was truncated, read it again alone.
+When something fails, search [Action-failures.md](Action-failures.md). Reading order:
+[README.md](README.md).
 
 ## API
 
@@ -121,8 +122,9 @@ and a public action in [notes-service/src/status/Status.ts](../examples/notes-se
 ## Implement actions
 
 `Action.implement` binds a handler to one action, or a record of handlers keyed by name to a
-list. Either may instead be a builder: an Effect that returns the handler or the record, which
-is how a handler gets a service.
+list. Either may instead be a builder: an Effect, run once at startup, that returns the handler
+or the record. It is how a handler gets a startup service; what differs per call, the caller
+first, the handler reads itself.
 
 ```ts
 export const notes = Action.implement(
@@ -183,7 +185,9 @@ export const authorize = Effect.fn("authorize")(function* (action: Action.Any) {
 [notes-service/src/identity/authorize.ts](../examples/notes-service/src/identity/authorize.ts)
 is that rule with `scopes: [scope]` added, the OAuth variant: it publishes discovery.
 Derive the rule from `action.readOnly`, never from an `mcp` hint: changing an action's
-`readOnly` then changes who may call it.
+`readOnly` then changes who may call it. Actions under another rule go in another
+`Action.implement` with its own `authorize`, or `Action.allowAll`, not a branch on
+`action.name`.
 
 - **A call runs authentication, then over HTTP and RPC the layer's `middleware`, input
   decoding, the authorizer, then the handler**, each refusing before the next. So a caller the
@@ -202,7 +206,8 @@ Derive the rule from `action.readOnly`, never from an `mcp` hint: changing an ac
   is built once for each implementation stating it: keep state they share in a service it
   yields.
 - **A limit, such as a rate limit, is the handler's, not the authorizer's.** It fails with an
-  error the action declares, and its limiter is a service the builder yields
+  error the action declares, and its limiter is a service the builder yields, apart from the
+  store
   ([kitchen-sink/src/issues/write-limit.ts](../examples/kitchen-sink/src/issues/write-limit.ts)):
   a service is shared wherever it is provided
   ([kitchen-sink/src/memory.ts](../examples/kitchen-sink/src/memory.ts)), state kept in a

package/docs/ActionCli-failures.md

@@ -100,3 +100,5 @@ The tasks are in [ActionCli.md](ActionCli.md).
   with `Command.make`: a command of your own that calls `Action.client` or `ActionHttp.client`
   fails with the action's own error. Pipe the command's whole Effect through
   `ActionCli.toUserError`, given the binding or the actions it calls, or derive the command with `ActionCli.command`.
+- `Argument of type 'string | undefined' is not assignable` at a `UserError`'s `userMessage`: it
+  is optional on the type. Read it with `?? ""`, or assert it with `toHaveProperty`.

package/docs/ActionCli.md

@@ -8,8 +8,9 @@ service you already serve. `make` and `remote` derive a command for every action
 implementations or the binding, so a new action is a new command: list `actions` to leave some
 out.
 
-Read this page alone, in one tool call: pages read together are cut. When something fails,
-search [ActionCli-failures.md](ActionCli-failures.md). Reading order: [README.md](README.md).
+Read this page alone, in one tool call; if its output says it was truncated, read it again alone.
+When something fails, search [ActionCli-failures.md](ActionCli-failures.md). Reading order:
+[README.md](README.md).
 
 ## API
 
@@ -147,9 +148,10 @@ In an aggregate, a command's options go under `commands`, keyed by the action's
 ### Add a command of your own
 
 Work every surface should offer, a bulk import for one, is an action first: a command of your
-own then only reads the file and calls it. For a syntax the options cannot express, such as a
-flag named apart from its field, build the command with native `Command.make`, `Flag` and `Argument`, and
-pass it in `subcommands`: `notes export <file>` takes `Argument.String("file")`
+own then only reads the file and calls it, as `notes import <file>` reads `Argument.FileText`
+and calls `importNotes`. For a syntax the options cannot express, such as a flag named apart
+from its field, build the command with native `Command.make`, `Flag` and `Argument`, and pass it
+in `subcommands`: `notes export <file>` takes `Argument.String("file")`
 ([notes-service/src/commands.ts](../examples/notes-service/src/commands.ts)):
 
 ```ts

package/docs/ActionHttp-failures.md

@@ -68,8 +68,8 @@ The tasks are in [ActionHttp.md](ActionHttp.md).
 
 ## Client methods
 
-- `HttpClientError` whose `reason._tag` is `DecodeError`, for a status such as 429: no schema
-  declares that status. Declare the error on the binding when middleware answers with it, or on
+- `HttpClientError` whose `reason._tag` is `DecodeError`, printed `Decode error (<status> …)`,
+  for a status such as 429: no schema declares that status. For a 500, see the empty 500 above. Declare the error on the binding when middleware answers with it, or on
   the action when its handler does.
 - `HttpClientError` whose `reason._tag` is `InvalidUrlError` outside a browser: relative routes
   have no page to resolve against. Set `baseUrl`.

package/docs/ActionHttp.md

@@ -4,8 +4,9 @@ JSON `POST` routes on Effect's `HttpApi`, one per action. `ActionHttp.make` bind
 mount path; the server mounts that one binding, every client calls it and the OpenAPI document is
 generated from it.
 
-Read this page alone, in one tool call: pages read together are cut. When something fails,
-search [ActionHttp-failures.md](ActionHttp-failures.md). Reading order: [README.md](README.md).
+Read this page alone, in one tool call; if its output says it was truncated, read it again alone.
+When something fails, search [ActionHttp-failures.md](ActionHttp-failures.md). Reading order:
+[README.md](README.md).
 
 ## API
 
@@ -89,7 +90,9 @@ Files: [quickstart/src/routes.ts](../examples/quickstart/src/routes.ts) and
 [notes-service/src/server.ts](../examples/notes-service/src/server.ts).
 
 - Pass every surface the same list of implementations: the layer serves the binding's actions
-  among them.
+  among them. Beside rpcs, one provider and one header decoding serve both
+  ([ActionRpc.md](ActionRpc.md#serve-the-rpcs), "The same actions as JSON too";
+  [kitchen-sink/src/server.ts](../examples/kitchen-sink/src/server.ts)).
 - A service a handler or an authorizer reads per request stays owed by the layer until router
   middleware around it, `HttpRouter.provideRequest` or the layer's own `middleware` provides it.
   Router middleware is the one that reads the request, such as a header:

package/docs/ActionMcp.md

@@ -5,19 +5,20 @@ after it. `layerHttp` mounts a Streamable HTTP endpoint, for clients that connec
 `runStdio` is the whole program of a subprocess a local agent starts. For a model your own code
 calls in process, use [ActionToolkit.md](ActionToolkit.md).
 
-Read this page alone, in one tool call: pages read together are cut. When something fails,
-search [ActionMcp-failures.md](ActionMcp-failures.md). Reading order: [README.md](README.md).
+Read this page alone, in one tool call; if its output says it was truncated, read it again alone.
+When something fails, search [ActionMcp-failures.md](ActionMcp-failures.md). Reading order:
+[README.md](README.md).
 
 ## API
 
 Import `@gjermundgaraba/effect-actions/ActionMcp`.
 
-| API                                   | Purpose                                                      |
-| ------------------------------------- | ------------------------------------------------------------ |
-| `layerHttp(implementations, options)` | A Layer serving the actions as tools at one HTTP endpoint.   |
-| `runStdio(implementations, options)`  | An Effect serving them on standard I/O until stdin closes.   |
-| `Options`                             | Type of `runStdio`'s options.                                |
-| `LayerHttpOptions`                    | Type of `layerHttp`'s options: `Options` and three for HTTP. |
+| API                                   | Purpose                                                     |
+| ------------------------------------- | ----------------------------------------------------------- |
+| `layerHttp(implementations, options)` | A Layer serving the actions as tools at one HTTP endpoint.  |
+| `runStdio(implementations, options)`  | An Effect serving them on standard I/O until stdin closes.  |
+| `Options`                             | Type of `runStdio`'s options.                               |
+| `LayerHttpOptions`                    | Type of `layerHttp`'s options: `Options` and four for HTTP. |
 
 `implementations` is one implementation or a list.
 
@@ -31,6 +32,7 @@ Import `@gjermundgaraba/effect-actions/ActionMcp`.
 | `features`                           | One Layer of native resources, prompts and tools to serve. |
 | `path`                               | HTTP only: the endpoint's path; defaults to `/mcp`.        |
 | `allowedOrigins`                     | HTTP only: the exact origins allowed; none by default.     |
+| `allowSubscriptions`                 | HTTP only: `false` turns off 2026-07-28 subscriptions.     |
 | `authentication`                     | HTTP only: the protected tools' authentication descriptor. |
 
 All but `actions`, `features` and `authentication` are Effect's own `McpServer` options, passed
@@ -48,16 +50,16 @@ export const routes = Layer.mergeAll(
 );
 ```
 
-See [quickstart/src/routes.ts](../examples/quickstart/src/routes.ts) and
-[quickstart/src/server.ts](../examples/quickstart/src/server.ts). Surfaces given the same
-implementations in one set of routes run each builder once, so a note written over HTTP is read
-as a tool: [notes-service/src/routes.ts](../examples/notes-service/src/routes.ts). For two
-servers, see [Action-in-process.md](Action-in-process.md#share-one-build-across-servers).
+See [quickstart/src/routes.ts](../examples/quickstart/src/routes.ts) and `server.ts` beside it.
+Surfaces in one set of routes run each builder once, so a note written over HTTP is read as a
+tool: [notes-service/src/routes.ts](../examples/notes-service/src/routes.ts). For two servers,
+see [Action-in-process.md](Action-in-process.md#share-one-build-across-servers).
 
 - The endpoint speaks MCP 2026-07-28, 2025-11-25 and 2025-06-18, as the client negotiates.
-  Claude Code 2.1 and Codex CLI 0.162 both connect, as tested in October 2026:
-  [notes-service](../examples/notes-service/README.md#run-it) has the commands,
-  [mcp-tools](../examples/mcp-tools/README.md#connect-a-client) those for stdio and Claude Desktop.
+  Claude Code 2.1 and Codex CLI 0.162 connect (October 2026):
+  `claude mcp add --transport http <name> <url>/mcp --header "Authorization: Bearer <token>"`,
+  `codex mcp add <name> --url <url>/mcp --bearer-token-env-var <VAR>`;
+  [mcp-tools](../examples/mcp-tools/README.md#connect-a-client) has stdio and Claude Desktop.
 - **A client of a 2025 revision opens a session** with `initialize`; a 2026-07-28 request stands
   alone. A session holds what its client sent there and no identity: each request authenticates,
   as its own caller. It lasts until its client ends it with a `DELETE`, answered 204, or the process stops, as
@@ -109,9 +111,7 @@ curl http://127.0.0.1:3000/mcp -d "$BODY" -H 'Content-Type: application/json' \
 - **No token arrives, so the host names the caller.** stdio takes no `authentication`: provide the
   protected tools' identity around `runStdio`, whose one caller is whoever started it. Each
   implementation's `authorize` still runs, so give that caller what it checks. Tools served
-  behind a token over HTTP keep their one protected contract here: never a public copy. An HTTP
-  server has many callers: never provide an identity at its startup, where it would stand for
-  every request.
+  behind a token over HTTP keep their one protected contract here: never a public copy.
 - **Test the tools without a process**: the implementations in process over a fake upstream
   ([mcp-tools/test/printers/printers.test.ts](../examples/mcp-tools/test/printers/printers.test.ts)),
   an endpoint in memory
@@ -126,7 +126,7 @@ tool's read-only hint, and the contract's `mcp` option holds its `title`, its ot
 [mcp-tools/src/printers/Printers.ts](../examples/mcp-tools/src/printers/Printers.ts) and
 [mcp-tools/src/instructions.ts](../examples/mcp-tools/src/instructions.ts).
 
-- MCP takes a write as destructive unless it states `destructiveHint: false`.
+- MCP takes a write as destructive unless it states `destructiveHint: false`: one that only adds.
 - A tool's input is one object with keys. Omit `input` for a tool without arguments, and wrap a
   union, an array or a scalar in a field.
 - An argument the schema refuses, an undeclared one included, is answered by the native server

package/docs/ActionRpc.md

@@ -4,8 +4,9 @@ Actions as Effect RPC, on Effect's own `RpcServer` and `RpcClient`: one unary rp
 Reach for it when a client keeps a connection open and calls often, such as a page on a
 WebSocket, or when the application already speaks Effect RPC.
 
-Read this page alone, in one tool call: pages read together are cut. When something fails,
-search [ActionRpc-failures.md](ActionRpc-failures.md). Reading order: [README.md](README.md).
+Read this page alone, in one tool call; if its output says it was truncated, read it again alone.
+When something fails, search [ActionRpc-failures.md](ActionRpc-failures.md). Reading order:
+[README.md](README.md).
 
 ## API
 

package/docs/ActionToolkit.md

@@ -6,25 +6,27 @@ calls your actions. Nothing authenticates: the host names the caller. Code of yo
 the same implementations typed, with `Action.client`
 ([Action-in-process.md](Action-in-process.md#call-actions-in-process)).
 
-Read this page alone, in one tool call: pages read together are cut. When something fails,
-search [ActionToolkit-failures.md](ActionToolkit-failures.md). Reading order: [README.md](README.md).
+Read this page alone, in one tool call; if its output says it was truncated, read it again alone.
+When something fails, search [ActionToolkit-failures.md](ActionToolkit-failures.md). Reading order:
+[README.md](README.md).
 
 ## API
 
 Import `@gjermundgaraba/effect-actions/ActionToolkit`.
 
-| API                               | Purpose                                                                 |
-| --------------------------------- | ----------------------------------------------------------------------- |
-| `make(implementations, options?)` | Project an implementation or a list; returns `{ toolkit, layer }`.      |
-| `toolkit`                         | A native `Toolkit`, one tool per action, named after it.                |
-| `layer`                           | The tools' handlers. Requires the startup services their builders read. |
+| API                               | Purpose                                                                        |
+| --------------------------------- | ------------------------------------------------------------------------------ |
+| `make(implementations, options?)` | Project an implementation or a list; returns `{ toolkit, layer }`.             |
+| `toolkit`                         | A native `Toolkit`, one tool per action, named after it.                       |
+| `layer`                           | The tools' handlers. Requires the startup services their builders read.        |
+| `openApprovals(history)`          | The approval requests a `Chat`'s history still holds open, each with its call. |
 
 | Option          | Meaning                                                                                                        |
 | --------------- | -------------------------------------------------------------------------------------------------------------- |
 | `actions`       | The actions that are tools: `[GetUser, RenameUser]`. Defaults to every action of the implementations.          |
 | `needsApproval` | `(call, context) =>` a boolean, or an `Effect` of one: the calls a model must have approved. Defaults to none. |
 
-Exported types: `Tools`, what `make` returns; `Options`, what it takes; `ToolCall<A>`, the call `needsApproval` receives, for a rule written apart from `make`.
+Exported types: `Tools`, what `make` returns; `Options`, what it takes; `ToolCall<A>`, the call `needsApproval` receives, for a rule written apart from `make`; `Approval`, what `openApprovals` lists.
 
 ## Give a model tools
 
@@ -52,7 +54,8 @@ conversations.pipe(
 - A turn's tool calls, the approved calls of an answering turn included, run concurrently unless `generateText` is given a `concurrency`. A service they share must tolerate it: [assistant/src/tasks/store.ts](../examples/assistant/src/tasks/store.ts) locks each change.
 - Arguments the input does not declare are dropped, where HTTP and a CLI refuse them ([guarantees.md](guarantees.md#wire-behavior)): a misspelled optional argument is ignored silently.
 - Beside other tools, merge natively and provide every handler layer: `Toolkit.merge(toolkit, others)` with `Layer.mergeAll(layer, othersHandlers)`.
-- **A model loop behind a route.** Yield `toolkit` and the model in the implementation's builder, `Action.implement(Ask, Effect.map(toolkit, (tools) => (input) => ...))`: what the handler itself yields is owed per request. Provide `layer` to the route's layer, `ActionHttp.layer(Http, ask).pipe(Layer.provide(layer))`, not in the handler, so the tools share the routes' build ([Action-in-process.md](Action-in-process.md#share-one-build-across-servers)). A tool call runs as the request's caller, unless the handler provides another around it. Keep each caller's `Chat` in a service between requests ([kitchen-sink/src/assistant/conversations.ts](../examples/kitchen-sink/src/assistant/conversations.ts)), and answer an approval in a later one: [kitchen-sink/src/assistant/handlers.ts](../examples/kitchen-sink/src/assistant/handlers.ts), with a scripted model in [demo-model.ts](../examples/kitchen-sink/src/assistant/demo-model.ts), provided in [kitchen-sink/src/routes.ts](../examples/kitchen-sink/src/routes.ts) and tested over HTTP in [kitchen-sink/test/assistant/assistant.test.ts](../examples/kitchen-sink/test/assistant/assistant.test.ts).
+- **A model loop behind a route.** Yield `toolkit` and the model in the implementation's builder, `Action.implement(Ask, Effect.map(toolkit, (tools) => (input) => ...))`: what the handler itself yields is owed per request. Provide `layer` to the route's layer, `ActionHttp.layer(Http, ask).pipe(Layer.provide(layer))`, not in the handler, so the tools share the routes' build ([Action-in-process.md](Action-in-process.md#share-one-build-across-servers)). A tool call runs as the request's caller, unless the handler provides another around it. Keep each caller's `Chat` in a service between requests ([kitchen-sink/src/assistant/conversations.ts](../examples/kitchen-sink/src/assistant/conversations.ts)), and answer an approval in a later one: [kitchen-sink/src/assistant/handlers.ts](../examples/kitchen-sink/src/assistant/handlers.ts), with a scripted model in [demo-model.ts](../examples/kitchen-sink/src/assistant/demo-model.ts), which the entrypoint provides through [kitchen-sink/src/memory.ts](../examples/kitchen-sink/src/memory.ts), and tested over HTTP in [kitchen-sink/test/assistant/assistant.test.ts](../examples/kitchen-sink/test/assistant/assistant.test.ts).
+- **The real model comes later?** Provide a scripted one from the entrypoint until then, as the kitchen-sink does. Reading the model with `Effect.serviceOption` hides the requirement: the server builds without one and every request fails.
 
 ### Call a tool by hand
 
@@ -109,8 +112,8 @@ chat
 
 - The answer needs the prompt history, where its request is found by `approvalId`. Sent alone through a bare `LanguageModel.generateText`, it runs nothing and raises nothing. Use a `Chat`, or send again the assistant message holding the call and its request, before the answer.
 - An approved call runs in the answering turn, before the model is asked again, as whoever that turn runs as: provide the caller who was asked. `authorize` runs for it too ([assistant/test/toolkit.test.ts](../examples/assistant/test/toolkit.test.ts)).
-- **Each request is answered on its own.** Of a turn's several requests, an approved call runs, a denied one (`approved: false`) does not and gives the model a failed result (`{ type: "execution-denied", reason }`, whose `reason` is `undefined` unless the answer gives one: not JSON, so never an action's success), and one left unanswered stays open for a later turn. To require every answer at once, check it in the host. Refuse an `approvalId` answered twice in one request: every answer is acted on, so its call would run twice. The answering turn's response does not repeat a request left open: read every open request from the `Chat`'s history, as [kitchen-sink/src/assistant/handlers.ts](../examples/kitchen-sink/src/assistant/handlers.ts) does. Effect finds an approval's call by its tool-call id, which a provider makes unique: a model of your own that repeats one in a `Chat` runs another call than was shown, or none.
+- **Each request is answered on its own.** Of a turn's several requests, an approved call runs, a denied one (`approved: false`) does not and gives the model a failed result (`{ type: "execution-denied", reason }`, whose `reason` is `undefined` unless the answer gives one: not JSON: a route answering with it as a `Schema.Unknown` success answers an empty 500), and one left unanswered stays open for a later turn. To require every answer at once, check it in the host. Refuse an `approvalId` answered twice in one request: every answer is acted on, so its call would run twice. The answering turn's response does not repeat a request left open: list every open one with `ActionToolkit.openApprovals(yield* Ref.get(chat.history))`, as [kitchen-sink/src/assistant/handlers.ts](../examples/kitchen-sink/src/assistant/handlers.ts) does. Effect finds an approval's call by its tool-call id, which a provider makes unique: where a model of your own repeats one, the last call with it runs, which `openApprovals` names and `response.toolCalls` may not.
 - **Continue on `toolCalls`, never on `toolResults`.** The answering turn's response holds the approved call's result, no tool call, and the model's reply to it: a loop that continues while a response has tool results asks the model again and loses that reply.
-- **If a turn fails or is interrupted after an approved call**, the model failing or the client going away, the call has run, the `Chat` has recorded nothing of that turn, and the same answer sent again runs the call again. End the conversation where a turn does not succeed, or record an answer before its turn, and say in the error that an approved call may have run. Run one turn of a conversation at a time, and look it up again once the lock is held, so a turn that waited does not run on a conversation just ended: [kitchen-sink/src/assistant/conversations.ts](../examples/kitchen-sink/src/assistant/conversations.ts) does both.
+- **If a turn fails or is interrupted once an approved call has started**, the model failing or the client going away, the call may have run, and may run again. A failed `generateText` records nothing of its turn, so the same answer sent again runs the call again. A failed `streamText` records its prompt and the parts it streamed: a call that returned has its result recorded, but one that failed or was cut off while running leaves its answer without a result, which the next turn acts on unasked; `openApprovals` leaves that request out, as another answer would run the call twice. End the conversation where a turn does not succeed, or record an answer in your own store before its turn, and say in the error that an approved call may have run. Run one turn of a conversation at a time, and look it up again once the lock is held, so a turn that waited does not run on a conversation just ended: [kitchen-sink/src/assistant/conversations.ts](../examples/kitchen-sink/src/assistant/conversations.ts) does both.
 - **Show the person what is asked.** A request names its call by `toolCallId`; that call, in `response.toolCalls`, holds the model's `params`, typed `unknown`. Show them as JSON, as [assistant/src/agent.ts](../examples/assistant/src/agent.ts) does, which joins the two; decode them with `Schema.toCodecJson(AddTask.input)`, the tool's parameters, only where you read a field.
-- **Only the person asked answers.** A `tool-approval-response` whose `approvalId` matches an open request in the history is acted on, as the turn's caller: take an `approvalId` only from that caller, and keep the `Chat` where its owner alone reaches it.
+- **Only the person asked answers.** A `tool-approval-response` whose `approvalId` matches a request in the history without a result is acted on, as the turn's caller, an answered one included: take an `approvalId` only from that caller, among those `openApprovals` lists, and keep the `Chat` where its owner alone reaches it.

package/docs/Authentication.md

@@ -4,8 +4,9 @@ How a remote caller proves the identity a protected action declares. `Authentica
 declares it, as a browser-safe descriptor; `Authentication.layer` is that descriptor's provider,
 running the verifier you write. Verifying a token, login and consent stay in the application.
 
-Read this page alone, in one tool call: pages read together are cut. When something fails,
-search [Authentication-failures.md](Authentication-failures.md). Reading order: [README.md](README.md).
+Read this page alone, in one tool call; if its output says it was truncated, read it again alone.
+When something fails, search [Authentication-failures.md](Authentication-failures.md). Reading
+order: [README.md](README.md).
 
 ## API
 

package/docs/CONTEXT.md

@@ -4,8 +4,9 @@ Vocabulary for `@gjermundgaraba/effect-actions`. The docs, the examples, the cod
 use these words with these meanings. Module names and Effect's own terms (`HttpApi`, `Tool`,
 `Toolkit`, `McpServer`, `Rpc`, `RpcGroup`, `RpcServer`, `Command`) mean what their modules say.
 
-Read this page alone, in one tool call: pages read together are cut. Tasks are routed from
-[README.md](README.md), and each module's failures from its `-failures.md` page.
+Read this page alone, in one tool call; if its output says it was truncated, read it again alone.
+Tasks are routed from [README.md](README.md), and each module's failures from its `-failures.md`
+page.
 
 ## Terms
 

package/docs/README.md

@@ -11,15 +11,19 @@ same schemas, handler and authorization.
 first (step 5), before the examples and the pages.
 
 1. **Open one page per tool call, with your file-reading tool.** A page fits one read. Several
-   in one call, however many commands it runs, are cut by its output limit, and what is cut goes
-   unnoticed.
+   in one call, however many commands it runs, can be cut by its output limit, with no mark or
+   with one that understates what is lost. If an output says it was truncated, read that page
+   again alone.
 2. **Start from the example closest to what you are building** ([Examples](#examples)). Its
    README has a layout tree and a "Where to look" table naming the file for each thing. Copy its
-   layout and idioms: the examples are the reference for how code is written.
+   layout and idioms: the examples are the reference for how code is written. An example shows
+   one way, not the rules, the alternatives or the traps: read steps 3 and 4 even when it fits.
 3. **Read [Action.md](Action.md) completely.** Every surface builds on it.
 4. **Read the page of each surface you serve** ([Pages](#pages)), and the example files its task
    sections link.
-5. **When something fails, search the `*-failures.md` pages** for a fragment of the message. Each
+5. **When something fails, search the `*-failures.md` pages** for a fragment of the message
+   without quotes, your own code's first compile error included, before reasoning it out:
+   `grep -rnF "<fragment>" node_modules/@gjermundgaraba/effect-actions/docs/*-failures.md`. Each
    module page has one beside it, such as [Action-failures.md](Action-failures.md).
 
 A service others call is [notes-service](../examples/notes-service/) plus
@@ -37,7 +41,7 @@ there is no package root.
 
 | Read                                                     | When you need to                                                                                                                            |
 | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| [setup.md](setup.md)                                     | install, import the modules, write the minimal program, lay out an application, bundle a browser client                                     |
+| [setup.md](setup.md)                                     | install, write `tsconfig.json`, import the modules, write the minimal program, lay out an application, bundle a browser client              |
 | [Action.md](Action.md)                                   | define a contract and who may call it, implement it, authorize calls, fail with declared and built-in errors                                |
 | [Action-in-process.md](Action-in-process.md)             | call actions from your own code, such as a job; share one build of the implementations across servers and jobs                              |
 | [ActionHttp.md](ActionHttp.md)                           | bind actions to JSON routes, serve them, limit request bodies, publish OpenAPI, call them from Effect or a browser                          |

package/docs/Testing-failures.md

@@ -3,7 +3,7 @@
 What you see when something is wrong, and the fix. Search for a fragment of the message.
 The tasks are in [Testing.md](Testing.md).
 
-- A route answers an empty 500: a defect, or a result that does not encode. `Testing.layer` logs the cause as an error, and nothing for a request that succeeds or is refused: read the test's output, or collect it with a `Logger` or an `ErrorReporter` provided around the layer.
+- A route answers an empty 500, which a client method reports as `HttpClientError: Decode error (500 …)`: a defect, or a result that does not encode. `Testing.layer` logs the cause as an error on the process console, under `it.effect` too, and nothing for a request that succeeds or is refused: read the test's output, or collect it with a `Logger` or an `ErrorReporter` provided around the layer.
 - A client method fails with `Action.Unauthenticated`: routes under `Testing.layer` keep their real authentication. Give the client a credential in `transformClient` ([Test as a signed-in caller](Testing.md#test-as-a-signed-in-caller)).
 - A protected route answers 401 where the test expects 415 or 400: authentication runs before the body is read. Send a valid credential.
 - `Type 'Provider<CurrentUser, "notes-service.Login">' is missing the following properties from type 'Scope'` at `it.effect`, or `… is not assignable to type 'never'` at `Effect.runPromise`: the routes serve a protected action without a provider of its descriptor. Provide the real one or a test verifier to the routes; a caller provided around `Testing.layer` does not satisfy them.
@@ -11,6 +11,7 @@ The tasks are in [Testing.md](Testing.md).
 - `Type '<Service>' is missing the following properties from type 'Scope'` at every `it.effect`, for a service that is no identity, such as a store, a limiter or a `LanguageModel`: a builder now yields it, and the routes require it. Provide its layer to `Testing.layer(routes)`, as the entrypoint provides it to the server.
 - `Type 'unknown' is not assignable to type 'Scope'` at `it.effect`, or `Argument of type 'Effect<…>' is not assignable` at an `Effect.flip` or `Effect.exit`, around a loop over an array of calls to different actions: their successes and errors differ, so the array has no one element type. Annotate it, `ReadonlyArray<Effect.Effect<unknown, unknown>>`, with the caller as a third parameter for `Action.client` calls of protected actions, or assert each call on its own.
 - An rpc call never answers under `Testing.layer`, and nothing is logged: the layer holds the rpc layer twice, under two protocols, and built it for the other one, a WebSocket. Give the rpc layer its WebSocket in the entrypoint, so the routes a test serves hold it once, under the test's protocol ([Serve the rpcs](ActionRpc.md#serve-the-rpcs)).
+- `Property '<field>' does not exist on type 'MethodError<Action<…>>'`, or on a built-in error, after `expect(error).toBeInstanceOf(…)`: `toBeInstanceOf` does not narrow the union of the action's errors. Compare with `toEqual(new X({ … }))`, or narrow with `instanceof` ([Assert on errors](Testing.md#assert-on-errors)).
 - A test passes whatever message an error carries: `toEqual` never compares a tagged error's `message`. Assert it separately ([Assert on errors](Testing.md#assert-on-errors)).
 - The test reads a service the handlers never changed: it was provided inside the routes and again to the test, two instances. Provide it once, around `Testing.layer`, with `Layer.provideMerge`.
 - `MCP tools/call "<name>" answered 404`: the endpoint is not at `/mcp`, the default. Pass `mcpClient` its `url`.

package/docs/Testing.md

@@ -8,8 +8,9 @@ tests of the surfaces beside them, in `it.effect` from `@effect/vitest`, which s
 `Scope` that `Action.client` and `ActionRpc.client` require, a `TestClock` and a `TestConsole`
 (both imported from `effect/testing`).
 
-Read this page alone, in one tool call: pages read together are cut. When something fails,
-search [Testing-failures.md](Testing-failures.md). Reading order: [README.md](README.md).
+Read this page alone, in one tool call; if its output says it was truncated, read it again alone.
+When something fails, search [Testing-failures.md](Testing-failures.md). Reading order:
+[README.md](README.md).
 
 ## API
 
@@ -30,7 +31,8 @@ Import `@gjermundgaraba/effect-actions/Testing`.
 | `mcpRequest`: `headers`        | Request headers.                                                                |
 
 Exported types: `McpClient<Actions>`, `McpClientOptions`, `McpRequestOptions`, and `McpParams`,
-the `params` of `mcpRequest`.
+the `params` of `mcpRequest`. A helper passing on a tool's `arguments` types them `Schema.Json`,
+and whole `params` `McpParams`, never `unknown`.
 
 ## Test an implementation in process
 
@@ -204,6 +206,11 @@ and so does `toStrictEqual`. Other fields are compared, so `toEqual(new NoteNotF
 asserts the `id`, and `toEqual(new Action.Forbidden({ scopes: ["issues:write"] }))` still needs the
 message asserted beside it. The message is all a model reads of a tool's failure.
 
+`toBeInstanceOf` narrows nothing: the flipped failure stays the union of the action's declared
+and built-in errors, so reading a field only one of them has, such as `retryAfterSeconds`, does
+not compile. Compare with `toEqual(new RateLimited({ retryAfterSeconds: 10 }))`, or narrow with
+`instanceof` first.
+
 A Toolkit raises neither a refusal nor a declared error: each is a result the model reads, so
 assert `isFailure` and `result.message`
 ([assistant/test/toolkit.test.ts](../examples/assistant/test/toolkit.test.ts)).

package/docs/setup-failures.md

@@ -3,6 +3,9 @@
 What you see when something is wrong, and the fix. Search for a fragment of the message.
 The tasks are in [setup.md](setup.md).
 
+- `TS1149: File name '…/assistant.ts' differs from already included file name '…/Assistant.ts' only in casing`:
+  a lowercase file is named for its domain beside the domain's contract. Name lowercase files for
+  their role, such as `handlers.ts` or `turns.ts`: on a disk that ignores case the two are one file.
 - `Cannot find module '@gjermundgaraba/effect-actions'`: there is no root export. Import a
   subpath from [Entry points](setup.md#entry-points), never the root or a `dist/` path.
 - A browser build fails with `Could not resolve "node:…"`, or warns
@@ -28,7 +31,7 @@ The tasks are in [setup.md](setup.md).
   such as `found 4.1.0`, or a start failing with `Cannot find module '…/effect/dist/…'` under an
   `@effect/*` package: more than one Effect release is installed, or one outside the peer
   range. Install the `effect` range [Install](setup.md#install) names, with every `@effect/*`
-  package at the version `effect` resolved to, such as `@effect/platform-node@4.0.2` beside
-  `effect@4.0.2`.
+  package at the version `effect` resolved to, such as `@effect/platform-node@4.0.4` beside
+  `effect@4.0.4`.
 - `Cannot find module 'effect/unstable/http'` (or `…/httpapi`, `…/cli`, `…/ai`): these modules
   are now `effect/http`, `effect/http-api`, `effect/cli` and `effect/ai`.