@gjermundgaraba/effect-actions 0.11.0 → 0.13.0

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

@@ -0,0 +1,24 @@
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import { MemberActions } from "./Actions.js";
+import { Admin, OperatorKey } from "./admin/Admin.js";
+import { Login, QuotaExceeded } from "./identity/Identity.js";
+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`.
+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 public `getStatus` is bound here too: one contract, one implementation, on both ports.
+export const AdminHttp = ActionHttp.make([GetStatus, ...Admin], {
+  prefix: "/admin",
+  authentication: OperatorKey,
+});

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

@@ -0,0 +1,12 @@
+import * as ActionRpc from "@gjermundgaraba/effect-actions/ActionRpc";
+import { MemberActions } from "./Actions.js";
+import { QuotaExceeded, Session } from "./identity/Identity.js";
+
+// The web app's binding: the members' actions as Effect RPC, one native rpc per action, over
+// one WebSocket. Browser-safe, as the HTTP binding is. It names the other descriptor of the
+// same identity: a page proves who it is with its session cookie, which the browser sends on
+// the socket's upgrade. Its `error` is what the layer's middleware, the quota, fails with.
+export const Rpc = ActionRpc.make(MemberActions, {
+  authentication: Session,
+  error: QuotaExceeded,
+});

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

@@ -0,0 +1,59 @@
+import { Context, Schema } from "effect";
+import { HttpApiSecurity } from "effect/http-api";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
+import { Workspace, WorkspaceNotFound } from "../workspaces/Workspaces.js";
+
+/** What a verified operator key can name. */
+export interface KeyOperator {
+  readonly id: string;
+  readonly trusted: false;
+}
+
+/** What only a host supplies, on its own console. No verifier returns one, so no key names it. */
+export interface TrustedOperator {
+  readonly id: string;
+  readonly trusted: true;
+}
+
+/**
+ * The operators' identity, another audience than the members: its own service, its own
+ * descriptor, its own port. Typed in two parts, so the trusted one cannot arrive over the wire.
+ */
+export class Operator extends Context.Service<Operator, KeyOperator | TrustedOperator>()(
+  "tracker/Operator",
+) {}
+
+// How a remote operator proves it: an API key in a header, a native scheme named by
+// `security`. A key cannot step up, and has no OAuth discovery.
+export const OperatorKey = Authentication.make("tracker.OperatorKey", Operator, {
+  security: HttpApiSecurity.apiKey({ in: "header", key: "x-operator-key" }),
+});
+
+// What the two actions on one workspace share, their input and success included.
+const onWorkspace = {
+  caller: Operator,
+  input: { workspace: Schema.String },
+  success: Workspace,
+  error: WorkspaceNotFound,
+  readOnly: false,
+} as const;
+
+export const ListWorkspaces = Action.make("listWorkspaces", {
+  description: "List every workspace and whether it is suspended.",
+  success: { workspaces: Schema.Array(Workspace) },
+  readOnly: true,
+  caller: Operator,
+});
+
+export const SuspendWorkspace = Action.make("suspendWorkspace", {
+  ...onWorkspace,
+  description: "Suspend a workspace: its members are refused on the public port until resumed.",
+});
+
+export const ResumeWorkspace = Action.make("resumeWorkspace", {
+  ...onWorkspace,
+  description: "Resume a suspended workspace.",
+});
+
+export const Admin = [ListWorkspaces, SuspendWorkspace, ResumeWorkspace] as const;

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

@@ -0,0 +1,18 @@
+import { Effect, Redacted } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+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.
+const verify = (
+  key: Redacted.Redacted<string>,
+): Effect.Effect<KeyOperator, Action.Unauthenticated> =>
+  Effect.fromNullishOr(keys.get(Redacted.value(key))).pipe(
+    Effect.mapError(() => new Action.Unauthenticated({ message: "Unknown operator key." })),
+  );
+
+// Server only: `OperatorKey`'s provider, which the admin port's routes require.
+export const authenticateOperator = Authentication.layer(OperatorKey, verify);

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

@@ -0,0 +1,27 @@
+import { Effect } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { Operator } from "./Admin.js";
+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.
+export const authorize = Effect.gen(function* () {
+  const grants = yield* Grants;
+
+  return (action: Action.Any) =>
+    Effect.gen(function* () {
+      const operator = yield* Operator;
+
+      // The one rule admits the console's operator too: no surface has a bypass of its own.
+      if (operator.trusted) return;
+
+      const grant: Grant = action.readOnly ? "workspaces:read" : "workspaces:suspend";
+
+      // No `scopes`: a key cannot be re-authorized, so this is a plain 403.
+      if (!(yield* grants.of(operator.id)).includes(grant)) {
+        return yield* new Action.Forbidden({ message: `Requires the ${grant} grant.` });
+      }
+    });
+});

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

@@ -0,0 +1,22 @@
+import { Context, Effect, Layer } from "effect";
+
+export type Grant = "workspaces:read" | "workspaces:suspend";
+
+/**
+ * What each operator may do. An API key carries no scopes, so the grants are kept here, on the
+ * server, and the authorizer looks them up.
+ */
+export class Grants extends Context.Service<
+  Grants,
+  { readonly of: (operator: string) => Effect.Effect<ReadonlyArray<Grant>> }
+>()("tracker/Grants") {
+  // DEMO ONLY: fixed grants. A real application reads them from its database.
+  static readonly layerDemo = Layer.sync(Grants, () => {
+    const grants = new Map<string, ReadonlyArray<Grant>>([
+      ["ops", ["workspaces:read", "workspaces:suspend"]],
+      ["support", ["workspaces:read"]],
+    ]);
+
+    return Grants.of({ of: (operator) => Effect.sync(() => grants.get(operator) ?? []) });
+  });
+}

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

@@ -0,0 +1,21 @@
+import { Effect } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { WorkspaceRegistry } from "../workspaces/registry.js";
+import { Admin } from "./Admin.js";
+import { authorize } from "./authorize.js";
+
+// The operators' actions. `authorize` is an Effect that builds the rule, so this
+// implementation owes `Grants` at startup, beside the registry its builder yields.
+export const admin = Action.implement(
+  Admin,
+  Effect.gen(function* () {
+    const registry = yield* WorkspaceRegistry;
+
+    return {
+      listWorkspaces: () => Effect.map(registry.list, (workspaces) => ({ workspaces })),
+      suspendWorkspace: ({ workspace }) => registry.setSuspended(workspace, true),
+      resumeWorkspace: ({ workspace }) => registry.setSuspended(workspace, false),
+    };
+  }),
+  { authorize },
+);

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

@@ -0,0 +1,8 @@
+import type { KeyOperator } from "./Admin.js";
+
+// DEMO ONLY: two fixed operator keys. A real application has no such table: it stores a hash
+// of each key it issued, and looks the operator up by it.
+export const keys = new Map<string, KeyOperator>([
+  ["ops-key", { id: "ops", trusted: false }],
+  ["support-key", { id: "support", trusted: false }],
+]);

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

@@ -0,0 +1,47 @@
+import { NodeRuntime } from "@effect/platform-node";
+import { Console, Effect, Layer } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { demoModel } from "./assistant/demo-model.js";
+import { CurrentMember } from "./identity/Identity.js";
+import { members } from "./identity/members.js";
+import { layer, triage } from "./issues/assistant.js";
+import { issues } from "./issues/handlers.js";
+import { IssueStore } from "./issues/store.js";
+import { limiter } from "./memory.js";
+
+// Entrypoint: `node --import tsx examples/kitchen-sink/src/agent.ts`.
+// The assistant as a local program: a model calling the issue actions as tools, in process.
+// The server serves the same tools behind a route, a turn per request: assistant/handlers.ts.
+
+const program = Effect.gen(function* () {
+  // Code of your own calls the implementation typed, with `Action.client`: the same decoding,
+  // `authorize` and handler, with no transport. The store is memory, so file an issue first.
+  const tracker = yield* Action.client(issues);
+
+  yield* tracker.createIssue({ title: "Crash on save", body: "Stack trace attached." });
+
+  const turn = yield* triage("Close what is done.");
+
+  // The read ran: its result is here. The write did not: it waits for the member's approval,
+  // which a host answers in the next turn, as assistant/handlers.ts does.
+  for (const { name, encodedResult } of turn.toolResults) {
+    yield* Console.log(`${name} answered`, encodedResult);
+  }
+
+  for (const part of turn.content) {
+    if (part.type === "tool-approval-request") {
+      yield* Console.log(`Call ${part.toolCallId} waits for approval.`);
+    }
+  }
+});
+
+program.pipe(
+  Effect.scoped,
+  // No remote caller: this host names the member the assistant acts for, around the turn.
+  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),
+  NodeRuntime.runMain,
+);

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

@@ -0,0 +1,82 @@
+import { Schema } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { CurrentMember } from "../identity/Identity.js";
+
+// The assistant behind a route: a model working on the issues with the tools of
+// issues/assistant.ts, one request per turn of a conversation. A request starts a turn and its
+// answer is the turn's end: the model's text, or the calls that wait for the member's approval.
+
+/**
+ * What a turn ended with. A call in `ran` ran in this turn, `failed` where it was refused or
+ * failed with a declared error; one the member denied, or one in a reply the provider cut
+ * short, did not run and is not listed. A call in `waiting` has not run: `answerAssistant`
+ * decides it. `waiting` holds every open request of the conversation: one this turn
+ * asked, and one an earlier answer left unanswered, until it is answered.
+ */
+export const Turn = Schema.Struct({
+  conversation: Schema.String,
+  text: Schema.String,
+  ran: Schema.Array(Schema.Struct({ tool: Schema.String, failed: Schema.Boolean })),
+  waiting: Schema.Array(
+    Schema.Struct({
+      approvalId: Schema.String,
+      tool: Schema.String,
+      // The arguments the model gave the call, as JSON text: what the member approves.
+      arguments: Schema.String,
+    }),
+  ),
+});
+
+// Another member's conversation is not found either: an id tells nothing of who holds it.
+export class ConversationNotFound extends Schema.TaggedError<ConversationNotFound>()(
+  "ConversationNotFound",
+  { conversation: Schema.String },
+  { httpApiStatus: 404 },
+) {}
+
+// The model failed in the middle of a turn. The conversation is over: its history holds
+// nothing of that turn, so it no longer says which calls ran.
+export class AssistantFailed extends Schema.TaggedError<AssistantFailed>()(
+  "AssistantFailed",
+  { message: Schema.String },
+  { httpApiStatus: 502 },
+) {}
+
+export const AskAssistant = Action.make("askAssistant", {
+  description:
+    "Ask the assistant about your workspace's issues, in a new conversation or one of yours.",
+  input: {
+    prompt: Schema.String.check(Schema.isMinLength(1)),
+    conversation: Schema.optional(Schema.String).annotate({
+      description: "The conversation to continue. Left out, a new one starts.",
+    }),
+  },
+  success: Turn,
+  error: [ConversationNotFound, AssistantFailed],
+  readOnly: false,
+  caller: CurrentMember,
+});
+
+export const AnswerAssistant = Action.make("answerAssistant", {
+  description: "Approve or deny the calls a turn of your conversation waits for.",
+  input: {
+    conversation: Schema.String,
+    // Each request once. Effect acts on every answer it is given: an `approvalId` approved
+    // twice in one request would run its call twice.
+    answers: Schema.Array(
+      Schema.Struct({ approvalId: Schema.String, approved: Schema.Boolean }),
+    ).check(
+      Schema.makeFilter(
+        (answers) =>
+          new Set(answers.map(({ approvalId }) => approvalId)).size === answers.length ||
+          "Answer each approvalId once",
+      ),
+    ),
+  },
+  success: Turn,
+  error: [ConversationNotFound, AssistantFailed],
+  readOnly: false,
+  caller: CurrentMember,
+});
+
+export const Assistant = [AskAssistant, AnswerAssistant] as const;

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

@@ -0,0 +1,71 @@
+import { Context, Effect, Layer, Semaphore } from "effect";
+import { Chat } from "effect/ai";
+import type { Member } from "../identity/Identity.js";
+import { ConversationNotFound } from "./Assistant.js";
+
+interface Conversation {
+  /** Effect's `Chat`: the history a model reads, in which an approval's answer finds its request. */
+  readonly chat: Chat.Chat;
+  readonly lock: Semaphore.Semaphore;
+}
+
+/**
+ * Where conversations are kept between requests, each with the member it belongs to. A turn
+ * names the member, so only its owner reaches a conversation: an approval is acted on as the
+ * turn's caller, and must come from the member who was asked.
+ */
+export class Conversations extends Context.Service<
+  Conversations,
+  {
+    /** Start a conversation of `owner`'s, and return its id. */
+    readonly open: (owner: Member) => Effect.Effect<string>;
+    /**
+     * Run one turn on a conversation's `Chat`. One turn runs at a time, and a turn that fails or
+     * is interrupted ends its conversation: the `Chat` records a turn only when it succeeds, so
+     * after any other end its history no longer says which calls ran, and an approval answered
+     * in that turn would run again.
+     */
+    readonly turn: <A, E, R>(
+      owner: Member,
+      id: string,
+      run: (chat: Chat.Chat) => Effect.Effect<A, E, R>,
+    ) => Effect.Effect<A, E | ConversationNotFound, R>;
+  }
+>()("tracker/Conversations") {
+  // DEMO ONLY: memory, lost when the process stops and never trimmed. A real store keeps each
+  // history where every instance reads it, `chat.exportJson` to save and `Chat.fromJson` to load.
+  static readonly layerMemory = Layer.sync(Conversations, () => {
+    const kept = new Map<string, Conversation>();
+
+    // A member is a person in a workspace, and an id is unguessable: both are in the key, as
+    // JSON, which keeps its three parts apart whatever they hold.
+    const keyOf = (owner: Member, id: string) => JSON.stringify([owner.workspace, owner.id, id]);
+
+    // Read when it runs, not when it is written: the second lookup of a turn runs under the lock.
+    const find = (key: string, id: string) =>
+      Effect.suspend(() => Effect.fromNullishOr(kept.get(key))).pipe(
+        Effect.mapError(() => new ConversationNotFound({ conversation: id })),
+      );
+
+    return Conversations.of({
+      open: Effect.fn("Conversations.open")(function* (owner) {
+        const id = crypto.randomUUID();
+
+        kept.set(keyOf(owner, id), { chat: yield* Chat.empty, lock: yield* Semaphore.make(1) });
+
+        return id;
+      }),
+      turn: (owner, id, run) => {
+        const key = keyOf(owner, id);
+
+        return Effect.flatMap(find(key, id), ({ lock }) =>
+          // Looked up again once the lock is held: a turn that waited for one that failed
+          // must find its conversation gone, not run on the history that turn left behind.
+          Effect.flatMap(find(key, id), ({ chat }) =>
+            Effect.onError(run(chat), () => Effect.sync(() => kept.delete(key))),
+          ).pipe(lock.withPermits(1)),
+        );
+      },
+    });
+  });
+}

package/examples/kitchen-sink/src/assistant/demo-model.ts

@@ -0,0 +1,33 @@
+import { Layer, Effect, Stream } from "effect";
+import { LanguageModel } from "effect/ai";
+
+// DEMO ONLY: a model that needs no API key. Asked by a person, it lists the open issues and
+// closes ACME-1; once its tools have answered, it says so. A real one is a provider's layer,
+// such as `AnthropicLanguageModel.model(...)`, provided in its place. Each call has an id of
+// its own, as a provider's has: Effect finds the call an approval is about by that id, so one
+// used twice in a conversation would run another call than the member was shown, or none.
+export const demoModel = Layer.effect(
+  LanguageModel.LanguageModel,
+  LanguageModel.make({
+    generateText: ({ prompt }) =>
+      Effect.sync(() =>
+        prompt.content.at(-1)?.role === "tool"
+          ? [{ type: "text", text: "Done." } as const]
+          : [
+              {
+                type: "tool-call",
+                id: crypto.randomUUID(),
+                name: "listIssues",
+                params: { status: "open" },
+              } as const,
+              {
+                type: "tool-call",
+                id: crypto.randomUUID(),
+                name: "closeIssue",
+                params: { id: "ACME-1" },
+              } as const,
+            ],
+      ),
+    streamText: () => Stream.empty,
+  }),
+);

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

@@ -0,0 +1,126 @@
+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";
+import { Conversations } from "./conversations.js";
+
+// A model that keeps calling tools is asked this many times in one turn, and no more.
+const requestsPerTurn = 6;
+
+type Response = LanguageModel.GenerateTextResponse<typeof toolkit.tools, "opaque">;
+
+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. Left out of `ran` below, which lists the calls that
+// ran.
+const didNotRun = Schema.is(
+  Schema.Struct({ type: Schema.Literals(["execution-denied", "execution-interrupted"]) }),
+);
+
+const callsToRead = (response: Response) =>
+  response.toolCalls.length > 0 && approvalsOf(response).length === 0;
+
+// 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`. 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* () {
+    const tools = yield* toolkit;
+    const model = yield* LanguageModel.LanguageModel;
+    const conversations = yield* Conversations;
+
+    const converse = (conversation: string, chat: Chat.Chat, prompt: Prompt.RawInput) =>
+      Effect.gen(function* () {
+        // One `generateText` is one request to the model: its tool calls run, and their
+        // results come back unread. The model is asked again, with nothing new, while it
+        // called tools and none of them waits for approval. Continue on tool calls, never on
+        // tool results: the turn answering an approval holds the approved call's result and
+        // the model's reply to it.
+        let response = yield* chat.generateText({ prompt, toolkit: tools });
+        const results = [...response.toolResults];
+
+        for (let asked = 1; asked < requestsPerTurn && callsToRead(response); asked++) {
+          response = yield* chat.generateText({ prompt: [], toolkit: tools });
+          results.push(...response.toolResults);
+        }
+
+        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 })),
+          // 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.
+        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.
+    const turn = (conversation: string, prompt: Prompt.RawInput) =>
+      Effect.flatMap(CurrentMember, (member) =>
+        conversations.turn(member, conversation, (chat) => converse(conversation, chat, prompt)),
+      ).pipe(
+        Effect.catchTag("AiError", () =>
+          Effect.fail(
+            new AssistantFailed({
+              message:
+                "The model failed and this conversation has ended. A call you approved in this turn may have run: read the issue before asking again.",
+            }),
+          ),
+        ),
+      );
+
+    return {
+      askAssistant: ({ prompt, conversation }) =>
+        conversation === undefined
+          ? Effect.flatMap(Effect.flatMap(CurrentMember, conversations.open), (opened) =>
+              turn(opened, prompt),
+            )
+          : 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 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, [
+          {
+            role: "tool",
+            content: answers.map(({ approvalId, approved }) => ({
+              type: "tool-approval-response" as const,
+              approvalId,
+              approved,
+            })),
+          },
+        ]),
+    };
+  }),
+  // Any member may ask. What the assistant may do for them is each tool's rule, not this one:
+  // a member without the write scope gets the tool's refusal as a result the model reads.
+  { authorize: Action.allowAll },
+);

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

