@gjermundgaraba/effect-actions 0.12.0 → 0.13.0

package/docs/setup.md

@@ -3,26 +3,28 @@
 Install the package, import its modules, write the smallest program, lay out an application and
 bundle a browser client.
 
-Read this page alone, in one tool call: pages read together are cut. When something fails,
-search [setup-failures.md](setup-failures.md). Reading order: [README.md](README.md).
+Read this page alone, in one tool call; if its output says it was truncated, read it again alone.
+When something fails, search [setup-failures.md](setup-failures.md). Reading order:
+[README.md](README.md).
 
 ## Install
 
 ```sh
-pnpm add @gjermundgaraba/effect-actions effect@~4.0.2
+pnpm add @gjermundgaraba/effect-actions effect@~4.0.3
 ```
 
 | Need                                | Add                                                              |
 | ----------------------------------- | ---------------------------------------------------------------- |
-| Node HTTP server, stdio host or CLI | `@effect/platform-node@~4.0.2`                                   |
-| Tests                               | `vitest@^5.0.3` and `@effect/vitest@~4.0.2`, as dev dependencies |
+| Node HTTP server, stdio host or CLI | `@effect/platform-node@~4.0.3`                                   |
+| Tests                               | `vitest@^5.0.3` and `@effect/vitest@~4.0.3`, as dev dependencies |
 | Type checking                       | `typescript@^7.0.2`, as a dev dependency                         |
+| Running a TypeScript entrypoint     | `tsx`, as a dev dependency: `node --import tsx <entrypoint>.ts`  |
 
 The `effect` peer admits only the patches of the Effect release the package is tested against:
 a minor release may change the unstable Effect modules the surfaces build on.
 
-Keep the tilde in `package.json`: `^4.0.2`, which npm writes for `effect@4.0.2`, admits a minor
-release outside the peer range. `npm install effect@~4.0.2` keeps it.
+Keep the tilde in `package.json`: `^4.0.3`, which npm writes for `effect@4.0.3`, admits a minor
+release outside the peer range. `npm install effect@~4.0.3` keeps it.
 
 Node `^22.12.0 || ^24.0.0 || >=26.0.0`: the package's `engines`, where its `devEngines` is
 what developing the library itself takes. TypeScript 7 or newer. ESM only. No example ships a

package/examples/kitchen-sink/README.md

