@gjermundgaraba/effect-actions 0.11.0 → 0.13.0

package/examples/assistant/test/identity/identity.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "@effect/vitest";
+import { Effect, Ref } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { identity } from "../../src/identity/handlers.js";
+import { CurrentCaller, type Member, type Operator } from "../../src/identity/Identity.js";
+import { members } from "../../src/identity/members.js";
+import { type Permission, Permissions } from "../../src/identity/permissions.js";
+
+const as = (caller: Member | Operator) => Effect.provideService(CurrentCaller, caller);
+
+const operator: Operator = { kind: "operator", id: "root" };
+
+describe("identity, in process", () => {
+  it.effect("answers each call with its own caller, from one client", () =>
+    Effect.gen(function* () {
+      const client = yield* Action.client(identity);
+
+      expect(yield* client.whoAmI().pipe(as(members.ada))).toEqual({ id: "ada", kind: "member" });
+      expect(yield* client.whoAmI().pipe(as(operator))).toEqual({ id: "root", kind: "operator" });
+    }).pipe(Effect.provide(Permissions.layerMemory)),
+  );
+
+  it.effect("gets the permission store once and asks it on every call", () =>
+    Effect.gen(function* () {
+      const granted = yield* Ref.make<ReadonlyArray<Permission>>([]);
+
+      // The store is a startup service, so it is provided where the client is acquired: the
+      // authorizer is built there. No call is given it again.
+      const client = yield* Action.client(identity).pipe(
+        Effect.provideService(Permissions, Permissions.of({ granted: () => Ref.get(granted) })),
+      );
+
+      const refusal = yield* Effect.flip(client.whoAmI().pipe(as(members.ada)));
+
+      expect(refusal).toBeInstanceOf(Action.Forbidden);
+      expect(refusal.message).toBe("Requires tasks:read.");
+
+      yield* Ref.set(granted, ["tasks:read"]);
+
+      expect(yield* client.whoAmI().pipe(as(members.ada))).toEqual({ id: "ada", kind: "member" });
+    }),
+  );
+});

package/examples/assistant/test/tasks/store.test.ts

@@ -0,0 +1,48 @@
+import { NodeServices } from "@effect/platform-node";
+import { describe, expect, it } from "@effect/vitest";
+import { ConfigProvider, Effect, FileSystem, Layer, Path } from "effect";
+import { TaskStore } from "../../src/tasks/store.js";
+
+// The file store, on a file of the test's own: `ASSISTANT_TASKS` is set through a
+// `ConfigProvider`, as the environment sets it for an entrypoint. The directory is removed
+// with the test's scope.
+const fileStore = Effect.gen(function* () {
+  const files = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const directory = yield* files.makeTempDirectoryScoped();
+  const tasks = path.join(directory, "tasks.json");
+  const config = ConfigProvider.fromUnknown({ ASSISTANT_TASKS: tasks });
+
+  return TaskStore.layerFile.pipe(Layer.provide(ConfigProvider.layer(config)));
+});
+
+describe("the file store", () => {
+  it.effect("gives each of several concurrent adds, as one model turn makes them, its own id", () =>
+    Effect.gen(function* () {
+      const store = yield* TaskStore;
+
+      const added = yield* Effect.all(
+        ["Book the venue", "Send invitations", "Order lunch"].map((title) =>
+          store.add("ada", title, "ada"),
+        ),
+        { concurrency: "unbounded" },
+      );
+
+      expect(added.map(({ id }) => id)).toEqual(["1", "2", "3"]);
+      expect(yield* store.list("ada")).toEqual(added);
+    }).pipe(Effect.provide(Layer.unwrap(fileStore)), Effect.provide(NodeServices.layer)),
+  );
+
+  it.effect("keeps tasks for the next process: a layer built again reads them", () =>
+    Effect.gen(function* () {
+      const store = yield* fileStore;
+      const add = Effect.flatMap(TaskStore, (tasks) => tasks.add("root", "Rotate keys", "ada"));
+      const list = Effect.flatMap(TaskStore, (tasks) => tasks.list(undefined));
+
+      // `local` builds the layer anew for each, as each run of the agent or of a command does.
+      const task = yield* add.pipe(Effect.provide(store, { local: true }));
+
+      expect(yield* list.pipe(Effect.provide(store, { local: true }))).toEqual([task]);
+    }).pipe(Effect.provide(NodeServices.layer)),
+  );
+});

