@gjermundgaraba/effect-actions 0.10.0 → 0.12.0

package/docs/ActionRpc.md

@@ -0,0 +1,178 @@
+# ActionRpc
+
+Actions as Effect RPC, on Effect's own `RpcServer` and `RpcClient`: one unary rpc per action.
+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).
+
+## API
+
+Import `@gjermundgaraba/effect-actions/ActionRpc`.
+
+| API                                     | Purpose                                                                    |
+| --------------------------------------- | -------------------------------------------------------------------------- |
+| `make(actions, options?)`               | Bind a list of actions; returns a `Binding`.                               |
+| `Rpc.actions`                           | The bound actions.                                                         |
+| `Rpc.error`                             | The errors every rpc declares besides its action's own.                    |
+| `Rpc.authentication`                    | The authentication descriptor of its protected actions, or `undefined`.    |
+| `Rpc.group`                             | Native `RpcGroup`, one rpc per action, for `RpcClient.make`.               |
+| `layer(Rpc, implementations, options?)` | Serve the rpcs of the bound actions the implementations hold.              |
+| `client(Rpc, options?)`                 | An Effect of a typed client; requires the client `Protocol` and a `Scope`. |
+
+Exported types: `Binding`; `Any`, any binding; `Client<typeof Rpc>`; `MethodError`, what one call fails with; `Options` of `make`, `LayerOptions` of `layer`, `ClientOptions` of `client`.
+
+| Option                   | Meaning                                                                                                |
+| ------------------------ | ------------------------------------------------------------------------------------------------------ |
+| `make`: `error`          | Errors the layer's `middleware` fails with: declared by every rpc, so clients decode them.             |
+| `make`: `authentication` | `Authentication.make(...)` of the protected actions' identity: required when the binding holds one.    |
+| `layer`: `actions`       | The bound actions it serves: `[GetUser]`. Defaults to every one the implementations hold.              |
+| `layer`: `middleware`    | Native `RpcMiddleware` around every rpc, inside authentication, outside decoding; the first innermost. |
+| `client`: options        | The native `RpcClient.make` options but `flatten`.                                                     |
+
+## Bind actions to rpcs
+
+Call `ActionRpc.make` once, in a file that imports no server code
+([setup.md](setup.md#bundle-for-a-browser)), and export the binding: the server serves it and
+every client calls it. A binding that holds a protected action names its authentication
+descriptor ([Authentication.md](Authentication.md#declare-how-callers-sign-in)).
+
+```ts
+export const Rpc = ActionRpc.make([ListRooms, ...Messages], { authentication: Login });
+```
+
+[live-rpc/src/Rpc.ts](../examples/live-rpc/src/Rpc.ts) is that binding;
+[kitchen-sink/src/Rpc.ts](../examples/kitchen-sink/src/Rpc.ts) adds `error`.
+
+Nothing streams. A page that follows changes calls again on its open socket, as `readMessages`
+does in [live-rpc/src/chat/Chat.ts](../examples/live-rpc/src/chat/Chat.ts).
+
+## Serve the rpcs
+
+In the routes file, give `ActionRpc.layer` the binding and the implementations, and provide
+what it requires except the protocol: the service of each listed middleware and, where it
+serves a protected action, the authentication provider
+([Authentication.md](Authentication.md#verify-credentials)). The entrypoint chooses the
+protocol and its serialization, then serves the result with `HttpRouter.serve`.
+
+```ts
+// routes.ts
+export const rpc = ActionRpc.layer(Rpc, [rooms, messages], { middleware: [ResolveRoom] }).pipe(
+  Layer.provide([resolveRoom, authenticate]),
+);
+
+// server.ts
+const socket = rpc.pipe(
+  Layer.provide(RpcServer.layerProtocolWebsocket({ path: "/rpc" })),
+  Layer.provide(RpcSerialization.layerJson),
+);
+```
+
+[live-rpc/src/routes.ts](../examples/live-rpc/src/routes.ts) and
+[live-rpc/src/server.ts](../examples/live-rpc/src/server.ts) are the two halves.
+
+- Provide the protocol to the rpc layer, inside what `HttpRouter.serve` serves:
+  `RpcServer.layerProtocolWebsocket` and `layerProtocolHttp` add their route to that router.
+- Export the rpc layer before it is given a protocol. `Testing.layer` cannot upgrade a
+  WebSocket, so a test gives that layer the HTTP protocol ([Testing.md](Testing.md#test-rpcs)).
+- Provide a JSON serialization, the same one on the client: `RpcSerialization.layerJson`,
+  `layerNdjson`, `layerJsonRpc()` or `layerNdJsonRpc()`.
+- Bound a WebSocket message on the server: `HttpServerRequest.MaxBodySize` does not, and Node's
+  reads up to 100 MiB whole. `server.ts` passes `websocket: { maxPayload }` to
+  `NodeHttpServer.layer`; a larger message closes the socket.
+- Authentication runs for every message of a protected rpc, not once per connection.
+- A limit in `middleware` may key on the caller and counts input that does not decode, as the
+  quota of [kitchen-sink/src/identity/quota.ts](../examples/kitchen-sink/src/identity/quota.ts)
+  does; a limit in a handler holds on every surface.
+- A middleware may require the identity only where every action its layer serves is
+  protected, and one protocol takes one `ActionRpc.layer`: a second layer given the same
+  protocol is never reached. So bind the protected actions alone, as
+  [kitchen-sink/src/Rpc.ts](../examples/kitchen-sink/src/Rpc.ts) does, or have the middleware
+  read the identity with `Effect.serviceOption`, which a public rpc's call lacks.
+- A protocol with no router, such as `RpcServer.layerProtocolSocketServer` or
+  `layerProtocolStdio`, serves protected actions too, but has no HTTP request, which limits its
+  provider and its verifier: [ActionRpc-failures.md](ActionRpc-failures.md).
+- **The same actions as JSON too.** Merge `ActionHttp.layer(Http, implementations)` beside the
+  rpc layer, each given its descriptor's provider
+  ([kitchen-sink/src/routes.ts](../examples/kitchen-sink/src/routes.ts) defines both, and
+  [server.ts](../examples/kitchen-sink/src/server.ts) merges them): one provider given to both
+  is built once. The routes need what
+  the rpcs did not: an `httpApiStatus` on each declared error, which answers 422 without one
+  ([live-rpc/src/chat/Chat.ts](../examples/live-rpc/src/chat/Chat.ts)); a request body limit;
+  and router middleware for a service an `RpcMiddleware` provides
+  ([ActionHttp.md](ActionHttp.md#serve-the-routes)). Write the header's decoding once, in a
+  function both middleware call.
+
+## Call the rpcs
+
+`ActionRpc.client(Rpc)` has the methods of `ActionHttp.client`
+([ActionHttp.md](ActionHttp.md#call-the-api-from-effect)): `client.readMessages({ after })`.
+Its connection is a Layer of Effect's own:
+
+```ts
+export const connection = (url: string) =>
+  RpcClient.layerProtocolSocket().pipe(
+    Layer.provide(Socket.layerWebSocket(url)),
+    Layer.provide(RpcSerialization.layerJson),
+  );
+```
+
+It leaves the WebSocket constructor to its host: a page provides
+`Socket.layerWebSocketConstructorGlobal`, and Node `NodeSocket.layerWebSocketConstructor`.
+[live-rpc/src/browser.ts](../examples/live-rpc/src/browser.ts) is a page's client module, and
+[live-rpc/src/client.ts](../examples/live-rpc/src/client.ts) runs it from Node.
+
+- The socket belongs to the Layer providing the protocol, not to the scope around the client:
+  provide the connection once, around the page's whole program, never around one call. A page
+  that is not one Effect program keeps it in a `ManagedRuntime` and calls with promises:
+  `connect(url)` in `browser.ts`, whose socket opens on the first call.
+- A declared error or a refusal is its call's typed failure: only that call fails, and the
+  socket stays open. RPC answers no 401 or 403 challenge, and a token may expire under an open
+  socket, so the page handles `Unauthenticated` itself
+  ([guarantees.md](guarantees.md#wire-behavior)).
+
+## Send request context with a call
+
+What travels beside a call's input, such as a token, a tenant or a room, goes in headers. On
+the client, wrap the call in `RpcClient.withHeaders`:
+
+```ts
+const here = RpcClient.withHeaders({ authorization: `Bearer ${token}`, [roomHeader]: name });
+
+client.postMessage({ text }).pipe(here);
+```
+
+On the server, authentication decodes the credential from those headers. Anything else is read
+by native `RpcMiddleware` listed in `layer`'s `middleware`, which provides it as a service to
+the handlers and to `authorize`:
+
+```ts
+export class ResolveRoom extends RpcMiddleware.Service<ResolveRoom, { provides: CurrentRoom }>()(
+  "live-rpc/ResolveRoom",
+) {}
+
+export const resolveRoom = Layer.succeed(ResolveRoom, (call, { headers }) =>
+  Effect.provideService(call, CurrentRoom, headers[roomHeader] ?? defaultRoom),
+);
+```
+
+[live-rpc/src/chat/room.ts](../examples/live-rpc/src/chat/room.ts) is that middleware, and
+[live-rpc/src/browser.ts](../examples/live-rpc/src/browser.ts) the client sending the header.
+
+- Over a WebSocket, a message's headers are the upgrade request's with its own merged over
+  them. A browser WebSocket sets no header on its upgrade, so a bearer token goes on each
+  message, and a refreshed token needs no new socket.
+- A cookie the browser attaches to the upgrade covers every message
+  ([kitchen-sink/src/browser.ts](../examples/kitchen-sink/src/browser.ts)). A browser attaches
+  it from any page, so refuse a foreign `Origin` on the upgrade, with a request policy
+  ([Authentication-advanced.md](Authentication-advanced.md#run-a-request-policy-before-authentication)).
+- An API key in the query string never reaches authentication.
+- A request-time requirement is never a startup service: `Layer.succeed(CurrentRoom, "lobby")`
+  provided to the layer leaves `CurrentRoom` owed, in its type.
+- Router middleware or `HttpRouter.provideRequest` around the layer provides one too, but over
+  a WebSocket it runs once, for the upgrade, so its value holds for the whole connection. What
+  differs per message needs a listed middleware.
+- Authentication runs outside the listed middleware, so none of them provides what a verifier
+  reads
+  ([Authentication-advanced.md](Authentication-advanced.md#read-request-context-in-a-verifier)).

package/docs/ActionToolkit-failures.md

@@ -0,0 +1,15 @@
+# ActionToolkit failure modes
+
+What you see when something is wrong, and the fix. Search for a fragment of the message.
+The tasks are in [ActionToolkit.md](ActionToolkit.md).
+
+- An approved call never runs, and nothing is raised: a `tool-approval-response` finds its request by `approvalId` in the prompt history, and was sent without it. Use a `Chat`, or resend the assistant message holding the call and its request before the response.
+- `Type 'X' is not assignable to type 'never'` where a turn or a call by hand runs, or `Service not found` in plain JavaScript: a request service is provided around the turn, or around the whole call effect, not to the stream alone, and a protected tool owes its identity whatever its handler reads. A startup service's Layer is provided to `layer`.
+- A returned failure whose `result` is an `AiError` with reason `ToolParameterValidationError` (`failureOrigin: "parameters"`), not a declared error: the arguments did not decode. Neither `authorize` nor the handler ran.
+- A turn fails with an `AiError`, `Failed to encode result for tool '<name>'`: the handler failed with an error its action does not declare, which a cast or plain JavaScript lets through. Declare it on the action.
+- A model reads base64 text where an image was meant: a tool's success holds an `Action.Image`, which a Toolkit gives the model as JSON text. Leave the action out of `actions`, or serve it over MCP, which sends an image block ([ActionMcp.md](ActionMcp.md#return-images-and-other-media)).
+- `Listed in actions, but no implementation holds it: <names>` thrown at `make`: those actions are not the implementations', by identity. `(another contract)` marks one whose name an implementation holds, as a second copy of the contracts module makes. Pass the implementation holding the action, or list the contract it implements.
+- `Duplicate tool: <name>` thrown at `make`: two implementations serve actions of one name. Rename one action; of two implementations of one contract, pass one.
+- A defect when a tool handles a call: the `layer` provided is another implementation's, with tools of the same names, which the types accept. Provide the `layer` that `make` returned with the `toolkit`.
+- Two toolkits of one implementation answer with one set of startup services: their `layer`s, given different services, were provided together, and one serves both. Use separate implementations for separate services.
+- A job or an agent beside `HttpRouter.serve` reads other state than the routes, or its builder runs twice: the toolkit's `layer` builds in another layer graph than the routes. Provide that `layer` inside the layer the server serves, or `Action.layer` and the services they share above both ([Action-in-process.md](Action-in-process.md#share-one-build-across-servers)).

package/docs/ActionToolkit.md

@@ -1,133 +1,116 @@
 # ActionToolkit
 
-Implementations as Effect's native AI `Toolkit`, for programs that call tools in-process
-with `LanguageModel` or by hand. No server. A tool takes and gives JSON, as a model does; code
-of your own calls the implementations typed, with `Action.client` ([Action.md](Action.md#clients)).
+Implementations as Effect's native AI `Toolkit`: one tool per action, run in the process that
+calls the model, with no server. Reach for it when a `LanguageModel` or a `Chat` in your program
+calls your actions. Nothing authenticates: the host names the caller. Code of your own calls
+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).
 
 ## API
 
 Import `@gjermundgaraba/effect-actions/ActionToolkit`.
 
-| API                               | Purpose                                                                                                             |
-| --------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| `make(implementations, options?)` | Project an implementation or a list; returns `{ toolkit, layer }`.                                                  |
-| `toolkit`                         | A native `Toolkit`: `toolkit.tools` holds the tool definitions by name, with typed schemas, MCP hints and approval. |
-| `layer`                           | The handler layer: builds handlers and built authorizers in its scope; requires build-time services.                |
-
-| Option          | Meaning                                                                                                                                    |
-| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| `actions`       | The actions that are tools, among the implementations': `[GetUser, RenameUser]`. Defaults to every action of them.                         |
-| `needsApproval` | `(call) =>` a boolean, or an `Effect` of one: the calls `LanguageModel` asks approval for instead of running them ([Approval](#approval)). |
-
-Exported types: `Tools`, what `make` returns; `Options`, what it takes; `ToolCall<A>`, the call `needsApproval` receives, `A` the union of its actions, for a rule written apart from `make`.
-
-A local surface: each implementation's `authorize` runs before the handlers of its protected
-actions, and the caller provides the identity.
-
-Each tool takes and gives the JSON encoding of the action's schemas, as a model speaks and
-as an MCP tool does, combines the action's errors with the built-in `InvalidInput`,
-`Unauthenticated` and `Forbidden` in a native union, and uses `failureMode: "return"`. Its request requirements are its handler's and its authorizer's, and a protected
-action's identity, whether or not anything reads it; build failures and services belong to the
-handler layer.
-
-## Canonical
-
-```ts example=toolkit-authorized.ts
-import { NodeRuntime } from "@effect/platform-node";
-import { Console, Effect, Layer, Stream } from "effect";
-import * as ActionToolkit from "@gjermundgaraba/effect-actions/ActionToolkit";
-import { actors, CurrentActor } from "./authorization.js";
-import { double, userActions } from "./handlers.js";
-import { Users } from "./users.js";
-
-// The implementations' `authorize` runs for the in-process caller as for the servers.
-const { toolkit, layer } = ActionToolkit.make([userActions, double]);
-
-const program = Effect.gen(function* () {
-  const tools = yield* toolkit;
-  const calls = yield* tools.handle("getUser", { id: "1" }); // encoded arguments
-  const results = yield* Stream.runCollect(calls);
-  yield* Console.log(results);
-}).pipe(
-  Effect.provideService(CurrentActor, actors.alice), // identity around the whole invocation
-  Effect.provide(layer.pipe(Layer.provide(Users.layerMemory))), // startup services only
-);
+| 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. |
 
-program.pipe(NodeRuntime.runMain);
-```
+| 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`.
+
+## Give a model tools
 
-With a model: pass `toolkit` as `toolkit` to `LanguageModel.generateText` and provide `layer`.
-Beside tools of your own, or provider-defined ones such as a web search, merge the toolkits
-natively and provide every handler layer:
+Pass `toolkit` to `LanguageModel.generateText` or a `Chat`, and provide `layer`:
+[assistant/src/toolkit.ts](../examples/assistant/src/toolkit.ts) and
+[assistant/src/agent.ts](../examples/assistant/src/agent.ts), with a scripted model in
+[assistant/src/scripted.ts](../examples/assistant/src/scripted.ts).
 
 ```ts
-LanguageModel.generateText({ prompt, toolkit: Toolkit.merge(toolkit, WebKit) }).pipe(
-  Effect.provide(Layer.mergeAll(layer, WebKitHandlers)),
+export const { toolkit, layer } = ActionToolkit.make([tasks, identity]);
+
+// One turn, as a member.
+const turn = chat.generateText({ prompt, toolkit }).pipe(actingFor(member));
+
+conversations.pipe(
+  Effect.provide(model),
+  // Once, around the program. Startup services only, never a caller.
+  Effect.provide(layer.pipe(Layer.provide([TaskStore.layerFile, Permissions.layerMemory]))),
 );
 ```
 
-### Approval
-
-```ts example=toolkit-approval.ts
-import { Effect, Option } from "effect";
-import { LanguageModel } from "effect/ai";
-import * as ActionToolkit from "@gjermundgaraba/effect-actions/ActionToolkit";
-import { type Actor, CurrentActor } from "./authorization.js";
-import { double, userActions } from "./handlers.js";
-
-// A model's writes wait for their caller's approval, except a rename of the caller itself:
-// `call.name` narrows `call.input` across both implementations. Without a caller, it asks.
-export const { toolkit, layer } = ActionToolkit.make([userActions, double], {
-  needsApproval: (call) =>
-    !call.action.readOnly &&
-    Effect.map(
-      Effect.serviceOption(CurrentActor),
-      Option.match({
-        onNone: () => true,
-        onSome: ({ id }) => call.name !== "renameUser" || call.input.id !== id,
-      }),
-    ),
-});
-
-// One turn: the caller is provided around it, for the approval, `authorize` and the handlers.
-export const chat = (actor: Actor, prompt: string) =>
-  LanguageModel.generateText({ prompt, toolkit }).pipe(Effect.provideService(CurrentActor, actor));
+- **One `generateText` is one request to the model.** Its tool calls run, and their results come back in the response, unread by the model. For the model to read them, ask the `Chat` again with `prompt: []` while a response has `toolCalls` and no `tool-approval-request`.
+- Without `actions`, every action of the implementations is a tool, one added later included. Where a model must not get them all, list the tools ([Action.md](Action.md#define-a-contract)): [kitchen-sink/src/issues/assistant.ts](../examples/kitchen-sink/src/issues/assistant.ts).
+- A refusal or a declared error is not raised: it is a tool result with `isFailure: true`, which the model reads.
+- 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).
+
+### Call a tool by hand
+
+`yield* toolkit` gives `tools.handle(name, arguments)`, which takes the JSON a model sends, an
+ISO string for a `Schema.Date`, and returns an Effect of a stream of results:
+[assistant/test/toolkit.test.ts](../examples/assistant/test/toolkit.test.ts). The handler starts
+when `handle` runs, so provide the caller around the whole
+`handle(...).pipe(Effect.flatMap(Stream.runCollect))`, not around the stream alone. `handle`
+never asks for approval.
+
+## Name the caller
+
+Provide the identity around each turn, or each call made by hand, as `actingFor` does in
+[assistant/src/toolkit.ts](../examples/assistant/src/toolkit.ts): the approval rule, `authorize`
+and the handlers of every call in the turn read it.
+
+- Never provide an identity to `layer`, which is built once for every caller. It satisfies no protected tool's call, which still owes its own in its type, and it silently answers for any call that lacks one.
+- A protected action's tool owes its identity whether or not its handler reads it ([Action.md](Action.md#say-who-may-call-an-action)).
+
+## Ask for approval
+
+`needsApproval` is one rule over every call a model makes, asked before the call runs. Every
+write: `needsApproval: (call) => !call.action.readOnly`
+([kitchen-sink/src/issues/assistant.ts](../examples/kitchen-sink/src/issues/assistant.ts)). A
+rule reading the call's input and its caller:
+[assistant/src/toolkit.ts](../examples/assistant/src/toolkit.ts).
+
+- `call` is `{ name, action, input }`, the input decoded, over every action of the implementations, whatever `actions` lists. Check `call.name` to narrow the other two.
+- The rule's `Effect` requires nothing: read the caller with `Effect.serviceOption`, and decide what the absence of one means.
+- Its `Effect` cannot fail in its type, and one that fails anyway runs the call unapproved. To ask when a policy cannot be read, end it with `Effect.orElseSucceed(() => true)`.
+- Approval is not authorization, which stays `authorize`. Only a model's turn asks for it, and `ActionMcp` has no such option.
+
+A call that needs approval does not run: the turn ends with a `tool-approval-request` part in
+`response.content` in place of its result. Start the next turn with the person's answers
+([assistant/src/agent.ts](../examples/assistant/src/agent.ts)):
+
+```ts
+chat
+  .generateText({
+    toolkit,
+    prompt: [
+      {
+        role: "tool",
+        content: asked.content.flatMap((part) =>
+          part.type === "tool-approval-request"
+            ? [{ type: "tool-approval-response", approvalId: part.approvalId, approved: true }]
+            : [],
+        ),
+      },
+    ],
+  })
+  .pipe(actingFor(member));
 ```
 
-A call that needs approval ends the turn with a `tool-approval-request` part instead of a
-result; the host answers it with a native `tool-approval-response` prompt part in the next turn.
-Every write, whoever calls: `needsApproval: (call) => !call.action.readOnly`. A
-toolkit made for another agent or policy from the same implementations runs with this `layer`:
-provide it once. So does one of fewer tools, such as an agent's
-`ActionToolkit.make(userActions, { actions: [GetUser] }).toolkit`.
-
-## Rules
-
-- Every action of the implementations passed becomes a tool, named after the action, with its `mcp` hints, unless `actions` lists the tools: then only those, each behind its implementation's authorizer and from its builder's one run, and an implementation holding none of them is not built. `make(implementations)` accepts one implementation or a list, such as `[userActions, double]`. The types take only actions of the implementations, and type `toolkit` and `layer`'s build services by the listed actions alone; `needsApproval`'s `call` is typed by every action of the implementations. Options whose `actions` may be absent, such as a value typed `ActionToolkit.Options<A>`, serve every action when it is absent and the listed ones when given, so their types owe what every action owes, and hold only the tools present either way ([guarantees.md](guarantees.md#names)).
-- A result's `result` is the action's decoded success or declared failure, and its `encodedResult` the JSON a model reads, such as `"42"` for a `BigInt`. Declared failures are returned as native tool results (`failureMode: "return"`), not raised.
-- `tools.handle(name, encodedInput)` takes JSON arguments, as a model sends them: an ISO string for a `Schema.Date`, `null` for an absent `Schema.optional` field. It returns an Effect producing a result stream. The handler starts while that stream is constructed, so request services must be provided around the entire `handle(...).pipe(Effect.flatMap(Stream.runCollect))`, not only around the stream.
-- Builders, calls and identity follow the [dependency lifetimes](guarantees.md#dependency-lifetimes), and authorization the [authorization rules](guarantees.md#authorization): `layer` builds, a call releases what it acquired when it ends, whether a model's turn or `tools.handle` makes it, and identity is supplied at invocation, never when building the layer. A protected tool's call owes its identity in its type; one call without it anyway, as from plain JavaScript, fails with `Unauthenticated` before `authorize` runs. The innermost caller provided wins: a call made under a narrower identity runs as that one.
-- A model loop in a route yields `toolkit` in its implementation's builder, `Action.implement(Chat, Effect.map(toolkit, (tools) => ({ prompt }) => ...), { authorize })`, and passes `tools` to `LanguageModel.generateText`; the route's layer takes the toolkit's `layer`, `ActionHttp.layer(ChatHttp, chat).pipe(Layer.provide(layer))`. That is one build, in the routes' layer graph, shared with every surface serving the same implementations. `Effect.provide(layer)` in the handler builds it for every call unless a surface of the graph serves the same implementations, and `HttpRouter.provideRequest(layer)` once, but in a layer graph of its own: a second build when another surface serves them and has not built them first.
-- Each tool carries only its own handler's request requirements, plus its authorizer's, not those of sibling actions.
-- `needsApproval` is one function over every call a model makes, before the call runs: `(call, context) =>`, where `call` is `{ name, action, input }`, the input decoded, and `context` is Effect's native approval context. `call` is typed by every action of the implementations, whatever `actions` lists, and checking `call.name` narrows `call.action` and `call.input` to that action's, across implementations too: `(call) => call.name === "erase" && call.input.id !== "draft"`. It gives a boolean, or an `Effect` of one that requires nothing: it runs in the caller's context, so it reads the caller with `Effect.serviceOption`. Default: no tool needs approval.
-- A `needsApproval` Effect that fails means no approval is needed, as `LanguageModel` decides natively. Its `Effect` cannot fail in its type: decide in `needsApproval` what a failure means, `Effect.orElseSucceed(() => true)` to ask when a policy cannot be read.
-- Tools belong to what runs them, their implementation's handlers behind its authorizer: the `layer` of a `make` call serves the tools it selected in any `toolkit` of the same implementations, a toolkit of fewer `actions` included, so toolkits made per agent or per approval policy run with one handler layer, built once. Two implementations never run each other's handlers, even with tools of one name, such as two implementations of one action behind different authorizers, whatever order their layers are provided in.
-- `toolkit` is a native `Toolkit`: `Toolkit.merge` combines it with other tools, and `yield* toolkit` gives the handled toolkit once the handler layers of all its tools are provided.
-- `LanguageModel` enforces approval; `tools.handle` ignores it, like any caller that is not a model's turn. It is not authorization, which stays the implementation's `authorize`. MCP has no such field, so `ActionMcp` takes no such option.
-- This is not an MCP server. Use `ActionMcp` to expose the same actions to external clients.
-- Every tool declares the built-in errors ([guarantees.md](guarantees.md#wire-behavior)), so an authorizer's refusal, or a handler's built-in failure, is an ordinary returned tool failure.
-
-## Failure modes
-
-- Tool missing from the toolkit: its implementation was not passed to `make`, or `actions` leaves it out.
-- `Listed in actions, but no implementation holds it: <names>` thrown at `make`: those actions are not among the implementations' actions, by identity. `(another contract)` marks one whose name an implementation holds, as a second copy of the contracts module makes. Pass the implementation holding it, or list the contract it implements.
-- A defect when a tool handles a call: no `layer` of its implementation is provided, only one of another implementation with tools of the same names, such as another implementation of the same actions, which the types accept. Provide a `layer` made from the implementations the `toolkit` was made from.
-- A job or an agent beside `HttpRouter.serve`, or a model loop in a route given `layer` with `HttpRouter.provideRequest`, reads other state than the routes, or its builder runs twice: its `layer` builds in another layer graph than the routes. Put it inside the layer the server serves, a route's toolkit in its builder ([Rules](#rules)), or provide `Action.layer` and the services they share above both ([dependency lifetimes](guarantees.md#dependency-lifetimes)).
-- Every toolkit of an implementation answering with one set of startup services: two layers of it, built apart with different services, were provided together, and one of them serves its tools. Use separate implementations for separate services.
-- Type error on `needsApproval`'s `Effect`, which requires a service such as the caller: `needsApproval` requires nothing. Read the caller with `Effect.serviceOption(CurrentActor)`, which gives `Option.none()` without one.
-- `Property '<field>' does not exist` on `call.input`: `call` is a union over every action of the toolkit, and another action's input lacks the field. Check `call.name` first.
-- `Duplicate tool: <name>` thrown at `make`: two implementations serve actions of the same name. Rename one action. `actions` tells apart only separate contracts sharing a name, listing one; two implementations of the same contract stay both listed: pass one implementation.
-- `Service not found` for a request tag at call time: it was provided only to the stream. Provide it around the whole call effect. Providing a service to `layer` does not fail: that startup value fills in for every call that lacks its own ([guarantees.md](guarantees.md#dependency-lifetimes)), so never provide an identity there; a protected tool's call still owes it in its type.
-- `Type 'CurrentActor' is not assignable to type 'never'` where a program calling a tool runs: the tool's action is protected, and its call owes the caller, whatever the handler reads. Provide it around the call, or around the turn.
-- A returned failure whose `result` is an `AiError` with reason `ToolParameterValidationError` (`failureOrigin: "parameters"`), not a declared error: the arguments did not decode. Authorization and the handler did not run.
-- Type error on `layer` requirements: a build-time service is missing. Provide its Layer before `layer`.
+- 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.
+- **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.
+- **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.

package/docs/Authentication-advanced.md

@@ -0,0 +1,139 @@
+# Authentication beyond a bearer token
+
+A verifier reading the request, an API key or a cookie, a route of your own, a policy before
+authentication, and a refusal outside the router.
+
+Read [Authentication.md](Authentication.md) first, and this page alone, in one tool call. When
+something fails, search [Authentication-failures.md](Authentication-failures.md). Reading order:
+[README.md](README.md).
+
+## API
+
+Import `@gjermundgaraba/effect-actions/Authentication`. `make` and `layer`:
+[Authentication.md](Authentication.md#api).
+
+| API                                    | Purpose                                                           |
+| -------------------------------------- | ----------------------------------------------------------------- |
+| `protect(descriptor)`                  | Router middleware authenticating a route of the host's own.       |
+| `bearerTokenOf(authorization)`         | The bearer token of an `Authorization` header value, an `Option`. |
+| `refusalResponse(error, options?)`     | A refusal's response, for a caller the router never routes.       |
+| `Protection`, `RefusalResponseOptions` | What `protect` returns, and what `refusalResponse` takes.         |
+
+| `refusalResponse` option | Meaning                                                                                  |
+| ------------------------ | ---------------------------------------------------------------------------------------- |
+| `authentication`         | The descriptor refusing: needed for an error it declares, or a scheme other than Bearer. |
+| `protectedResource`      | The resource `layer` was given: challenges name its metadata URL and `scopesRequired`.   |
+| `authorization`          | The request's `Authorization` header: a 401 to a presented token says `invalid_token`.   |
+
+## Read request context in a verifier
+
+A verifier may read per-request services: the request, or one of your own, such as the tenant a
+request addresses, which native router middleware provides. Provide that middleware after the
+provider, in a `Layer.provide` of its own; in one array, the members provide to the routes and
+not to one another, and the tenant stays owed:
+
+```ts
+routes.pipe(Layer.provide(authenticate), Layer.provide(resolveTenant.layer));
+```
+
+See [kitchen-sink/src/workspaces/tenant.ts](../examples/kitchen-sink/src/workspaces/tenant.ts)
+and [kitchen-sink/src/identity/authenticate.ts](../examples/kitchen-sink/src/identity/authenticate.ts).
+
+- Router middleware provided around the routes runs before their authentication. Middleware
+  that reads the identity runs inside it: give it to the layer as its own `middleware`
+  ([ActionHttp.md](ActionHttp.md#serve-the-routes), [ActionRpc.md](ActionRpc.md#serve-the-rpcs)).
+
+## Use a scheme other than Bearer
+
+Name the scheme in `make`'s `security`: an API key in a cookie, a header or the query, such as
+`HttpApiSecurity.apiKey({ in: "cookie", key: "tracker_session" })`, or `HttpApiSecurity.basic`.
+See [kitchen-sink/src/identity/Identity.ts](../examples/kitchen-sink/src/identity/Identity.ts)
+and [kitchen-sink/src/identity/authenticate.ts](../examples/kitchen-sink/src/identity/authenticate.ts)
+for a session cookie beside Bearer, and [kitchen-sink/src/admin/Admin.ts](../examples/kitchen-sink/src/admin/Admin.ts)
+and [kitchen-sink/src/admin/authenticate.ts](../examples/kitchen-sink/src/admin/authenticate.ts)
+for an API key in a header.
+
+- OAuth is Bearer's. Another scheme takes no `protectedResource` and nothing steps up under it:
+  the scopes a `Forbidden` names there are sent in its JSON and challenge nothing.
+- A browser attaches a cookie to any page's request, so refuse a foreign `Origin` before
+  authentication reads the cookie
+  ([Run a request policy before authentication](#run-a-request-policy-before-authentication)).
+  CORS guards the JSON routes alone ([ActionHttp.md](ActionHttp.md#call-the-api-from-a-browser));
+  a WebSocket upgrade is never preflighted, so for rpcs over a socket under a cookie that policy
+  is the only check ([ActionRpc.md](ActionRpc.md#send-request-context-with-a-call)).
+- A scheme the deployment decides, such as a cookie name a framework prefixes over HTTPS, is
+  still one declaration: the server builds its descriptor at startup, under the same name and
+  identity, and from that one value its binding, its endpoint and its `protect`; a browser's
+  binding keeps a static one.
+- Basic's credential reaches the verifier when its username or its password is non-empty, so a
+  verifier may receive an empty username.
+
+## Protect a route of your own
+
+A descriptor covers action routes alone. A route of the host's own, such as a download or a
+WebSocket upgrade, takes `Authentication.protect(descriptor)`:
+
+```ts
+HttpRouter.add("GET", "/attachments/:id", handler).pipe(
+  Layer.provide(Authentication.protect(Session).layer),
+);
+```
+
+It answers a refusal the route fails with as an action's is answered. See
+[kitchen-sink/src/attachments/download.ts](../examples/kitchen-sink/src/attachments/download.ts)
+and [kitchen-sink/test/attachments/attachments.test.ts](../examples/kitchen-sink/test/attachments/attachments.test.ts).
+
+- No authorizer runs for such a route: it states its own authorization.
+- Every response to a request authentication covers is `Cache-Control: no-store` unless the
+  route states its own caching. A route that does says `private` unless its answer is the same
+  for every caller, or a cache in front of the server may serve it to anyone.
+- The route of an RPC protocol needs no `protect`: `ActionRpc.layer` authenticates each
+  message itself.
+
+## Run a request policy before authentication
+
+A check that must refuse a request before its credential is read, such as a `Host` or `Origin`
+allowlist, is not the layer's own `middleware`, which runs inside authentication. Make it
+global router middleware, `HttpRouter.middleware(check, { global: true })`, which covers every
+request of the router, and provide it last:
+
+```ts
+routes.pipe(Layer.provide(authenticate), Layer.provide(requestPolicy));
+```
+
+See [kitchen-sink/src/request-policy.ts](../examples/kitchen-sink/src/request-policy.ts),
+`publicRoutes` in [kitchen-sink/src/routes.ts](../examples/kitchen-sink/src/routes.ts) and
+[kitchen-sink/test/request-policy.test.ts](../examples/kitchen-sink/test/request-policy.test.ts).
+
+- **An MCP endpoint's `allowedOrigins` checks no `Host`.** It refuses only an unlisted `Origin`:
+  a request sending none passes, whatever its `Host`. The example's policy refuses a `Host` that
+  is neither loopback nor the public URL's, the check against DNS rebinding.
+- **The order decides whether the policy covers discovery.** Global middleware runs in the
+  order it registers, a provider publishing a protected resource registers its discovery when
+  it is built, and the layer provided last is built first. A policy merged beside the routes,
+  with the provider provided around the merge, registers after the provider, and a foreign
+  `Host` reads the discovery document.
+
+## Refuse outside the router
+
+A caller the router never routes, such as a Node `upgrade` handler admitting a socket, holds a
+header and no request. Read the token with `bearerTokenOf`, verify it with the verifier the
+routes use, and answer a refusal with `refusalResponse` ([options](#api)):
+
+```ts
+const admit = (authorization: string | undefined): Effect.Effect<User, Response> =>
+  Effect.fromOption(
+    Authentication.bearerTokenOf(authorization),
+    () => new Action.Unauthenticated(),
+  ).pipe(
+    Effect.flatMap(verify),
+    Effect.mapError((error) =>
+      HttpServerResponse.toWeb(
+        Authentication.refusalResponse(error, { protectedResource, authorization }),
+      ),
+    ),
+  );
+```
+
+- `protectedResource` is a value, not the Effect building it: where `layer` builds the resource
+  from configuration, build the handler's from the same configuration.