@gjermundgaraba/effect-actions 0.16.0 → 0.18.0

package/docs/ActionToolkit.md

@@ -44,7 +44,7 @@ const turn = chat.generateText({ prompt, toolkit }).pipe(actingFor(member));
 conversations.pipe(
   Effect.provide(model),
   // Once, around the program. Startup services only, never a caller.
-  Effect.provide(layer.pipe(Layer.provide([TaskStore.layerFile, Permissions.layerMemory]))),
+  Effect.provide(layer.pipe(Layer.provide([tasksFile, Permissions.layerMemory]))),
 );
 ```
 
@@ -53,10 +53,32 @@ conversations.pipe(
 - A refusal or a declared error is not raised: it is a tool result with `isFailure: true`, which the model reads. So are arguments that do not decode, an `AiError` (`ToolParameterValidationError`), not `InvalidInput`: neither `authorize` nor the handler ran.
 - A turn's tool calls, the approved calls of an answering turn included, run concurrently unless `generateText` is given a `concurrency`. A service they share must tolerate it: [assistant/src/tasks/store.ts](../examples/assistant/src/tasks/store.ts) locks each change.
 - Arguments the input does not declare are dropped, where HTTP and a CLI refuse them ([guarantees.md](guarantees.md#wire-behavior)): a misspelled optional argument is ignored silently.
-- Beside other tools, merge natively and provide every handler layer: `Toolkit.merge(toolkit, others)` with `Layer.mergeAll(layer, othersHandlers)`.
 - **A model loop behind a route.** Yield `toolkit` and the model in the implementation's builder, `Action.implement(Ask, Effect.map(toolkit, (tools) => (input) => ...))`: what the handler itself yields is owed per request. Provide `layer` to the route's layer, `ActionHttp.layer(Http, ask).pipe(Layer.provide(layer))`, not in the handler, so the tools share the routes' build ([Action-in-process.md](Action-in-process.md#share-one-build-across-servers)). A tool call runs as the request's caller, unless the handler provides another around it. Keep each caller's `Chat` in a service between requests ([kitchen-sink/src/assistant/conversations.ts](../examples/kitchen-sink/src/assistant/conversations.ts)), and answer an approval in a later one: [kitchen-sink/src/assistant/handlers.ts](../examples/kitchen-sink/src/assistant/handlers.ts), with a scripted model in [demo-model.ts](../examples/kitchen-sink/src/assistant/demo-model.ts), which the entrypoint provides through [kitchen-sink/src/memory.ts](../examples/kitchen-sink/src/memory.ts), and tested over HTTP in [kitchen-sink/test/assistant/assistant.test.ts](../examples/kitchen-sink/test/assistant/assistant.test.ts). Name the files as it does, the route's contract `Assistant.ts` and the loop `handlers.ts`, from the first one written: a lowercase `assistant.ts` beside the contract fails with TS1149 ([setup-failures.md](setup-failures.md)).
 - **The real model comes later?** Provide a scripted one from the entrypoint until then, as the kitchen-sink does. Reading the model with `Effect.serviceOption` hides the requirement: the server builds without one and every request fails.
 
+### Customize the native tools
+
+Give a generated tool a title for your approval display with native `Tool` and `Toolkit` from
+`effect/ai`: [assistant/src/toolkit.ts](../examples/assistant/src/toolkit.ts). The host reads the
+title when printing approval requests in [agent.ts](../examples/assistant/src/agent.ts).
+
+```ts
+const actions = ActionToolkit.make([tasks, identity]);
+const toolkit = Toolkit.merge(
+  actions.toolkit,
+  Toolkit.make(actions.toolkit.tools.addTask.annotate(Tool.Title, "Add a task")),
+);
+const layer = actions.layer;
+```
+
+- `Toolkit.merge` keeps the later definition on a name collision. Put the customized one last;
+  keep names distinct when adding unrelated tools.
+- `annotate` and `annotateMerge` return a new definition preserving the generated tool's handler
+  identity and approval rule. Keep the original `layer`. Recreating it with `Tool.make` under
+  the same name does not preserve that binding.
+- To add other native tools, use `Toolkit.merge(toolkit, others)` and provide both handler layers
+  with `Layer.mergeAll(layer, othersHandlers)`.
+
 ### Call a tool by hand
 
 `yield* toolkit` gives `tools.handle(name, arguments)`, which takes the JSON a model sends, an
@@ -116,4 +138,5 @@ chat
 - **Continue on `toolCalls`, never on `toolResults`.** The answering turn's response holds the approved call's result, no tool call, and the model's reply to it: a loop that continues while a response has tool results asks the model again and loses that reply.
 - **If a turn fails or is interrupted once an approved call has started**, the model failing or the client going away, the call may have run, and may run again. A failed `generateText` records nothing of its turn, so the same answer sent again runs the call again. A failed `streamText` records its prompt and the parts it streamed: a call that returned has its result recorded, but one that failed or was cut off while running leaves its answer without a result, which the next turn acts on unasked; `openApprovals` leaves that request out, as another answer would run the call twice. End the conversation where a turn does not succeed, or record an answer in your own store before its turn, and say in the error that an approved call may have run. Run one turn of a conversation at a time, and look it up again once the lock is held, so a turn that waited does not run on a conversation just ended: [kitchen-sink/src/assistant/conversations.ts](../examples/kitchen-sink/src/assistant/conversations.ts) does both.
 - **Show the person what is asked.** A request names its call by `toolCallId`; that call, in `response.toolCalls`, holds the model's `params`, typed `unknown`. Show them as JSON, as [assistant/src/agent.ts](../examples/assistant/src/agent.ts) does, which joins the two; decode them with `Schema.toCodecJson(AddTask.input)`, the tool's parameters, only where you read a field.
+- **If repeating a write would create an unwanted additional effect, retries need application-owned deduplication.** Keep the same operation key across attempts, as in [notes-service's creation example](../examples/notes-service/README.md#retry-a-creation). Approval history alone does not make the mutation and its result record atomic.
 - **Only the person asked answers.** A `tool-approval-response` whose `approvalId` matches a request in the history without a result is acted on, as the turn's caller, an answered one included: take an `approvalId` only from that caller, among those `openApprovals` lists, and keep the `Chat` where its owner alone reaches it.

package/docs/Authentication-failures.md

@@ -64,7 +64,7 @@ Tasks: [Authentication.md](Authentication.md),
   too ([ActionMcp.md](ActionMcp.md#protect-tools)).
 - A verifier's declared error arrives as 422: the error states no `httpApiStatus`. Give it the
   status it means, such as `{ httpApiStatus: 503 }`.
-- `ActionMcp.client` fails with an `McpCallError`, not a typed error, when the verifier fails
+- `ActionMcp.client` fails with an `McpCallError` whose `reason` is a `StatusError`, not a typed error, when the verifier fails
   with an error its descriptor declares: over MCP that failure is the endpoint's HTTP answer,
   before any tool runs. Pass the endpoint's descriptor as the client's `authentication`.
 - A route's `Cache-Control` is replaced by `no-store`: only a route's own answer keeps its

package/docs/CONTEXT.md

@@ -38,7 +38,8 @@ page.
 
 The parts of the layout every example uses: [examples/README.md](../examples/README.md#how-they-are-laid-out).
 
-- **Domain**: one subject of the application, such as notes or identity, and the folder holding everything about it. A folder is never a mechanism, such as `contracts/` or `handlers/`.
+- **Domain**: one subject of the application, such as notes or identity, and the folder holding everything about it. A folder is never a mechanism, such as `contracts/` or `handlers/`, but **Platform**.
+- **Platform**: `platform/`, the one folder named for a mechanism: the adapters, each a service's Layer over a technology, such as a file or an upstream HTTP API. A domain imports none of them; an entrypoint provides them.
 - **Contract file**: the PascalCase file of a domain, such as `notes/Notes.ts`: its schemas, errors and actions, and the identity and descriptor it declares. It imports no server code.
 - **Routes**: `routes.ts`, the host's surfaces as one Layer. A route, singular, is one HTTP route.
 - **Entrypoint**: a file that runs the application one way, such as `server.ts`, `stdio.ts` or `cli.ts`: the **composition root**, the one place that chooses the services, the platform and, on a local surface, the caller.

package/docs/README.md

@@ -10,10 +10,10 @@ same schemas, handler and authorization.
 **Arriving with an error?** Search the `*-failures.md` pages for a fragment of its message
 first (step 5), before the examples and the pages.
 
-1. **Open one page per tool call, with your file-reading tool.** A page fits one read. Several
-   in one call, however many commands it runs, can be cut by its output limit, with no mark or
-   with one that understates what is lost. If an output says it was truncated, read that page
-   again alone.
+1. **Open one page per tool call, with your file-reading tool.** Pages are kept small to reduce
+   truncation. Several in one call, however many commands it runs, can be cut by its output
+   limit, with no mark or with one that understates what is lost. If an output says it was
+   truncated, read that page again alone.
 2. **Start from the example closest to what you are building** ([Examples](#examples)). Its
    README has a layout tree and a "Where to look" table naming the file for each thing. Copy its
    layout and idioms: the examples are the reference for how code is written. An example shows

package/docs/Testing.md

@@ -126,7 +126,9 @@ the endpoint serves, such as `implementation.actions`. Its failures:
 [ActionMcp-failures.md](ActionMcp-failures.md).
 
 A method fails with the action's declared errors and the built-in ones as decoded values, and with
-`McpCallError` for any other answer, a result without its structured content included;
+`McpCallError` for any other answer: its `reason` says which, `StatusError`, `ProtocolError`,
+`NoReply`, `UndeclaredError` or `NoStructuredContent`, with what the endpoint sent, so a test
+asserts on `reason` and `Effect.catchReason("McpCallError", "StatusError", ...)` recovers one;
 structured content that does not decode as the success is a `SchemaError`, and a request that
 fails Effect's `HttpClientError`. Only a tool's result carries the action's own errors: an HTTP
 answer other than 200 decodes as a refusal, or, given the endpoint's `authentication`, as an error

package/examples/README.md

@@ -38,22 +38,30 @@ the parts of it that it needs:
 ├── src/
 │   ├── <domain>/
 │   │   ├── <Domain>.ts    the contract: schemas, errors, actions
-│   │   ├── <service>.ts   a service and its Layer
+│   │   ├── <service>.ts   a service, its constructor and any in-memory Layer
 │   │   └── handlers.ts    the implementation: contract to service
+│   ├── platform/          a service's Layer over a database, a file or an upstream API
 │   ├── Api.ts, Rpc.ts     the bindings, where a surface has one
 │   ├── routes.ts          the host's remote surfaces as Layers, where it serves any
 │   └── server.ts …        one entrypoint per way of running it
 └── test/
     ├── <domain>/          what the domain does
+    ├── platform/          an adapter, against a stand-in for what it reaches
     └── 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.
+  `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

