@gjermundgaraba/effect-actions 0.11.0 → 0.12.0

package/examples/kitchen-sink/src/issues/Issues.ts

@@ -0,0 +1,109 @@
+import { Effect, Schema } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { CurrentMember } from "../identity/Identity.js";
+
+export const Status = Schema.Literals(["open", "closed"]);
+
+export const Comment = Schema.Struct({ author: Schema.String, text: Schema.String });
+
+export const Issue = Schema.Struct({
+  id: Schema.String,
+  title: Schema.String,
+  body: Schema.String,
+  status: Status,
+  assignee: Schema.optional(Schema.String),
+  comments: Schema.Array(Comment),
+});
+
+export type Issue = typeof Issue.Type;
+
+// A declared error is part of the contract: every client decodes it as this class, and its
+// status is what HTTP answers with. Without `httpApiStatus` it would be a 422.
+export class IssueNotFound extends Schema.TaggedError<IssueNotFound>()(
+  "IssueNotFound",
+  { id: Schema.String },
+  { httpApiStatus: 404 },
+) {}
+
+export class RateLimited extends Schema.TaggedError<RateLimited>()(
+  "RateLimited",
+  { retryAfterSeconds: Schema.Finite },
+  { httpApiStatus: 429 },
+) {}
+
+// A shared error list: what any write to an existing issue may fail with. Each such action
+// spreads this one array into its `error`, here and in attachments/Attachments.ts, so an error
+// added to the list is declared by all of them.
+export const IssueWriteErrors = [IssueNotFound, RateLimited] as const;
+
+// An option bundle. What the two actions changing an issue share is one constant object spread
+// into `Action.make`, typed as if written inline. `readOnly` and `description` stay on each
+// action: authorization and an MCP client's hints read them.
+const change = {
+  caller: CurrentMember,
+  error: IssueWriteErrors,
+  // MCP hints, in MCP's names. They tell a model what a tool does and enforce nothing; the
+  // read-only hint is `readOnly` itself.
+  mcp: { destructiveHint: false, openWorldHint: false },
+} as const;
+
+const Text = Schema.String.check(Schema.isMinLength(1));
+
+export const ListIssues = Action.make("listIssues", {
+  description: "List your workspace's issues, newest first, without bodies or comments.",
+  input: {
+    // Optional: left out, issues of every status are listed.
+    status: Schema.optional(Status),
+    // Defaulted: left out, the handler receives 20. A field description is also the help text
+    // of its CLI flag and the description in the tool's schema.
+    limit: Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 100 })).pipe(
+      Schema.annotate({ description: "How many issues to list, at most 100." }),
+      Schema.withDecodingDefaultKey(Effect.succeed(20)),
+    ),
+  },
+  success: {
+    issues: Schema.Array(
+      Schema.Struct({ id: Schema.String, title: Schema.String, status: Status }),
+    ),
+  },
+  readOnly: true,
+  caller: CurrentMember,
+});
+
+export const GetIssue = Action.make("getIssue", {
+  description: "Read one issue with its comments.",
+  input: { id: Schema.String },
+  success: Issue,
+  error: IssueNotFound,
+  readOnly: true,
+  caller: CurrentMember,
+});
+
+export const CreateIssue = Action.make("createIssue", {
+  description: "File an issue in your workspace.",
+  input: { title: Text, body: Schema.String, assignee: Schema.optional(Schema.String) },
+  success: Issue,
+  error: RateLimited,
+  readOnly: false,
+  caller: CurrentMember,
+  mcp: { title: "File an issue", destructiveHint: false, openWorldHint: false },
+});
+
+export const CommentOnIssue = Action.make("commentOnIssue", {
+  ...change,
+  description: "Add a comment to an issue.",
+  input: { id: Schema.String, text: Text },
+  success: Issue,
+  readOnly: false,
+});
+
+export const CloseIssue = Action.make("closeIssue", {
+  ...change,
+  description: "Close an issue. Closing a closed issue changes nothing.",
+  input: { id: Schema.String },
+  success: Issue,
+  readOnly: false,
+  mcp: { ...change.mcp, idempotentHint: true },
+});
+
+export const Issues = [ListIssues, GetIssue, CreateIssue, CommentOnIssue, CloseIssue] as const;

package/examples/kitchen-sink/src/issues/assistant.ts

