@gjermundgaraba/effect-actions 0.11.0 → 0.13.0

package/examples/assistant/README.md

@@ -0,0 +1,92 @@
+# assistant
+
+An application with no server: its actions run in the process that calls them. A team's task
+list is worked on by a model, through tools, and by whoever runs the machine, through commands.
+Both are the same implementations behind the same authorization. It opens no port.
+
+Start here if a model calls your code in process (an agent, a chat bot, a job), or if you are
+building a local command-line tool. For a service others call over the network, start from
+[notes-service](../notes-service/).
+
+## Run it
+
+From the repository root, after `vp install` (from an installed package, see
+[Run one](../README.md#run-one)):
+
+```sh
+node --import tsx examples/assistant/src/agent.ts               # a scripted model: no API key
+
+node --import tsx examples/assistant/src/cli.ts --help
+node --import tsx examples/assistant/src/cli.ts list-tasks      # what the model added
+node --import tsx examples/assistant/src/cli.ts add-task --title "Pay the caterer" --assignee grace
+node --import tsx examples/assistant/src/cli.ts complete-task 1
+echo "Vegetarian for six." | node --import tsx examples/assistant/src/cli.ts annotate-task --id 3
+node --import tsx examples/assistant/src/cli.ts list-tasks -a grace --json 2>/dev/null
+
+vp test examples/assistant
+```
+
+The agent and each command are separate processes. They share one JSON file, named by
+`ASSISTANT_TASKS` and kept in the system's temporary directory by default. Running the agent
+again adds the same tasks again: delete the file to start over. The model is scripted, the
+members and their permissions are fixed tables, and nothing locks the file between processes:
+replace all three before relying on any of it.
+
+## Layout
+
+```text
+src/
+├── tasks/
+│   ├── Tasks.ts         contract: schemas, an error, four actions
+│   ├── store.ts         TaskStore and its Layers: memory, and a JSON file
+│   └── handlers.ts      Action.implement: contract to store
+├── identity/
+│   ├── Identity.ts      contract: CurrentCaller, a Member or the Operator; whoAmI
+│   ├── permissions.ts   Permissions, the store the authorizer reads
+│   ├── authorize.ts     the one authorization rule, built from Permissions
+│   ├── members.ts       the demo team
+│   └── handlers.ts
+├── 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
+├── 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
+```
+
+- **Two surfaces, no transport.** `toolkit.ts` and `commands.ts` take the same implementations.
+  Neither holds a caller or a store: `agent.ts` and `cli.ts` provide those, and so does a test.
+- **The caller comes from the host, per call.** Nothing here authenticates anyone. `agent.ts`
+  provides the member around each turn; `cli.ts` provides the operator on the command. A caller
+  is never given to the toolkit's `layer`, which is built once for every member.
+- **The operator is a type, not a flag.** `Member | Operator` is what an action may be called
+  as. Only `cli.ts` builds an `Operator`, and the demo team is typed as members, so no sign-in
+  produces one. A model's caller is named through `actingFor`, which takes a `Member`. The tools
+  themselves accept either: keeping the operator away from a model is the host's doing.
+- **Approval is not authorization.** `needsApproval` decides which of a model's calls wait for a
+  person. `authorize` decides who may call at all, and runs for an approved call too.
+
+## 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`            |

package/examples/assistant/src/agent.ts

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

package/examples/assistant/src/cli.ts

@@ -0,0 +1,34 @@
+import { userInfo } from "node:os";
+import { NodeRuntime, NodeServices } from "@effect/platform-node";
+import { Effect, Layer } from "effect";
+import { Command } from "effect/cli";
+import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
+import { commands } from "./commands.js";
+import { CurrentCaller, type Operator } from "./identity/Identity.js";
+import { Permissions } from "./identity/permissions.js";
+import { TaskStore } from "./tasks/store.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
+// itself: whoever runs the command, as the trusted operator. Being local earns nothing more:
+// `authorize` runs here as for a model's tool call, and admits the operator by name.
+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.provideSync(CurrentCaller, operator),
+);
+
+// A command writes its result alone to stdout: JSON, or what `render` returns. Its failure
+// goes to stderr under an `ERROR` heading, as JSON such as `{"_tag":"TaskNotFound","id":"9"}`,
+// exiting 1, and so do its handler's logs, such as the store's. What happens outside the
+// command is `runMain`'s to report, on stdout: a defect, such as a tasks file that does not
+// decode. `logToStderr`, applied last, moves that to stderr too, so
+// `assistant list-tasks --json | jq` reads results.
+Command.run(assistant, { version: "1.0.0" }).pipe(
+  Effect.provide(NodeServices.layer),
+  ActionCli.logToStderr,
+  NodeRuntime.runMain,
+);

package/examples/assistant/src/commands.ts

@@ -0,0 +1,25 @@
+import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
+import { identity } from "./identity/handlers.js";
+import { tasks } from "./tasks/handlers.js";
+
+// The same implementations as local commands: `assistant <action>`, a subcommand per action in
+// kebab case, a flag per input field. A command runs the handler in this process, behind the
+// same `authorize`. `add-task` and `who-am-i` are as derived; the others each change one thing.
+export const commands = ActionCli.make([tasks, identity], {
+  name: "assistant",
+  commands: {
+    // `assistant list-tasks -a ada`: a short flag beside `--assignee`. `render` prints a line
+    // per task for a person, and adds `--json` for the JSON a script reads.
+    listTasks: {
+      aliases: { assignee: "a" },
+      render: ({ tasks }) =>
+        tasks
+          .map((task) => `${task.done ? "[x]" : "[ ]"} ${task.id} ${task.title} (${task.assignee})`)
+          .join("\n"),
+    },
+    // `assistant complete-task 2`: an argument instead of `--id 2`.
+    completeTask: { positional: ["id"] },
+    // `assistant annotate-task --id 2 < notes.md`: the notes are piped in, not a flag.
+    annotateTask: { stdin: "notes" },
+  },
+});

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

@@ -0,0 +1,33 @@
+import { Context, Schema } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+
+/** A teammate: what a sign-in can name. The assistant acts for one in each turn. */
+export interface Member {
+  readonly kind: "member";
+  readonly id: string;
+}
+
+/**
+ * Whoever runs the machine. Only a host builds one, in its own code: nothing that turns a
+ * credential into a caller is typed to return it, so no token can claim to be the operator.
+ */
+export interface Operator {
+  readonly kind: "operator";
+  readonly id: string;
+}
+
+/**
+ * Who is calling. A protected action declares it, `caller: CurrentCaller`. Nothing here
+ * authenticates anyone: the host provides it around each call, as the member a model acts for
+ * or as the operator at the terminal.
+ */
+export class CurrentCaller extends Context.Service<CurrentCaller, Member | Operator>()(
+  "assistant/CurrentCaller",
+) {}
+
+export const WhoAmI = Action.make("whoAmI", {
+  description: "Show who the assistant is acting for.",
+  success: { id: Schema.String, kind: Schema.Literals(["member", "operator"]) },
+  readOnly: true,
+  caller: CurrentCaller,
+});

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

@@ -0,0 +1,24 @@
+import { Effect } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { CurrentCaller } from "./Identity.js";
+import { type Permission, Permissions } from "./permissions.js";
+
+// The one rule, for a model's tool call and for a command alike. It is built as handlers are:
+// this Effect runs once and gets the permission store, a startup service; the function it
+// returns runs before every handler and reads the caller of that call.
+export const authorize = Effect.gen(function* () {
+  const permissions = yield* Permissions;
+
+  return Effect.fn("authorize")(function* (action: Action.Any) {
+    const caller = yield* CurrentCaller;
+
+    // The operator is trusted, and has no entry in the store. Only a host can name one.
+    if (caller.kind === "operator") return;
+
+    const permission: Permission = action.readOnly ? "tasks:read" : "tasks:write";
+
+    if (!(yield* permissions.granted(caller.id)).includes(permission)) {
+      return yield* new Action.Forbidden({ message: `Requires ${permission}.` });
+    }
+  });
+});

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

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

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

@@ -0,0 +1,9 @@
+import type { Member } from "./Identity.js";
+
+// DEMO ONLY: the team, by name. A real host maps the user its chat platform has verified to a
+// `Member`. Typed as members alone: no entry, and so no sign-in, can be the operator.
+export const members = {
+  ada: { kind: "member", id: "ada" },
+  grace: { kind: "member", id: "grace" },
+  guest: { kind: "member", id: "guest" },
+} as const satisfies Readonly<Record<string, Member>>;

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

@@ -0,0 +1,23 @@
+import { Context, Effect, Layer } from "effect";
+
+export type Permission = "tasks:read" | "tasks:write";
+
+/**
+ * What each member may do. Permissions are kept here, not in the identity, so changing one
+ * takes effect on the member's next call.
+ */
+export class Permissions extends Context.Service<
+  Permissions,
+  { readonly granted: (memberId: string) => Effect.Effect<ReadonlyArray<Permission>> }
+>()("assistant/Permissions") {
+  // DEMO ONLY: a fixed table. A real application reads its database or its directory.
+  static readonly layerMemory = Layer.sync(Permissions, () => {
+    const table = new Map<string, ReadonlyArray<Permission>>([
+      ["ada", ["tasks:read", "tasks:write"]],
+      ["grace", ["tasks:read", "tasks:write"]],
+      ["guest", ["tasks:read"]],
+    ]);
+
+    return Permissions.of({ granted: (memberId) => Effect.sync(() => table.get(memberId) ?? []) });
+  });
+}

package/examples/assistant/src/scripted.ts

@@ -0,0 +1,23 @@
+import { Effect, Layer, Ref, Stream } from "effect";
+import { LanguageModel, type Response } from "effect/ai";
+
+// DEMO ONLY: a model that needs no API key. It answers its first request with the first reply
+// it was given, its second with the second, whatever the prompt says, and with nothing once
+// they run out. It stands exactly where a provider's model layer goes, such as
+// `OpenAiLanguageModel.model(...)` of `@effect/ai-openai`.
+export const scripted = (...replies: ReadonlyArray<ReadonlyArray<Response.PartEncoded>>) =>
+  Layer.effect(
+    LanguageModel.LanguageModel,
+    Effect.gen(function* () {
+      const answered = yield* Ref.make(0);
+
+      return yield* LanguageModel.make({
+        generateText: () =>
+          Effect.map(
+            Ref.getAndUpdate(answered, (count) => count + 1),
+            (count) => [...(replies[count] ?? [])],
+          ),
+        streamText: () => Stream.empty,
+      });
+    }),
+  );

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

@@ -0,0 +1,63 @@
+import { Schema } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { CurrentCaller } from "../identity/Identity.js";
+
+export const Task = Schema.Struct({
+  id: Schema.String,
+  title: Schema.String,
+  assignee: Schema.String,
+  addedBy: Schema.String,
+  notes: Schema.String,
+  done: Schema.Boolean,
+});
+
+export type Task = typeof Task.Type;
+
+// A declared error is part of the contract. A tool returns it to the model as a result it can
+// read, and a command prints it on stderr as JSON and exits 1.
+export class TaskNotFound extends Schema.TaggedError<TaskNotFound>()("TaskNotFound", {
+  id: Schema.String,
+}) {}
+
+// A field's description is what a model reads beside the tool, and the flag's help text.
+const Id = Schema.String.annotate({ description: "The id listed beside the task." });
+
+const Assignee = Schema.String.annotate({ description: "A teammate's name, such as ada." });
+
+const team = { caller: CurrentCaller } as const;
+
+export const ListTasks = Action.make("listTasks", {
+  ...team,
+  description: "List the team's tasks, or one teammate's.",
+  input: { assignee: Schema.optionalKey(Assignee) },
+  success: { tasks: Schema.Array(Task) },
+  readOnly: true,
+});
+
+export const AddTask = Action.make("addTask", {
+  ...team,
+  description: "Add a task and assign it to a teammate.",
+  input: { title: Schema.String.check(Schema.isMinLength(1)), assignee: Assignee },
+  success: Task,
+  readOnly: false,
+});
+
+export const CompleteTask = Action.make("completeTask", {
+  ...team,
+  description: "Mark a task as done.",
+  input: { id: Id },
+  success: Task,
+  error: TaskNotFound,
+  readOnly: false,
+});
+
+export const AnnotateTask = Action.make("annotateTask", {
+  ...team,
+  description: "Replace a task's notes.",
+  input: { id: Id, notes: Schema.String.annotate({ description: "The notes, as plain text." }) },
+  success: Task,
+  error: TaskNotFound,
+  readOnly: false,
+});
+
+export const Tasks = [ListTasks, AddTask, CompleteTask, AnnotateTask] as const;

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

@@ -0,0 +1,25 @@
+import { Effect } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { authorize } from "../identity/authorize.js";
+import { CurrentCaller } from "../identity/Identity.js";
+import { Tasks } from "./Tasks.js";
+import { TaskStore } from "./store.js";
+
+// The builder gets the store. It runs once for a toolkit's layer, however many calls a model
+// makes, and each time a command runs. `CurrentCaller` is read per call. No handler knows whether a model or a person at a terminal
+// called it, and none checks a permission: `authorize` has run before it.
+export const tasks = Action.implement(
+  Tasks,
+  Effect.gen(function* () {
+    const store = yield* TaskStore;
+
+    return {
+      listTasks: ({ assignee }) => Effect.map(store.list(assignee), (tasks) => ({ tasks })),
+      addTask: ({ title, assignee }) =>
+        Effect.flatMap(CurrentCaller, (caller) => store.add(caller.id, title, assignee)),
+      completeTask: ({ id }) => store.complete(id),
+      annotateTask: ({ id, notes }) => store.annotate(id, notes),
+    };
+  }),
+  { authorize },
+);

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

@@ -0,0 +1,96 @@
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Config, Context, Effect, FileSystem, Layer, Ref, Schema, 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.
+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.
+  const lock = Semaphore.makeUnsafe(1);
+
+  const change = Effect.fn("TaskStore.change")(function* (id: string, to: (task: Task) => Task) {
+    const tasks = yield* load;
+    const task = tasks.find((each) => each.id === id);
+
+    if (task === undefined) return yield* new TaskNotFound({ id });
+
+    const changed = to(task);
+
+    yield* save(tasks.map((each) => (each.id === id ? changed : each)));
+
+    return changed;
+  }, Semaphore.withPermit(lock));
+
+  return TaskStore.of({
+    list: (assignee) =>
+      Effect.map(load, (tasks) =>
+        assignee === undefined ? tasks : tasks.filter((task) => task.assignee === assignee),
+      ),
+    add: Effect.fn("TaskStore.add")(function* (addedBy, title, assignee) {
+      const tasks = yield* load;
+      const task = { id: `${tasks.length + 1}`, title, assignee, addedBy, notes: "", done: false };
+
+      yield* save([...tasks, task]);
+
+      return task;
+    }, Semaphore.withPermit(lock)),
+    complete: (id) => change(id, (task) => ({ ...task, done: true })),
+    annotate: (id, notes) => change(id, (task) => ({ ...task, notes })),
+  });
+};
+
+/** The team's tasks. Its methods require nothing: a layer captures where the tasks are kept. */
+export class TaskStore extends Context.Service<
+  TaskStore,
+  {
+    readonly list: (assignee: string | undefined) => Effect.Effect<TaskList>;
+    readonly add: (addedBy: string, title: string, assignee: string) => Effect.Effect<Task>;
+    readonly complete: (id: string) => Effect.Effect<Task, TaskNotFound>;
+    readonly annotate: (id: string, notes: string) => Effect.Effect<Task, TaskNotFound>;
+  }
+>()("assistant/TaskStore") {
+  /** Memory, lost with the process: what a test provides. */
+  static readonly layerMemory = Layer.effect(
+    TaskStore,
+    Effect.map(Ref.make<TaskList>([]), (tasks) =>
+      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

@@ -0,0 +1,30 @@
+import { Effect, Option } from "effect";
+import * as ActionToolkit from "@gjermundgaraba/effect-actions/ActionToolkit";
+import { identity } from "./identity/handlers.js";
+import { CurrentCaller, type Member } from "./identity/Identity.js";
+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], {
+  // 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.
+  // This is not authorization: an approved call still passes through `authorize`.
+  needsApproval: (call) =>
+    !call.action.readOnly &&
+    Effect.map(
+      Effect.serviceOption(CurrentCaller),
+      Option.match({
+        onNone: () => true,
+        onSome: (caller) => call.name !== "addTask" || call.input.assignee !== caller.id,
+      }),
+    ),
+});
+
+// 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
+// function's doing, and that of every host using it.
+export const actingFor = (member: Member) => Effect.provideService(CurrentCaller, member);

package/examples/assistant/test/commands.test.ts

@@ -0,0 +1,57 @@
+import { NodeServices } from "@effect/platform-node";
+import { describe, expect, it } from "@effect/vitest";
+import { Effect, Layer, Stdio, Stream } from "effect";
+import { Command } from "effect/cli";
+import { TestConsole } from "effect/testing";
+import { commands } from "../src/commands.js";
+import { CurrentCaller, type Operator } from "../src/identity/Identity.js";
+import { Permissions } from "../src/identity/permissions.js";
+import { TaskStore } from "../src/tasks/store.js";
+
+// What the commands add to the implementations: their syntax and what they print. The services
+// are provided around a test, not on the command as cli.ts does, so the commands of one test
+// share one store in memory.
+const services = Layer.mergeAll(TaskStore.layerMemory, Permissions.layerMemory);
+
+const operator: Operator = { kind: "operator", id: "root" };
+
+// Effect's own runner, given arguments instead of the process's. `it.effect` provides a console
+// that keeps what is printed, and stdin is the text given here.
+const run = (args: ReadonlyArray<string>, stdin = "") =>
+  Command.runWith(commands.pipe(Command.provideSync(CurrentCaller, operator)), { version: "0" })(
+    args,
+  ).pipe(
+    Effect.andThen(TestConsole.logLines),
+    Effect.provide(Stdio.layerTest({ stdin: Stream.make(new TextEncoder().encode(stdin)) })),
+    Effect.provide(NodeServices.layer),
+  );
+
+describe("the commands", () => {
+  it.effect("run as the operator the host names, taking an argument and stdin", () =>
+    Effect.gen(function* () {
+      yield* run(["add-task", "--title", "Rotate the keys", "--assignee", "ada"]);
+      yield* run(["annotate-task", "--id", "1"], "Before Friday.\n");
+      yield* run(["complete-task", "1"]);
+
+      const store = yield* TaskStore;
+
+      expect(yield* store.list("ada")).toMatchObject([
+        { addedBy: "root", notes: "Before Friday.", done: true },
+      ]);
+    }).pipe(Effect.provide(services)),
+  );
+
+  it.effect("print what `render` returns, and JSON where a command states none", () =>
+    Effect.gen(function* () {
+      yield* run(["add-task", "--title", "Rotate the keys", "--assignee", "ada"]);
+
+      const printed = yield* run(["list-tasks", "-a", "ada"]);
+
+      expect(printed.at(-1)).toBe("[ ] 1 Rotate the keys (ada)");
+
+      const json = yield* run(["who-am-i"]);
+
+      expect(json.at(-1)).toBe(JSON.stringify({ id: "root", kind: "operator" }, undefined, 2));
+    }).pipe(Effect.provide(services)),
+  );
+});