@gjermundgaraba/effect-actions 0.19.0 → 0.21.0

package/docs/ActionHttp.md

@@ -1,13 +1,8 @@
 # ActionHttp
 
-JSON `POST` routes on Effect's `HttpApi`, one per action. `ActionHttp.make` binds actions to a
-mount path; the server mounts that one binding, every client calls it and the OpenAPI document is
-generated from it.
+JSON `POST` routes on Effect's `HttpApi`, one per action. `ActionHttp.make` binds actions to a mount path; the server mounts that one binding, every client calls it and the OpenAPI document is generated from it.
 
-A message the library throws says its fix; for a compiler diagnostic or Effect's own error, search
-[ActionHttp-failures.md](ActionHttp-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.
+A message the library throws says its fix; for a compiler diagnostic or Effect's own error, search [ActionHttp-failures.md](ActionHttp-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.
 
 ## Bind actions to routes
 
@@ -15,6 +10,7 @@ Call `ActionHttp.make` once, in a contract-only file, and export the binding:
 
 ```ts example=notes-service/src/Api.ts
 import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+
 import { Login, WhoAmI } from "./identity/Identity.js";
 import { Notes } from "./notes/Notes.js";
 import { GetStatus } from "./status/Status.js";
@@ -29,25 +25,19 @@ export const Http = ActionHttp.make([GetStatus, ...Notes, WhoAmI], {
 });
 ```
 
-[quickstart/src/Api.ts](../examples/quickstart/src/Api.ts) binds public actions with no options;
-[kitchen-sink/src/Api.ts](../examples/kitchen-sink/src/Api.ts) gives `prefix` and `error` and makes
-two bindings, one per identity. What every endpoint declares is on `ActionHttp.make`, the rules of
-`prefix`, `error` and `authentication` on `ActionHttp.Options`, and a protected action's descriptor
-in [Authentication.md](Authentication.md#declare-how-callers-sign-in).
+[quickstart/src/Api.ts](../examples/quickstart/src/Api.ts) binds public actions with no options; [kitchen-sink/src/Api.ts](../examples/kitchen-sink/src/Api.ts) gives `prefix` and `error` and makes two bindings, one per identity. What every endpoint declares is on `ActionHttp.make`, the rules of `prefix`, `error` and `authentication` on `ActionHttp.Options`, and a protected action's descriptor in [Authentication.md](Authentication.md#declare-how-callers-sign-in).
 
 ## Serve the routes
 
-Give `ActionHttp.layer` the binding and the implementations, merge it with the host's other
-routes, provide the descriptor's provider
-([Authentication.md](Authentication.md#verify-credentials)), and serve the result with
-`HttpRouter.serve`.
+Give `ActionHttp.layer` the binding and the implementations, merge it with the host's other routes, provide the descriptor's provider ([Authentication.md](Authentication.md#verify-credentials)), and serve the result with `HttpRouter.serve`.
 
 ```ts example=notes-service/src/routes.ts
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
 import { Layer } from "effect";
 import { HttpRouter, HttpServerResponse } from "effect/http";
 import { OpenApi } from "effect/http-api";
-import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
-import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
+
 import { Http } from "./Api.js";
 import { identity } from "./identity/handlers.js";
 import { Login } from "./identity/Identity.js";
@@ -70,7 +60,7 @@ const health = HttpRouter.add("GET", "/healthz", HttpServerResponse.text("ok"));
 const openApi = HttpRouter.add(
   "GET",
   "/api/openapi.json",
-  HttpServerResponse.jsonUnsafe(OpenApi.fromApi(Http.api)),
+  HttpServerResponse.jsonUnsafe(OpenApi.fromApi(Http.api))
 );
 
 // What the host serves: the JSON routes, the same actions as MCP tools at `/mcp`, and the host's
@@ -85,12 +75,13 @@ const serving = (requestScoped: boolean) =>
     ActionMcp.layerHttp(implementations, {
       name: "notes-service",
       version: "1.0.0",
-      instructions: "Notes belong to the signed-in user. Read a note before updating it.",
+      instructions:
+        "Notes belong to the signed-in user. Read a note before updating it.",
       authentication: Login,
       requestScoped,
     }),
     health,
-    openApi,
+    openApi
   ).pipe(Layer.provide(authenticate));
 
 export const routes = serving(false);
@@ -98,17 +89,17 @@ export const routes = serving(false);
 export const requestScopedRoutes = serving(true);
 ```
 
-The smallest routes are [quickstart/src/routes.ts](../examples/quickstart/src/routes.ts). What
-each route answers and what an `ErrorReporter` is given are on `ActionHttp.layer`.
+The smallest routes are [quickstart/src/routes.ts](../examples/quickstart/src/routes.ts). What each route answers and what an `ErrorReporter` is given are on `ActionHttp.layer`.
 
-The entrypoint serves the routes, with a request body limit; what that limit covers is on
-`ActionHttp.layer`.
+The entrypoint serves the routes, with a request body limit; what that limit covers is on `ActionHttp.layer`.
 
 ```ts example=notes-service/src/server.ts
 import { createServer } from "node:http";
+
 import { NodeHttpServer, NodeRuntime } from "@effect/platform-node";
 import { ByteSize, Config, Effect, Layer } from "effect";
 import { HttpRouter, HttpServerRequest } from "effect/http";
+
 import { NoteStore } from "./notes/store.js";
 import { routes } from "./routes.js";
 
@@ -117,93 +108,122 @@ import { routes } from "./routes.js";
 const server = Layer.unwrap(
   Effect.gen(function* () {
     // The loopback default serves this machine alone; HOST=0.0.0.0 lets others reach it.
-    const host = yield* Config.String("HOST").pipe(Config.withDefault("127.0.0.1"));
+    const host = yield* Config.String("HOST").pipe(
+      Config.withDefault("127.0.0.1")
+    );
+
     const port = yield* Config.Port("PORT").pipe(Config.withDefault(3000));
 
     return HttpRouter.serve(routes).pipe(
       Layer.provide(NodeHttpServer.layer(createServer, { host, port })),
       // Request bodies have no size limit unless the host sets one. This covers every route that
       // reads its body whole.
-      Layer.provide(Layer.succeed(HttpServerRequest.MaxBodySize, ByteSize.mebibytes(1))),
+      Layer.provide(
+        Layer.succeed(HttpServerRequest.MaxBodySize, ByteSize.mebibytes(1))
+      ),
       // DEMO ONLY: notes live in this process's memory; a deployment provides a store that lasts.
-      Layer.provide(NoteStore.layerMemory),
+      Layer.provide(NoteStore.layerMemory)
     );
-  }),
+  })
 );
 
-Layer.launch(server).pipe(NodeRuntime.runMain);
+Layer.launch(server).pipe(NodeRuntime.runMain());
 ```
 
-- A service a verifier, handler or authorizer reads per request is provided by router middleware
-  around the layer
-  ([kitchen-sink/src/workspaces/tenant.ts](../examples/kitchen-sink/src/workspaces/tenant.ts),
-  read by the verifier, provided in
-  [kitchen-sink/src/routes.ts](../examples/kitchen-sink/src/routes.ts)), or, for a handler or
-  authorizer, by `ActionHttp.LayerOptions.middleware`; declaring it, and why not
-  `HttpRouter.provideRequest`, are on `ActionHttp.layer`.
+- A service a verifier, handler or authorizer reads per request is provided by router middleware around the layer ([kitchen-sink/src/workspaces/tenant.ts](../examples/kitchen-sink/src/workspaces/tenant.ts), read by the verifier, provided in [kitchen-sink/src/routes.ts](../examples/kitchen-sink/src/routes.ts)), or, for a handler or authorizer, by `ActionHttp.LayerOptions.middleware`; declaring it, and why not `HttpRouter.provideRequest`, are on `ActionHttp.layer`.
 
 ### Split a binding across layers, and add middleware
 
-Serve each action from exactly one layer. Files:
-[kitchen-sink/src/routes.ts](../examples/kitchen-sink/src/routes.ts) (`api`),
-[kitchen-sink/src/identity/quota.ts](../examples/kitchen-sink/src/identity/quota.ts). Where a
-check runs decides what it sees:
+Serve each action from exactly one layer. Files: [kitchen-sink/src/routes.ts](../examples/kitchen-sink/src/routes.ts) (`api`), [kitchen-sink/src/identity/quota.ts](../examples/kitchen-sink/src/identity/quota.ts). Where a check runs decides what it sees:
 
-| Where                                                    | Runs                                     | Use it for                                                 |
-| -------------------------------------------------------- | ---------------------------------------- | ---------------------------------------------------------- |
-| Global router middleware                                 | before routing, on every route           | a Host or Origin policy, CORS                              |
+| Where | Runs | Use it for |
+| --- | --- | --- |
+| Global router middleware | before routing, on every route | a Host or Origin policy, CORS |
 | Router middleware provided to an `ActionHttp.layer` call | around its routes, before authentication | a per-request service; a limit on unauthenticated requests |
-| `ActionHttp.LayerOptions.middleware`                     | after authentication, before decoding    | a limit keyed by the caller, counting invalid input too    |
-| The handler ([Action.md](Action.md#authorize-calls))     | after decoding and the authorizer        | a limit that holds on every surface, MCP included          |
+| `ActionHttp.LayerOptions.middleware` | after authentication, before decoding | a limit keyed by the caller, counting invalid input too |
+| The handler ([Action.md](Action.md#authorize-calls)) | after decoding and the authorizer | a limit that holds on every surface, MCP included |
 
-What router middleware answering with a binding error must send is on `ActionHttp.Options.error`.
-A request policy that must run before authentication and OAuth discovery:
-[Authentication-advanced.md](Authentication-advanced.md#run-a-request-policy-before-authentication).
+What router middleware answering with a binding error must send is on `ActionHttp.Options.error`. A request policy that must run before authentication and OAuth discovery: [Authentication-advanced.md](Authentication-advanced.md#run-a-request-policy-before-authentication).
 
 ### Publish the OpenAPI document
 
-Give `Http.api`, a plain `HttpApi`, to `OpenApi.fromApi`, `HttpApiSwagger.layer` or
-`HttpApiScalar.layer`, on routes of the host's own: `openApi` above,
-[kitchen-sink/src/routes.ts](../examples/kitchen-sink/src/routes.ts) (`documentation`). What the
-document holds and omits is on `ActionHttp.Binding.api`.
+Give `Http.api`, a plain `HttpApi`, to `OpenApi.fromApi`, `HttpApiSwagger.layer` or `HttpApiScalar.layer`, on routes of the host's own: `openApi` above, [kitchen-sink/src/routes.ts](../examples/kitchen-sink/src/routes.ts) (`documentation`). What the document holds and omits is on `ActionHttp.Binding.api`.
 
 ## Call the API from Effect
 
-What a call fails with is on `ActionHttp.client`, and a token or a per-request sign-in goes
-through `ActionHttp.ClientOptions.transformClient`.
+What a call fails with is on `ActionHttp.client`, and a token or a per-request sign-in goes through `ActionHttp.ClientOptions.transformClient`.
 
 ```ts example=quickstart/src/client.ts
 import { NodeRuntime } from "@effect/platform-node";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
 import { Console, Effect } from "effect";
 import { FetchHttpClient } from "effect/http";
-import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+
 import { Http } from "./Api.js";
 
 // Entrypoint: `node --import tsx examples/quickstart/src/client.ts`, with the server running.
 // One typed method per action of the binding.
 // DEMO ONLY: a deployed client reads its `baseUrl` from configuration (kitchen-sink/src/seed.ts).
 Effect.gen(function* () {
-  const client = yield* ActionHttp.client(Http, { baseUrl: "http://127.0.0.1:3000" });
+  const client = yield* ActionHttp.client(Http, {
+    baseUrl: "http://127.0.0.1:3000",
+  });
 
   yield* Console.log(yield* client.greet({ name: "Ada" }));
-}).pipe(Effect.provide(FetchHttpClient.layer), NodeRuntime.runMain);
+}).pipe(Effect.provide(FetchHttpClient.layer), NodeRuntime.runMain());
 ```
 
-[kitchen-sink/src/seed.ts](../examples/kitchen-sink/src/seed.ts) reads `baseUrl` from `Config`,
-sends headers and handles errors by tag. `ActionMcp.client` takes the same `transformClient`, and
-`ActionCli.remote` the unyielded `ActionHttp.client(Http, …)` as its `client`.
+[kitchen-sink/src/seed.ts](../examples/kitchen-sink/src/seed.ts) reads `baseUrl` from `Config`, sends headers and handles errors by tag. `ActionMcp.client` takes the same `transformClient`, and `ActionCli.remote` the unyielded `ActionHttp.client(Http, …)` as its `client`.
+
+- In a test, provide `Testing.layer(routes)` instead of a network client ([Testing.md](Testing.md#test-routes-in-memory), [notes-service/test/routes.test.ts](../examples/notes-service/test/routes.test.ts)).
+
+## Serve and watch events
+
+List [event types](Event.md) in the binding beside the actions, and their implementations in `layer`'s list, and in its `actions` where it is given: each is served at `POST <prefix>/events/<name>`, which answers a page of JSON, or an SSE stream to a request that accepts `text/event-stream`. Experimental, as [events](Event.md) are.
+
+```ts example=build-events/src/Api.ts
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+
+import {
+  BuildFinished,
+  FinishBuild,
+  PipelineStatus,
+  StartBuild,
+  TailLog,
+} from "./builds/Builds.js";
+import { DeployRequested, RequestDeploy } from "./deploys/Deploys.js";
+import { Login } from "./identity/Identity.js";
+
+// The HTTP binding: each action at `POST /api/<name>`, and each event at
+// `POST /api/events/<name>`, which answers a page of JSON, or, asked for `text/event-stream`,
+// holds a stream open. It imports no server code, so a client imports it with the contracts.
+export const Http = ActionHttp.make(
+  [
+    FinishBuild,
+    StartBuild,
+    TailLog,
+    BuildFinished,
+    PipelineStatus,
+    RequestDeploy,
+    DeployRequested,
+  ],
+  { authentication: Login }
+);
+```
+
+[build-events/src/routes.ts](../examples/build-events/src/routes.ts) serves the same implementations over HTTP, MCP and RPC. A client of the binding has `watch(event, input, options)`, as `Action.client`'s: [build-events/test/http.test.ts](../examples/build-events/test/http.test.ts) watches by stream and by poll. What a route answers is on `layer`; what a watch fails with is on `client`. A protected event's binding also has `/subscribe` and `/unsubscribe` routes, for webhook delivery ([Webhook.md](Webhook.md)), which `make` says when it adds.
+
+- **Not a browser `EventSource`.** It sends neither a JSON body nor a header credential, so a page watches with `fetchClient`, whose `watch` reads the stream through `fetch`.
+
+- **Which deployment.** As over MCP, a log source and a `subscription` hook need one server that outlives a request.
+
+## Serve what another server serves
 
-- In a test, provide `Testing.layer(routes)` instead of a network client
-  ([Testing.md](Testing.md#test-routes-in-memory),
-  [notes-service/test/routes.test.ts](../examples/notes-service/test/routes.test.ts)).
+`ActionHttp.placed(binding, client)` stands, in a surface's list of implementations, for the binding's actions and event types where another server serves them, such as a Worker in front of the Durable Object that holds the data: each call and subscription is sent on, with the caller's headers, to the server `client` reaches for its input and its contract, which serves them in its own `ActionHttp.layer` of the binding, and its answer is passed back. `ActionHttp.layer`, `ActionMcp.layerHttp` and `ActionRpc.layer` take it beside their own implementations. Both servers verify the credential, so both are given the verifier; the server reached authorizes. Its rules are on `ActionHttp.placed`. An application doing it, a Worker sending each room's calls to its Durable Object, is `@gjermundgaraba/effect-actions-cloudflare`'s chat-rooms, through `ActionDurableObject.placed`: that package's `docs/ActionDurableObject-placement.md`.
 
 ## Call the API from a browser
 
-Code outside an Effect builds the client once with `ActionHttp.fetchClient` and runs each call
-with `Effect.runPromise`. Files:
-[notes-service/src/browser.ts](../examples/notes-service/src/browser.ts),
-[kitchen-sink/src/sdk.ts](../examples/kitchen-sink/src/sdk.ts) (a `baseUrl`, two headers).
+Code outside an Effect builds the client once with `ActionHttp.fetchClient` and runs each call with `Effect.runPromise`. Files: [notes-service/src/browser.ts](../examples/notes-service/src/browser.ts), [kitchen-sink/src/sdk.ts](../examples/kitchen-sink/src/sdk.ts) (a `baseUrl`, two headers).
 
-- A page on another origin needs the server to allow it with `HttpRouter.cors`; sending cookies
-  from there is on `ActionHttp.FetchClientOptions.fetch`.
+- A page on another origin needs the server to allow it with `HttpRouter.cors`; sending cookies from there is on `ActionHttp.FetchClientOptions.fetch`.
 - Bundling the page: [setup.md](setup.md#bundle-for-a-browser).

package/docs/ActionMcp-failures.md

@@ -9,7 +9,8 @@ What you see when something is wrong, and the fix. Search for a fragment of the
 - `subscriptions/listen` answered with JSON-RPC error `-32601`, Method not found: an endpoint without `features` has no 2026-07-28 subscriptions unless `allowSubscriptions` is `true`, and a `requestScoped` one has none. Pass `true` where a handler changes the server through `McpServer.McpServer`.
 - A request over HTTP answers 400, `MCP-Session-Id header is required; send initialize to start a session`: its `MCP-Protocol-Version` header is absent or names a 2025 revision, so it is a session's request, and it follows no `initialize`. One answering 404 names a session that ended, or one of a process since restarted: the client opens another.
 - A hand-written HTTP request answers 400 with JSON-RPC error `-32602`, `Required request metadata is missing` or `io.modelcontextprotocol/clientCapabilities request metadata is required`: it names 2026-07-28 in `MCP-Protocol-Version` and its `params._meta` lacks `io.modelcontextprotocol/protocolVersion`, for the first message, or `io.modelcontextprotocol/clientCapabilities`, for the second. Build it with `ActionMcp.request`, or copy the `curl` of [mcp-tools](../examples/mcp-tools/README.md#connect-a-client).
-- A hand-written HTTP request answers 400 with JSON-RPC error `-32020`, `MCP-Protocol-Version header is required`, `Mcp-Method header does not match request method` or `Mcp-Name header does not match request parameters`: those headers repeat a 2026-07-28 request's revision, method and `tools/call` name, and one is absent or differs from its body. Build it with `ActionMcp.request`.
+- A hand-written HTTP request answers 400 with JSON-RPC error `-32020`, `MCP-Protocol-Version header is required`, `Mcp-Method header does not match request method` or `Mcp-Name header does not match request parameters`: those headers repeat a 2026-07-28 request's revision, method and `tools/call`, `events/poll`, `events/stream`, `events/subscribe` or `events/unsubscribe` name, and one is absent or differs from its body. Build it with `ActionMcp.request`.
+- `events/list`, `events/poll` or `events/stream` answered with JSON-RPC error `-32601`, Method not found: the client opened a 2025 session with `initialize`, and events are served to 2026-07-28 requests alone. Send those, as `ActionMcp.client` does.
 - A hand-written HTTP request answers an empty 406: its `Accept` header does not list both `application/json` and `text/event-stream`, as `*/*` does not. Send both.
 - A request written by hand to a stdio server answers JSON-RPC error `-32602`, `Invalid request metadata`: it is neither preceded by `initialize` nor carries the 2026-07-28 metadata. Open with `initialize` and `notifications/initialized`, or give the request's `_meta` its `io.modelcontextprotocol/protocolVersion` and `io.modelcontextprotocol/clientCapabilities`.
 - `Tool <name> has an output schema but did not return structured content` raised by a Python MCP client for an action that returns nothing: its success is sent as `null`, which a Python SDK release before the fix of python-sdk#3345 reads as missing. Update the SDK.

package/docs/ActionMcp.md

@@ -1,48 +1,34 @@
 # ActionMcp
 
-MCP tools from implementations, on Effect's native `McpServer`: one tool per served action, named
-after it. `layerHttp` mounts a Streamable HTTP endpoint, for clients that connect to a URL;
-`runStdio` is the whole program of a subprocess a local agent starts. For a model your own code
-calls in process, use [ActionToolkit.md](ActionToolkit.md).
+MCP tools from implementations, on Effect's native `McpServer`: one tool per served action, named after it. `layerHttp` mounts a Streamable HTTP endpoint, for clients that connect to a URL; `runStdio` is the whole program of a subprocess a local agent starts. For a model your own code calls in process, use [ActionToolkit.md](ActionToolkit.md).
 
-A message the library throws says its fix; for a compiler diagnostic or Effect's own error,
-search [ActionMcp-failures.md](ActionMcp-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.
+A message the library throws says its fix; for a compiler diagnostic or Effect's own error, search [ActionMcp-failures.md](ActionMcp-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.
 
 ## Serve tools over HTTP
 
-Merge `layerHttp` into the routes, beside any other surface, and serve them with
-`HttpRouter.serve`:
+Merge `layerHttp` into the routes, beside any other surface, and serve them with `HttpRouter.serve`:
 
 ```ts example=quickstart/src/routes.ts
-import { Layer } from "effect";
 import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
 import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
+import { Layer } from "effect";
+
 import { Http } from "./Api.js";
 import { greeting } from "./greeting/handlers.js";
 
 // One implementation, two surfaces: a JSON route and an MCP tool at `/mcp`.
 export const routes = Layer.mergeAll(
   ActionHttp.layer(Http, greeting),
-  ActionMcp.layerHttp(greeting, { name: "greetings", version: "1.0.0" }),
+  ActionMcp.layerHttp(greeting, { name: "greetings", version: "1.0.0" })
 );
 ```
 
-[quickstart/src/server.ts](../examples/quickstart/src/server.ts) serves them. Surfaces in one
-set of routes share each builder, as `Action.implement` says:
-[notes-service/src/routes.ts](../examples/notes-service/src/routes.ts).
-
-- Claude Code 2.1 and Codex CLI 0.162 connect:
-  `claude mcp add --transport http <name> <url>/mcp --header "Authorization: Bearer <token>"`,
-  `codex mcp add <name> --url <url>/mcp --bearer-token-env-var <VAR>`;
-  [mcp-tools](../examples/mcp-tools/README.md#connect-a-client) has stdio and Claude Desktop.
-- Where an endpoint without `authentication` listens, and its body limit:
-  [mcp-tools/src/server.ts](../examples/mcp-tools/src/server.ts).
-- **On a serverless host**, such as Cloudflare Workers, pass `requestScoped: true`:
-  [notes-service/src/worker.ts](../examples/notes-service/src/worker.ts).
-- The endpoint takes no layer middleware. A limit that must hold for tools goes in the handlers:
-  [kitchen-sink/src/issues/write-limit.ts](../examples/kitchen-sink/src/issues/write-limit.ts).
+[quickstart/src/server.ts](../examples/quickstart/src/server.ts) serves them. Surfaces in one set of routes share each builder, as `Action.implement` says: [notes-service/src/routes.ts](../examples/notes-service/src/routes.ts).
+
+- Claude Code 2.1 and Codex CLI 0.162 connect: `claude mcp add --transport http <name> <url>/mcp --header "Authorization: Bearer <token>"`, `codex mcp add <name> --url <url>/mcp --bearer-token-env-var <VAR>`; [mcp-tools](../examples/mcp-tools/README.md#connect-a-client) has stdio and Claude Desktop.
+- Where an endpoint without `authentication` listens, and its body limit: [mcp-tools/src/server.ts](../examples/mcp-tools/src/server.ts).
+- **On a serverless host**, such as Cloudflare Workers, pass `requestScoped: true`: [notes-service/src/worker.ts](../examples/notes-service/src/worker.ts). For an endpoint in a Cloudflare Durable Object: the `@gjermundgaraba/effect-actions-cloudflare` package's docs.
+- The endpoint takes no layer middleware. A limit that must hold for tools goes in the handlers: [kitchen-sink/src/issues/write-limit.ts](../examples/kitchen-sink/src/issues/write-limit.ts).
 
 ## Serve tools over stdio
 
@@ -50,9 +36,10 @@ Provide `Stdio` and the startup services, then run it:
 
 ```ts example=notes-service/src/stdio.ts
 import { NodeRuntime, NodeStdio } from "@effect/platform-node";
-import { Effect } from "effect";
 import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
 import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
+import { Effect } from "effect";
+
 import { identity } from "./identity/handlers.js";
 import { CurrentUser } from "./identity/Identity.js";
 import { users } from "./identity/users.js";
@@ -68,98 +55,139 @@ import { status } from "./status/handlers.js";
 // over stdio, so this host names the caller itself. It is a process of its own with services
 // of its own. DEMO ONLY: this in-memory store holds its notes, not the running server's. To
 // share them, both provide a store they both reach, such as a database.
-ActionMcp.runStdio([status, notes, identity], { name: "notes-service", version: "1.0.0" }).pipe(
+ActionMcp.runStdio([status, notes, identity], {
+  name: "notes-service",
+  version: "1.0.0",
+}).pipe(
   // DEMO ONLY: a real host reads who started it, from its own login or configuration.
   Effect.provideService(CurrentUser, users.ada),
   Effect.provide([NodeStdio.layer, NoteStore.layerMemory]),
   // stdout carries the protocol alone, so logs and failures go to stderr.
   ActionCli.logToStderr,
-  NodeRuntime.runMain,
+  NodeRuntime.runMain()
 );
 ```
 
-[mcp-tools/src/stdio.ts](../examples/mcp-tools/src/stdio.ts) serves public tools. What
-`ActionCli.logToStderr` moves, and what it cannot, is on `ActionCli.logToStderr`. Test the tools
-without a process: [Testing.md](Testing.md#test-mcp-tools).
+[mcp-tools/src/stdio.ts](../examples/mcp-tools/src/stdio.ts) serves public tools. What `ActionCli.logToStderr` moves, and what it cannot, is on `ActionCli.logToStderr`. Test the tools without a process: [Testing.md](Testing.md#test-mcp-tools).
 
-To try a server by hand, send one request as `ActionMcp.request` builds it, its 2026-07-28
-metadata in `_meta`: [mcp-tools](../examples/mcp-tools/README.md#connect-a-client) has the
-`curl`, with HTTP's five headers, and
-[notes-service](../examples/notes-service/README.md#run-it) the stdio command.
+To try a server by hand, send one request as `ActionMcp.request` builds it, its 2026-07-28 metadata in `_meta`: [mcp-tools](../examples/mcp-tools/README.md#connect-a-client) has the `curl`, with HTTP's five headers, and [notes-service](../examples/notes-service/README.md#run-it) the stdio command.
 
 ## Describe tools to a model
 
-A tool is its contract ([Action.md](Action.md#define-a-contract)): a model knows only the action's
-name, its `description`, and its input schema with each field's `description`; how the tool
-presents itself is `Action.Options`'s `mcp`. The server's `instructions` say what the tools are
-for together. See
-[mcp-tools/src/printers/Printers.ts](../examples/mcp-tools/src/printers/Printers.ts) and
-[mcp-tools/src/instructions.ts](../examples/mcp-tools/src/instructions.ts).
-
-- Constrain in the schema what a model may send: `PrinterId` in
-  [mcp-tools/src/printers/Printers.ts](../examples/mcp-tools/src/printers/Printers.ts). Which
-  checks reach the listed schema is on `Action.Options.input`.
-- A model acts on a declared error's `message`, so write it for the model:
-  [mcp-tools/src/platform/print-farm.ts](../examples/mcp-tools/src/platform/print-farm.ts).
-- `ActionMcp.Options`'s `actions` lists the tools, and only listed actions must suit MCP:
-  [kitchen-sink/src/Actions.ts](../examples/kitchen-sink/src/Actions.ts). Leave out an action a
-  model should not call, or one that takes a secret ([Action.md](Action.md#define-a-contract)).
+A tool is its contract ([Action.md](Action.md#define-a-contract)): a model knows only the action's name, its `description`, and its input schema with each field's `description`; how the tool presents itself is `Action.Options`'s `mcp`. The server's `instructions` say what the tools are for together. See [mcp-tools/src/printers/Printers.ts](../examples/mcp-tools/src/printers/Printers.ts) and [mcp-tools/src/instructions.ts](../examples/mcp-tools/src/instructions.ts).
+
+- Constrain in the schema what a model may send: `PrinterId` in [mcp-tools/src/printers/Printers.ts](../examples/mcp-tools/src/printers/Printers.ts). Which checks reach the listed schema is on `Action.Options.input`.
+- A model acts on a declared error's `message`, so write it for the model: [mcp-tools/src/platform/print-farm.ts](../examples/mcp-tools/src/platform/print-farm.ts).
+- `ActionMcp.Options`'s `actions` lists the tools, and only listed actions must suit MCP: [kitchen-sink/src/Actions.ts](../examples/kitchen-sink/src/Actions.ts). Leave out an action a model should not call, or one that takes a secret ([Action.md](Action.md#define-a-contract)).
 
 ## Return images and other media
 
-Give the success an `Action.Image` field and return its bytes and MIME type from the handler:
-`get_camera_snapshot` in
-[mcp-tools/src/printers/Printers.ts](../examples/mcp-tools/src/printers/Printers.ts);
-`ActionMcp.client` decodes it back. Where `ActionMcp` refuses one is on `Action.Image`:
-[kitchen-sink/src/Actions.ts](../examples/kitchen-sink/src/Actions.ts).
+Give the success an `Action.Image` field and return its bytes and MIME type from the handler: `get_camera_snapshot` in [mcp-tools/src/printers/Printers.ts](../examples/mcp-tools/src/printers/Printers.ts); `ActionMcp.client` decodes it back. Where `ActionMcp` refuses one is on `Action.Image`: [kitchen-sink/src/Actions.ts](../examples/kitchen-sink/src/Actions.ts).
 
 ## Protect tools
 
-Name the protected actions' authentication descriptor as `authentication` and provide its
-provider to the routes: [notes-service/src/routes.ts](../examples/notes-service/src/routes.ts).
-Write the [descriptor](Authentication.md#declare-how-callers-sign-in) and its
-[provider](Authentication.md#verify-credentials) once for every surface, and
-[publish discovery](Authentication.md#publish-oauth-discovery) so an MCP client finds where to
-sign in. What a signed-in caller may do is each implementation's
-[`authorize`](Action.md#authorize-calls), which runs on every call of a protected tool.
+Name the protected actions' authentication descriptor as `authentication` and provide its provider to the routes: [notes-service/src/routes.ts](../examples/notes-service/src/routes.ts). Write the [descriptor](Authentication.md#declare-how-callers-sign-in) and its [provider](Authentication.md#verify-credentials) once for every surface, and [publish discovery](Authentication.md#publish-oauth-discovery) so an MCP client finds where to sign in. What a signed-in caller may do is each implementation's [`authorize`](Action.md#authorize-calls), which runs on every call of a protected tool.
+
+- **One endpoint or two.** What a mixed endpoint, serving public and protected tools, shows and runs signed out is on `ActionMcp.LayerHttpOptions`'s `authentication`.
+- Test as a signed-in caller ([Testing.md](Testing.md#test-as-a-signed-in-caller)): [notes-service/test/routes.test.ts](../examples/notes-service/test/routes.test.ts).
+
+## Serve events
+
+List [event implementations](Event.md) beside the actions, and their event types in `actions` where it is given: `layerHttp` and `runStdio` serve them as MCP events, SEP-3415's `events/list`, `events/poll` and `events/stream`, to 2026-07-28 clients. Experimental, as [events](Event.md) are.
+
+```ts example=build-events/src/routes.ts
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
+import * as ActionRpc from "@gjermundgaraba/effect-actions/ActionRpc";
+import * as Webhook from "@gjermundgaraba/effect-actions/Webhook";
+import { Layer } from "effect";
+import { RpcSerialization, RpcServer } from "effect/rpc";
+
+import { Http } from "./Api.js";
+import { buildEvents } from "./builds/events.js";
+import { builds } from "./builds/handlers.js";
+import { logs } from "./builds/log.js";
+import { statusEvents } from "./builds/status.js";
+import { deployEvents } from "./deploys/events.js";
+import { deploys } from "./deploys/handlers.js";
+import { Login } from "./identity/Identity.js";
+import { authenticate } from "./identity/verifier.js";
+import { Rpc } from "./Rpc.js";
+
+// Every domain's implementation, once: the events beside the actions, in one list.
+const implementations = [
+  builds,
+  logs,
+  buildEvents,
+  statusEvents,
+  deploys,
+  deployEvents,
+];
+
+// The actions as MCP tools and the events as MCP events, at `/mcp`. A client polls with
+// `events/poll`, or holds `events/stream` open and is pushed each occurrence. Both events are
+// protected, so each request needs a member's token, and each subscriber sees what its token
+// lets it. This long-lived process holds the deploy event's `subscription` hook between polls and
+// its log in memory, and pushes each occurrence: a `requestScoped` endpoint would serve the events
+// by poll and webhook alone, and a serverless host, where no process lasts, check sources alone,
+// without `Webhook.layer`.
+//
+// A tool answers one result, so `tailLog` would collect a whole log before answering, all of it
+// in a model's context: its implementation, `logs`, is left out, and the endpoint serves every
+// other action and every event.
+const mcp = ActionMcp.layerHttp(
+  [builds, buildEvents, statusEvents, deploys, deployEvents],
+  {
+    name: "build-events",
+    version: "1.0.0",
+    authentication: Login,
+  }
+);
+
+// The same implementations as routes under `/api`, for a client that speaks HTTP rather than
+// MCP: one implementation of each event serves every surface.
+const api = ActionHttp.layer(Http, implementations);
+
+// And as Effect RPC at `/rpc`, over HTTP. A watch is a stream rpc that never ends, so the
+// serialization frames each element as it is sent: `layerNdjson` does, where `layerJson` would
+// answer once every stream of the request ended, which a watch never does.
+const rpc = ActionRpc.layer(Rpc, implementations).pipe(
+  Layer.provide(RpcServer.layerProtocolHttp({ path: "/rpc" })),
+  Layer.provide(RpcSerialization.layerNdjson)
+);
+
+// Webhook delivery for MCP and HTTP alike: a member names a callback URL and a secret, with
+// MCP's `events/subscribe` or `POST /api/events/<name>/subscribe`, and each occurrence it may see
+// is POSTed there, signed. One layer holds the subscriptions of both, so either surface refreshes
+// one made over the other. `persist` keeps each in a `KeyValueStore`, so a restart goes on
+// delivering from where it reached, as the subscriber `Login`'s `schema` keeps. It needs an
+// `HttpClient` to POST, `Dns` to check where each callback resolves, and the store, which
+// `server.ts` provides.
+export const routes = Layer.mergeAll(mcp, api, rpc).pipe(
+  Layer.provide(authenticate),
+  Layer.provide(Webhook.layer({ persist: true }))
+);
+```
+
+[build-events/test/routes.test.ts](../examples/build-events/test/routes.test.ts) watches both events with `client`, by stream and by poll. What each method answers, and when the endpoint refuses to start, is on `layerHttp`; what a watch fails with is on `client`.
+
+Webhook delivery, `events/subscribe` and `events/unsubscribe`, is `Webhook.layer`'s ([Webhook.md](Webhook.md)), provided to the endpoint.
 
-- **One endpoint or two.** What a mixed endpoint, serving public and protected tools, shows and
-  runs signed out is on `ActionMcp.LayerHttpOptions`'s `authentication`.
-- Test as a signed-in caller ([Testing.md](Testing.md#test-as-a-signed-in-caller)):
-  [notes-service/test/routes.test.ts](../examples/notes-service/test/routes.test.ts).
+- **Which deployment.** Push needs a server that outlives a request, so a `requestScoped` endpoint serves events by poll, and by webhook where `Webhook.layer` is provided. Sources, logs, `subscription` hooks' leases and webhook subscriptions are built once with the endpoint, either way. On a host with no lasting process, such as a serverless platform, serve check sources alone, without a `subscription` hook or `Webhook.layer`: nothing refuses the others, and under `Event.layerMemory` each instance keeps its own log of a log source, whose cursors another reads as a gap, and its own leases and webhook subscriptions, lost as it ends.
 
 ## Allow browser clients
 
-A browser MCP client sends its page's `Origin`. List the origins it may come from as
-`allowedOrigins`, and add CORS where one is configured:
-[mcp-tools/src/routes.ts](../examples/mcp-tools/src/routes.ts), and
-[kitchen-sink/src/request-policy.ts](../examples/kitchen-sink/src/request-policy.ts) with
-authentication.
+A browser MCP client sends its page's `Origin`. List the origins it may come from as `allowedOrigins`, and add CORS where one is configured: [mcp-tools/src/routes.ts](../examples/mcp-tools/src/routes.ts), and [kitchen-sink/src/request-policy.ts](../examples/kitchen-sink/src/request-policy.ts) with authentication.
 
-- Authentication runs before the Origin check, so a request from an unlisted origin that must
-  authenticate, or sends a token, gets 401 without a valid one, not 403.
-- `allowedOrigins` checks no `Host`, and a request sending no `Origin` passes. A `Host`
-  allowlist, or an Origin check that must run first, is a request policy:
-  [Authentication-advanced.md](Authentication-advanced.md#run-a-request-policy-before-authentication).
+- Authentication runs before the Origin check, so a request from an unlisted origin that must authenticate, or sends a token, gets 401 without a valid one, not 403.
+- `allowedOrigins` checks no `Host`, and a request sending no `Origin` passes. A `Host` allowlist, or an Origin check that must run first, is a request policy: [Authentication-advanced.md](Authentication-advanced.md#run-a-request-policy-before-authentication).
 
 ## Add native prompts and resources
 
-Merge Effect's own `McpServer.resource`, `McpServer.prompt` and `McpServer.toolkit` layers into
-one and pass it as `features`:
-[kitchen-sink/src/issues/guide.ts](../examples/kitchen-sink/src/issues/guide.ts), given in
-[kitchen-sink/src/routes.ts](../examples/kitchen-sink/src/routes.ts) and
-[kitchen-sink/src/stdio.ts](../examples/kitchen-sink/src/stdio.ts). Where their services
-come from is on `ActionMcp.Options`'s `features`, and when they need a credential on
-`ActionMcp.LayerHttpOptions`'s `authentication`.
+Merge Effect's own `McpServer.resource`, `McpServer.prompt` and `McpServer.toolkit` layers into one and pass it as `features`: [kitchen-sink/src/issues/guide.ts](../examples/kitchen-sink/src/issues/guide.ts), given in [kitchen-sink/src/routes.ts](../examples/kitchen-sink/src/routes.ts) and [kitchen-sink/src/stdio.ts](../examples/kitchen-sink/src/stdio.ts). Where their services come from is on `ActionMcp.Options`'s `features`, and when they need a credential on `ActionMcp.LayerHttpOptions`'s `authentication`.
 
 ## Send notifications from a handler
 
-A handler yields `McpServer.McpServer` and sends through it:
-`server.notifications["notifications/progress"]({ progressToken, progress })`.
-`McpSchema.McpRequestContext` holds what the client sent: its `clientInfo`, and the request's
-`_meta` as `requestMetadata`. The endpoint and `runStdio` provide both; an implementation also
-served on another surface reads them with `Effect.serviceOption`.
+A handler yields `McpServer.McpServer` and sends through it: `server.notifications["notifications/progress"]({ progressToken, progress })`. `McpSchema.McpRequestContext` holds what the client sent: its `clientInfo`, and the request's `_meta` as `requestMetadata`. The endpoint and `runStdio` provide both; an implementation also served on another surface reads them with `Effect.serviceOption`.
 
-- On 2026-07-28, a progress notification is sent only with the token its request carried,
-  `requestMetadata?.progressToken`. With another, or when the client sent none, it is dropped
-  silently.
+- On 2026-07-28, a progress notification is sent only with the token its request carried, `requestMetadata?.progressToken`. With another, or when the client sent none, it is dropped silently.