@gjermundgaraba/effect-actions 0.18.2 → 0.20.0

package/docs/ActionToolkit.md

@@ -4,139 +4,142 @@ Implementations as Effect's native AI `Toolkit`: one tool per action, run in the
 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)).
+([Action.md](Action.md#call-actions-in-process)).
 
-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.        |
-| `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`; `Approval`, what `openApprovals` lists.
+A message the library throws says its fix; for a compiler diagnostic or Effect's own error, search [ActionToolkit-failures.md](ActionToolkit-failures.md). For one symbol, `grep -rn <symbol> node_modules/@gjermundgaraba/effect-actions/dist/`: each declaration's JSDoc carries its rules and gotchas, and this page only what an example cannot show.
 
 ## Give a model tools
 
-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
-export const { toolkit, layer } = ActionToolkit.make([tasks, identity]);
+`ActionToolkit.make` projects implementations into `{ toolkit, layer }`. Pass `toolkit` to
+`LanguageModel.generateText` or a `Chat`, and provide `layer` once, around the program:
+
+```ts example=assistant/src/toolkit.ts
+import { Effect, Option } from "effect";
+import { Tool, Toolkit } from "effect/ai";
+import * as ActionToolkit from "@gjermundgaraba/effect-actions/ActionToolkit";
+import { identity } from "./identity/handlers.js";
+import { CurrentCaller, type Member } from "./identity/Identity.js";
+import { tasks } from "./tasks/handlers.js";
+
+// `actions.layer` holds the handlers, and requires the startup services their builders read;
+// neither it nor `actions.toolkit` holds a caller.
+const actions = ActionToolkit.make([tasks, identity], {
+  // One rule over every call a model makes, asked before the call runs. A read runs at once. A
+  // write waits for a person to approve it, except a task the caller adds to their own list:
+  // `call.name` narrows `call.input` to that action's. Without a caller, it asks.
+  needsApproval: (call) =>
+    !call.action.readOnly &&
+    Effect.map(
+      Effect.serviceOption(CurrentCaller),
+      Option.match({
+        onNone: () => true,
+        onSome: (caller) => call.name !== "addTask" || call.input.assignee !== caller.id,
+      }),
+    ),
+});
+
+// A title for this assistant's approval display. The model still calls the tool `addTask`.
+// The later definition wins; annotating the generated tool keeps its handler and approval rule.
+export const toolkit = Toolkit.merge(
+  actions.toolkit,
+  Toolkit.make(actions.toolkit.tools.addTask.annotate(Tool.Title, "Add a task")),
+);
 
-// One turn, as a member.
-const turn = chat.generateText({ prompt, toolkit }).pipe(actingFor(member));
+export const layer = actions.layer;
 
-conversations.pipe(
-  Effect.provide(model),
-  // Once, around the program. Startup services only, never a caller.
-  Effect.provide(layer.pipe(Layer.provide([tasksFile, Permissions.layerMemory]))),
-);
+// One toolkit serves every member, so who a turn runs as is provided around that turn. This is
+// how this example names a model's caller, and it takes a `Member`. The tools themselves accept
+// any `CurrentCaller`, so keeping the operator away from a model is this function's doing, and
+// that of every host using it.
+export const actingFor = (member: Member) => Effect.provideService(CurrentCaller, member);
 ```
 
-- **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. So are arguments that do not decode, an `AiError` (`ToolParameterValidationError`), not `InvalidInput`: neither `authorize` nor the handler ran.
-- 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.
-- **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). Name the files as it does, the route's contract `Assistant.ts` and the loop `handlers.ts`, from the first one written: a lowercase `assistant.ts` beside the contract fails with TS1149 ([setup-failures.md](setup-failures.md)).
-- **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.
+[assistant/src/agent.ts](../examples/assistant/src/agent.ts) runs the turns and provides `layer`
+with its startup services, with a scripted model in
+[assistant/src/scripted.ts](../examples/assistant/src/scripted.ts). What a call returns, a
+refusal and arguments that do not decode included, is on `ActionToolkit.make`; the options'
+rules are on `ActionToolkit.Options`.
+
+- **Let the model read its tools' results** by asking again:
+  [kitchen-sink/src/assistant/handlers.ts](../examples/kitchen-sink/src/assistant/handlers.ts).
+- Where a model must not get every action, list the tools
+  ([Action.md](Action.md#define-a-contract)):
+  [kitchen-sink/src/issues/assistant.ts](../examples/kitchen-sink/src/issues/assistant.ts).
+- A turn's tool calls, the approved calls of an answering turn included, run concurrently unless
+  `generateText` is given a `concurrency`:
+  [assistant/src/tasks/store.ts](../examples/assistant/src/tasks/store.ts) locks each change.
+- **A model loop behind a route.** Yield `toolkit` and the model in the implementation's
+  builder, and provide `layer` to the route's layer,
+  `ActionHttp.layer(Http, ask).pipe(Layer.provide(layer))`, so the tools share the routes' build
+  ([Action.md](Action.md#share-one-build-across-servers)):
+  [kitchen-sink/src/assistant/handlers.ts](../examples/kitchen-sink/src/assistant/handlers.ts),
+  keeping each caller's `Chat` in
+  [conversations.ts](../examples/kitchen-sink/src/assistant/conversations.ts), with a scripted
+  model in [demo-model.ts](../examples/kitchen-sink/src/assistant/demo-model.ts) that the
+  entrypoint provides through [kitchen-sink/src/memory.ts](../examples/kitchen-sink/src/memory.ts),
+  tested over HTTP in
+  [kitchen-sink/test/assistant/assistant.test.ts](../examples/kitchen-sink/test/assistant/assistant.test.ts).
+  Name the files as it does, the route's contract `Assistant.ts` and the loop `handlers.ts`,
+  from the first one written.
+- **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.
 
 ### Customize the native tools
 
-Give a generated tool a title for your approval display with native `Tool` and `Toolkit` from
-`effect/ai`: [assistant/src/toolkit.ts](../examples/assistant/src/toolkit.ts). The host reads the
-title when printing approval requests in [agent.ts](../examples/assistant/src/agent.ts).
+Give a generated tool a title, or other annotations, with native `Tool` and `Toolkit` from
+`effect/ai`, as `toolkit` above does; [agent.ts](../examples/assistant/src/agent.ts) reads the
+title when printing approval requests.
 
-```ts
-const actions = ActionToolkit.make([tasks, identity]);
-const toolkit = Toolkit.merge(
-  actions.toolkit,
-  Toolkit.make(actions.toolkit.tools.addTask.annotate(Tool.Title, "Add a task")),
-);
-const layer = actions.layer;
-```
-
-- `Toolkit.merge` keeps the later definition on a name collision. Put the customized one last;
-  keep names distinct when adding unrelated tools.
-- `annotate` and `annotateMerge` return a new definition preserving the generated tool's handler
-  identity and approval rule. Keep the original `layer`. Recreating it with `Tool.make` under
-  the same name does not preserve that binding.
 - To add other native tools, use `Toolkit.merge(toolkit, others)` and provide both handler layers
   with `Layer.mergeAll(layer, othersHandlers)`.
 
 ### 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.
+`yield* toolkit` gives `tools.handle(name, arguments)`:
+[assistant/test/toolkit.test.ts](../examples/assistant/test/toolkit.test.ts). Its rules, where
+to provide the caller among them, are on `ActionToolkit.Tools`.
 
 ## 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)).
+[assistant/src/toolkit.ts](../examples/assistant/src/toolkit.ts). Why never to `layer`, and that
+a protected tool owes it whatever its handler reads, are on `Action.Options.caller`
+([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`
+To ask before 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.
+rule reading the call's input and its caller is `toolkit` above; its rules are on
+`ActionToolkit.Options`.
 
 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));
-```
-
-- 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: 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 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.
-- **If repeating a write would create an unwanted additional effect, retries need application-owned deduplication.** Keep the same operation key across attempts, as in [notes-service's creation example](../examples/notes-service/README.md#retry-a-creation). Approval history alone does not make the mutation and its result record atomic.
-- **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.
+`response.content` in place of its result. Start the next turn with the person's answers, in a
+`Chat`, as the caller who was asked:
+[assistant/src/agent.ts](../examples/assistant/src/agent.ts) shows both and says why, tested in
+[assistant/test/toolkit.test.ts](../examples/assistant/test/toolkit.test.ts).
+
+- **Each request is answered on its own**: an approved call runs, a denied one does not, and one
+  left unanswered stays open for a later turn; to require every answer at once, check it in the
+  host. List the open ones with `ActionToolkit.openApprovals(yield* Ref.get(chat.history))`.
+  The kitchen-sink refuses an `approvalId` answered twice
+  ([Assistant.ts](../examples/kitchen-sink/src/assistant/Assistant.ts)), gives each call its own
+  id ([demo-model.ts](../examples/kitchen-sink/src/assistant/demo-model.ts)) and lets only its
+  owner reach a conversation
+  ([conversations.ts](../examples/kitchen-sink/src/assistant/conversations.ts)).
+- A denied call's result, `{ type: "execution-denied", reason }`, has `reason` `undefined` unless
+  the answer gives one, so it is not JSON: a route answering it as a `Schema.Unknown` success
+  answers an empty 500.
+- **If a turn fails or is interrupted once an approved call has started**, the call may have
+  run: end the conversation and say so in the error, as
+  [kitchen-sink/src/assistant/conversations.ts](../examples/kitchen-sink/src/assistant/conversations.ts)
+  and [handlers.ts](../examples/kitchen-sink/src/assistant/handlers.ts) do. What a failed
+  `streamText` leaves is on `ActionToolkit.openApprovals`.
+- **Show the person what is asked**: [assistant/src/agent.ts](../examples/assistant/src/agent.ts)
+  joins each request to its call by `toolCallId`; how to read the arguments is on
+  `ActionToolkit.Approval`.
+- **If repeating a write would create an unwanted additional effect, retries need
+  application-owned deduplication.** Keep the same operation key across attempts, as in
+  [notes-service's creation example](../examples/notes-service/README.md#retry-a-creation).
+  Approval history alone does not make the mutation and its result record atomic.

package/docs/Authentication-advanced.md

@@ -3,137 +3,200 @@
 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`.   |
+A message the library throws says its fix; for a compiler diagnostic or Effect's own error,
+search [Authentication-failures.md](Authentication-failures.md). For one symbol,
+`grep -rn <symbol> node_modules/@gjermundgaraba/effect-actions/dist/`: each declaration's JSDoc
+carries its rules and gotchas, and this page only what an example cannot show.
 
 ## 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));
+request addresses, which native router middleware provides:
+
+```ts example=kitchen-sink/src/workspaces/tenant.ts
+import { Context, Effect, Option } from "effect";
+import { HttpRouter, HttpServerRequest } from "effect/http";
+
+/**
+ * The workspace a request addresses, from its `X-Workspace` header. It is request context, not
+ * an identity: the verifier reads it to decide which of an account's memberships the caller
+ * acts in. Handlers never read it; they read the workspace of the authenticated member.
+ */
+export class Tenant extends Context.Service<Tenant, Option.Option<string>>()("tracker/Tenant") {}
+
+// Native router middleware. It provides `Tenant` to whatever it is provided to, per request:
+// to the verifier too, when it is provided after the authentication, in a `Layer.provide` of
+// its own: in one array with the authentication it would leave `Tenant` owed, since an array's
+// layers provide to the routes, not to one another.
+export const resolveTenant = HttpRouter.middleware<{ provides: Tenant }>()((route) =>
+  Effect.flatMap(HttpServerRequest.HttpServerRequest, (request) =>
+    Effect.provideService(route, Tenant, Option.fromNullishOr(request.headers["x-workspace"])),
+  ),
+);
 ```
 
-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)).
+The verifier reading it is `authenticateBearer` in
+[kitchen-sink/src/identity/authenticate.ts](../examples/kitchen-sink/src/identity/authenticate.ts),
+and `publicRoutes` in [kitchen-sink/src/routes.ts](../examples/kitchen-sink/src/routes.ts)
+provides the middleware.
 
 ## 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)
+Name the scheme in `Authentication.Options.security`, whose JSDoc says what each scheme gives
+up. See `Session` in
+[kitchen-sink/src/identity/Identity.ts](../examples/kitchen-sink/src/identity/Identity.ts) and
+`authenticateSession` in
+[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.
+For a cookie covering rpcs over a WebSocket, see
+[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, as
+`Authentication.layer` says.
 
 ## 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),
+A route of the host's own, such as a download or a WebSocket upgrade, takes
+`Authentication.protect(descriptor)`, whose rules, authorization and caching included, are on
+its JSDoc:
+
+```ts example=kitchen-sink/src/attachments/download.ts
+import { Effect, Layer } from "effect";
+import { HttpRouter, HttpServerResponse } from "effect/http";
+import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
+import { authorize } from "../identity/authorize.js";
+import { CurrentMember, Session } from "../identity/Identity.js";
+import { GetAttachment } from "./Attachments.js";
+import { AttachmentStore } from "./store.js";
+
+// A route of the host's own: `GET /attachments/<id>` answers the image's bytes, for an `<img>`
+// of the web app, which no action can (an action answers JSON), behind
+// `Authentication.protect(Session)`: the page's cookie, which the web app's rpcs use. A token
+// holder has no use for it: `getAttachment` gives an API client the same image.
+export const download = Layer.unwrap(
+  Effect.map(AttachmentStore, (store) =>
+    HttpRouter.add(
+      "GET",
+      "/attachments/:id",
+      Effect.gen(function* () {
+        // The rule of the action it mirrors.
+        yield* authorize(GetAttachment);
+
+        const member = yield* CurrentMember;
+        const { id = "" } = yield* HttpRouter.params;
+        const { image } = yield* store.get(member.workspace, id);
+
+        // An attachment never changes, but it is one workspace's: `private`.
+        return HttpServerResponse.uint8Array(image.data, {
+          contentType: image.mimeType,
+          headers: {
+            "cache-control": "private, max-age=31536000, immutable",
+            // What a member uploaded is served from the application's own origin, and an image
+            // can be a document: an SVG opened by its URL, not in an `<img>`, runs its scripts
+            // as the member reading it. `sandbox` gives it no origin and no scripts, and
+            // `nosniff` keeps the browser to the type stated.
+            "content-security-policy": "sandbox",
+            "x-content-type-options": "nosniff",
+          },
+        });
+      }).pipe(
+        Effect.catchTag("AttachmentNotFound", () =>
+          Effect.succeed(HttpServerResponse.empty({ status: 404 })),
+        ),
+      ),
+    ).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.
+[kitchen-sink/test/attachments/attachments.test.ts](../examples/kitchen-sink/test/attachments/attachments.test.ts)
+asserts what it answers.
 
 ## 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:
+For a check that must refuse a request before its credential is read, such as a `Host` or
+`Origin` allowlist, make global router middleware, `HttpRouter.middleware(check, { global: true })`,
+and provide it in the last `Layer.provide`:
+
+```ts example=kitchen-sink/src/request-policy.ts
+import { Effect, Layer, Option } from "effect";
+import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/http";
+import { allowedOrigins, publicUrl } from "./config.js";
+
+const loopback = ["localhost", "127.0.0.1"];
+
+// Which Host and Origin a request may carry: not the library's concern, but every request of
+// both ports passes it first. A Host that is neither loopback nor the public URL's is refused,
+// against DNS rebinding. The web app signs in with a cookie, which a browser attaches to
+// any page's request, so a foreign Origin must be refused before authentication reads it.
+// That is why this is global router middleware (`global: true`): it runs before routing, so
+// before every route's authentication. As a layer's own `middleware` it would run inside the
+// authentication, too late.
+export const requestPolicy = HttpRouter.middleware(
+  Effect.gen(function* () {
+    const hosts = [...loopback, new URL(yield* publicUrl).hostname];
+    const origins = yield* allowedOrigins;
+
+    return (httpEffect) =>
+      Effect.gen(function* () {
+        const request = yield* HttpServerRequest.HttpServerRequest;
+        const url = HttpServerRequest.toURL(request.modify({ url: request.originalUrl }));
+
+        if (Option.isNone(url) || !hosts.includes(url.value.hostname)) {
+          return HttpServerResponse.text("Host not allowed", { status: 403 });
+        }
+
+        const origin = request.headers["origin"];
+
+        // The request's own origin is that of a page served from this port directly. Behind a
+        // proxy ending TLS it is an `http:` one from Effect 4.0.6, whose `originalUrl` takes the
+        // scheme of the connection, whatever `X-Forwarded-Proto` says, so the public URL's
+        // origin is among `origins`.
+        if (origin !== undefined && origin !== url.value.origin && !origins.includes(origin)) {
+          return HttpServerResponse.text("Origin not allowed", { status: 403 });
+        }
+
+        return yield* httpEffect;
+      });
+  }),
+  { global: true },
+);
 
-```ts
-routes.pipe(Layer.provide(authenticate), Layer.provide(requestPolicy));
+// CORS for the one cross-origin caller, a browser MCP client. `HttpRouter.cors` is global to
+// the router too: it answers the preflight before any route's authentication, and adds its
+// headers to refusals as well. An MCP endpoint's `allowedOrigins` is no CORS: it only refuses
+// origins. The headers are those an MCP client sends and must be able to read. A client of an
+// MCP revision with sessions sends its session's id on each request, reads it from the answer
+// that opened the session, and ends the session with a `DELETE`.
+export const cors = Layer.unwrap(
+  Effect.map(allowedOrigins, (origins) =>
+    HttpRouter.cors({
+      allowedOrigins: origins,
+      allowedMethods: ["POST", "DELETE"],
+      allowedHeaders: [
+        "Content-Type",
+        "Authorization",
+        "X-Workspace",
+        "MCP-Protocol-Version",
+        "MCP-Method",
+        "MCP-Name",
+        "Mcp-Session-Id",
+      ],
+      exposedHeaders: ["WWW-Authenticate", "MCP-Protocol-Version", "Mcp-Session-Id"],
+    }),
+  ),
+);
 ```
 
-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.
+See `publicRoutes` in [kitchen-sink/src/routes.ts](../examples/kitchen-sink/src/routes.ts);
+[kitchen-sink/test/request-policy.test.ts](../examples/kitchen-sink/test/request-policy.test.ts)
+asserts it.
 
 ## 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.
+For a caller the router never routes, such as a Node `upgrade` handler admitting a socket, read
+the token with `Authentication.bearerTokenOf` and answer a refusal with
+`Authentication.refusalResponse`, whose JSDoc holds the rest.