package/examples/assistant/test/tasks/tasks.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from "@effect/vitest";
+import { Effect, Layer } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { CurrentCaller, type Member, type Operator } from "../../src/identity/Identity.js";
+import { members } from "../../src/identity/members.js";
+import { Permissions } from "../../src/identity/permissions.js";
+import { tasks } from "../../src/tasks/handlers.js";
+import { TaskNotFound } from "../../src/tasks/Tasks.js";
+import { TaskStore } from "../../src/tasks/store.js";
+
+// What the implementation does, with no model and no command line: `Action.client` runs the
+// same decoding, `authorize` and handler every surface runs. Each call names its caller.
+const as = (caller: Member | Operator) => Effect.provideService(CurrentCaller, caller);
+
+const operator: Operator = { kind: "operator", id: "root" };
+
+// A test supplies its services as an entrypoint does: here the store is memory.
+const services = Layer.mergeAll(TaskStore.layerMemory, Permissions.layerMemory);
+
+describe("tasks, in process", () => {
+  it.effect("records which caller added a task, a member or the operator", () =>
+    Effect.gen(function* () {
+      const client = yield* Action.client(tasks);
+
+      yield* client.addTask({ title: "Book the venue", assignee: "ada" }).pipe(as(members.ada));
+      yield* client.addTask({ title: "Send invitations", assignee: "grace" }).pipe(as(operator));
+
+      const { tasks: listed } = yield* client.listTasks().pipe(as(members.grace));
+
+      expect(listed.map(({ id, addedBy }) => [id, addedBy])).toEqual([
+        ["1", "ada"],
+        ["2", "root"],
+      ]);
+      expect(yield* client.listTasks({ assignee: "grace" }).pipe(as(members.grace))).toMatchObject({
+        tasks: [{ title: "Send invitations" }],
+      });
+    }).pipe(Effect.provide(services)),
+  );
+
+  it.effect("refuses a write from a member the store grants reading alone", () =>
+    Effect.gen(function* () {
+      const client = yield* Action.client(tasks);
+      const add = client.addTask({ title: "Order lunch", assignee: "guest" });
+
+      const refusal = yield* Effect.flip(add.pipe(as(members.guest)));
+
+      // `toEqual` on an error compares its fields and never its message, so the message is
+      // asserted on its own.
+      expect(refusal).toBeInstanceOf(Action.Forbidden);
+      expect(refusal.message).toBe("Requires tasks:write.");
+      expect(yield* client.listTasks().pipe(as(members.guest))).toEqual({ tasks: [] });
+    }).pipe(Effect.provide(services)),
+  );
+
+  it.effect("admits the operator, whom the permission store does not know", () =>
+    Effect.gen(function* () {
+      const client = yield* Action.client(tasks);
+      const add = client.addTask({ title: "Rotate the keys", assignee: "ada" });
+      const { id } = yield* add.pipe(as(operator));
+
+      expect(yield* client.completeTask({ id }).pipe(as(operator))).toMatchObject({ done: true });
+    }).pipe(Effect.provide(services)),
+  );
+
+  it.effect("fails with the declared error for a task that does not exist", () =>
+    Effect.gen(function* () {
+      const client = yield* Action.client(tasks);
+      const annotate = client.annotateTask({ id: "9", notes: "Urgent." });
+
+      expect(yield* Effect.flip(annotate.pipe(as(members.ada)))).toEqual(
+        new TaskNotFound({ id: "9" }),
+      );
+    }).pipe(Effect.provide(services)),
+  );
+});