@@ -0,0 +1,23 @@
+import { LanguageModel } from "effect/ai";
+import * as ActionToolkit from "@gjermundgaraba/effect-actions/ActionToolkit";
+import { issues } from "./handlers.js";
+import { CloseIssue, CommentOnIssue, GetIssue, ListIssues } from "./Issues.js";
+
+// The actions a model may call, listed here, where they are served: an action added to the
+// contracts later is no tool until it is listed. Filing issues is left to people.
+const tools = [ListIssues, GetIssue, CommentOnIssue, CloseIssue] as const;
+
+// Some of the issue actions as a model's tools: Effect's native `Toolkit`, in process, with no
+// server between. `toolkit` holds the tool definitions and `layer` their handlers, the same
+// implementation every other surface serves, behind the same `authorize` and write limit.
+export const { toolkit, layer } = ActionToolkit.make(issues, {
+  actions: tools,
+  // One rule over every call a model makes, before the call runs: a write ends the turn with
+  // an approval request instead of a result. Approval is not authorization: `authorize` still
+  // runs for an approved call, as for any other.
+  needsApproval: (call) => !call.action.readOnly,
+});
+
+// One turn of the assistant. The caller provides the model, and the member it acts for around
+// the whole turn: approval, `authorize` and the handlers all read that one caller.
+export const triage = (prompt: string) => LanguageModel.generateText({ prompt, toolkit });

package/examples/kitchen-sink/src/issues/guide.ts

@@ -0,0 +1,37 @@
+import { Effect, Layer, Schema } from "effect";
+import { McpServer } from "effect/ai";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { Issues } from "./Issues.js";
+
+const guide = `# Triage
+
+- An issue is \`open\` or \`closed\`. Its id is the workspace's key and a number: \`ACME-12\`.
+- Read an issue before commenting on it, and comment before closing it: say why.
+- Writes are limited to ten a minute. When refused, wait as long as the error says.
+`;
+
+// The contracts keyed by name, each its exact contract. The prompt below names its tools through
+// them, so renaming an action is a compile error here, not a stale instruction to a model.
+const tools = Action.byName(Issues);
+
+// Effect's own MCP resources and prompts, served beside the actions' tools as an endpoint's
+// `features`. They are native, not actions: no `authorize` runs for them, and they run with
+// the services they were built with, never a request's, so they cannot read the caller.
+// Content that depends on the caller is an action.
+export const features = Layer.mergeAll(
+  McpServer.resource({
+    uri: "tracker://guides/triage",
+    name: "Triage guide",
+    mimeType: "text/markdown",
+    content: Effect.succeed(guide),
+  }),
+  McpServer.prompt({
+    name: "triage",
+    description: "Go through the open issues and propose what to do with each.",
+    parameters: { focus: Schema.String },
+    content: ({ focus }) =>
+      Effect.succeed(
+        `Call ${tools.listIssues.name} for the open issues and ${tools.getIssue.name} for those about ${focus}. For each, propose ${tools.commentOnIssue.name} or ${tools.closeIssue.name}. Follow tracker://guides/triage.`,
+      ),
+  }),
+);

package/examples/kitchen-sink/src/issues/handlers.ts

@@ -0,0 +1,37 @@
+import { Effect } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { authorize } from "../identity/authorize.js";
+import { CurrentMember } from "../identity/Identity.js";
+import { Issues } from "./Issues.js";
+import { IssueStore } from "./store.js";
+import { writeLimit } from "./write-limit.js";
+
+// Several actions sharing one builder. It runs once, at startup, however many surfaces serve
+// these actions, and yields the startup services: the store, and the write limit built on the
+// limiter. `CurrentMember` is a per-request service: each handler reads it per call, so one
+// build serves every caller. No handler checks a scope: `authorize` has run before it.
+export const issues = Action.implement(
+  Issues,
+  Effect.gen(function* () {
+    const store = yield* IssueStore;
+    const limited = yield* writeLimit;
+
+    return {
+      listIssues: ({ status, limit }) =>
+        Effect.gen(function* () {
+          const member = yield* CurrentMember;
+          const listed = yield* store.list(member.workspace, status, limit);
+
+          return { issues: listed.map(({ id, title, status }) => ({ id, title, status })) };
+        }),
+      getIssue: ({ id }) =>
+        Effect.flatMap(CurrentMember, (member) => store.get(member.workspace, id)),
+      // One function wraps every limited handler, and gives it the member it counted.
+      createIssue: (draft) => limited((member) => store.create(member.workspace, draft)),
+      commentOnIssue: ({ id, text }) =>
+        limited((member) => store.comment(member.workspace, id, { author: member.id, text })),
+      closeIssue: ({ id }) => limited((member) => store.close(member.workspace, id)),
+    };
+  }),
+  { authorize },
+);

