@gjermundgaraba/effect-actions 0.18.2 → 0.20.0

package/examples/assistant/README.md

@@ -4,10 +4,6 @@ An application with no server: its actions run in the process that calls them. A
 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
@@ -28,9 +24,7 @@ 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.
+again adds the same tasks again: delete the file to start over.
 
 ## Layout
 
@@ -61,36 +55,24 @@ test/
 └── 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`                                   |
-| 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`                            |
+| To see                                                                | Read                                               |
+| --------------------------------------------------------------------- | -------------------------------------------------- |
+| Implementations as a native Effect AI `Toolkit`                       | `src/toolkit.ts`                                   |
+| Native tool titles in the approval display                            | `src/toolkit.ts`, `src/agent.ts`                   |
+| One approval rule reading the call and its caller                     | `src/toolkit.ts`                                   |
+| A turn run as a member, and an approval answered through a `Chat`     | `src/agent.ts`                                     |
+| Where a real `LanguageModel` plugs in                                 | `src/agent.ts`, `src/scripted.ts`                  |
+| Local commands with `positional`, `aliases`, `render`, `stdin`        | `src/commands.ts`                                  |
+| Services provided on the command, and the host naming the caller      | `src/cli.ts`                                       |
+| A command's result alone on stdout, its handler's logs on stderr      | `src/cli.ts`, `src/platform/tasks-file.ts`         |
+| `logToStderr` moving a defect's report from stdout to stderr          | `src/cli.ts`                                       |
+| An identity only the host builds: the trusted operator                | `src/identity/Identity.ts`                         |
+| An authorizer built once from a service, reading the caller per call  | `src/identity/authorize.ts`                        |
+| One service with two Layers: a file for entrypoints, memory for tests | `src/tasks/store.ts`, `src/platform/tasks-file.ts` |
+| Changes serialized, since a turn's tool calls run concurrently        | `src/tasks/store.ts`                               |
+| Testing handlers and authorization, each caller around its calls      | `test/tasks/tasks.test.ts`                         |
+| Testing a Layer over a temporary file, its path set through config    | `test/platform/tasks-file.test.ts`                 |
+| Testing a tool call, an approval required, an approval answered       | `test/toolkit.test.ts`                             |
+| Testing a command's syntax and output without a process               | `test/commands.test.ts`                            |

package/examples/assistant/src/agent.ts

@@ -15,8 +15,7 @@ import { actingFor, layer, toolkit } from "./toolkit.js";
 // 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.