package/examples/assistant/test/toolkit.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, it } from "@effect/vitest";
+import { Effect, Layer, Stream } from "effect";
+import { Chat, LanguageModel } from "effect/ai";
+import type { Member } from "../src/identity/Identity.js";
+import { members } from "../src/identity/members.js";
+import { Permissions } from "../src/identity/permissions.js";
+import { scripted } from "../src/scripted.js";
+import { TaskStore } from "../src/tasks/store.js";
+import { actingFor, layer, toolkit } from "../src/toolkit.js";
+
+// What the toolkit adds to the implementations: a caller per call, and a model's approvals.
+// The handlers run in this process, on a store in memory the tests can read too.
+const tools = layer.pipe(
+  Layer.provideMerge(Layer.mergeAll(TaskStore.layerMemory, Permissions.layerMemory)),
+);
+
+// A model's call of `addTask`, as a provider sends it.
+const adding = (id: string, assignee: string) =>
+  ({ type: "tool-call", id, name: "addTask", params: { title: "Order lunch", assignee } }) as const;
+
+// Which calls of a turn ran, and which wait for a person.
+const outcome = (response: LanguageModel.GenerateTextResponse<typeof toolkit.tools, "opaque">) => ({
+  ran: response.toolResults.map(({ id }) => id),
+  waiting: response.content.flatMap((part) =>
+    part.type === "tool-approval-request" ? [part.toolCallId] : [],
+  ),
+});
+
+describe("the toolkit", () => {
+  it.effect("runs each call as the member provided around it", () =>
+    Effect.gen(function* () {
+      const { handle } = yield* toolkit;
+
+      // A call by hand, with the JSON arguments a model sends. The member goes around the whole
+      // call, the collecting of its results included.
+      const add = handle("addTask", { title: "Order lunch", assignee: "guest" }).pipe(
+        Effect.flatMap(Stream.runCollect),
+      );
+
+      // A refusal is not raised: it is a result the model reads, as a declared error is.
+      expect(yield* add.pipe(actingFor(members.guest))).toMatchObject([
+        { isFailure: true, result: { message: "Requires tasks:write." } },
+      ]);
+      expect(yield* add.pipe(actingFor(members.ada))).toMatchObject([
+        { isFailure: false, result: { id: "1", addedBy: "ada" } },
+      ]);
+    }).pipe(Effect.provide(tools)),
+  );
+
+  it.effect("asks for approval before a model adds to a list that is not its caller's", () =>
+    Effect.gen(function* () {
+      // `LanguageModel` is what enforces approval: a call by hand, as above, is never asked.
+      // The model answers each member with the same two calls.
+      const plan = (member: Member) =>
+        LanguageModel.generateText({ prompt: "Plan the launch.", toolkit }).pipe(
+          actingFor(member),
+          Effect.map(outcome),
+          Effect.provide(scripted([adding("for ada", "ada"), adding("for grace", "grace")])),
+        );
+
+      expect(yield* plan(members.ada)).toEqual({ ran: ["for ada"], waiting: ["for grace"] });
+      expect(yield* plan(members.grace)).toEqual({ ran: ["for grace"], waiting: ["for ada"] });
+
+      // A call that waits has not run.
+      const store = yield* TaskStore;
+
+      expect((yield* store.list(undefined)).map(({ addedBy }) => addedBy)).toEqual([
+        "ada",
+        "grace",
+      ]);
+    }).pipe(Effect.provide(tools)),
+  );
+
+  it.effect("authorizes an approved call too: approval lets no one do what they may not", () =>
+    Effect.gen(function* () {
+      // The `Chat` keeps the request in its history, which the answer is matched against.
+      const chat = yield* Chat.empty;
+
+      const asked = yield* chat
+        .generateText({ prompt: "Add lunch to Ada's list.", toolkit })
+        .pipe(actingFor(members.guest));
+
+      expect(outcome(asked)).toEqual({ ran: [], waiting: ["for ada"] });
+
+      // The approved call runs in the turn that carries the answer, as that turn's caller.
+      const answered = yield* chat
+        .generateText({
+          prompt: [
+            {
+              role: "tool",
+              content: asked.content.flatMap((part) =>
+                part.type === "tool-approval-request"
+                  ? [
+                      {
+                        type: "tool-approval-response",
+                        approvalId: part.approvalId,
+                        approved: true,
+                      },
+                    ]
+                  : [],
+              ),
+            },
+          ],
+          toolkit,
+        })
+        .pipe(actingFor(members.guest));
+
+      expect(answered.toolResults).toMatchObject([
+        {
+          id: "for ada",
+          isFailure: true,
+          result: { message: "Requires tasks:write." },
+        },
+      ]);
+
+      const store = yield* TaskStore;
+
+      expect(yield* store.list(undefined)).toEqual([]);
+    }).pipe(Effect.provide(scripted([adding("for ada", "ada")])), Effect.provide(tools)),
+  );
+});

package/examples/kitchen-sink/README.md

