@gjermundgaraba/effect-actions 0.20.0 → 0.21.0

package/docs/setup.md

@@ -1,34 +1,28 @@
 # Setup
 
-Install the package, import its modules, write the smallest program, lay out an application and
-bundle a browser client.
+Install the package, import its modules, write the smallest program, lay out an application and bundle a browser client.
 
 A message the library throws says its fix; for a compiler diagnostic or Effect's own error, search [setup-failures.md](setup-failures.md).
 
 ## Install
 
 ```sh
-pnpm add @gjermundgaraba/effect-actions effect@~4.0.4
+pnpm add @gjermundgaraba/effect-actions effect@~4.0.5
 ```
 
-| Need                                | Add                                                             |
-| ----------------------------------- | --------------------------------------------------------------- |
-| Node HTTP server, stdio host or CLI | `@effect/platform-node@~4.0.4`                                  |
-| Tests                               | `vitest@^5` and `@effect/vitest@~4.0.4`, as dev dependencies    |
-| Type checking                       | `typescript@^7.0.2`, as a dev dependency                        |
-| Node's types, for `node:` imports   | `@types/node`, as a dev dependency                              |
-| Running a TypeScript entrypoint     | `tsx`, as a dev dependency: `node --import tsx <entrypoint>.ts` |
+| Need | Add |
+| --- | --- |
+| Node HTTP server, stdio host or CLI | `@effect/platform-node@~4.0.5` |
+| Tests | `vitest@^5` and `@effect/vitest@~4.0.5`, as dev dependencies |
+| Type checking | `typescript@^7.0.2`, as a dev dependency |
+| Node's types, for `node:` imports | `@types/node`, as a dev dependency |
+| Running a TypeScript entrypoint | `tsx`, as a dev dependency: `node --import tsx <entrypoint>.ts` |
 
-The `effect` peer admits the 4.0.x patches from the oldest whose APIs the package uses, and no
-minor release: a minor release may change the unstable Effect modules the surfaces build on.
+The `effect` peer admits the 4.0.x patches from the oldest whose APIs the package uses, and no minor release: a minor release may change the unstable Effect modules the surfaces build on.
 
-Keep the tilde in `package.json`: `^4.0.4`, which npm writes for `effect@4.0.4`, admits a minor
-release outside the peer range. `npm install effect@~4.0.4` keeps it.
+Keep the tilde in `package.json`: `^4.0.5`, which npm writes for `effect@4.0.5`, admits a minor release outside the peer range. `npm install effect@~4.0.5` keeps it.
 
-Node `>=26`: the package's `engines`, the Node the library is developed and tested on. TypeScript 7 or newer. ESM only. The repository checks the
-examples with a stricter `tsconfig.json`; this is the minimum a project needs. The package's modules resolve only through its
-`exports`, which `"module": "nodenext"` reads, as a bundler project's
-`"moduleResolution": "bundler"` does. `"strict": true` is required, by Effect:
+Node `>=26.12.0`: the package's `engines`, the Node the library is developed and tested on. TypeScript 7 or newer. ESM only. The repository checks the examples with a stricter `tsconfig.json`; this is the minimum a project needs. The package's modules resolve only through its `exports`, which `"module": "nodenext"` reads, as a bundler project's `"moduleResolution": "bundler"` does. `"strict": true` is required, by Effect:
 
 ```json
 {
@@ -47,24 +41,17 @@ examples with a stricter `tsconfig.json`; this is the minimum a project needs. T
 
 ## Entry points
 
-There is no package root. Import one module per subpath, as a namespace,
-`import * as Action from "@gjermundgaraba/effect-actions/Action"`.
-The modules: `Action`, `ActionHttp`, `ActionMcp`, `ActionRpc`, `ActionToolkit`, `ActionCli`,
-`Authentication`, `Testing`.
+There is no package root. Import one module per subpath, as a namespace, `import * as Action from "@gjermundgaraba/effect-actions/Action"`. The modules: `Action`, `Event`, `ActionHttp`, `ActionMcp`, `ActionRpc`, `ActionToolkit`, `ActionCli`, `Authentication`, `Webhook`, `Testing`.
 
-Effect's own modules are subpaths of `effect` too: `effect/http` (`HttpRouter`, `HttpClient`,
-`FetchHttpClient`), `effect/http-api` (`OpenApi`, `HttpApiMiddleware`), `effect/rpc`
-(`RpcServer`, `RpcClient`), `effect/ai` (`LanguageModel`, `Chat`), `effect/cli` (`Command`) and
-`effect/socket` (`Socket`).
+Effect's own modules are subpaths of `effect` too: `effect/http` (`HttpRouter`, `HttpClient`, `FetchHttpClient`), `effect/http-api` (`OpenApi`, `HttpApiMiddleware`), `effect/rpc` (`RpcServer`, `RpcClient`), `effect/ai` (`LanguageModel`, `Chat`), `effect/cli` (`Command`) and `effect/socket` (`Socket`).
 
 ## Minimal program
 
-One action, served as a JSON route and as an MCP tool: four declarations, each in a file of
-[quickstart/src/](../examples/quickstart/src/).
+One action, served as a JSON route and as an MCP tool: four declarations, each in a file of [quickstart/src/](../examples/quickstart/src/).
 
 ```ts example=quickstart/src/greeting/Greeting.ts