+// Printing only.
 const report = (member: Member) => (response: Response) => {
   const waiting = response.content.flatMap((part) =>
     part.type === "tool-approval-request" ? [part.toolCallId] : [],
@@ -89,7 +88,7 @@ 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.
+  // Startup services only: where tasks and permissions are kept.
   Effect.provide(layer.pipe(Layer.provide([tasksFile, Permissions.layerMemory]))),
   Effect.provide(NodeServices.layer),
   NodeRuntime.runMain,

package/examples/assistant/src/cli.ts

@@ -11,22 +11,17 @@ 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
 // 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.
+// `authorize` runs here as for a model's tool call, and admits the operator by its kind.
 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(tasksFile, 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.
+// A command's defect, such as a tasks file that does not decode, `runMain` reports on stdout.
+// `logToStderr`, applied last, moves that to stderr, so `assistant list-tasks --json | jq` reads
+// results alone.
 Command.run(assistant, { version: "1.0.0" }).pipe(
   Effect.provide(NodeServices.layer),
   ActionCli.logToStderr,

package/examples/assistant/src/commands.ts

@@ -2,15 +2,17 @@ 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.
+// The same implementations as local commands, `assistant <action>`: 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 their syntax or output.
 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.
+    // per task for a person, and adds `--json` for the JSON a script reads. `description` is the
+    // command's help, saying what a line holds; the action's stays what a model reads.
     listTasks: {
+      description: "Print one line per task: [x] when done, then its id, title and assignee.",
       aliases: { assignee: "a" },
       render: ({ tasks }) =>
         tasks

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

@@ -3,9 +3,9 @@ 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.
+// The one rule, for a model's tool call and for a command alike. The permission store is a
+// startup service, so this Effect gets it; the caller differs per call, so the function it
+// returns reads it.
 export const authorize = Effect.gen(function* () {
   const permissions = yield* Permissions;
 

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

@@ -13,8 +13,7 @@ export const Task = Schema.Struct({
 
 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.
+// A declared error is part of the contract.
 export class TaskNotFound extends Schema.TaggedError<TaskNotFound>()("TaskNotFound", {
   id: Schema.String,
 }) {}

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

@@ -5,9 +5,9 @@ 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.
+// The builder gets the store. `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* () {

package/examples/assistant/src/toolkit.ts

@@ -5,14 +5,12 @@ 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.
+// `actions.layer` holds the handlers, and requires the startup services their builders read;
+// neither it nor `actions.toolkit` holds a caller.
 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.
-  // This is not authorization: an approved call still passes through `authorize`.
   needsApproval: (call) =>
     !call.action.readOnly &&
     Effect.map(
@@ -33,8 +31,8 @@ export const toolkit = Toolkit.merge(
 
 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
-// function's doing, and that of every host using it.
+// One toolkit serves every member, so who a turn runs as is provided around that turn. 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

@@ -15,16 +15,21 @@ 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.
+// Effect's own runner, given arguments instead of the process's, and stdin the text given here.
+// The console of `it.effect` keeps every line printed, so a run returns the lines it added.
 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),
-  );
+  Effect.gen(function* () {
+    const before = (yield* TestConsole.logLines).length;
+
+    yield* Command.runWith(commands.pipe(Command.provideSync(CurrentCaller, operator)), {
+      version: "0",
+    })(args).pipe(
+      Effect.provide(Stdio.layerTest({ stdin: Stream.make(new TextEncoder().encode(stdin)) })),
+      Effect.provide(NodeServices.layer),
+    );
+
+    return (yield* TestConsole.logLines).slice(before);
+  });
 
 describe("the commands", () => {
   it.effect("run as the operator the host names, taking an argument and stdin", () =>
@@ -47,11 +52,11 @@ describe("the commands", () => {
 
       const printed = yield* run(["list-tasks", "-a", "ada"]);
 
-      expect(printed.at(-1)).toBe("[ ] 1 Rotate the keys (ada)");
+      expect(printed).toEqual(["[ ] 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));
+      expect(json).toEqual([JSON.stringify({ id: "root", kind: "operator" }, undefined, 2)]);
     }).pipe(Effect.provide(services)),
   );
 });

package/examples/assistant/test/tasks/tasks.test.ts

@@ -44,8 +44,6 @@ describe("tasks, in process", () => {
 
       const refusal = yield* Effect.flip(add.pipe(as(members.guest)));
 
-      // `toEqual` on an error compares its fields and never its message, so the message is
-      // asserted on its own.
       expect(refusal).toBeInstanceOf(Action.Forbidden);
       expect(refusal.message).toBe("Requires tasks:write.");
       expect(yield* client.listTasks().pipe(as(members.guest))).toEqual({ tasks: [] });

package/examples/assistant/test/toolkit.test.ts

@@ -49,7 +49,6 @@ describe("the toolkit", () => {
 
   it.effect("asks for approval before a model adds to a list that is not its caller's", () =>
     Effect.gen(function* () {
-      // `LanguageModel` is what enforces approval: a call by hand, as above, is never asked.
       // The model answers each member with the same two calls.
       const plan = (member: Member) =>
         LanguageModel.generateText({ prompt: "Plan the launch.", toolkit }).pipe(

package/examples/kitchen-sink/README.md

@@ -5,10 +5,7 @@ and nearly every option. Members of a workspace file, discuss and close issues,
 screenshots, over HTTP, MCP, Effect RPC, a CLI and an assistant, in process and behind a route.
 Operators suspend workspaces on a second port, or from a console on the host.
 
-Open it when you need a working use of one feature: the [index](#index) maps each export and
-option to the file that shows it. To start an application, copy
-[notes-service](../notes-service/) instead; it is this layout at a size you can read in one
-sitting.
+The [index](#index) maps each export and option to the file that shows it.
 
 ## Run it
 
@@ -42,17 +39,15 @@ subprocess. `sdk.ts` and `browser.ts` are imported by client code, not run. The
 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.
-
-| Credential                            | Who                    | May                                    |
-| ------------------------------------- | ---------------------- | -------------------------------------- |
-| `Authorization: Bearer ada`           | ada, in acme or globex | read and write in acme, read in globex |
-| `Authorization: Bearer linus`         | linus, in acme         | read                                   |
-| `Authorization: Bearer grace`         | grace, in globex       | read and write                         |
-| `Cookie: tracker_session=ada-at-acme` | ada in acme, on `/rpc` | read and write                         |
-| `X-Operator-Key: ops-key`             | operator `ops`         | list, suspend and resume workspaces    |
-| `X-Operator-Key: support-key`         | operator `support`     | list workspaces                        |
+| Credential                                | Who                        | May                                    |
+| ----------------------------------------- | -------------------------- | -------------------------------------- |
+| `Authorization: Bearer ada`               | ada, in acme or globex     | read and write in acme, read in globex |
+| `Authorization: Bearer linus`             | linus, in acme             | read                                   |
+| `Authorization: Bearer grace`             | grace, in globex           | read and write                         |
+| `Cookie: tracker_session=ada-at-acme`     | ada in acme, on `/rpc`     | read and write                         |
+| `Cookie: tracker_session=grace-at-globex` | grace in globex, on `/rpc` | read and write                         |
+| `X-Operator-Key: ops-key`                 | operator `ops`             | list, suspend and resume workspaces    |
+| `X-Operator-Key: support-key`             | operator `support`         | list workspaces                        |
 
 A bearer request names its workspace in `X-Workspace: acme`. `kay` (token `kay`, session
 `kay-at-acme`) is a member of acme granted no scope yet. The session cookie also opens
@@ -125,34 +120,18 @@ test/
 └── admin/                 the operators' grants; the trusted operator
 ```
 
-- **A folder per domain.** `identity/` and `admin/` are the two audiences; `workspaces/`,
-  `issues/` and `attachments/` are what they work on. In each, the PascalCase file is the
-  contract and imports no server code; the lowercase files run on the server.
-- **Top-level files are the host's.** `Actions.ts`, `Api.ts` and `Rpc.ts` say what is served
-  where, and stay browser-safe. `routes.ts` builds the surfaces. Each entrypoint chooses the
-  services, here from `memory.ts`. `server.ts` also chooses the rpcs' protocol, and a local
-  one lists the implementations it serves itself.
-- **Three callers' credentials, three descriptors.** API clients, the CLI and MCP clients send
-  a bearer token (`Login`). The web app sends its session cookie (`Session`) for the same
-  identity, on its own binding. Operators send a key (`OperatorKey`) for another identity, on
-  another port.
-- **Two limits, in two places.** The request quota is HTTP and RPC middleware
-  (`identity/quota.ts`): it counts before the input is decoded. The write limit is the
-  handlers' (`issues/write-limit.ts`): it holds on every surface, MCP and the assistant
-  included.
-
 ## Where to look
 
-| To see                                                                  | Read                                                    |
-| ----------------------------------------------------------------------- | ------------------------------------------------------- |
-| How one request is authenticated, placed in a tenant, authorized        | `src/identity/authenticate.ts`, `src/routes.ts`         |
-| Two audiences on two ports over one set of services                     | `src/server.ts`, `src/routes.ts`, `test/routes.test.ts` |
-| Which actions each surface serves, and why one is no tool               | `src/Actions.ts`                                        |
-| A limit before decoding and a limit in the handlers                     | `src/identity/quota.ts`, `src/issues/write-limit.ts`    |
-| An image for a model and a client (an action), and for a page (a route) | `src/attachments/`                                      |
-| A caller the host names itself                                          | `src/stdio.ts`, `src/ops.ts`, `src/agent.ts`            |
-| A model loop behind a route, approvals answered in a later request      | `src/assistant/handlers.ts`, `src/routes.ts`            |
-| What to test in process and what over the wire                          | `test/issues/issues.test.ts`, `test/routes.test.ts`     |
+| To see                                                                  | Read                                                                                                     |
+| ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| How one request is authenticated, placed in a tenant, authorized        | `src/identity/authenticate.ts`, `src/workspaces/tenant.ts`, `src/identity/authorize.ts`, `src/routes.ts` |
+| Two audiences on two ports over one set of services                     | `src/server.ts`, `src/routes.ts`, `test/routes.test.ts`                                                  |
+| Which actions each surface serves, and why one is no tool               | `src/Actions.ts`                                                                                         |
+| A limit before decoding and a limit in the handlers                     | `src/identity/quota.ts`, `src/issues/write-limit.ts`                                                     |
+| An image for a model and a client (an action), and for a page (a route) | `src/attachments/`                                                                                       |
+| A caller the host names itself                                          | `src/stdio.ts`, `src/ops.ts`, `src/agent.ts`                                                             |
+| A model loop behind a route, approvals answered in a later request      | `src/assistant/handlers.ts`, `src/routes.ts`                                                             |
+| What to test in process and what over the wire                          | `test/issues/issues.test.ts`, `test/routes.test.ts`                                                      |
 
 ## Index
 
@@ -265,13 +244,13 @@ search for in the file.
 
 ### ActionCli
 
-| Export or option                                               | File                                       |
-| -------------------------------------------------------------- | ------------------------------------------ |
-| `remote`: `name`, `commands`, `client`                         | `src/cli.ts`                               |
-| `commands`: `stdin`, `positional`, `aliases`, `render`, `name` | `src/cli.ts`                               |
-| A client from `Config`, its credentials optional               | `src/cli.ts`                               |
-| `make`, with a trusted identity the host supplies              | `src/ops.ts`                               |
-| `logToStderr`                                                  | `src/cli.ts`, `src/ops.ts`, `src/stdio.ts` |
+| Export or option                                                              | File                                       |
+| ----------------------------------------------------------------------------- | ------------------------------------------ |
+| `remote`: `name`, `commands`, `client`                                        | `src/cli.ts`                               |
+| `commands`: `stdin`, `positional`, `aliases`, `render`, `name`, `description` | `src/cli.ts`                               |
+| A client from `Config`, its credentials optional                              | `src/cli.ts`                               |
+| `make`, with a trusted identity the host supplies                             | `src/ops.ts`                               |
+| `logToStderr`                                                                 | `src/cli.ts`, `src/ops.ts`, `src/stdio.ts` |
 
 ### Testing
 
@@ -304,8 +283,9 @@ Left out because this application has no honest place for them:
   [notes-service](../notes-service/) has two.
 - `ActionRpc.layer`'s `actions`, `Rpc.group`, and `ActionRpc.client`'s options.
 - A binding's other fields, `Http.actions`, `Http.error` and `Http.authentication`.
-- `ActionMcp`'s `path`, `description`, `websiteUrl`, `icons` and `extensions`; `fetchClient`'s
-  `fetch`.
+- `ActionMcp`'s `path`, `description`, `websiteUrl`, `icons`, `extensions`, `allowSubscriptions`
+  and `requestScoped` ([notes-service](../notes-service/) has it), and `McpCallError`;
+  `fetchClient`'s `fetch`.
 - `needsApproval` as an Effect reading the caller: the rule here is a boolean of the action.
 - `Action.InvalidInput.fromSchemaError`, the `Action.Refusal` and `Action.BuiltIn` schemas, and the
   helper types: `Action.Issue`, `Errors`, `Handlers`, `Client`, `AnyImplementation`,
@@ -314,5 +294,3 @@ Left out because this application has no honest place for them:
   `McpSchema.McpRequestContext`.
 - A tenant taken from a subdomain. The workspace is a header, so the OAuth resource the server
   publishes is one fixed URL.
-- A second way to the attachment's bytes for token holders: the download route takes the web
-  app's cookie alone, and an API client reads the image through `getAttachment`.

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

@@ -12,8 +12,7 @@ export const MemberActions = [WhoAmI, ...Issues, AttachImage, GetAttachment, ...
 
 /**
  * The MCP tools, for the HTTP endpoint and the stdio server alike. `attachImage` is left out:
- * a model should not carry an image's bytes as an argument. So is the assistant: it is a model
- * itself, and its tools are already here. An action added to a domain later is no tool until
- * it is listed here.
+ * listing it throws, since MCP takes no image as input. So is the assistant: it is a model
+ * itself, and its tools are already here.
  */
 export const Tools = [GetStatus, WhoAmI, ...Issues, GetAttachment] as const;

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

@@ -7,16 +7,15 @@ import { GetStatus } from "./workspaces/Workspaces.js";
 // The members' HTTP binding: every action at `POST /api/v1/<name>`. It is plain data and
 // imports no server code, so the server, the CLI, the SDK and a test all import this one value.
 // - `authentication`: how the protected actions' caller proves who it is. `getStatus` is public.
-// - `error`: what middleware around the routes may answer with, on any endpoint. Every endpoint
-//   declares it, so a client decodes a 429 as a typed `QuotaExceeded`.
+// - `error`: the quota middleware's, so a client decodes its 429 as a typed `QuotaExceeded`.
 export const Http = ActionHttp.make([GetStatus, ...MemberActions], {
   prefix: "/api/v1",
   authentication: Login,
   error: QuotaExceeded,
 });
 
-// The operators' binding: other actions, another identity, another descriptor. One binding has
-// one identity, so a second audience is a second binding, here served on a port of its own.
+// The operators' binding: other actions, another identity, another descriptor, served on a port
+// of its own.
 // The public `getStatus` is bound here too: one contract, one implementation, on both ports.
 export const AdminHttp = ActionHttp.make([GetStatus, ...Admin], {
   prefix: "/admin",

package/examples/kitchen-sink/src/admin/Admin.ts

@@ -10,7 +10,7 @@ export interface KeyOperator {
   readonly trusted: false;
 }
 
-/** What only a host supplies, on its own console. No verifier returns one, so no key names it. */
+/** What only a host supplies, on its own console. */
 export interface TrustedOperator {
   readonly id: string;
   readonly trusted: true;

package/examples/kitchen-sink/src/admin/authenticate.ts

@@ -4,9 +4,9 @@ import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
 import { type KeyOperator, OperatorKey } from "./Admin.js";
 import { keys } from "./keys.js";
 
-// Typed to return a `KeyOperator`, never the `Operator` union: whatever a key maps to, it
-// cannot be the trusted operator. The verifier receives what its scheme decodes, the header's
-// value, and needs no startup service, so it is passed as it is.
+// Typed to return a `KeyOperator`, never the `Operator` union (Admin.ts says why). The verifier
+// receives what its scheme decodes, the header's value, and needs no startup service, so it is
+// passed as it is.
 const verify = (
   key: Redacted.Redacted<string>,
 ): Effect.Effect<KeyOperator, Action.Unauthenticated> =>

package/examples/kitchen-sink/src/admin/authorize.ts

@@ -5,8 +5,7 @@ import { type Grant, Grants } from "./grants.js";
 
 // An authorizer built from a startup service, as a handler builder builds handlers: the
 // Effect yields `Grants` once, when the implementation is built, and the function it returns
-// reads the operator on every call. Written as a plain function yielding `Grants` per call, it
-// would make `Grants` a request-time requirement of every surface.
+// reads the operator on every call.
 export const authorize = Effect.gen(function* () {
   const grants = yield* Grants;
 

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

@@ -38,8 +38,8 @@ const program = Effect.gen(function* () {
 program.pipe(
   Effect.scoped,
   // No remote caller: this host names the member the assistant acts for, around the turn.
+  // DEMO ONLY: a real host names whoever asked.
   Effect.provideService(CurrentMember, members.ada),
-  // Startup services only. An identity provided here would be every caller's.
   Effect.provide(layer.pipe(Layer.provideMerge(Layer.merge(IssueStore.layerMemory, limiter)))),
   // DEMO ONLY: a scripted model. A real one is a provider's layer, in its place.
   Effect.provide(demoModel),

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

@@ -56,8 +56,6 @@ export const assistant = Action.implement(
         return {
           conversation,
           text: response.text,
-          // A refusal or a declared error is a result too, which the model has read. So is
-          // Effect's result for a call that did not run: left out.
           ran: results
             .filter(({ result }) => !didNotRun(result))
             .map(({ name, isFailure }) => ({ tool: name, failed: isFailure })),
@@ -78,10 +76,7 @@ export const assistant = Action.implement(
         Effect.provideService(LanguageModel.LanguageModel, model),
       );
 
-    // If the model fails after an approved call, the call has run and the `Chat` has recorded
-    // nothing of the turn: the same answer sent again would run the call again. So
-    // `Conversations` ends the conversation of a turn that fails, and the error says what
-    // may have happened.
+    // A failed turn says what may have run.
     const turn = (conversation: string, prompt: Prompt.RawInput) =>
       Effect.flatMap(CurrentMember, (member) =>
         conversations.turn(member, conversation, (chat) => converse(conversation, chat, prompt)),

package/examples/kitchen-sink/src/attachments/Attachments.ts

@@ -19,23 +19,19 @@ export class AttachmentNotFound extends Schema.TaggedError<AttachmentNotFound>()
   { httpApiStatus: 404 },
 ) {}
 
-// `Action.Image` is `{ data: Uint8Array, mimeType: string }`. In an input it is JSON on every
-// surface, the bytes in base64. This action is no MCP tool (see `Tools` in Actions.ts): a tool
-// call passes its arguments through the model's context, and MCP takes no image as input.
+// `Action.Image` is `{ data: Uint8Array, mimeType: string }`. In an input it is JSON over HTTP,
+// RPC and the CLI, the bytes in base64.
 export const AttachImage = Action.make("attachImage", {
   description: "Attach an image, such as a screenshot, to an issue.",
   input: { issue: Schema.String, name: Schema.String, image: Action.Image },
   success: Attachment,
-  // A write to an issue as a comment is: the errors those declare, the write limit's included.
   error: IssueWriteErrors,
   readOnly: false,
   caller: CurrentMember,
 });
 
-// `Action.Image` as a top-level field of the success: an MCP tool lifts it out of the result
-// into an image block the model sees as an image, beside the JSON of `{ attachment }`. HTTP,
-// RPC and the CLI send it as JSON. A model never reads a media field's own description, so the
-// action's description says what the image is.
+// `Action.Image` as a top-level field of the success, so an MCP tool shows the model the image
+// itself, beside the JSON of `{ attachment }`.
 export const GetAttachment = Action.make("getAttachment", {
   description: "Fetch an attachment: its name and size, and the image itself.",
   input: { id: Schema.String },

package/examples/kitchen-sink/src/attachments/download.ts

@@ -7,26 +7,23 @@ import { GetAttachment } from "./Attachments.js";
 import { AttachmentStore } from "./store.js";
 
 // A route of the host's own: `GET /attachments/<id>` answers the image's bytes, for an `<img>`
-// of the web app, which no action can (an action answers JSON). A descriptor covers action
-// routes alone, so this one takes `Authentication.protect(Session)`: router middleware that
-// verifies the page's cookie with the provider the web app's rpcs use, provides
-// `CurrentMember`, and answers a refusal the route fails with as an action's is answered. A
-// token holder has no use for it: `getAttachment` gives an API client the same image.
+// of the web app, which no action can (an action answers JSON), behind
+// `Authentication.protect(Session)`: the page's cookie, which the web app's rpcs use. A token
+// holder has no use for it: `getAttachment` gives an API client the same image.
 export const download = Layer.unwrap(
   Effect.map(AttachmentStore, (store) =>
     HttpRouter.add(
       "GET",
       "/attachments/:id",
       Effect.gen(function* () {
-        // The route states its own authorization. It reuses the rule of the action it mirrors.
+        // The rule of the action it mirrors.
         yield* authorize(GetAttachment);
 
         const member = yield* CurrentMember;
         const { id = "" } = yield* HttpRouter.params;
         const { image } = yield* store.get(member.workspace, id);
 
-        // Authentication marks what it covers `no-store` unless the route states its own
-        // caching. An attachment never changes, but it is one workspace's: `private`.
+        // An attachment never changes, but it is one workspace's: `private`.
         return HttpServerResponse.uint8Array(image.data, {
           contentType: image.mimeType,
           headers: {

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

@@ -16,11 +16,10 @@ export const attachments = Action.implement(
     return {
       attachImage: ({ issue, name, image }) =>
         Effect.gen(function* () {
-          // Input that decodes but cannot be served is the built-in `InvalidInput`, which
-          // every surface declares: no second error for bad input. Its `issues` name the
+          // Input that decodes but cannot be served is `InvalidInput`; its `issues` name the
           // field, as the library's own do for input that does not decode.
           if (!image.mimeType.startsWith("image/")) {
-            const message = `Expected an image, got ${image.mimeType}.`;
+            const message = "Expected an image MIME type.";
 
             return yield* new Action.InvalidInput({
               message,