@@ -0,0 +1,318 @@
+# kitchen-sink
+
+The reference application: one multi-tenant issue tracker that uses every module of the library
+and nearly every option. Members of a workspace file, discuss and close issues, and attach
+screenshots, over HTTP, MCP, Effect RPC, a CLI and an assistant, in process and behind a route.
+Operators suspend workspaces on a second port, or from a console on the host.
+
+Open it when you need a working use of one feature: the [index](#index) maps each export and
+option to the file that shows it. To start an application, copy
+[notes-service](../notes-service/) instead; it is this layout at a size you can read in one
+sitting.
+
+## Run it
+
+From the repository root, after `vp install` (from an installed package, see
+[Run one](../README.md#run-one)):
+
+```sh
+node --import tsx examples/kitchen-sink/src/server.ts    # members on 127.0.0.1:3000, operators on :3001
+node --import tsx examples/kitchen-sink/src/seed.ts      # files ACME-1 with a screenshot and a comment
+
+export TRACKER_TOKEN=ada TRACKER_WORKSPACE=acme          # a demo member, see below
+node --import tsx examples/kitchen-sink/src/cli.ts --help
+node --import tsx examples/kitchen-sink/src/cli.ts list-issues -n 5
+node --import tsx examples/kitchen-sink/src/cli.ts get-issue ACME-1
+echo "It crashes on an empty draft" | node --import tsx examples/kitchen-sink/src/cli.ts create-issue --title Crash
+node --import tsx examples/kitchen-sink/src/cli.ts ask-assistant --prompt "Close what is done."   # answers with a call to approve
+
+# The admin port takes an operator key, not a member's token.
+curl -s 127.0.0.1:3001/admin/suspendWorkspace -H 'Content-Type: application/json' \
+  -H 'X-Operator-Key: ops-key' -d '{"workspace":"acme"}'
+
+node --import tsx examples/kitchen-sink/src/ops.ts list-workspaces   # the operators' console, no server
+node --import tsx examples/kitchen-sink/src/agent.ts                 # the assistant, with a scripted model
+
+vp test examples/kitchen-sink
+```
+
+`HOST`, `PORT`, `ADMIN_PORT`, `PUBLIC_URL` and `MCP_ORIGIN` configure the server; `TRACKER_URL`
+points the CLI and the seed at it. `stdio.ts` is an MCP server for a local agent to start as a
+subprocess. `sdk.ts` and `browser.ts` are imported by client code, not run. The OpenAPI
+document is at `/api/v1/openapi.json`, Swagger UI at `/docs`, the MCP endpoint at `/mcp`, the
+socket at `/rpc`.
+
+Everything is a demo: stores are memory, and the credentials are fixed strings. Replace both
+before deploying anything.
+
+| Credential                            | Who                    | May                                    |
+| ------------------------------------- | ---------------------- | -------------------------------------- |
+| `Authorization: Bearer ada`           | ada, in acme or globex | read and write in acme, read in globex |
+| `Authorization: Bearer linus`         | linus, in acme         | read                                   |
+| `Authorization: Bearer grace`         | grace, in globex       | read and write                         |
+| `Cookie: tracker_session=ada-at-acme` | ada in acme, on `/rpc` | read and write                         |
+| `X-Operator-Key: ops-key`             | operator `ops`         | list, suspend and resume workspaces    |
+| `X-Operator-Key: support-key`         | operator `support`     | list workspaces                        |
+
+A bearer request names its workspace in `X-Workspace: acme`. `kay` (token `kay`, session
+`kay-at-acme`) is a member of acme granted no scope yet. The session cookie also opens
+`GET /attachments/<id>`, the image for a page of the web app; a token holder calls `getAttachment`.
+
+## Layout
+
+```text
+src/
+├── identity/              who is calling
+│   ├── Identity.ts        contract: CurrentMember, scopes, the Login and Session descriptors, whoAmI
+│   ├── members.ts         DEMO ONLY: the people of the demo
+│   ├── directory.ts       Directory: who a token or a session names
+│   ├── authenticate.ts    Authentication.layer for both descriptors, OAuth discovery
+│   ├── authorize.ts       the members' rule: readOnly to a scope
+│   ├── quota.ts           the request quota, as HTTP and as RPC middleware
+│   └── handlers.ts
+├── workspaces/            the tenants
+│   ├── Workspaces.ts      contract: Workspace, the public getStatus
+│   ├── registry.ts        WorkspaceRegistry: the workspaces and their suspension
+│   ├── tenant.ts          Tenant, and the router middleware that resolves it per request
+│   └── handlers.ts
+├── issues/
+│   ├── Issues.ts          contract: schemas, errors, five actions
+│   ├── store.ts           IssueStore, scoped by workspace
+│   ├── write-limit.ts     the write limit, wrapped around handlers
+│   ├── handlers.ts        Action.implement over the store
+│   ├── guide.ts           a native MCP resource and prompt
+│   └── assistant.ts       the actions as a model's Toolkit, with approval
+├── assistant/             the model loop, served: a turn per request
+│   ├── Assistant.ts       contract: a turn, askAssistant and answerAssistant
+│   ├── conversations.ts   Conversations: each member's Chat, one turn at a time, ended where a turn fails
+│   ├── demo-model.ts      DEMO ONLY: a scripted model
+│   └── handlers.ts        the loop, approvals across requests, what a turn reports
+├── attachments/
+│   ├── Attachments.ts     contract: an image in an input and in a success
+│   ├── store.ts
+│   ├── handlers.ts
+│   └── download.ts        GET /attachments/:id, the host's own route, for the web app
+├── admin/                 the operators, a second audience
+│   ├── Admin.ts           contract: Operator, the OperatorKey descriptor, three actions
+│   ├── grants.ts          Grants: what each operator may do
+│   ├── authorize.ts       the operators' rule, built from Grants
+│   ├── keys.ts            DEMO ONLY: the operator keys
+│   ├── authenticate.ts    Authentication.layer for OperatorKey
+│   └── handlers.ts
+├── Actions.ts             which actions each surface gets
+├── Api.ts                 the two HTTP bindings
+├── Rpc.ts                 the RPC binding
+├── config.ts              what a deployment sets
+├── request-policy.ts      the Host and Origin policy, and CORS
+├── routes.ts              every surface of both ports, and the builders they share
+├── memory.ts              DEMO ONLY: the services in memory
+├── server.ts              entrypoint: both ports, the rpcs over a WebSocket
+├── stdio.ts               entrypoint: MCP for a local agent
+├── cli.ts                 entrypoint: the members' commands, calling the server
+├── ops.ts                 entrypoint: the operators' console, in process
+├── agent.ts               entrypoint: the assistant
+├── seed.ts                entrypoint: an Effect program calling the API
+├── sdk.ts                 entrypoint: a promise client
+└── browser.ts             entrypoint: the web app's RPC client
+test/
+├── routes.test.ts         the host's surfaces: one port over HTTP and MCP, then both ports
+├── request-policy.test.ts raw requests to each port as a web handler
+├── issues/                in process, with Action.client; the assistant's tools
+├── assistant/             the assistant over HTTP, with a scripted model
+├── support/               the scripted model the assistant's tests give the routes
+├── identity/              what authentication adds: tokens over HTTP, sessions over RPC
+├── attachments/           images over HTTP and MCP; the download route
+└── admin/                 the operators' grants; the trusted operator
+```
+
+- **A folder per domain.** `identity/` and `admin/` are the two audiences; `workspaces/`,
+  `issues/` and `attachments/` are what they work on. In each, the PascalCase file is the
+  contract and imports no server code; the lowercase files run on the server.
+- **Top-level files are the host's.** `Actions.ts`, `Api.ts` and `Rpc.ts` say what is served
+  where, and stay browser-safe. `routes.ts` builds the surfaces. Each entrypoint chooses the
+  services, here from `memory.ts`. `server.ts` also chooses the rpcs' protocol, and a local
+  one lists the implementations it serves itself.
+- **Three callers' credentials, three descriptors.** API clients, the CLI and MCP clients send
+  a bearer token (`Login`). The web app sends its session cookie (`Session`) for the same
+  identity, on its own binding. Operators send a key (`OperatorKey`) for another identity, on
+  another port.
+- **Two limits, in two places.** The request quota is HTTP and RPC middleware
+  (`identity/quota.ts`): it counts before the input is decoded. The write limit is the
+  handlers' (`issues/write-limit.ts`): it holds on every surface, MCP and the assistant
+  included.
+
+## Where to look
+
+| To see                                                                  | Read                                                    |
+| ----------------------------------------------------------------------- | ------------------------------------------------------- |
+| How one request is authenticated, placed in a tenant, authorized        | `src/identity/authenticate.ts`, `src/routes.ts`         |
+| Two audiences on two ports over one set of services                     | `src/server.ts`, `src/routes.ts`, `test/routes.test.ts` |
+| Which actions each surface serves, and why one is no tool               | `src/Actions.ts`                                        |
+| A limit before decoding and a limit in the handlers                     | `src/identity/quota.ts`, `src/issues/write-limit.ts`    |
+| An image for a model and a client (an action), and for a page (a route) | `src/attachments/`                                      |
+| A caller the host names itself                                          | `src/stdio.ts`, `src/ops.ts`, `src/agent.ts`            |
+| A model loop behind a route, approvals answered in a later request      | `src/assistant/handlers.ts`, `src/routes.ts`            |
+| What to test in process and what over the wire                          | `test/issues/issues.test.ts`, `test/routes.test.ts`     |
+
+## Index
+
+Each export and option the example uses, and where. A symbol in parentheses is the name to
+search for in the file.
+
+### Action
+
+| Export or option                                               | File                                                                                 |
+| -------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| `make`: `input`, `success`, `error`, `readOnly`                | `src/issues/Issues.ts`                                                               |
+| `make`: `caller: Action.Anyone`, a public action               | `src/workspaces/Workspaces.ts` (`GetStatus`)                                         |
+| `make`: `caller`, an identity service                          | `src/identity/Identity.ts` (`CurrentMember`, `WhoAmI`)                               |
+| `make`: `mcp` (`title`, hints)                                 | `src/issues/Issues.ts` (`CreateIssue`, `CloseIssue`)                                 |
+| `make`: no `input`                                             | `src/identity/Identity.ts` (`WhoAmI`)                                                |
+| `make`: an optional and a defaulted input field                | `src/issues/Issues.ts` (`ListIssues`)                                                |
+| `make`: errors with `httpApiStatus`                            | `src/issues/Issues.ts` (`IssueNotFound`, `RateLimited`)                              |
+| `make`: a shared error list                                    | `src/issues/Issues.ts` (`IssueWriteErrors`), `src/attachments/Attachments.ts`        |
+| `make`: an option bundle, spread                               | `src/issues/Issues.ts` (`change`), `src/admin/Admin.ts` (`onWorkspace`)              |
+| `Image`, in a success and in an input                          | `src/attachments/Attachments.ts`                                                     |
+| `byName`                                                       | `src/issues/guide.ts` (`tools`)                                                      |
+| `implement`: one action, a plain handler                       | `src/identity/handlers.ts`                                                           |
+| `implement`: one action, a builder                             | `src/workspaces/handlers.ts`                                                         |
+| `implement`: several actions sharing a builder                 | `src/issues/handlers.ts`                                                             |
+| Startup services and per-request services                      | `src/issues/handlers.ts`                                                             |
+| A rate limit in handlers, shared by several                    | `src/issues/write-limit.ts`, `src/issues/handlers.ts`, `src/attachments/handlers.ts` |
+| `implement`: `authorize`, a rule from `readOnly`               | `src/identity/authorize.ts`                                                          |
+| `implement`: `authorize`, an Effect building it                | `src/admin/authorize.ts`                                                             |
+| `allowAll`                                                     | `src/identity/handlers.ts`                                                           |
+| `Forbidden` with `scopes`, and without                         | `src/identity/authorize.ts`, `src/admin/authorize.ts`                                |
+| `Unauthenticated`                                              | `src/identity/directory.ts`, `src/admin/authenticate.ts`                             |
+| `InvalidInput` with `issues`, from a handler                   | `src/attachments/handlers.ts`                                                        |
+| `layer`, one builder run for an implementation two ports serve | `src/routes.ts` (`builders`), `src/server.ts`, `test/routes.test.ts`                 |
+| `client`                                                       | `src/agent.ts`, `test/issues/issues.test.ts`                                         |
+| `client`: `actions`                                            | `test/issues/issues.test.ts`                                                         |
+| `Any`, an authorizer's parameter                               | `src/identity/authorize.ts`                                                          |
+
+### Authentication
+
+| Export or option                                               | File                                                            |
+| -------------------------------------------------------------- | --------------------------------------------------------------- |
+| `make`, Bearer, with a declared `error` (503)                  | `src/identity/Identity.ts` (`Login`, `IssuerUnavailable`)       |
+| `make`: `security`, a cookie, for the same identity            | `src/identity/Identity.ts` (`Session`)                          |
+| `make`: `security`, an API key in a header                     | `src/admin/Admin.ts` (`OperatorKey`)                            |
+| `layer`, a verifier built from startup services                | `src/identity/authenticate.ts`                                  |
+| `layer`, a plain verifier                                      | `src/admin/authenticate.ts`                                     |
+| `layer`: `protectedResource`, an Effect over `Config`          | `src/identity/authenticate.ts` (`protectedResource`)            |
+| `ProtectedResource`                                            | `src/identity/authenticate.ts`                                  |
+| A request service the verifier reads, and its order            | `src/workspaces/tenant.ts`, `src/routes.ts` (`publicRoutes`)    |
+| `protect`, a route of the host's own, by the cookie descriptor | `src/attachments/download.ts`                                   |
+| A trusted identity no verifier returns                         | `src/admin/Admin.ts`, `src/admin/authenticate.ts`, `src/ops.ts` |
+| A verifier's declared error over MCP                           | `test/identity/identity.test.ts`                                |
+| A test replacing a verifier's service                          | `test/identity/identity.test.ts` (`issuerDown`)                 |
+
+### ActionHttp
+
+| Export or option                                               | File                                                                        |
+| -------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `make`: `prefix`, `authentication`, `error`                    | `src/Api.ts` (`Http`)                                                       |
+| A second binding for a second identity                         | `src/Api.ts` (`AdminHttp`)                                                  |
+| One action in two bindings                                     | `src/Api.ts` (`GetStatus`), `src/routes.ts` (`adminRoutes`)                 |
+| `layer`: `actions`                                             | `src/routes.ts` (`api`)                                                     |
+| `layer`: `middleware`                                          | `src/routes.ts` (`api`), `src/identity/quota.ts` (`HttpQuota`)              |
+| Global router middleware, before authentication and discovery  | `src/request-policy.ts` (`requestPolicy`), `src/routes.ts` (`publicRoutes`) |
+| `Http.api`, `Http.prefix`: the OpenAPI document and Swagger UI | `src/routes.ts` (`documentation`)                                           |
+| A request body limit                                           | `src/server.ts`                                                             |
+| Two `HttpRouter.serve`, what they share provided outside both  | `src/server.ts`                                                             |
+| `client`: `baseUrl`, `transformClient`                         | `src/seed.ts`                                                               |
+| `fetchClient`                                                  | `src/sdk.ts`                                                                |
+| Declared errors handled by tag                                 | `src/seed.ts`, `src/sdk.ts`                                                 |
+
+### ActionMcp
+
+| Export or option                                 | File                                                |
+| ------------------------------------------------ | --------------------------------------------------- |
+| `layerHttp`, public and protected tools together | `src/routes.ts` (`mcp`)                             |
+| `layerHttp`: `authentication`, `instructions`    | `src/routes.ts` (`mcp`)                             |
+| `layerHttp`: `actions`, one action left off      | `src/routes.ts` (`mcp`), `src/Actions.ts` (`Tools`) |
+| `layerHttp`: `allowedOrigins`                    | `src/routes.ts` (`mcp`), `test/routes.test.ts`      |
+| `layerHttp`: `features`, a resource and a prompt | `src/issues/guide.ts`                               |
+| CORS for a browser MCP client                    | `src/request-policy.ts` (`cors`)                    |
+| `runStdio`, the host naming the caller           | `src/stdio.ts`                                      |
+| An image block from a media field                | `src/attachments/Attachments.ts` (`GetAttachment`)  |
+
+### ActionRpc
+
+| Export or option                  | File                                                          |
+| --------------------------------- | ------------------------------------------------------------- |
+| `make`: `authentication`, `error` | `src/Rpc.ts`                                                  |
+| `layer`: `middleware`             | `src/routes.ts` (`rpc`), `src/identity/quota.ts` (`RpcQuota`) |
+| A WebSocket protocol              | `src/server.ts` (`socket`)                                    |
+| `client`, over a WebSocket        | `src/browser.ts`                                              |
+| A credential per message          | `test/identity/session.test.ts` (`as`)                        |
+
+### ActionToolkit
+
+| Export or option                                    | File                                 |
+| --------------------------------------------------- | ------------------------------------ |
+| `make`: `actions`, `needsApproval` (a boolean rule) | `src/issues/assistant.ts`            |
+| `toolkit` given to `LanguageModel`                  | `src/issues/assistant.ts` (`triage`) |
+| `layer`, and the caller per turn                    | `src/agent.ts`                       |
+| `toolkit` and the model yielded in a builder        | `src/assistant/handlers.ts`          |
+| `layer` provided to the routes                      | `src/routes.ts` (`assistantTools`)   |
+| An approval answered in a later request             | `src/assistant/handlers.ts`          |
+| `tools.handle`, a call made by hand                 | `test/issues/assistant.test.ts`      |
+
+### ActionCli
+
+| Export or option                                               | File                                       |
+| -------------------------------------------------------------- | ------------------------------------------ |
+| `remote`: `name`, `commands`                                   | `src/cli.ts`                               |
+| `commands`: `stdin`, `positional`, `aliases`, `render`, `name` | `src/cli.ts`                               |
+| A client from `Config`, its credentials optional               | `src/cli.ts`                               |
+| `make`, with a trusted identity the host supplies              | `src/ops.ts`                               |
+| `logToStderr`                                                  | `src/cli.ts`, `src/ops.ts`, `src/stdio.ts` |
+
+### Testing
+
+| Export or option                                 | File                                                          |
+| ------------------------------------------------ | ------------------------------------------------------------- |
+| `layer(routes)`                                  | `test/identity/identity.test.ts`                              |
+| `layer(routes)`, twice, over shared builders     | `test/routes.test.ts` (`shared`)                              |
+| `layer(handler)`, over `HttpRouter.toWebHandler` | `test/request-policy.test.ts`                                 |
+| `mcpClient`: `transformClient`                   | `test/routes.test.ts`                                         |
+| `mcpClient`, decoding an image                   | `test/attachments/attachments.test.ts`                        |
+| `McpCallError`                                   | `test/identity/identity.test.ts`                              |
+| `mcpRequest`: `headers`, `url`                   | `test/attachments/attachments.test.ts`, `test/routes.test.ts` |
+| RPC in memory, over Effect's HTTP protocol       | `test/identity/session.test.ts`                               |
+| A service the test and the routes both read      | `test/identity/session.test.ts` (`served`)                    |
+| A test replacing one service                     | `test/identity/identity.test.ts` (`servedWith`)               |
+| `Action.client`, a caller per call               | `test/issues/issues.test.ts`                                  |
+| A scripted `LanguageModel`                       | `test/issues/assistant.test.ts`, `test/support/scripted.ts`   |
+| A test replacing the model the routes are given  | `test/assistant/assistant.test.ts` (`served`)                 |
+| An error's message asserted beside its fields    | `test/issues/issues.test.ts`                                  |
+
+## Not shown
+
+Left out because this application has no honest place for them:
+
+- `Authentication.refusalResponse` and `bearerTokenOf`. They serve a caller the router never
+  routes, such as a Node `upgrade` handler. Every caller here is routed: the socket is Effect's
+  own WebSocket route, authenticated per message.
+- A descriptor with `HttpApiSecurity.basic`, and an API key in the query.
+- `Action.implement` with a plain record of handlers: every implementation of several actions
+  here has a builder. `implementation.actions`. `mcp._meta`.
+- `ActionCli.command` and `remoteCommand`, one action as one command; `make`'s and `remote`'s
+  `actions`; `remote`'s static `client` option. Both CLIs here are aggregates of every action,
+  and the remote one reads its client from `Config`. `subcommands` and `toUserError`, a command
+  written by hand: [notes-service](../notes-service/) has one.
+- `ActionRpc.layer`'s `actions`, `Rpc.group`, and `ActionRpc.client`'s options.
+- A binding's other fields, `Http.actions`, `Http.error` and `Http.authentication`.
+- `ActionMcp`'s `path`, `description`, `websiteUrl`, `icons` and `extensions`; `fetchClient`'s
+  `fetch`.
+- `needsApproval` as an Effect reading the caller: the rule here is a boolean of the action.
+- `Action.InvalidInput.fromSchemaError`, the `Action.Refusal` and `Action.BuiltIn` schemas, and the
+  helper types: `Action.Issue`, `Errors`, `Handlers`, `Client`, `AnyImplementation`,
+  `BuildServices`, `ActionHttp.Client`, `Authentication.Any`.
+- A handler sending MCP notifications through `McpServer.McpServer`, and one reading
+  `McpSchema.McpRequestContext`.
+- A tenant taken from a subdomain. The workspace is a header, so the OAuth resource the server
+  publishes is one fixed URL.
+- A second way to the attachment's bytes for token holders: the download route takes the web
+  app's cookie alone, and an API client reads the image through `getAttachment`.

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

@@ -0,0 +1,19 @@
+import { Assistant } from "./assistant/Assistant.js";
+import { AttachImage, GetAttachment } from "./attachments/Attachments.js";
+import { WhoAmI } from "./identity/Identity.js";
+import { Issues } from "./issues/Issues.js";
+import { GetStatus } from "./workspaces/Workspaces.js";
+
+// Which actions each surface gets. A contract says nothing about where it is served: each
+// surface takes a list, and these are the lists, built from the contracts themselves.
+
+/** What a signed-in member may call: every protected action of the public port. */
+export const MemberActions = [WhoAmI, ...Issues, AttachImage, GetAttachment, ...Assistant] as const;
+
+/**
+ * The MCP tools, for the HTTP endpoint and the stdio server alike. `attachImage` is left out:
+ * a model should not carry an image's bytes as an argument. So is the assistant: it is a model
+ * itself, and its tools are already here. An action added to a domain later is no tool until
+ * it is listed here.
+ */
+export const Tools = [GetStatus, WhoAmI, ...Issues, GetAttachment] as const;