package/examples/assistant/README.md

@@ -38,7 +38,7 @@ replace all three before relying on any of it.
 src/
 ├── tasks/
 │   ├── Tasks.ts         contract: schemas, an error, four actions
-│   ├── store.ts         TaskStore and its Layers: memory, and a JSON file
+│   ├── store.ts         TaskStore, its constructor and its memory Layer
 │   └── handlers.ts      Action.implement: contract to store
 ├── identity/
 │   ├── Identity.ts      contract: CurrentCaller, a Member or the Operator; whoAmI
@@ -46,13 +46,16 @@ src/
 │   ├── authorize.ts     the one authorization rule, built from Permissions
 │   ├── members.ts       the demo team
 │   └── handlers.ts
+├── platform/
+│   └── tasks-file.ts    DEMO ONLY: TaskStore's Layer over a JSON file
 ├── toolkit.ts           the implementations as a Toolkit, and which calls need approval
 ├── commands.ts          the implementations as commands, and each command's syntax
 ├── scripted.ts          a model that needs no API key
 ├── agent.ts             entrypoint: a model calling the tools, as a member
 └── cli.ts               entrypoint: the commands, as the operator
 test/
-├── tasks/               the implementation in process, with Action.client; the file store
+├── tasks/               the implementation in process, with Action.client
+├── platform/            the file store, on a file of the test's own
 ├── identity/            the authorizer: a caller per call, the permission store once
 ├── toolkit.test.ts      a tool call, approvals, an approved call still authorized
 └── commands.test.ts     the commands run in memory: syntax and output