@@ -36,10 +36,11 @@ node --import tsx examples/kitchen-sink/src/agent.ts                 # the assis
 vp test examples/kitchen-sink
 ```
 
-`PORT`, `ADMIN_PORT`, `PUBLIC_URL` and `MCP_ORIGIN` configure the server; `TRACKER_URL` points the
-CLI and the seed at it. `stdio.ts` is an MCP server for a local agent to start as a subprocess.
-`sdk.ts` and `browser.ts` are imported by client code, not run. The OpenAPI document is at
-`/api/v1/openapi.json`, Swagger UI at `/docs`, the MCP endpoint at `/mcp`, the socket at `/rpc`.
+`HOST`, `PORT`, `ADMIN_PORT`, `PUBLIC_URL` and `MCP_ORIGIN` configure the server; `TRACKER_URL`
+points the CLI and the seed at it. `stdio.ts` is an MCP server for a local agent to start as a
+subprocess. `sdk.ts` and `browser.ts` are imported by client code, not run. The OpenAPI
+document is at `/api/v1/openapi.json`, Swagger UI at `/docs`, the MCP endpoint at `/mcp`, the
+socket at `/rpc`.
 
 Everything is a demo: stores are memory, and the credentials are fixed strings. Replace both
 before deploying anything.

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

@@ -1,6 +1,7 @@
 import { Effect, Ref, Schema } from "effect";
 import { type Chat, LanguageModel, type Prompt } from "effect/ai";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as ActionToolkit from "@gjermundgaraba/effect-actions/ActionToolkit";
 import { CurrentMember } from "../identity/Identity.js";
 import { toolkit } from "../issues/assistant.js";
 import { AssistantFailed, Assistant } from "./Assistant.js";
@@ -15,7 +16,8 @@ const approvalsOf = (response: Response) =>
   response.content.filter((part) => part.type === "tool-approval-request");
 
 // What Effect gives the model as the result of a call that did not run: one its member denied,
-// or one in a reply the provider cut short.
+// or one in a reply the provider cut short. Left out of `ran` below, which lists the calls that
+// ran.
 const didNotRun = Schema.is(
   Schema.Struct({ type: Schema.Literals(["execution-denied", "execution-interrupted"]) }),
 );
@@ -23,45 +25,12 @@ const didNotRun = Schema.is(
 const callsToRead = (response: Response) =>
   response.toolCalls.length > 0 && approvalsOf(response).length === 0;
 
-// Every request of a conversation that an answer would still act on, with the call it would
-// run: read from the `Chat`'s history, by the rule Effect applies when an answer arrives. A
-// request is open until its call has a result, a denial's included, and its call is the last
-// in the history with that id. So a request an earlier answer left open is listed in every
-// turn until it is answered, and what is listed is what an approval runs.
-const openRequestsOf = ({ content: messages }: Prompt.Prompt) => {
-  const resolved = new Set(
-    messages.flatMap((message) =>
-      message.role === "tool"
-        ? message.content.flatMap((part) => (part.type === "tool-result" ? [part.id] : []))
-        : [],
-    ),
-  );
-
-  const said = messages.flatMap((message) => (message.role === "assistant" ? message.content : []));
-  const calls = said.filter((part) => part.type === "tool-call");
-
-  return said.flatMap((request) => {
-    if (request.type !== "tool-approval-request" || resolved.has(request.toolCallId)) return [];
-
-    const call = calls.findLast(({ id }) => id === request.toolCallId);
-
-    return call === undefined
-      ? []
-      : [
-          {
-            approvalId: request.approvalId,
-            tool: call.name,
-            arguments: JSON.stringify(call.params),
-          },
-        ];
-  });
-};
-
 // The model loop behind a route. The builder runs once, at startup, and yields what a turn is
 // built from: the tools with their handlers, the model, and where conversations are kept. A
 // handler yielding them would owe them per request, which no route provides. `CurrentMember`
 // is the one per-request service: each tool call of a turn runs as the request's caller,
-// through that tool's own `authorize`.
+// through that tool's own `authorize`. A conversation keeps its owner's id, never the member
+// itself, whose scopes would go stale between requests.
 export const assistant = Action.implement(
   Assistant,
   Effect.gen(function* () {
@@ -92,7 +61,17 @@ export const assistant = Action.implement(
           ran: results
             .filter(({ result }) => !didNotRun(result))
             .map(({ name, isFailure }) => ({ tool: name, failed: isFailure })),
-          waiting: openRequestsOf(yield* Ref.get(chat.history)),
+          // Every request of the conversation still waiting for an answer, with the call it
+          // would run, read from the `Chat`'s history by the rule Effect applies when an answer
+          // arrives: one an earlier answer left open is listed in every turn until answered.
+          // The arguments are shown as JSON, as the member approves them.
+          waiting: ActionToolkit.openApprovals(yield* Ref.get(chat.history)).map(
+            ({ approvalId, name, params }) => ({
+              approvalId,
+              tool: name,
+              arguments: JSON.stringify(params),
+            }),
+          ),
         };
       }).pipe(
         // The model is a startup service, given to each turn here.
@@ -126,7 +105,8 @@ export const assistant = Action.implement(
           : turn(conversation, prompt),
       // The answers start the next turn, in which an approved call runs, as this request's
       // caller, before the model is asked again. Only the member who was asked reaches the
-      // conversation, and an `approvalId` that matches no open request of it runs nothing.
+      // conversation, and a turn that fails ends it, so no answer is left without its result:
+      // an `approvalId` that `openApprovals` would not list runs nothing.
       answerAssistant: ({ conversation, answers }) =>
         turn(conversation, [
           {

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

@@ -43,8 +43,9 @@ const change = {
   caller: CurrentMember,
   error: IssueWriteErrors,
   // MCP hints, in MCP's names. They tell a model what a tool does and enforce nothing; the
-  // read-only hint is `readOnly` itself.
-  mcp: { destructiveHint: false, openWorldHint: false },
+  // read-only hint is `readOnly` itself. A write is destructive unless it only adds, as a
+  // comment does: closing is not stated `false`.
+  mcp: { openWorldHint: false },
 } as const;
 
 const Text = Schema.String.check(Schema.isMinLength(1));
@@ -95,6 +96,7 @@ export const CommentOnIssue = Action.make("commentOnIssue", {
   input: { id: Schema.String, text: Text },
   success: Issue,
   readOnly: false,
+  mcp: { ...change.mcp, destructiveHint: false },
 });
 
 export const CloseIssue = Action.make("closeIssue", {

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

@@ -10,7 +10,8 @@ import { RateLimited } from "./Issues.js";
 // as any declared error. The limiter is a service, so its counts are shared wherever it is
 // provided: memory.ts provides Effect's own, `RateLimiter.layer` over a store. `consume` counts
 // in a fixed window unless given `algorithm: "token-bucket"`: ten writes in each minute, so
-// twenty may pass across the boundary between two.
+// twenty may pass across the boundary between two. A strict limit, ten in any sixty seconds,
+// is a service of your own of the same shape, yielded here, never part of the issue store.
 export const writeLimit = Effect.gen(function* () {
   const limiter = yield* RateLimiter.RateLimiter;
 

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

@@ -19,6 +19,8 @@ const socket = rpc.pipe(
 
 const server = Layer.unwrap(
   Effect.gen(function* () {
+    // The loopback default serves this machine alone; HOST=0.0.0.0 lets others reach it.
+    const host = yield* Config.String("HOST").pipe(Config.withDefault("127.0.0.1"));
     const publicPort = yield* Config.Port("PORT").pipe(Config.withDefault(3000));
     const adminPort = yield* Config.Port("ADMIN_PORT").pipe(Config.withDefault(3001));
 
@@ -26,9 +28,7 @@ const server = Layer.unwrap(
 
     const listen = (port: number) =>
       NodeHttpServer.layer(createServer, {
-        // This machine alone. A server others reach reads its host from config:
-        // `Config.String("HOST").pipe(Config.withDefault("127.0.0.1"))`.
-        host: "127.0.0.1",
+        host,
         port,
         // A message on the WebSocket of `/rpc` is no request body, so the limit below does not
         // bound it: Node's WebSocket server reads one of up to 100 MiB whole unless told

package/examples/live-rpc/README.md

@@ -15,7 +15,7 @@ From the repository root, after `vp install` (from an installed package, see
 [Run one](../README.md#run-one)):
 
 ```sh