package/examples/kitchen-sink/src/issues/store.ts

@@ -0,0 +1,96 @@
+import { Context, Effect, Layer } from "effect";
+import { type Comment, type Issue, IssueNotFound, type Status } from "./Issues.js";
+
+/**
+ * Where issues live, each in one workspace. Every method takes the workspace, so tenant
+ * isolation is the data access's: no surface and no handler can skip it, and an issue of
+ * another workspace is simply not found.
+ */
+export class IssueStore extends Context.Service<
+  IssueStore,
+  {
+    readonly list: (
+      workspace: string,
+      status: typeof Status.Type | undefined,
+      limit: number,
+    ) => Effect.Effect<ReadonlyArray<Issue>>;
+    readonly get: (workspace: string, id: string) => Effect.Effect<Issue, IssueNotFound>;
+    readonly create: (
+      workspace: string,
+      draft: Pick<Issue, "title" | "body" | "assignee">,
+    ) => Effect.Effect<Issue>;
+    readonly comment: (
+      workspace: string,
+      id: string,
+      comment: typeof Comment.Type,
+    ) => Effect.Effect<Issue, IssueNotFound>;
+    readonly close: (workspace: string, id: string) => Effect.Effect<Issue, IssueNotFound>;
+  }
+>()("tracker/IssueStore") {
+  // DEMO ONLY: memory, lost when the process stops. A real store is another Layer of this
+  // service, chosen by the entrypoint.
+  static readonly layerMemory = Layer.sync(IssueStore, () => {
+    const issues = new Map<string, Array<Issue>>();
+
+    const of = (workspace: string) => issues.get(workspace) ?? [];
+
+    const get = Effect.fn("IssueStore.get")(function* (workspace: string, id: string) {
+      const issue = of(workspace).find((candidate) => candidate.id === id);
+
+      if (issue === undefined) return yield* new IssueNotFound({ id });
+
+      return issue;
+    });
+
+    // No `yield*` between the read and the write: a fiber may be set aside at one, and two
+    // changes that each read the issue before either wrote would keep only the second. A
+    // database does this in one statement or a transaction.
+    const change = Effect.fn("IssueStore.change")(function* (
+      workspace: string,
+      id: string,
+      to: (issue: Issue) => Issue,
+    ) {
+      const issue = of(workspace).find((candidate) => candidate.id === id);
+
+      if (issue === undefined) return yield* new IssueNotFound({ id });
+
+      const changed = to(issue);
+
+      issues.set(
+        workspace,
+        of(workspace).map((current) => (current === issue ? changed : current)),
+      );
+
+      return changed;
+    });
+
+    return IssueStore.of({
+      list: (workspace, status, limit) =>
+        Effect.sync(() =>
+          of(workspace)
+            .filter((issue) => status === undefined || issue.status === status)
+            .toReversed()
+            .slice(0, limit),
+        ),
+      get,
+      create: (workspace, draft) =>
+        Effect.sync(() => {
+          const existing = of(workspace);
+
+          const issue: Issue = {
+            ...draft,
+            id: `${workspace.toUpperCase()}-${existing.length + 1}`,
+            status: "open",
+            comments: [],
+          };
+
+          issues.set(workspace, [...existing, issue]);
+
+          return issue;
+        }),
+      comment: (workspace, id, comment) =>
+        change(workspace, id, (issue) => ({ ...issue, comments: [...issue.comments, comment] })),
+      close: (workspace, id) => change(workspace, id, (issue) => ({ ...issue, status: "closed" })),
+    });
+  });
+}

package/examples/kitchen-sink/src/issues/write-limit.ts