@@ -72,21 +75,22 @@ test/
 
 ## Where to look
 
-| To see                                                               | Read                               |
-| -------------------------------------------------------------------- | ---------------------------------- |
-| Implementations as a native Effect AI `Toolkit`                      | `src/toolkit.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/tasks/store.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, chosen by the entrypoint                | `src/tasks/store.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/tasks/store.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`            |
+| 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, chosen by the entrypoint                | `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`                            |

package/examples/assistant/src/agent.ts

@@ -1,11 +1,11 @@
 import { NodeRuntime, NodeServices } from "@effect/platform-node";
-import { Console, Effect, Layer } from "effect";
-import { Chat, type LanguageModel, type Prompt } from "effect/ai";
+import { Console, Context, Effect, Layer } from "effect";
+import { Chat, type LanguageModel, type Prompt, Tool } 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 { TaskStore } from "./tasks/store.js";
+import { tasksFile } from "./platform/tasks-file.js";
 import { actingFor, layer, toolkit } from "./toolkit.js";
 
 // Entrypoint: `node --import tsx examples/assistant/src/agent.ts`.
@@ -28,9 +28,13 @@ const report = (member: Member) => (response: Response) => {
       ...response.toolResults.map(
         ({ name, encodedResult }) => `  ${name} -> ${JSON.stringify(encodedResult)}`,
       ),
-      ...response.toolCalls.flatMap(({ id, name, params }) =>
-        waiting.includes(id) ? [`  ${name} ${JSON.stringify(params)} waits for approval`] : [],
-      ),
+      ...response.toolCalls.flatMap(({ id, name, params }) => {
+        const title = Context.getOrElse(toolkit.tools[name].annotations, Tool.Title, () => name);
+
+        return waiting.includes(id)
+          ? [`  ${title} ${JSON.stringify(params)} waits for approval`]
+          : [];
+      }),
       ...(response.text === "" ? [] : [`  "${response.text}"`]),
     ].join("\n"),
   );
@@ -86,7 +90,7 @@ conversations.pipe(
   // 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. Never a caller.
-  Effect.provide(layer.pipe(Layer.provide([TaskStore.layerFile, Permissions.layerMemory]))),
+  Effect.provide(layer.pipe(Layer.provide([tasksFile, Permissions.layerMemory]))),
   Effect.provide(NodeServices.layer),
   NodeRuntime.runMain,
 );

package/examples/assistant/src/cli.ts

@@ -6,7 +6,7 @@ import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
 import { commands } from "./commands.js";
 import { CurrentCaller, type Operator } from "./identity/Identity.js";
 import { Permissions } from "./identity/permissions.js";
-import { TaskStore } from "./tasks/store.js";
+import { tasksFile } from "./platform/tasks-file.js";
 
 // Entrypoint: `node --import tsx examples/assistant/src/cli.ts list-tasks`.
 // The operator's own tool. No credential arrives at a terminal, so this host names the caller
@@ -17,7 +17,7 @@ const operator: Operator = { kind: "operator", id: userInfo().username };
 const assistant = commands.pipe(
   // Services go on the command, so they are built when an action runs: `--help` and a
   // mistyped flag never open the tasks file.
-  Command.provide(Layer.mergeAll(TaskStore.layerFile, Permissions.layerMemory)),
+  Command.provide(Layer.mergeAll(tasksFile, Permissions.layerMemory)),
   Command.provideSync(CurrentCaller, operator),
 );
 

package/examples/assistant/src/platform/tasks-file.ts

@@ -0,0 +1,38 @@
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Config, Effect, FileSystem, Layer, Schema } from "effect";
+import { TaskStore } from "../tasks/store.js";
+import { Task } from "../tasks/Tasks.js";
+
+const TasksFile = Schema.fromJsonString(Schema.Array(Task));
+
+// DEMO ONLY: one JSON file, rewritten on every change. Changes are serialized within a
+// process, by the store's lock, but nothing locks the file across processes: the agent and a
+// command writing at once lose a task. A real application uses a database. The agent and the
+// commands are separate processes: this file is what lets one see what the other wrote.
+export const tasksFile = Layer.effect(
+  TaskStore,
+  Effect.gen(function* () {
+    const files = yield* FileSystem.FileSystem;
+
+    const path = yield* Config.String("ASSISTANT_TASKS").pipe(
+      Config.withDefault(join(tmpdir(), "assistant-tasks.json")),
+    );
+
+    const load = files.readFileString(path).pipe(
+      Effect.catchReason("PlatformError", "NotFound", () => Effect.succeed("[]")),
+      Effect.flatMap(Schema.decodeEffect(TasksFile)),
+      Effect.orDie,
+    );
+
+    const save = (tasks: ReadonlyArray<Task>) =>
+      Schema.encodeEffect(TasksFile)(tasks).pipe(
+        Effect.flatMap((json) => files.writeFileString(path, json)),
+        // A log, not a result: a command sends its handler's logs to stderr.
+        Effect.tap(() => Effect.log(`Saved ${tasks.length} tasks to ${path}.`)),
+        Effect.orDie,
+      );
+
+    return TaskStore.make(load, save);
+  }),
+);

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

@@ -1,14 +1,10 @@
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { Config, Context, Effect, FileSystem, Layer, Ref, Schema, Semaphore } from "effect";
+import { Context, Effect, Layer, Ref, Semaphore } from "effect";
 import { Task, TaskNotFound } from "./Tasks.js";
 
 type TaskList = ReadonlyArray<Task>;
 
-const TasksFile = Schema.fromJsonString(Schema.Array(Task));
-
-// Every method reads the whole list, and a change writes it back: the two layers below differ
-// only in where the list is kept.
+// Every method reads the whole list, and a change writes it back: a layer says only where the
+// list is kept, in memory below or in a file (src/platform/tasks-file.ts).
 const make = (load: Effect.Effect<TaskList>, save: (tasks: TaskList) => Effect.Effect<void>) => {
   // A model's tool calls in one turn run concurrently. Two changes reading the list before
   // either writes it would lose one, so a change holds this lock from its read to its write.
@@ -55,6 +51,9 @@ export class TaskStore extends Context.Service<
     readonly annotate: (id: string, notes: string) => Effect.Effect<Task, TaskNotFound>;
   }
 >()("assistant/TaskStore") {
+  /** The store over a list kept by `load` and `save`, each change serialized. */
+  static readonly make = make;
+
   /** Memory, lost with the process: what a test provides. */
   static readonly layerMemory = Layer.effect(
     TaskStore,
@@ -62,35 +61,4 @@ export class TaskStore extends Context.Service<
       make(Ref.get(tasks), (next) => Ref.set(tasks, next)),
     ),
   );
-
-  // DEMO ONLY: one JSON file, rewritten on every change. Changes are serialized within a
-  // process, by the lock above, but nothing locks the file across processes: the agent and a
-  // command writing at once lose a task. A real application uses a database. The agent and the
-  // commands are separate processes: this file is what lets one see what the other wrote.
-  static readonly layerFile = Layer.effect(
-    TaskStore,
-    Effect.gen(function* () {
-      const files = yield* FileSystem.FileSystem;
-
-      const path = yield* Config.String("ASSISTANT_TASKS").pipe(
-        Config.withDefault(join(tmpdir(), "assistant-tasks.json")),
-      );
-
-      const load = files.readFileString(path).pipe(
-        Effect.catchReason("PlatformError", "NotFound", () => Effect.succeed("[]")),
-        Effect.flatMap(Schema.decodeEffect(TasksFile)),
-        Effect.orDie,
-      );
-
-      const save = (tasks: TaskList) =>
-        Schema.encodeEffect(TasksFile)(tasks).pipe(
-          Effect.flatMap((json) => files.writeFileString(path, json)),
-          // A log, not a result: a command sends its handler's logs to stderr.
-          Effect.tap(() => Effect.log(`Saved ${tasks.length} tasks to ${path}.`)),
-          Effect.orDie,
-        );
-
-      return make(load, save);
-    }),
-  );
 }

package/examples/assistant/src/toolkit.ts

@@ -1,4 +1,5 @@
 import { Effect, Option } from "effect";
+import { Tool, Toolkit } from "effect/ai";
 import * as ActionToolkit from "@gjermundgaraba/effect-actions/ActionToolkit";
 import { identity } from "./identity/handlers.js";
 import { CurrentCaller, type Member } from "./identity/Identity.js";
@@ -7,7 +8,7 @@ import { tasks } from "./tasks/handlers.js";
 // The implementations as a native Effect AI Toolkit: a tool per action, run in this process.
 // `toolkit` goes to `LanguageModel.generateText`; `layer` holds the handlers, and requires the
 // startup services their builders read. Neither holds a caller.
-export const { toolkit, layer } = ActionToolkit.make([tasks, identity], {
+const actions = ActionToolkit.make([tasks, identity], {
   // One rule over every call a model makes, asked before the call runs. A read runs at once. A
   // write waits for a person to approve it, except a task the caller adds to their own list:
   // `call.name` narrows `call.input` to that action's. Without a caller, it asks.
@@ -23,6 +24,15 @@ export const { toolkit, layer } = ActionToolkit.make([tasks, identity], {
     ),
 });
 
+// A title for this assistant's approval display. The model still calls the tool `addTask`.
+// The later definition wins; annotating the generated tool keeps its handler and approval rule.
+export const toolkit = Toolkit.merge(
+  actions.toolkit,
+  Toolkit.make(actions.toolkit.tools.addTask.annotate(Tool.Title, "Add a task")),
+);
+
+export const layer = actions.layer;
+
 // Who a turn runs as is provided around that turn, never to `layer`: one toolkit serves every
 // member. This is how this example names a model's caller, and it takes a `Member`. The tools
 // themselves accept any `CurrentCaller`, so keeping the operator away from a model is this

package/examples/assistant/test/{tasks/store.test.ts → platform/tasks-file.test.ts}

@@ -1,6 +1,7 @@
 import { NodeServices } from "@effect/platform-node";
 import { describe, expect, it } from "@effect/vitest";
 import { ConfigProvider, Effect, FileSystem, Layer, Path } from "effect";
+import { tasksFile } from "../../src/platform/tasks-file.js";
 import { TaskStore } from "../../src/tasks/store.js";
 
 // The file store, on a file of the test's own: `ASSISTANT_TASKS` is set through a
@@ -13,7 +14,7 @@ const fileStore = Effect.gen(function* () {
   const tasks = path.join(directory, "tasks.json");
   const config = ConfigProvider.fromUnknown({ ASSISTANT_TASKS: tasks });
 
-  return TaskStore.layerFile.pipe(Layer.provide(ConfigProvider.layer(config)));
+  return tasksFile.pipe(Layer.provide(ConfigProvider.layer(config)));
 });
 
 describe("the file store", () => {

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

@@ -3,6 +3,7 @@ import { Config, Effect, flow, Option } from "effect";
 import { Command } from "effect/cli";
 import { HttpClient, HttpClientRequest } from "effect/http";
 import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
 import { Http } from "./Api.js";
 
 // Entrypoint: `node --import tsx examples/kitchen-sink/src/cli.ts list-issues`.
@@ -41,27 +42,24 @@ const tracker = ActionCli.remote(Http, {
         `${attachment.name}: ${image.mimeType}, ${image.data.byteLength} bytes`,
     },
   },
-}).pipe(
-  // The connection is read from `Config` when a command runs, so `--help` needs none of it.
-  // It is provided on this command, so it reaches these commands' requests and no others.
-  // The token and the workspace are optional: `tracker get-status` is public and needs neither,
-  // and any other command without them gets the server's 401.
-  Command.provideEffect(
-    HttpClient.HttpClient,
-    Effect.gen(function* () {
-      const url = yield* Config.String("TRACKER_URL").pipe(
-        Config.withDefault("http://127.0.0.1:3000"),
-      );
+  // The connection, read from `Config` when a command runs, so `--help` needs none of it. It is
+  // these commands' client, so it reaches their requests and no others. The token and the
+  // workspace are optional: `tracker get-status` is public and needs neither, and any other
+  // command without them gets the server's 401.
+  client: Effect.gen(function* () {
+    const baseUrl = yield* Config.String("TRACKER_URL").pipe(
+      Config.withDefault("http://127.0.0.1:3000"),
+    );
 
-      const token = yield* Config.option(Config.Redacted("TRACKER_TOKEN"));
-      const workspace = yield* Config.option(Config.String("TRACKER_WORKSPACE"));
+    const token = yield* Config.option(Config.Redacted("TRACKER_TOKEN"));
+    const workspace = yield* Config.option(Config.String("TRACKER_WORKSPACE"));
 
-      const unchanged = (request: HttpClientRequest.HttpClientRequest) => request;
+    const unchanged = (request: HttpClientRequest.HttpClientRequest) => request;
 
-      return HttpClient.mapRequest(
-        yield* HttpClient.HttpClient,
+    return yield* ActionHttp.client(Http, {
+      baseUrl,
+      transformClient: HttpClient.mapRequest(
         flow(
-          HttpClientRequest.prependUrl(url),
           Option.match(token, {
             onNone: () => unchanged,
             onSome: (value) => HttpClientRequest.bearerToken(value),
@@ -71,10 +69,10 @@ const tracker = ActionCli.remote(Http, {
             onSome: (slug) => HttpClientRequest.setHeader("x-workspace", slug),
           }),
         ),
-      );
-    }),
-  ),
-);
+      ),
+    });
+  }),
+});
 
 // A result is printed on stdout. A failure goes to stderr, under an `ERROR` heading, as the JSON
 // HTTP sends, such as `{"_tag":"IssueNotFound","id":"ACME-9"}`, and the command exits 1.

package/examples/mcp-tools/README.md

@@ -91,9 +91,11 @@ and no `name` or `arguments`.
 src/
 ├── printers/
 │   ├── Printers.ts    contract: the printer, the one declared error, the five tools
-│   ├── farm.ts        PrintFarm, the upstream API as a service, and its Layer
-│   ├── fake.ts        DEMO ONLY: the farm's API answered in memory, as an HttpClient
+│   ├── farm.ts        PrintFarm, the upstream as a service: what the handlers call
 │   └── handlers.ts    Action.implement: tool to service
+├── platform/
+│   ├── print-farm.ts  printFarm, PrintFarm's Layer over the farm's HTTP API
+│   └── fake-farm.ts   DEMO ONLY: the farm's API answered in memory, as an HttpClient
 ├── instructions.ts    the server's name, version and its instructions for the model
 ├── routes.ts          the HTTP surface: /mcp and /healthz
 ├── server.ts          entrypoint: MCP over HTTP
@@ -103,13 +105,14 @@ test/
 └── routes.test.ts     over MCP in memory, with Testing.layer
 ```
 