-import { Schema } from "effect";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { Schema } from "effect";
 
 // A contract: what the action takes and answers, whether it changes anything, and who may
 // call it. It imports no server code, so any client can import it, a browser page included.
@@ -78,16 +65,20 @@ export const Greet = Action.make("greet", {
 ```
 
 ```ts example=quickstart/src/greeting/handlers.ts
-import { Effect } from "effect";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { Effect } from "effect";
+
 import { Greet } from "./Greeting.js";
 
 // The implementation: the contract bound to its handler. Every surface takes this one value.
-export const greeting = Action.implement(Greet, ({ name }) => Effect.succeed(`Hello, ${name}!`));
+export const greeting = Action.implement(Greet, ({ name }) =>
+  Effect.succeed(`Hello, ${name}!`)
+);
 ```
 
 ```ts example=quickstart/src/Api.ts
 import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+
 import { Greet } from "./greeting/Greeting.js";
 
 // The HTTP binding: `POST /api/greet`. The server serves it and the client calls it.
@@ -95,41 +86,30 @@ export const Http = ActionHttp.make([Greet]);
 ```
 
 ```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" })
 );
 ```
 
-Serve `routes` with `HttpRouter.serve` and a platform server layer
-([quickstart/src/server.ts](../examples/quickstart/src/server.ts)), call the route with the
-binding's typed client ([quickstart/src/client.ts](../examples/quickstart/src/client.ts)), and
-test both in memory ([quickstart/test/routes.test.ts](../examples/quickstart/test/routes.test.ts)).
-[notes-service](../examples/notes-service/) is this program grown into a service, in the same
-layout.
+Serve `routes` with `HttpRouter.serve` and a platform server layer ([quickstart/src/server.ts](../examples/quickstart/src/server.ts)), call the route with the binding's typed client ([quickstart/src/client.ts](../examples/quickstart/src/client.ts)), and test both in memory ([quickstart/test/routes.test.ts](../examples/quickstart/test/routes.test.ts)). [notes-service](../examples/notes-service/) is this program grown into a service, in the same layout.
 
 ## Lay out an application
 
-Copy the examples' layout:
-[examples/README.md](../examples/README.md#how-they-are-laid-out).
+Copy the examples' layout: [examples/README.md](../examples/README.md#how-they-are-laid-out).
 
 ## Bundle for a browser
 
-Import into the page only the contract files, the binding and a client module of your own:
-[notes-service/src/browser.ts](../examples/notes-service/src/browser.ts) over HTTP, with
-promises, [live-rpc/src/browser.ts](../examples/live-rpc/src/browser.ts) over a WebSocket.
-
-- `Action`, `ActionHttp`, `ActionRpc` and `Authentication` are the browser-safe modules: they
-  use nothing of Node or a server platform.
-- Keep `Action.implement` and `Authentication.layer` out of every file the page imports: a
-  bundler keeps such a call, and what its handlers or verifier import, even unused.
-- Those four modules import Effect through `effect`, `effect/http` and `effect/http-api` alone,
-  and `ActionRpc` through `effect/rpc` too. A page loading Effect from an import map serves
-  those, and `effect/socket` for a WebSocket client.
+Import into the page only the contract files, the binding and a client module of your own: [notes-service/src/browser.ts](../examples/notes-service/src/browser.ts) over HTTP, with promises, [live-rpc/src/browser.ts](../examples/live-rpc/src/browser.ts) over a WebSocket.
+
+- `Action`, `Event`, `ActionHttp`, `ActionRpc` and `Authentication` are the browser-safe modules: they use nothing of Node or a server platform.
+- Keep `Action.implement` and `Authentication.layer` out of every file the page imports: a bundler keeps such a call, and what its handlers or verifier import, even unused.
+- Those five modules import Effect through `effect`, `effect/http` and `effect/http-api` alone, and `ActionRpc` through `effect/rpc` too. A page loading Effect from an import map serves those, and `effect/socket` for a WebSocket client.

package/examples/README.md

@@ -1,33 +1,23 @@
 # Examples
 
-Complete applications built with `@gjermundgaraba/effect-actions`. Each is a directory you can
-run, with its own tests and a README that says what it shows and where. They are type-checked,
-linted and tested with the library, and they ship in the package, at
-`node_modules/@gjermundgaraba/effect-actions/examples`.
+Complete applications built with `@gjermundgaraba/effect-actions`. Each is a directory you can run, with its own tests and a README that says what it shows and where. They are type-checked, linted and tested with the library, and they ship in the package, at `node_modules/@gjermundgaraba/effect-actions/examples`.
 
-[quickstart](quickstart/), [notes-service](notes-service/), [mcp-tools](mcp-tools/),
-[assistant](assistant/), [live-rpc](live-rpc/) and [kitchen-sink](kitchen-sink/): which to start
-from, by what you are building, is the table in [docs/README.md](../docs/README.md#examples).
+[quickstart](quickstart/), [notes-service](notes-service/), [mcp-tools](mcp-tools/), [assistant](assistant/), [live-rpc](live-rpc/), [build-events](build-events/) and [kitchen-sink](kitchen-sink/): which to start from, by what you are building, is the table in [docs/README.md](../docs/README.md#examples).
 
 ## Run one
 
-From the repository root, after `vp install`, each README's commands work as written, for
-example:
+From the repository root, after `vp install`, each README's commands work as written, for example:
 
 ```sh
 node --import tsx examples/notes-service/src/server.ts
 vp test examples/notes-service
 ```
 
-In a project that installs the package, copy an example's directory out of `node_modules` and
-run it the same way: the examples import the package by its name. They need `tsx`,
-`@effect/platform-node` and `@types/node` beside `effect`, and `vitest` with `@effect/vitest` for
-their tests.
+In a project that installs the package, copy an example's directory out of `node_modules` and run it the same way: the examples import the package by its name. They need `tsx`, `@effect/platform-node` and `@types/node` beside `effect`, and `vitest` with `@effect/vitest` for their tests.
 
 ## How they are laid out
 
-Every example follows one layout, which is the one we recommend for an application. Each has
-the parts of it that it needs:
+Every example follows one layout, which is the one we recommend for an application. Each has the parts of it that it needs:
 
 ```text
 <example>/
@@ -46,27 +36,12 @@ the parts of it that it needs:
     └── routes.test.ts     what the surfaces add, called in memory
 ```
 
-- **Folders are domains, not mechanisms.** Everything about notes is in `notes/`; there is no
-  `contracts/`, `handlers/` or `tools/` folder. `platform/`, the adapters, is the one exception.
-- **The PascalCase file in a domain is its contract.** It imports no server code, so a browser
-  or a CLI can import it. Lowercase files beside it run on the server, each named for its role
-  (`handlers.ts`, `store.ts`), never for the domain: `notes.ts` beside `Notes.ts` is one file on
-  a disk that ignores case.
-- **Technology stays out of domains.** A domain's service declares what its handlers need; a
-  Layer that reaches a file system, a database or another service's API is an adapter, in
-  `platform/`, named for what it reaches (`tasks-file.ts`, `print-farm.ts`), and turns that
-  technology's failures into the domain's declared errors, or into defects where no caller can
-  act on them. A Layer in memory, which reaches
-  nothing, stays beside its service.
-- **An entrypoint is where implementations are chosen**: which store, which platform, and on a
-  local surface which caller. Nothing below it knows what it got, so a test chooses its own.
-- **Tests mirror the source.** A domain's tests sit in `test/<domain>/`, most calling its
-  implementation in process with `Action.client`; a test of a root file, such as `routes.ts`,
-  sits beside them and calls the real routes in memory with `Testing.layer`. One opens a port:
-  live-rpc's `server.test.ts`, for the WebSocket no in-memory test reaches.
+- **Folders are domains, not mechanisms.** Everything about notes is in `notes/`; there is no `contracts/`, `handlers/` or `tools/` folder. `platform/`, the adapters, is the one exception.
+- **The PascalCase file in a domain is its contract.** It imports no server code, so a browser or a CLI can import it. Lowercase files beside it run on the server, each named for its role (`handlers.ts`, `store.ts`), never for the domain: `notes.ts` beside `Notes.ts` is one file on a disk that ignores case.
+- **Technology stays out of domains.** A domain's service declares what its handlers need; a Layer that reaches a file system, a database or another service's API is an adapter, in `platform/`, named for what it reaches (`tasks-file.ts`, `print-farm.ts`), and turns that technology's failures into the domain's declared errors, or into defects where no caller can act on them. A Layer in memory, which reaches nothing, stays beside its service.
+- **An entrypoint is where implementations are chosen**: which store, which platform, and on a local surface which caller. Nothing below it knows what it got, so a test chooses its own.
+- **Tests mirror the source.** A domain's tests sit in `test/<domain>/`, most calling its implementation in process with `Action.client`; a test of a root file, such as `routes.ts`, sits beside them and calls the real routes in memory with `Testing.layer`. One opens a port: live-rpc's `server.test.ts`, for the WebSocket no in-memory test reaches.
 
-In a monorepo, the contract files and the binding are the package that the server, the CLI and
-the website all depend on; the rest is the server.
+In a monorepo, the contract files and the binding are the package that the server, the CLI and the website all depend on; the rest is the server.
 
-Every token, user and store in these examples is a demo. Each place that must change before a
-deployment is marked `DEMO ONLY`.
+Every token, user and store in these examples is a demo. Each place that must change before a deployment is marked `DEMO ONLY`.

package/examples/assistant/README.md

@@ -1,13 +1,10 @@
 # assistant
 
-An application with no server: its actions run in the process that calls them. A team's task
-list is worked on by a model, through tools, and by whoever runs the machine, through commands.
-Both are the same implementations behind the same authorization. It opens no port.
+An application with no server: its actions run in the process that calls them. A team's task list is worked on by a model, through tools, and by whoever runs the machine, through commands. Both are the same implementations behind the same authorization. It opens no port.
 
 ## Run it
 
-From the repository root, after `vp install` (from an installed package, see
-[Run one](../README.md#run-one)):
+From the repository root, after `vp install` (from an installed package, see [Run one](../README.md#run-one)):
 
 ```sh
 node --import tsx examples/assistant/src/agent.ts               # a scripted model: no API key
@@ -22,9 +19,7 @@ node --import tsx examples/assistant/src/cli.ts list-tasks -a grace --json 2>/de
 vp test examples/assistant
 ```
 
-The agent and each command are separate processes. They share one JSON file, named by
-`ASSISTANT_TASKS` and kept in the system's temporary directory by default. Running the agent
-again adds the same tasks again: delete the file to start over.
+The agent and each command are separate processes. They share one JSON file, named by `ASSISTANT_TASKS` and kept in the system's temporary directory by default. Running the agent again adds the same tasks again: delete the file to start over.
 
 ## Layout
 
@@ -57,22 +52,22 @@ test/
 
 ## Where to look
 
-| To see                                                                | Read                                               |
-| --------------------------------------------------------------------- | -------------------------------------------------- |
-| Implementations as a native Effect AI `Toolkit`                       | `src/toolkit.ts`                                   |
-| Native tool titles in the approval display                            | `src/toolkit.ts`, `src/agent.ts`                   |
-| One approval rule reading the call and its caller                     | `src/toolkit.ts`                                   |
-| A turn run as a member, and an approval answered through a `Chat`     | `src/agent.ts`                                     |
-| Where a real `LanguageModel` plugs in                                 | `src/agent.ts`, `src/scripted.ts`                  |
-| Local commands with `positional`, `aliases`, `render`, `stdin`        | `src/commands.ts`                                  |
-| Services provided on the command, and the host naming the caller      | `src/cli.ts`                                       |
-| A command's result alone on stdout, its handler's logs on stderr      | `src/cli.ts`, `src/platform/tasks-file.ts`         |
-| `logToStderr` moving a defect's report from stdout to stderr          | `src/cli.ts`                                       |
-| An identity only the host builds: the trusted operator                | `src/identity/Identity.ts`                         |
-| An authorizer built once from a service, reading the caller per call  | `src/identity/authorize.ts`                        |
+| To see | Read |
+| --- | --- |
+| Implementations as a native Effect AI `Toolkit` | `src/toolkit.ts` |
+| Native tool titles in the approval display | `src/toolkit.ts`, `src/agent.ts` |
+| One approval rule reading the call and its caller | `src/toolkit.ts` |
+| A turn run as a member, and an approval answered through a `Chat` | `src/agent.ts` |
+| Where a real `LanguageModel` plugs in | `src/agent.ts`, `src/scripted.ts` |
+| Local commands with `positional`, `aliases`, `render`, `stdin` | `src/commands.ts` |
+| Services provided on the command, and the host naming the caller | `src/cli.ts` |
+| A command's result alone on stdout, its handler's logs on stderr | `src/cli.ts`, `src/platform/tasks-file.ts` |
+| `logToStderr` moving a defect's report from stdout to stderr | `src/cli.ts` |
+| An identity only the host builds: the trusted operator | `src/identity/Identity.ts` |
+| An authorizer built once from a service, reading the caller per call | `src/identity/authorize.ts` |
 | One service with two Layers: a file for entrypoints, memory for tests | `src/tasks/store.ts`, `src/platform/tasks-file.ts` |
-| Changes serialized, since a turn's tool calls run concurrently        | `src/tasks/store.ts`                               |
-| Testing handlers and authorization, each caller around its calls      | `test/tasks/tasks.test.ts`                         |
-| Testing a Layer over a temporary file, its path set through config    | `test/platform/tasks-file.test.ts`                 |
-| Testing a tool call, an approval required, an approval answered       | `test/toolkit.test.ts`                             |
-| Testing a command's syntax and output without a process               | `test/commands.test.ts`                            |
+| Changes serialized, since a turn's tool calls run concurrently | `src/tasks/store.ts` |
+| Testing handlers and authorization, each caller around its calls | `test/tasks/tasks.test.ts` |
+| Testing a Layer over a temporary file, its path set through config | `test/platform/tasks-file.test.ts` |
+| Testing a tool call, an approval required, an approval answered | `test/toolkit.test.ts` |
+| Testing a command's syntax and output without a process | `test/commands.test.ts` |

package/examples/assistant/src/agent.ts

@@ -1,11 +1,13 @@
 import { NodeRuntime, NodeServices } from "@effect/platform-node";
 import { Console, Context, Effect, Layer } from "effect";
-import { Chat, type LanguageModel, type Prompt, Tool } from "effect/ai";
+import { Chat, Tool } from "effect/ai";
+import type { LanguageModel, Prompt } from "effect/ai";
+
 import type { Member } from "./identity/Identity.js";
 import { members } from "./identity/members.js";
 import { Permissions } from "./identity/permissions.js";
-import { scripted } from "./scripted.js";
 import { tasksFile } from "./platform/tasks-file.js";
+import { scripted } from "./scripted.js";
 import { actingFor, layer, toolkit } from "./toolkit.js";
 
 // Entrypoint: `node --import tsx examples/assistant/src/agent.ts`.
@@ -13,29 +15,39 @@ import { actingFor, layer, toolkit } from "./toolkit.js";
 // port. Every tool call passes through the same `authorize` and handlers as the commands.
 
 // What a turn answers with: its text, the calls the model made and what they returned.
-type Response = LanguageModel.GenerateTextResponse<typeof toolkit.tools, "opaque">;
+type Response = LanguageModel.GenerateTextResponse<
+  typeof toolkit.tools,
+  "opaque"
+>;
 
 // Printing only.
 const report = (member: Member) => (response: Response) => {
-  const waiting = response.content.flatMap((part) =>
-    part.type === "tool-approval-request" ? [part.toolCallId] : [],
+  const waiting = new Set(
+    response.content.flatMap((part) =>
+      part.type === "tool-approval-request" ? [part.toolCallId] : []
+    )
   );
 
   return Console.log(
     [
       `As ${member.id}:`,
       ...response.toolResults.map(
-        ({ name, encodedResult }) => `  ${name} -> ${JSON.stringify(encodedResult)}`,
+        ({ name, encodedResult }) =>
+          `  ${name} -> ${JSON.stringify(encodedResult)}`
       ),
       ...response.toolCalls.flatMap(({ id, name, params }) => {
-        const title = Context.getOrElse(toolkit.tools[name].annotations, Tool.Title, () => name);
+        const title = Context.getOrElse(
+          toolkit.tools[name].annotations,
+          Tool.Title,
+          () => name
+        );
 
-        return waiting.includes(id)
+        return waiting.has(id)
           ? [`  ${title} ${JSON.stringify(params)} waits for approval`]
           : [];
       }),
       ...(response.text === "" ? [] : [`  "${response.text}"`]),
-    ].join("\n"),
+    ].join("\n")
   );
 };
 
@@ -43,7 +55,9 @@ const report = (member: Member) => (response: Response) => {
 // provided around the whole turn, so the approval rule, `authorize` and the handlers of every
 // call in it see that member.
 const turn = (chat: Chat.Chat, member: Member, prompt: Prompt.RawInput) =>
-  chat.generateText({ prompt, toolkit }).pipe(actingFor(member), Effect.tap(report(member)));
+  chat
+    .generateText({ prompt, toolkit })
+    .pipe(actingFor(member), Effect.tap(report(member)));
 
 const conversations = Effect.gen(function* () {
   // A `Chat` keeps the conversation's history, and approval depends on it: an answer is matched
@@ -54,7 +68,11 @@ const conversations = Effect.gen(function* () {
 
   // Ada's own task is added at once. The task for Grace is not run: the turn ends with a
   // request for approval in place of that call's result.
-  const asked = yield* turn(withAda, members.ada, "Add the venue for me, invitations for Grace.");
+  const asked = yield* turn(
+    withAda,
+    members.ada,
+    "Add the venue for me, invitations for Grace."
+  );
 
   // A real host shows each request to the person and waits. Their answers start the next turn,
   // in which an approved call runs before the model is asked again. It runs as whoever that
@@ -64,32 +82,56 @@ const conversations = Effect.gen(function* () {
       role: "tool",
       content: asked.content.flatMap((part) =>
         part.type === "tool-approval-request"
-          ? [{ type: "tool-approval-response", approvalId: part.approvalId, approved: true }]
-          : [],
+          ? [
+              {
+                type: "tool-approval-response",
+                approvalId: part.approvalId,
+                approved: true,
+              },
+            ]
+          : []
       ),
     },
   ]);
 
   // The same toolkit, another member. The guest may read, so the write comes back refused.
-  yield* turn(yield* Chat.empty, members.guest, "What is there to do? Add lunch for me.");
+  yield* turn(
+    yield* Chat.empty,
+    members.guest,
+    "What is there to do? Add lunch for me."
+  );
 });
 
 const adding = (id: string, title: string, assignee: string) =>
-  ({ type: "tool-call", id, name: "addTask", params: { title, assignee } }) as const;
+  ({
+    type: "tool-call",
+    id,
+    name: "addTask",
+    params: { title, assignee },
+  }) as const;
 
 // DEMO ONLY: what the model answers, request by request, so this runs without an API key.
 const model = scripted(
-  [adding("1", "Book the venue", "ada"), adding("2", "Send invitations", "grace")],
+  [
+    adding("1", "Book the venue", "ada"),
+    adding("2", "Send invitations", "grace"),
+  ],
   [{ type: "text", text: "Both tasks are on the list." }],
-  [{ type: "tool-call", id: "3", name: "listTasks", params: {} }, adding("4", "Lunch", "guest")],
+  [
+    { type: "tool-call", id: "3", name: "listTasks", params: {} },
+    adding("4", "Lunch", "guest"),
+  ]
 );
 
 conversations.pipe(
-  // A real `LanguageModel` plugs in here: the layer of a provider's model, with the layer of
-  // that provider's client, in place of the scripted one. Nothing below this line changes.
-  Effect.provide(model),
-  // Startup services only: where tasks and permissions are kept.
-  Effect.provide(layer.pipe(Layer.provide([tasksFile, Permissions.layerMemory]))),
-  Effect.provide(NodeServices.layer),
-  NodeRuntime.runMain,
+  Effect.provide(
+    Layer.mergeAll(
+      // A real `LanguageModel` plugs in here: the layer of a provider's model, with the layer
+      // of that provider's client, in place of the scripted one. Nothing else changes.
+      model,
+      // Startup services only: where tasks and permissions are kept.
+      layer.pipe(Layer.provide([tasksFile, Permissions.layerMemory]))
+    ).pipe(Layer.provideMerge(NodeServices.layer))
+  ),
+  NodeRuntime.runMain()
 );

package/examples/assistant/src/cli.ts

@@ -1,10 +1,13 @@
 import { userInfo } from "node:os";
+
 import { NodeRuntime, NodeServices } from "@effect/platform-node";
+import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
 import { Effect, Layer } from "effect";
 import { Command } from "effect/cli";
-import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
+
 import { commands } from "./commands.js";
-import { CurrentCaller, type Operator } from "./identity/Identity.js";
+import { CurrentCaller } from "./identity/Identity.js";
+import type { Operator } from "./identity/Identity.js";
 import { Permissions } from "./identity/permissions.js";
 import { tasksFile } from "./platform/tasks-file.js";
 
@@ -16,7 +19,7 @@ const operator: Operator = { kind: "operator", id: userInfo().username };
 
 const assistant = commands.pipe(
   Command.provide(Layer.mergeAll(tasksFile, Permissions.layerMemory)),
-  Command.provideSync(CurrentCaller, operator),
+  Command.provideSync(CurrentCaller, operator)
 );
 
 // A command's defect, such as a tasks file that does not decode, `runMain` reports on stdout.
@@ -25,5 +28,5 @@ const assistant = commands.pipe(
 Command.run(assistant, { version: "1.0.0" }).pipe(
   Effect.provide(NodeServices.layer),
   ActionCli.logToStderr,
-  NodeRuntime.runMain,
+  NodeRuntime.runMain()
 );

package/examples/assistant/src/commands.ts

@@ -1,4 +1,5 @@
 import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
+
 import { identity } from "./identity/handlers.js";
 import { tasks } from "./tasks/handlers.js";
 
@@ -12,11 +13,15 @@ export const commands = ActionCli.make([tasks, identity], {
     // per task for a person, and adds `--json` for the JSON a script reads. `description` is the
     // command's help, saying what a line holds; the action's stays what a model reads.
     listTasks: {
-      description: "Print one line per task: [x] when done, then its id, title and assignee.",
+      description:
+        "Print one line per task: [x] when done, then its id, title and assignee.",
       aliases: { assignee: "a" },
-      render: ({ tasks }) =>
-        tasks
-          .map((task) => `${task.done ? "[x]" : "[ ]"} ${task.id} ${task.title} (${task.assignee})`)
+      render: ({ tasks: listed }) =>
+        listed
+          .map(
+            (task) =>
+              `${task.done ? "[x]" : "[ ]"} ${task.id} ${task.title} (${task.assignee})`
+          )
           .join("\n"),
     },
     // `assistant complete-task 2`: an argument instead of `--id 2`.

package/examples/assistant/src/identity/Identity.ts

@@ -1,5 +1,5 @@
-import { Context, Schema } from "effect";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { Context, Schema } from "effect";
 
 /** A teammate: what a sign-in can name. The assistant acts for one in each turn. */
 export interface Member {
@@ -21,9 +21,10 @@ export interface Operator {
  * authenticates anyone: the host provides it around each call, as the member a model acts for
  * or as the operator at the terminal.
  */
-export class CurrentCaller extends Context.Service<CurrentCaller, Member | Operator>()(
-  "assistant/CurrentCaller",
-) {}
+export class CurrentCaller extends Context.Service<
+  CurrentCaller,
+  Member | Operator
+>()("assistant/CurrentCaller") {}
 
 export const WhoAmI = Action.make("whoAmI", {
   description: "Show who the assistant is acting for.",

package/examples/assistant/src/identity/authorize.ts

@@ -1,7 +1,9 @@
-import { Effect } from "effect";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { Effect } from "effect";
+
 import { CurrentCaller } from "./Identity.js";
-import { type Permission, Permissions } from "./permissions.js";
+import { Permissions } from "./permissions.js";
+import type { Permission } from "./permissions.js";
 
 // The one rule, for a model's tool call and for a command alike. The permission store is a
 // startup service, so this Effect gets it; the caller differs per call, so the function it
@@ -13,12 +15,18 @@ export const authorize = Effect.gen(function* () {
     const caller = yield* CurrentCaller;
 
     // The operator is trusted, and has no entry in the store. Only a host can name one.
-    if (caller.kind === "operator") return;
+    if (caller.kind === "operator") {
+      return;
+    }
 
-    const permission: Permission = action.readOnly ? "tasks:read" : "tasks:write";
+    const permission: Permission = action.readOnly
+      ? "tasks:read"
+      : "tasks:write";
 
     if (!(yield* permissions.granted(caller.id)).includes(permission)) {
-      return yield* new Action.Forbidden({ message: `Requires ${permission}.` });
+      return yield* new Action.Forbidden({
+        message: `Requires ${permission}.`,
+      });
     }
   });
 });

package/examples/assistant/src/identity/handlers.ts

@@ -1,10 +1,11 @@
-import { Effect } from "effect";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { Effect } from "effect";
+
 import { authorize } from "./authorize.js";
 import { CurrentCaller, WhoAmI } from "./Identity.js";
 
 export const identity = Action.implement(
   WhoAmI,
   () => Effect.map(CurrentCaller, ({ id, kind }) => ({ id, kind })),
-  { authorize },
+  { authorize }
 );

package/examples/assistant/src/identity/permissions.ts

@@ -8,16 +8,22 @@ export type Permission = "tasks:read" | "tasks:write";
  */
 export class Permissions extends Context.Service<
   Permissions,
-  { readonly granted: (memberId: string) => Effect.Effect<ReadonlyArray<Permission>> }
+  {
+    readonly granted: (
+      memberId: string
+    ) => Effect.Effect<readonly Permission[]>;
+  }
 >()("assistant/Permissions") {
   // DEMO ONLY: a fixed table. A real application reads its database or its directory.
   static readonly layerMemory = Layer.sync(Permissions, () => {
-    const table = new Map<string, ReadonlyArray<Permission>>([
+    const table = new Map<string, readonly Permission[]>([
       ["ada", ["tasks:read", "tasks:write"]],
       ["grace", ["tasks:read", "tasks:write"]],
       ["guest", ["tasks:read"]],
     ]);
 
-    return Permissions.of({ granted: (memberId) => Effect.sync(() => table.get(memberId) ?? []) });
+    return Permissions.of({
+      granted: (memberId) => Effect.sync(() => table.get(memberId) ?? []),
+    });
   });
 }