-node --import tsx examples/live-rpc/src/server.ts     # 127.0.0.1:3000, PORT to change
+node --import tsx examples/live-rpc/src/server.ts     # 127.0.0.1:3000, HOST and PORT to change
 node --import tsx examples/live-rpc/src/client.ts     # CHAT_URL to change, ws://127.0.0.1:3000/rpc
 
 vp test examples/live-rpc

package/examples/live-rpc/src/chat/Chat.ts

@@ -21,9 +21,11 @@ export class MessageNotFound extends Schema.TaggedError<MessageNotFound>()(
   { httpApiStatus: 404 },
 ) {}
 
+// A refusal carries what the caller sent and no more: who wrote the message is for the actions
+// that read it, under their own rule.
 export class NotAuthor extends Schema.TaggedError<NotAuthor>()(
   "NotAuthor",
-  { id: Schema.Int, author: Schema.String },
+  { id: Schema.Int },
   { httpApiStatus: 403 },
 ) {}
 

package/examples/live-rpc/src/chat/handlers.ts

@@ -16,8 +16,8 @@ export const rooms = Action.implement(
   }),
 );
 
-// The builder runs once, at startup: it is where a handler gets its services. The caller and
-// the room are read per call, inside each handler, because every message has its own.
+// The builder runs once, at startup: it is where a handler gets its startup services. The
+// caller and the room are read per call, inside each handler, because every message has its own.
 export const messages = Action.implement(
   Messages,
   Effect.gen(function* () {

package/examples/live-rpc/src/chat/store.ts

@@ -45,7 +45,7 @@ export class MessageStore extends Context.Service<
 
         if (message === undefined) return yield* new MessageNotFound({ id });
 
-        if (message.author !== author) return yield* new NotAuthor({ id, author: message.author });
+        if (message.author !== author) return yield* new NotAuthor({ id });
 
         rooms.set(name, { last, messages: messages.filter((kept) => kept !== message) });
       }),

package/examples/live-rpc/src/server.ts

@@ -20,14 +20,14 @@ const socket = rpc.pipe(
 
 const server = Layer.unwrap(
   Effect.gen(function* () {
+    // The loopback default serves this machine alone; HOST=0.0.0.0 lets others reach it.
+    const host = yield* Config.String("HOST").pipe(Config.withDefault("127.0.0.1"));
     const port = yield* Config.Port("PORT").pipe(Config.withDefault(3000));
 
     return HttpRouter.serve(socket).pipe(
       Layer.provide(
         NodeHttpServer.layer(createServer, {
-          // This machine alone. A server others reach reads its host from config:
-          // `Config.String("HOST").pipe(Config.withDefault("127.0.0.1"))`.
-          host: "127.0.0.1",
+          host,
           port,
           // A message on a WebSocket is no request body, so `HttpServerRequest.MaxBodySize`
           // does not bound it: Node's WebSocket server reads one of up to 100 MiB whole unless

package/examples/live-rpc/test/chat/chat.test.ts

@@ -42,7 +42,7 @@ describe("messages, in process", () => {
       const { id } = yield* client.postMessage({ text: "Oops." }).pipe(as("ada", "lobby"));
 
       expect(yield* Effect.flip(client.deleteMessage({ id }).pipe(as("grace", "lobby")))).toEqual(
-        new NotAuthor({ id, author: "ada" }),
+        new NotAuthor({ id }),
       );
 
       yield* client.deleteMessage({ id }).pipe(as("ada", "lobby"));

package/examples/mcp-tools/README.md

@@ -5,8 +5,10 @@ authentication of its own. It signs in to the farm once, with its own account, a
 reach it may call every tool, so it runs as a local subprocess of an agent or on a network only
 trusted clients are on.
 
-Start here if you are putting an existing API in front of a model. For tools that belong to the
-signed-in user, start from [notes-service](../notes-service/).
+Start here if you are putting an existing API in front of a model, then read
+[ActionMcp.md](../../docs/ActionMcp.md). For tools that need a token, its "Protect tools" shows
+the verifier, and [notes-service](../notes-service/) is a server whose tools belong to the
+signed-in user.
 
 ## Run it
 
@@ -28,7 +30,8 @@ vp test examples/mcp-tools
 
 The farm is a fake, answered in memory, so any URL, user and password work: replace it with a
 real HTTP client before deploying anything. `ALLOWED_ORIGINS` lists the browser origins the HTTP
-endpoint accepts and answers with CORS headers, comma-separated; `HOST` is the interface it listens on.
+endpoint accepts and answers with CORS headers, comma-separated; `HOST` is the interface it
+listens on.
 
 ## Connect a client
 
@@ -102,7 +105,9 @@ test/
 
 - **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.
+  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.
 - **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
   message a model can act on. No handler catches anything.

package/examples/mcp-tools/src/printers/Printers.ts

@@ -67,8 +67,8 @@ export const GetCameraSnapshot = Action.make("get_camera_snapshot", {
   mcp: { title: "Camera snapshot" },
 });
 
-// A write that adds something and removes nothing says so: MCP assumes a write is destructive
-// unless `destructiveHint` is false. A second call is refused, so it is not idempotent.
+// Destructive, MCP's default for a write: a print sets a machine to work and spends material,
+// which is more than adding a record. A second call is refused, so it is not idempotent.
 export const StartPrint = Action.make("start_print", {
   ...tool,
   description:
@@ -80,7 +80,7 @@ export const StartPrint = Action.make("start_print", {
   },
   success: Printer,
   readOnly: false,
-  mcp: { title: "Start a print", destructiveHint: false },
+  mcp: { title: "Start a print" },
 });
 
 // Idempotent: the same call again leaves the printer as the first left it.
@@ -95,7 +95,9 @@ export const SetPaused = Action.make("set_paused", {
   },
   success: Printer,
   readOnly: false,
-  mcp: { title: "Pause or resume a print", destructiveHint: false, idempotentHint: true },
+  // Destructive, MCP's default for a write: a pause interrupts a running print. Only a write
+  // that only adds, such as creating a record, says `destructiveHint: false`.
+  mcp: { title: "Pause or resume a print", idempotentHint: true },
 });
 
 // Destructive, which is MCP's default for a write, so no `destructiveHint` is stated.

package/examples/mcp-tools/src/server.ts

@@ -8,8 +8,9 @@ import { routes } from "./routes.js";
 
 // Entrypoint: `node --import tsx examples/mcp-tools/src/server.ts`, with FARM_URL, FARM_USER
 // and FARM_PASSWORD set. MCP over HTTP, for clients that connect to a URL.
-// Nothing here authenticates a caller, so where it listens is its access control: the loopback
-// interface by default, or a network only trusted clients are on.
+// These tools are public: no route asks for a token, so where the server listens is its access
+// control, the loopback interface by default or a network only trusted clients are on. Tools
+// that need a caller take a verifier, as docs/ActionMcp.md's "Protect tools" shows.
 const server = Layer.unwrap(
   Effect.gen(function* () {
     const host = yield* Config.String("HOST").pipe(Config.withDefault("127.0.0.1"));

package/examples/mcp-tools/test/routes.test.ts

@@ -79,11 +79,11 @@ describe("the tools, over MCP", () => {
         },
         {
           name: "start_print",
-          annotations: { title: "Start a print", ...hints(false, false, false) },
+          annotations: { title: "Start a print", ...hints(false, true, false) },
         },
         {
           name: "set_paused",
-          annotations: { title: "Pause or resume a print", ...hints(false, false, true) },
+          annotations: { title: "Pause or resume a print", ...hints(false, true, true) },
         },
         {
           name: "cancel_print",

package/examples/notes-service/README.md

@@ -23,6 +23,7 @@ node --import tsx examples/notes-service/src/cli.ts --help
 echo "First draft" | node --import tsx examples/notes-service/src/cli.ts create-note --title Plan
 node --import tsx examples/notes-service/src/cli.ts list-notes
 node --import tsx examples/notes-service/src/cli.ts export notes.md   # a command written by hand
+node --import tsx examples/notes-service/src/cli.ts import notes.md   # one importNotes call
 
 vp test examples/notes-service
 ```
@@ -36,8 +37,8 @@ codex mcp add notes --url http://127.0.0.1:3000/mcp --bearer-token-env-var NOTES
 
 `src/stdio.ts` is the other way in: a subprocess the host starts, with a store of its own.
 
-The server reads `PORT` (default 3000) and `PUBLIC_URL`, the address it tells OAuth clients it
-is at; the CLI reads `NOTES_URL` and `NOTES_TOKEN`. Change the port and set all three to match.
+The server reads `HOST` (default `127.0.0.1`), `PORT` (default 3000) and `PUBLIC_URL`, the
+address it tells OAuth clients it is at; the CLI reads `NOTES_URL` and `NOTES_TOKEN`. Change the port and set all three to match.
 Every command asks for `NOTES_TOKEN`, the public `get-status` included: without it a command
 prints one message on stderr saying to set it, and exits 1. `--help` needs none.
 
@@ -77,7 +78,8 @@ test/
   `contracts/` or `handlers/` folder.
 - **The PascalCase file is the contract.** `Notes.ts`, `Identity.ts`, `Status.ts` and `Api.ts`
   import no server code, so a browser or a CLI imports them. The lowercase files beside them run
-  on the server.
+  on the server, each named for its role, never the domain: `notes.ts` beside `Notes.ts` is one
+  file on a disk that ignores case (TS1149).
 - **One entrypoint per way of running it.** Each chooses its own implementations: `server.ts`
   picks the store and the HTTP server, `stdio.ts` names the local user, a test provides its own
   store. Nothing below an entrypoint knows which it got.
@@ -99,6 +101,7 @@ test/
 | The same actions over stdio, the host naming the caller       | `src/stdio.ts`                   |
 | A CLI derived from the binding: an argument, a field on stdin | `src/commands.ts`                |
 | A command written by hand beside the derived ones             | `src/commands.ts`                |
+| A bulk import as one action, its command reading a file       | `src/notes/`, `src/commands.ts`  |
 | The CLI's connection, read from config when a command runs    | `src/commands.ts`, `src/cli.ts`  |
 | A missing token as one message, not a `ConfigError` report    | `src/commands.ts`                |
 | A promise client handling each declared error by its tag      | `src/browser.ts`                 |

package/examples/notes-service/src/commands.ts

@@ -5,6 +5,13 @@ import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
 import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
 import { Http } from "./Api.js";
 
+// The file's format: each note a `# ` title line, a blank line and its body, the notes apart by
+// a blank line. A body line that starts as a title would is written with a backslash before it,
+// as Markdown escapes one, and `import` takes it off, so every note reads back as it was.
+const escape = (body: string) => body.replaceAll(/^(?=\\*# )/gmu, "\\");
+
+const unescape = (body: string) => body.replaceAll(/^\\(?=\\*# )/gmu, "");
+
 // A command of your own, for what no single action does: this one calls two and writes a file.
 // It is a native Effect CLI command, so its syntax and its output are what you write: `notes
 // export notes.md` takes its argument from `Argument`, as a flag would come from `Flag`. It
@@ -22,7 +29,7 @@ const exportNotes = Command.make(
 
       yield* files.writeFileString(
         file,
-        whole.map((note) => `# ${note.title}\n\n${note.body}`).join("\n\n"),
+        whole.map((note) => `# ${note.title}\n\n${escape(note.body)}`).join("\n\n"),
       );
 
       yield* Console.log(`Wrote ${whole.length} notes to ${file}`);
@@ -40,6 +47,47 @@ const exportNotes = Command.make(
     ),
 ).pipe(Command.withDescription("Write every note to a file, as Markdown."));
 
+// The other half of `export`: it reads such a file and creates its notes with one call of the
+// bulk action, so the server checks every note before it writes any, and a file of more than
+// the action's 100 is refused whole. The command reads the file and nothing more.
+// `Argument.FileText` reads it, and a missing file is a usage error naming it, where
+// `Argument.String` and `FileSystem` would print the platform's error. Text before the first
+// title is refused, not dropped: the file is not one `export` wrote. The derived `import-notes`
+// stays beside it, taking the notes as a JSON array in `--notes`.
+const importNotes = Command.make(
+  "import",
+  {
+    text: Argument.FileText("file").pipe(
+      Argument.withDescription("A Markdown file as `notes export` writes it."),
+    ),
+  },
+  ({ text }) =>
+    Effect.gen(function* () {
+      const client = yield* ActionHttp.client(Http);
+
+      if (text === "") return yield* Console.log("Created 0 notes");
+
+      if (!text.startsWith("# ")) {
+        return yield* new CliError.UserError({
+          cause: text.split("\n", 1)[0],
+          userMessage: "The file does not start with a `# ` title, as `notes export` writes one.",
+        });
+      }
+
+      const notes = text.split(/\n\n(?=# )/u).map((note) => {
+        const [title = "", ...body] = note.slice(2).split("\n\n");
+
+        return { title, body: unescape(body.join("\n\n")) };
+      });
+
+      const { notes: created } = yield* client.importNotes({ notes });
+
+      yield* Console.log(`Created ${created.length} notes`);
+    }).pipe(ActionCli.toUserError(Http)),
+).pipe(
+  Command.withDescription("Create the notes of a file `export` wrote, all or none, at most 100."),
+);
+
 // A command per action of the binding, a flag per input field, each calling the server over
 // HTTP. It imports the binding alone, never a handler. It is apart from cli.ts so a test runs
 // it: test/commands.test.ts.
@@ -54,7 +102,7 @@ export const commands = ActionCli.remote(Http, {
   },
   // `Command.withSubcommands` on the result would replace the derived commands, so your own
   // go here.
-  subcommands: [exportNotes],
+  subcommands: [exportNotes, importNotes],
 });
 
 // Where the server is and who is calling, read from config: the `HttpClient` every command

package/examples/notes-service/src/notes/Notes.ts

@@ -32,8 +32,13 @@ const Id = Schema.String.annotate({
   description: "The note's id, as the list of your notes shows it.",
 });
 
-const Title = Schema.String.check(Schema.isMinLength(1)).annotate({
-  description: "A short name for the note, at least one character.",
+// A check's `message` is what a caller reads when the value fails it, in place of the
+// generic "Expected a value with a length of at least 1". A model and a CLI user read it too.
+const Title = Schema.String.check(
+  Schema.isMinLength(1, { message: "A note needs a title." }),
+  Schema.isPattern(/^[^\r\n\u2028\u2029]*$/u, { message: "A title is one line." }),
+).annotate({
+  description: "A short name for the note: one line, at least one character.",
 });
 
 const Body = Schema.String.annotate({ description: "The note's whole text." });
@@ -77,7 +82,8 @@ export const UpdateNote = Action.make("updateNote", {
   error: [NoteNotFound, NoteChanged],
   readOnly: false,
   caller: CurrentUser,
-  mcp: { destructiveHint: false },
+  // No `destructiveHint`: an update replaces the body, so it is destructive, MCP's default for
+  // a write. `createNote` and `importNotes`, which only add, say `false`.
 });
 
 export const DeleteNote = Action.make("deleteNote", {
@@ -88,4 +94,26 @@ export const DeleteNote = Action.make("deleteNote", {
   caller: CurrentUser,
 });
 
-export const Notes = [ListNotes, GetNote, CreateNote, UpdateNote, DeleteNote] as const;
+// Work every surface should offer is an action, a bulk import included: the HTTP API, the MCP
+// tools and the CLI then all have it, and the whole list is decoded, so checked, before the
+// handler writes any of it. A command of your own only reads the file and calls this once
+// (commands.ts). `importNotes` adds and removes nothing, so `destructiveHint` is `false`.
+export const ImportNotes = Action.make("importNotes", {
+  description:
+    "Create several notes at once, such as those `notes export` wrote. Every note is checked " +
+    "before any is written: an import holding one that is not valid writes none.",
+  input: {
+    notes: Schema.Array(Schema.Struct({ title: Title, body: Body }))
+      .check(
+        Schema.isMinLength(1, { message: "An import holds at least one note." }),
+        Schema.isMaxLength(100, { message: "An import holds at most 100 notes." }),
+      )
+      .annotate({ description: "The notes to create, in order: from 1 to 100." }),
+  },
+  success: { notes: Schema.Array(Note) },
+  readOnly: false,
+  caller: CurrentUser,
+  mcp: { destructiveHint: false },
+});
+
+export const Notes = [ListNotes, GetNote, CreateNote, UpdateNote, DeleteNote, ImportNotes] as const;

package/examples/notes-service/src/notes/handlers.ts

@@ -6,8 +6,9 @@ import { Notes } from "./Notes.js";
 import { NoteStore } from "./store.js";
 
 // The builder runs once, at startup, however many surfaces serve these actions: it is where a
-// handler gets its services. `CurrentUser` is read per call. Each handler is a thin step from
-// the contract to the store, and none checks a scope: `authorize` has run before it.
+// handler gets the services that last the process, never the caller. `CurrentUser` is read per
+// call, inside each handler. Each handler is a thin step from the contract to the store, and
+// none checks a scope: `authorize` has run before it.
 export const notes = Action.implement(
   Notes,
   Effect.gen(function* () {
@@ -27,6 +28,11 @@ export const notes = Action.implement(
       updateNote: ({ id, body, revision }) =>
         Effect.flatMap(CurrentUser, (user) => store.update(user.id, id, body, revision)),
       deleteNote: ({ id }) => Effect.flatMap(CurrentUser, (user) => store.remove(user.id, id)),
+      importNotes: ({ notes }) =>
+        Effect.map(
+          Effect.flatMap(CurrentUser, (user) => store.createAll(user.id, notes)),
+          (created) => ({ notes: created }),
+        ),
     };
   }),
   { authorize },

package/examples/notes-service/src/notes/store.ts

@@ -11,6 +11,11 @@ export class NoteStore extends Context.Service<
     readonly list: (owner: string) => Effect.Effect<ReadonlyArray<Note>>;
     readonly get: (owner: string, id: string) => Effect.Effect<Note, NoteNotFound>;
     readonly create: (owner: string, title: string, body: string) => Effect.Effect<Note>;
+    /** Every note or none: a database does this in one transaction. */
+    readonly createAll: (
+      owner: string,
+      notes: ReadonlyArray<{ readonly title: string; readonly body: string }>,
+    ) => Effect.Effect<ReadonlyArray<Note>>;
     readonly update: (
       owner: string,
       id: string,
@@ -48,6 +53,12 @@ export class NoteStore extends Context.Service<
       get,
       create: (owner, title, body) =>
         Effect.sync(() => save(owner, { id: crypto.randomUUID(), title, body, revision: 1 })),
+      createAll: (owner, all) =>
+        Effect.sync(() =>
+          all.map(({ title, body }) =>
+            save(owner, { id: crypto.randomUUID(), title, body, revision: 1 }),
+          ),
+        ),
       // No `yield*` between the read and the write: a fiber may be set aside at one, and two
       // updates that each read revision 1 before either wrote would both succeed. A database
       // does this with a conditional update or a transaction.

package/examples/notes-service/src/server.ts

@@ -10,12 +10,12 @@ import { routes } from "./routes.js";
 // and starts Node's HTTP server; nothing below it knows which of those it got.
 const server = Layer.unwrap(
   Effect.gen(function* () {
+    // The loopback default serves this machine alone; HOST=0.0.0.0 lets others reach it.
+    const host = yield* Config.String("HOST").pipe(Config.withDefault("127.0.0.1"));
     const port = yield* Config.Port("PORT").pipe(Config.withDefault(3000));
 
     return HttpRouter.serve(routes).pipe(
-      // `127.0.0.1` serves this machine alone. A server others reach reads its host from
-      // config: `Config.String("HOST").pipe(Config.withDefault("127.0.0.1"))`.
-      Layer.provide(NodeHttpServer.layer(createServer, { host: "127.0.0.1", port })),
+      Layer.provide(NodeHttpServer.layer(createServer, { host, port })),
       // Request bodies have no size limit unless the host sets one. This covers every route.
       Layer.provide(Layer.succeed(HttpServerRequest.MaxBodySize, ByteSize.mebibytes(1))),
       Layer.provide(NoteStore.layerMemory),