@gjermundgaraba/effect-actions 0.16.0 → 0.17.0

package/dist/mcp/client.mjs

@@ -1,8 +1,10 @@
+import { Anyone } from "../contract/caller.mjs";
 import { Refusal } from "../contract/errors.mjs";
-import { Anyone, assertOnce, projectedErrors } from "../contract/rules.mjs";
+import { assertOnce } from "../contract/names.mjs";
+import { projectedErrors } from "../contract/declared.mjs";
 import { checked } from "../contract/call.mjs";
 import { defaultPath, httpProtocol, liftOf, unliftedFrom } from "./protocol.mjs";
-import { Effect, Option, Predicate, Schema, identity } from "effect";
+import { Effect, Match, Option, Predicate, Schema, identity } from "effect";
 import { McpSchema } from "effect/ai";
 import { HttpClient, HttpClientRequest } from "effect/http";
 import { Sse } from "effect/encoding";
@@ -42,14 +44,56 @@ const statelessRequest = (method, params) => {
 		}
 	};
 };
+/** The endpoint answered with an HTTP status other than 200, and a body no declared error decodes. */
+var StatusError = class extends Schema.TaggedError()("StatusError", {
+	status: Schema.Int,
+	body: Schema.String
+}) {};
 /**
-* An answer a client method cannot read as the action's success or a declared error, such as
-* the native server's message for invalid arguments or an unknown tool, or a result without
-* its structured content. Its message holds the answer. Structured content that does not
-* decode as the success is a `SchemaError` instead, and a request that fails an
-* `HttpClientError`.
+* The endpoint answered with a JSON-RPC error, such as the native server's for invalid arguments
+* or an unknown tool.
 */