@@ -0,0 +1,41 @@
+import { Duration, Effect } from "effect";
+import { RateLimiter } from "effect/persistence";
+import { CurrentMember, type Member } from "../identity/Identity.js";
+import { RateLimited } from "./Issues.js";
+
+// The write limit: ten writes a minute per member. It is the handlers', not a surface's, so it
+// holds wherever they run: HTTP, MCP, RPC, stdio and the assistant's tools all count against
+// the one limiter. A builder yields this once and wraps each limited handler in the function
+// it gets, which fails with an error those actions' contracts declare; every surface sends it
+// as any declared error. The limiter is a service, so its counts are shared wherever it is
+// provided: memory.ts provides Effect's own, `RateLimiter.layer` over a store. `consume` counts
+// in a fixed window unless given `algorithm: "token-bucket"`: ten writes in each minute, so
+// twenty may pass across the boundary between two.
+export const writeLimit = Effect.gen(function* () {
+  const limiter = yield* RateLimiter.RateLimiter;
+
+  return <A, E, R>(write: (member: Member) => Effect.Effect<A, E, R>) =>
+    Effect.gen(function* () {
+      const member = yield* CurrentMember;
+
+      yield* limiter
+        .consume({
+          key: JSON.stringify(["writes", member.workspace, member.id]),
+          limit: 10,
+          window: "1 minute",
+          onExceeded: "fail",
+        })
+        .pipe(
+          Effect.catchReason(
+            "RateLimiterError",
+            "RateLimitExceeded",
+            ({ retryAfter }) =>
+              Effect.fail(new RateLimited({ retryAfterSeconds: Duration.toSeconds(retryAfter) })),
+            // Any other reason is the limiter's store failing: a defect, not the caller's.
+            Effect.die,
+          ),
+        );
+
+      return yield* write(member);
+    });
+});

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

@@ -0,0 +1,30 @@
+import { Layer } from "effect";
+import { RateLimiter } from "effect/persistence";
+import { Grants } from "./admin/grants.js";
+import { Conversations } from "./assistant/conversations.js";
+import { demoModel } from "./assistant/demo-model.js";
+import { AttachmentStore } from "./attachments/store.js";
+import { Directory } from "./identity/directory.js";
+import { IssueStore } from "./issues/store.js";
+import { WorkspaceRegistry } from "./workspaces/registry.js";
+
+// DEMO ONLY: the application's services as their memory or fixed-data Layers, lost when the
+// process stops. A real entrypoint provides a database-backed Layer per service instead, and a
+// test replaces the one it is about.
+
+/** Both stores. The attachment store is built on the issue store: `provideMerge` keeps it. */
+export const stores = AttachmentStore.layerMemory.pipe(Layer.provideMerge(IssueStore.layerMemory));
+
+/** Effect's own limiter, counting in memory. `RateLimiter.layerStoreRedis` counts across processes. */
+export const limiter = RateLimiter.layer.pipe(Layer.provide(RateLimiter.layerStoreMemory));
+
+/** Everything the server needs, for both ports. A local entrypoint provides only what it serves. */
+export const memory = Layer.mergeAll(
+  stores,
+  limiter,
+  WorkspaceRegistry.layerMemory,
+  Directory.layerDemo,
+  Grants.layerDemo,
+  Conversations.layerMemory,
+  demoModel,
+);

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

@@ -0,0 +1,42 @@
+import { NodeRuntime, NodeServices } from "@effect/platform-node";
+import { Effect, Layer } from "effect";
+import { Command } from "effect/cli";
+import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
+import { Operator, type TrustedOperator } from "./admin/Admin.js";
+import { Grants } from "./admin/grants.js";
+import { admin } from "./admin/handlers.js";
+import { WorkspaceRegistry } from "./workspaces/registry.js";
+
+// Entrypoint: `node --import tsx examples/kitchen-sink/src/ops.ts list-workspaces`.
+// The operators' console: the admin actions run in this process, on the host's own services,
+// with no server and no key. A local command is no bypass: the implementation's `authorize`
+// runs here as on the admin port, and admits the operator this host supplies.
+
+// Only a host can name the trusted operator: no verifier's return type includes it.
+const operator: TrustedOperator = { id: "console", trusted: true };
+
+const ops = ActionCli.make(admin, {
+  name: "tracker-ops",
+  commands: {
+    listWorkspaces: {
+      render: ({ workspaces }) =>
+        workspaces
+          .map(({ slug, name, suspended }) => `${slug}  ${name}${suspended ? "  (suspended)" : ""}`)
+          .join("\n"),
+    },
+    suspendWorkspace: { positional: ["workspace"] },
+    resumeWorkspace: { positional: ["workspace"] },
+  },
+}).pipe(
+  // Services go on the command: built when an action runs, never for `--help` or a mistyped
+  // flag. Only what these actions are built from. DEMO ONLY: memory, so this console sees its
+  // own process, not the server's data. A real one provides the database Layers the server does.
+  Command.provide(Layer.merge(WorkspaceRegistry.layerMemory, Grants.layerDemo)),
+  Command.provideSync(Operator, operator),
+);
+
+Command.run(ops, { version: "1.0.0" }).pipe(
+  Effect.provide(NodeServices.layer),
+  ActionCli.logToStderr,
+  NodeRuntime.runMain,
+);