-- **The upstream is a service, built once.** `PrintFarm.layer` reads its URL and credentials
-  from `Config`, takes whichever `HttpClient` the entrypoint provides, and signs in while it is
-  built. The handlers get it already signed in and only delegate: `handlers.ts` maps each tool
-  onto a method of `farm.ts`, which knows nothing of tools, so a second caller of the farm, a
-  job or another surface, takes the service alone.
+- **The upstream is a service, built once.** `farm.ts` declares what the handlers need of the
+  farm, and `platform/print-farm.ts` is its Layer over the farm's HTTP API: it reads its URL and
+  credentials from `Config`, takes whichever `HttpClient` the entrypoint provides, and signs in
+  while it is built. The handlers get it already signed in and only delegate: `handlers.ts`
+  maps each tool onto a method of `PrintFarm`, which knows nothing of tools or HTTP, so a second
+  caller of the farm, a job or another surface, takes the service alone.
 - **One declared error, mapped in one place.** A refusal, an unreachable farm, an answer of
-  another shape and one that never comes each leave `farm.ts` as a `PrintFarmError` with a
+  another shape and one that never comes each leave `platform/print-farm.ts` as a `PrintFarmError` with a
   message a model can act on. No handler catches anything.
 - **What a model sends is checked by the contract.** A printer id becomes part of the farm's
   URL, so its schema admits only what is safe there, and anything else is refused before a