-var McpCallError = class extends Schema.TaggedError()("McpCallError", { message: Schema.String }) {};
+var ProtocolError = class extends Schema.TaggedError()("ProtocolError", {
+	code: Schema.Finite,
+	message: Schema.String
+}) {};
+/** The endpoint answered 200 without a JSON-RPC reply to read, as JSON or as an event stream. */
+var NoReply = class extends Schema.TaggedError()("NoReply", { body: Schema.String }) {};
+/** The tool returned an error whose text decodes as none of the action's declared errors. */
+var UndeclaredError = class extends Schema.TaggedError()("UndeclaredError", { text: Schema.String }) {};
+/** The tool returned a result without the structured content its action's success needs. */
+var NoStructuredContent = class extends Schema.TaggedError()("NoStructuredContent", { body: Schema.String }) {};
+const Reason = Schema.Union([
+	StatusError,
+	ProtocolError,
+	NoReply,
+	UndeclaredError,
+	NoStructuredContent
+]);
+const sentenceOf = Match.typeTags()({
+	StatusError: ({ status, body }) => `answered ${status}: ${body}`,
+	ProtocolError: ({ code, message }) => `failed with ${code}: ${message}`,
+	NoReply: ({ body }) => `had no reply: ${body}`,
+	UndeclaredError: ({ text }) => `returned an error: ${text}`,
+	NoStructuredContent: ({ body }) => `returned no structured content: ${body}`
+});
+/**
+* An answer a client method cannot read as the action's success or a declared error: `reason`
+* says which, with what the endpoint sent, so a caller branches on it with
+* `Effect.catchReason("McpCallError", "StatusError", ...)`. `message` names the tool and the
+* reason. Structured content that does not decode as the success is a `SchemaError` instead,
+* and a request that fails an `HttpClientError`.
+*/
+var McpCallError = class extends Schema.TaggedError()("McpCallError", {
+	tool: Schema.String,
+	reason: Reason,
+	message: Schema.String
+}) {};
+const callError = (tool, reason) => new McpCallError({
+	tool,
+	reason,
+	message: `MCP tools/call "${tool}" ${sentenceOf(reason)}`
+});
 const textOf = (block) => block?.type === "text" ? block.text : void 0;
 const ToolCallReply = Schema.Union([Schema.Struct({ result: McpSchema.CallToolResult }), Schema.Struct({ error: Schema.Struct({
 	code: Schema.Finite,
@@ -67,7 +111,6 @@ const replyOf = (response, text) => {
 const failWith = (errors, text, otherwise) => Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.toCodecJson(Schema.Union(errors))))(text).pipe(Effect.mapError(() => otherwise), Effect.flatMap(Effect.fail));
 const callTool = (client, url, action, lift, refusedWith, input) => {
 	const { name } = action;
-	const other = (answer) => new McpCallError({ message: `MCP tools/call "${name}" ${answer}` });
 	return Effect.gen(function* () {
 		const encoded = yield* Schema.encodeEffect(Schema.toCodecJson(action.input))(input);
 		const response = yield* client.execute(request("tools/call", {
@@ -75,19 +118,19 @@ const callTool = (client, url, action, lift, refusedWith, input) => {
 			arguments: encoded
 		}, { url }));
 		const text = yield* response.text;
-		if (response.status !== 200) return yield* failWith(refusedWith, text, other(`answered ${response.status}: ${text}`));
+		if (response.status !== 200) return yield* failWith(refusedWith, text, callError(name, new StatusError({
+			status: response.status,
+			body: text
+		})));
 		const reply = replyOf(response, text);
-		if (Option.isNone(reply)) return yield* Effect.fail(other(`had no reply: ${text}`));
-		if ("error" in reply.value) {
-			const { code, message } = reply.value.error;
-			return yield* Effect.fail(other(`failed with ${code}: ${message}`));
-		}
+		if (Option.isNone(reply)) return yield* Effect.fail(callError(name, new NoReply({ body: text })));
+		if ("error" in reply.value) return yield* Effect.fail(callError(name, new ProtocolError(reply.value.error)));
 		const { result } = reply.value;
 		if (result.isError === true) {
 			const error = textOf(result.content.find((block) => block.type === "text")) ?? "";
-			return yield* failWith(projectedErrors(action), error, other(`returned an error: ${error}`));
+			return yield* failWith(projectedErrors(action), error, callError(name, new UndeclaredError({ text: error })));
 		}
-		if (result.structuredContent === void 0 && lift.rest !== void 0) return yield* Effect.fail(other(`returned no structured content: ${text}`));
+		if (result.structuredContent === void 0 && lift.rest !== void 0) return yield* Effect.fail(callError(name, new NoStructuredContent({ body: text })));
 		return yield* Schema.decodeUnknownEffect(Schema.toCodecJson(action.success))(unliftedFrom(lift, result));
 	});
 };

package/dist/mcp/protocol.mjs

@@ -1,4 +1,4 @@
-import { unsuspended } from "../contract/rules.mjs";
+import { unsuspended } from "../contract/ast.mjs";
 import { Media, isMarked, kindOf } from "../contract/media.mjs";
 import { Predicate, Schema, SchemaAST } from "effect";
 import { McpProtocol } from "effect/ai";

package/docs/Action.md

@@ -158,11 +158,25 @@ and the whole builder above [notes-service/src/notes/handlers.ts](../examples/no
 - **Pass the builder to `implement` itself.** Through `.pipe(...)` or a wrapper such as
   `Effect.withSpan(builder, name)`, an `Effect.fn` handler it returns takes an `any` input. A
   builder written apart returns its record `satisfies Action.Handlers<typeof actions>`.
-- **Leave a handler's `Effect.fn` unnamed**: each handler already runs in a span named after its
-  action, and its log lines carry `action.name` and `action.read_only`.
+- **Leave a handler's `Effect.fn` unnamed** unless you need handler-only timing: each action
+  already has a span ([Observe calls](#observe-calls)).
 - **Calling the function you passed to `implement` skips authorization.** Call the
   implementation through [`Action.client`](Action-in-process.md#call-actions-in-process).
 
+## Observe calls
+
+The span named after an action includes authorization, handler execution and call cleanup.
+Its exit reflects the final dispatch outcome; the span and its logs carry `action.name` and
+`action.read_only`.
+
+Transport credential verification, input decoding and response encoding run outside this span.
+A request rejected by verification or decoding has no action span; response encoding can fail
+after the action span succeeds.
+
+Add a named handler span to measure handler time alone. The named authorizer in
+[notes-service/src/identity/authorize.ts](../examples/notes-service/src/identity/authorize.ts)
+similarly measures authorization as a child of the action span.
+
 ## Authorize calls
 
 An implementation holding a protected action states `{ authorize }`: a function of the called
@@ -233,5 +247,5 @@ failure compiles. What each surface answers is in [guarantees.md](guarantees.md#
   or `Forbidden`. Passed on, it is this server's own refusal: a caller whose token is valid is
   told to sign in again. Map it to an error the action declares, or to a defect.
 - **Map that client's `HttpClientError` and `SchemaError` to one declared error a caller can
-  act on** ([mcp-tools/src/printers/farm.ts](../examples/mcp-tools/src/printers/farm.ts)). As
+  act on** ([mcp-tools/src/platform/print-farm.ts](../examples/mcp-tools/src/platform/print-farm.ts)). As
   defects, a model reads only a generic text.

package/docs/ActionCli.md

@@ -47,7 +47,7 @@ Pass implementations to `make`, and provide the services and the caller on the c
 
 ```ts
 const assistant = ActionCli.make([tasks, identity], { name: "assistant" }).pipe(
-  Command.provide(Layer.mergeAll(TaskStore.layerFile, Permissions.layerMemory)),
+  Command.provide(Layer.mergeAll(tasksFile, Permissions.layerMemory)),
   Command.provideSync(CurrentCaller, operator),
 );
 ```

package/docs/ActionMcp.md

@@ -21,7 +21,7 @@ Import `@gjermundgaraba/effect-actions/ActionMcp`.
 | `LayerHttpOptions`                    | Type of `layerHttp`'s options: `Options` and HTTP's own.    |
 | `client(actions, options?)`           | An Effect of a client calling each action's tool.           |
 | `request(method, params?, options?)`  | One MCP request, as the native `HttpClientRequest` to send. |
-| `McpCallError`                        | A client method's failure for an answer it cannot decode.   |
+| `McpCallError`                        | A client method's undecodable answer, by tagged `reason`.   |
 
 `implementations` is one implementation or a list.
 
@@ -140,7 +140,7 @@ tool's read-only hint, and the contract's `mcp` option holds its `title`, its ot
   field's `description`, annotated before the check: after a custom one it is lost too.
 - A declared error reaches the model as an `isError` result whose text is the error's JSON. Write
   its `message` for the model, which acts on it:
-  [mcp-tools/src/printers/farm.ts](../examples/mcp-tools/src/printers/farm.ts). Every other case:
+  [mcp-tools/src/platform/print-farm.ts](../examples/mcp-tools/src/platform/print-farm.ts). Every other case:
   [guarantees.md](guarantees.md#wire-behavior).
 - `actions` lists the tools, and only listed actions must suit MCP:
   [kitchen-sink/src/Actions.ts](../examples/kitchen-sink/src/Actions.ts). Leave out an action a

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", () => {