@@ -0,0 +1,48 @@
+import { Schema } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { CurrentMember } from "../identity/Identity.js";
+import { IssueWriteErrors } from "../issues/Issues.js";
+
+export const Attachment = Schema.Struct({
+  id: Schema.String,
+  issue: Schema.String,
+  name: Schema.String,
+  mimeType: Schema.String,
+  size: Schema.Finite,
+});
+
+export type Attachment = typeof Attachment.Type;
+
+export class AttachmentNotFound extends Schema.TaggedError<AttachmentNotFound>()(
+  "AttachmentNotFound",
+  { id: Schema.String },
+  { 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.
+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.
+export const GetAttachment = Action.make("getAttachment", {
+  description: "Fetch an attachment: its name and size, and the image itself.",
+  input: { id: Schema.String },
+  success: { attachment: Attachment, image: Action.Image },
+  error: AttachmentNotFound,
+  readOnly: true,
+  caller: CurrentMember,
+});
+
+export const Attachments = [AttachImage, GetAttachment] as const;

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

@@ -0,0 +1,49 @@
+import { Effect, Layer } from "effect";
+import { HttpRouter, HttpServerResponse } from "effect/http";
+import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
+import { authorize } from "../identity/authorize.js";
+import { CurrentMember, Session } from "../identity/Identity.js";
+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.
+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.
+        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`.
+        return HttpServerResponse.uint8Array(image.data, {
+          contentType: image.mimeType,
+          headers: {
+            "cache-control": "private, max-age=31536000, immutable",
+            // What a member uploaded is served from the application's own origin, and an image
+            // can be a document: an SVG opened by its URL, not in an `<img>`, runs its scripts
+            // as the member reading it. `sandbox` gives it no origin and no scripts, and
+            // `nosniff` keeps the browser to the type stated.
+            "content-security-policy": "sandbox",
+            "x-content-type-options": "nosniff",
+          },
+        });
+      }).pipe(
+        Effect.catchTag("AttachmentNotFound", () =>
+          Effect.succeed(HttpServerResponse.empty({ status: 404 })),
+        ),
+      ),
+    ).pipe(Layer.provide(Authentication.protect(Session).layer)),
+  ),
+);