package/examples/kitchen-sink/src/request-policy.ts

@@ -0,0 +1,63 @@
+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. 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. Whether it also runs before the discovery the Bearer provider
+// publishes, global middleware too, is decided where it is provided: last, in routes.ts.
+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;
+
+        if (origin !== undefined && origin !== url.value.origin && !origins.includes(origin)) {
+          return HttpServerResponse.text("Origin not allowed", { status: 403 });
+        }
+
+        return yield* httpEffect;
+      });
+  }),
+  { global: true },
+);
+
+// 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"],
+    }),
+  ),
+);

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

@@ -0,0 +1,120 @@
+import { Effect, Layer } from "effect";
+import { HttpRouter, HttpServerResponse } from "effect/http";
+import { HttpApiSwagger, OpenApi } from "effect/http-api";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+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 { MemberActions, Tools } from "./Actions.js";
+import { authenticateOperator } from "./admin/authenticate.js";
+import { assistant } from "./assistant/handlers.js";
+import { admin } from "./admin/handlers.js";
+import { AdminHttp, Http } from "./Api.js";
+import { download } from "./attachments/download.js";
+import { attachments } from "./attachments/handlers.js";
+import { allowedOrigins } from "./config.js";
+import { authenticateBearer, authenticateSession } from "./identity/authenticate.js";
+import { identity } from "./identity/handlers.js";
+import { Login } from "./identity/Identity.js";
+import { HttpQuota, quota, RpcQuota } from "./identity/quota.js";
+import { layer as assistantTools } from "./issues/assistant.js";
+import { features } from "./issues/guide.js";
+import { issues } from "./issues/handlers.js";
+import { cors, requestPolicy } from "./request-policy.js";
+import { Rpc } from "./Rpc.js";
+import { status } from "./workspaces/handlers.js";
+import { resolveTenant } from "./workspaces/tenant.js";
+import { GetStatus } from "./workspaces/Workspaces.js";
+
+// Every domain's implementation of the public port's actions, once. Each surface below takes
+// this one list and serves the actions its binding or its `actions` names.
+const implementations = [status, identity, issues, attachments, assistant];
+
+// JSON routes at `/api/v1/<action>`, in two layers of one binding, each naming its `actions`.
+// The quota requires the caller, and a public route has none, so `getStatus` is served by a
+// layer without it. The middleware runs inside authentication and before the input is decoded.
+const api = Layer.mergeAll(
+  ActionHttp.layer(Http, implementations, { actions: [GetStatus] }),
+  ActionHttp.layer(Http, implementations, { actions: MemberActions, middleware: [HttpQuota] }),
+);
+
+// The same actions as MCP tools at `/mcp`: a mixed endpoint. Listing the tools and calling
+// `getStatus` need no token; any other request answers the 401 an MCP client signs in on, the
+// one opening a session included, since a session may call any tool.
+const mcp = Layer.unwrap(
+  Effect.map(allowedOrigins, (origins) =>
+    ActionMcp.layerHttp(implementations, {
+      name: "tracker",
+      version: "1.0.0",
+      instructions: "Read an issue before commenting on it or closing it.",
+      authentication: Login,
+      actions: Tools,
+      features,
+      // The endpoint's own Origin allowlist, narrower than the request policy, which has
+      // already refused a foreign Origin: that policy also lets through a page of any name
+      // this host answers to, such as http://127.0.0.1:3000. Not listed here, such a page gets
+      // a 403 from the endpoint.
+      allowedOrigins: origins,
+    }),
+  ),
+);
+
+// The members' actions as Effect RPC, for the web app, behind its session cookie and the same
+// quota as native RPC middleware. It still requires its protocol and serialization, chosen by
+// whoever serves it: server.ts gives it a WebSocket, and a test Effect's HTTP protocol, which
+// answers in memory.
+export const rpc = ActionRpc.layer(Rpc, implementations, { middleware: [RpcQuota] }).pipe(
+  Layer.provide([authenticateSession, quota, assistantTools]),
+);
+
+// Effect's own tools read the binding's native `HttpApi`: the OpenAPI document and a Swagger
+// UI, each showing the bearer scheme on every route but `getStatus`.
+const documentation = Layer.mergeAll(
+  HttpRouter.add(
+    "GET",
+    `${Http.prefix}/openapi.json`,
+    HttpServerResponse.jsonUnsafe(OpenApi.fromApi(Http.api)),
+  ),
+  HttpApiSwagger.layer(Http.api, { path: "/docs" }),
+);
+
+const health = HttpRouter.add("GET", "/healthz", HttpServerResponse.text("ok"));
+
+// The public port's HTTP routes: what members reach, but for the rpcs, which server.ts serves
+// beside these. Each `Layer.provide` gives what the layers before it still owe, and is built
+// before them. Two things follow from that order.
+//
+// - `resolveTenant`, in a `Layer.provide` of its own after the authentication, gives the
+//   `Tenant` the Bearer verifier reads per request. In one array with `authenticateBearer` it
+//   would leave `Tenant` owed: an array's members provide to the routes, not to one another.
+// - Global middleware runs in the order it registers, and it registers when its layer is
+//   built. The request policy, provided last, is built first, so it runs before everything:
+//   before CORS, and before the OAuth discovery the Bearer provider registers when it is
+//   built. Merged beside the routes instead, it would register after that provider, and a
+//   foreign Host could read the discovery document.
+//
+// The assistant's builder yields its tools, so their handlers are provided to the layers
+// serving it, here and on `rpc`: one Layer, built once in the layer graph serving both, where
+// the tools run the issue implementation the routes serve, with no second build of it.
+export const publicRoutes = Layer.mergeAll(api, mcp, download, documentation, health).pipe(
+  Layer.provide(assistantTools),
+  Layer.provide([authenticateBearer, authenticateSession, quota]),
+  Layer.provide(resolveTenant.layer),
+  Layer.provide(cors),
+  Layer.provide(requestPolicy),
+);
+
+// The admin port: what operators reach, and nothing else. It is a router of its own, with its
+// own binding, descriptor and provider, so no member's token is even understood here. It
+// serves one implementation the public port serves too, `status`.
+export const adminRoutes = Layer.mergeAll(
+  ActionHttp.layer(AdminHttp, [status, admin]),
+  health,
+).pipe(Layer.provide(authenticateOperator), Layer.provide(requestPolicy));
+
+// Every builder as one layer. The two ports are two layer graphs, and each would run the
+// builder of an implementation it serves: `status`, which both serve, twice, each port then
+// reporting an `instance` of its own. Provided above both, with the services, each builder
+// runs once for every surface of both ports. The assistant's is left out: the public port
+// alone serves it, and builds it once for its routes and its rpcs.
+export const builders = Action.layer([status, identity, issues, attachments, admin]);

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