@@ -128,14 +131,14 @@ test/
 | One declared error shared by every tool                         | `src/printers/Printers.ts`       |
 | An input a model cannot use to reach another URL                | `src/printers/Printers.ts`       |
 | A tool answering an image beside other fields                   | `src/printers/Printers.ts`       |
-| An upstream client reading `Config`, signing in once            | `src/printers/farm.ts`           |
-| An upstream's failures mapped to the declared error             | `src/printers/farm.ts`           |
+| An upstream client reading `Config`, signing in once            | `src/platform/print-farm.ts`     |
+| An upstream's failures mapped to the declared error             | `src/platform/print-farm.ts`     |
 | A builder yielding a service, and handlers that only delegate   | `src/printers/handlers.ts`       |
 | Server `instructions`, shared by both transports                | `src/instructions.ts`            |
 | Allowed origins from `Config`, their CORS, and `/healthz`       | `src/routes.ts`                  |
 | A request body limit, and where an unauthenticated server binds | `src/server.ts`                  |
 | A stdio server whose logs go to stderr                          | `src/stdio.ts`                   |
-| A fake upstream provided as a Layer, to a test or an entrypoint | `src/printers/fake.ts`           |
+| A fake upstream provided as a Layer, to a test or an entrypoint | `src/platform/fake-farm.ts`      |
 | Testing tools and each upstream failure's message in process    | `test/printers/printers.test.ts` |
 | Testing listed hints, an image and the origin check in memory   | `test/routes.test.ts`            |
 | Testing CORS for one configured origin and for several          | `test/routes.test.ts`            |

package/examples/mcp-tools/src/{printers/fake.ts → platform/fake-farm.ts}

@@ -1,10 +1,10 @@
 import { Buffer } from "node:buffer";
 import { Effect, Layer, Option, Schema } from "effect";
 import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/http";
-import type { Printer } from "./Printers.js";
+import type { Printer } from "../printers/Printers.js";
 
 // DEMO ONLY: the farm's HTTP API answered in memory, so the example and its tests run without
-// a farm. It is an `HttpClient`, so `PrintFarm.layer` sends it the requests it would send over
+// a farm. It is an `HttpClient`, so `printFarm` sends it the requests it would send over
 // the network. A real application has no such file: its entrypoints provide a real client,
 // `FetchHttpClient.layer` from `effect/http`.