@@ -0,0 +1,46 @@
+import { Effect, flow } from "effect";
+import { HttpClient, HttpClientRequest } from "effect/http";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import { Http } from "./Api.js";
+import type { Issue } from "./issues/Issues.js";
+
+// Entrypoint for code written with promises: an integration, a bot, another product's page.
+// It imports the binding and nothing of the server, so a bundler keeps the contracts and
+// Effect's fetch client, no handler.
+export const connect = (options: {
+  readonly url: string;
+  readonly token: string;
+  readonly workspace: string;
+}) => {
+  // Built once, outside any Effect, over `fetch`: its methods require nothing, so each call
+  // runs with `Effect.runPromise`.
+  const api = ActionHttp.fetchClient(Http, {
+    baseUrl: options.url,
+    transformClient: HttpClient.mapRequest(
+      flow(
+        HttpClientRequest.bearerToken(options.token),
+        HttpClientRequest.setHeader("x-workspace", options.workspace),
+      ),
+    ),
+  });
+
+  return {
+    // A method takes the action's decoded input, so a field with a decoding default is given
+    // here; only a call without any argument sends `{}` and gets the defaults.
+    openIssues: (limit = 20) =>
+      Effect.runPromise(
+        Effect.map(api.listIssues({ status: "open", limit }), ({ issues }) => issues),
+      ),
+
+    // A declared error is a typed failure, handled by its tag: a missing issue is `undefined`.
+    issue: (id: string): Promise<Issue | undefined> =>
+      api.getIssue({ id }).pipe(
+        Effect.catchTag("IssueNotFound", () => Effect.succeed(undefined)),
+        Effect.runPromise,
+      ),
+
+    // Left unhandled, a declared error rejects the promise as its decoded value, so a caller's
+    // `catch` may test `error instanceof RateLimited`.
+    file: (title: string, body: string) => Effect.runPromise(api.createIssue({ title, body })),
+  };
+};