feat(core): upload files to a chat, and serve them back

packages/contracts/src/attachments.ts

@@ -0,0 +1,45 @@
+import { Schema } from "effect";
+import { uuidSchema } from "./uuid.ts";
+
+/** The largest file a person can attach to a message, in bytes. */
+export const MAX_ATTACHMENT_BYTES = 30 * 1024 * 1024;
+
+/** The most files one message can carry, and so the most a person can have uploaded and not yet sent. */
+export const MAX_ATTACHMENTS_PER_MESSAGE = 20;
+
+const MAX_ATTACHMENT_NAME_CHARACTERS = 255;
+
+/** A file's name as the person's computer had it, shown beside it and offered when it is downloaded. */
+export const attachmentNameSchema = Schema.Trim.check(
+	Schema.isMinLength(1),
+	Schema.isMaxLength(MAX_ATTACHMENT_NAME_CHARACTERS),
+	// Control characters would break the name out of a download's header.
+	Schema.isPattern(/^[^\p{Cc}]*$/u),
+);
+
+/**
+ * A media type such as `image/png` or `text/plain; charset=utf-8`, served
+ * back as the file's `Content-Type`, so nothing in it can break out of that
+ * header.
+ */
+export const mediaTypeSchema = Schema.Trim.check(
+	Schema.isMaxLength(255),
+	Schema.isPattern(/^[\w.+-]+\/[\w.+-]+(\s*;\s*[\w.+-]+=("[^"\r\n]*"|[\w.+-]+))*$/),
+);
+
+export const uploadAttachmentQuerySchema = Schema.Struct({
+	name: attachmentNameSchema,
+	/** The file's media type, when the uploader knows it; otherwise it is taken from the name. */
+	type: Schema.optional(mediaTypeSchema),
+});
+
+/** A file uploaded to a chat, ready to attach to a message. */
+export const uploadedAttachmentSchema = Schema.Struct({
+	id: uuidSchema,
+	name: attachmentNameSchema,
+	contentType: mediaTypeSchema,
+	/** In bytes. */
+	size: Schema.Int,
+});
+
+export type UploadedAttachment = typeof uploadedAttachmentSchema.Type;

packages/contracts/src/http/groups/chats.ts

@@ -1,5 +1,6 @@
 import { Schema } from "effect";
 import { HttpApiEndpoint, HttpApiGroup, HttpApiSchema } from "effect/unstable/httpapi";
+import { uploadAttachmentQuerySchema, uploadedAttachmentSchema } from "../../attachments.ts";
 import {
 	activityFeedSchema,
 	approvalInboxSchema,
@@ -14,7 +15,7 @@ import {
 } from "../../chats.ts";
 import { messageSchema, newMessageSchema } from "../../threads.ts";
 import { workspaceIdOrSlugSchema } from "../../workspaces.ts";
-import { BadRequest, Conflict, refused } from "../errors.ts";
+import { BadRequest, Conflict, PayloadTooLarge, refused } from "../errors.ts";
 import { Session } from "../middleware.ts";
 
 export class ChatsApi extends HttpApiGroup.make("chats")
@@ -69,5 +70,22 @@ export class ChatsApi extends HttpApiGroup.make("chats")
 			success: messageSchema.pipe(HttpApiSchema.status(201)),
 			error: [BadRequest, Conflict, ...refused],
 		}),
+		/**
+		 * Uploads a file to attach to a message the caller then sends. The body
+		 * is the file's bytes, and `Content-Type` its media type.
+		 */
+		HttpApiEndpoint.post("uploadFile", "/chats/:chatId/files", {
+			params: { chatId: Schema.String },
+			query: uploadAttachmentQuerySchema,
+			payload: Schema.Uint8Array.pipe(HttpApiSchema.asUint8Array()),
+			success: uploadedAttachmentSchema.pipe(HttpApiSchema.status(201)),
+			error: [BadRequest, PayloadTooLarge, Conflict, ...refused],
+		}),
+		/** A file attached to a message in the chat, with its own media type. */
+		HttpApiEndpoint.get("file", "/chats/:chatId/files/:fileId", {
+			params: { chatId: Schema.String, fileId: Schema.String },
+			success: HttpApiSchema.StreamUint8Array(),
+			error: refused,
+		}),
 	)
 	.middleware(Session) {}

packages/contracts/src/index.ts

@@ -6,6 +6,7 @@ export * from "./agents.ts";
 export * from "./api.ts";
 export * from "./appearance.ts";
 export * from "./artifacts.ts";
+export * from "./attachments.ts";
 export * from "./built-in-tools.ts";
 export * from "./chats.ts";
 export * from "./connections.ts";

packages/core/drizzle/20261014032053_chat_attachments/migration.sql

@@ -0,0 +1,25 @@
+-- Edited by hand, keep when regenerating: `kind` has no default in the schema,
+-- so drizzle-kit writes this column without one, which fails on a table that
+-- already has rows. The DEFAULT here fills in the rows already there, all tool
+-- results, and the last statement drops it again.
+ALTER TABLE "thread_file" ADD COLUMN "kind" text DEFAULT 'tool_result' NOT NULL;--> statement-breakpoint
+ALTER TABLE "thread_file" ADD COLUMN "name" text;--> statement-breakpoint
+ALTER TABLE "thread_file" ADD COLUMN "uploader_id" uuid;--> statement-breakpoint
+ALTER TABLE "thread_file" ADD COLUMN "message_id" uuid;--> statement-breakpoint
+ALTER TABLE "thread_file" ADD COLUMN "position" integer;--> statement-breakpoint
+CREATE INDEX "thread_file_message_idx" ON "thread_file" ("message_id");--> statement-breakpoint
+ALTER TABLE "thread_file" ADD CONSTRAINT "thread_file_uploader_id_user_id_fkey" FOREIGN KEY ("uploader_id") REFERENCES "user"("id") ON DELETE SET NULL;--> statement-breakpoint
+ALTER TABLE "thread_file" ADD CONSTRAINT "thread_file_message_id_message_id_fkey" FOREIGN KEY ("message_id") REFERENCES "message"("id") ON DELETE CASCADE;--> statement-breakpoint
+ALTER TABLE "thread_file" ADD CONSTRAINT "thread_file_kind_valid" CHECK ("kind" in ('tool_result', 'upload', 'agent_attachment'));--> statement-breakpoint
+ALTER TABLE "thread_file" ADD CONSTRAINT "thread_file_source_valid" CHECK (case "kind"
+				when 'upload' then "name" is not null and "tool_call_id" is null
+					and ("message_id" is null) = ("position" is null)
+				when 'agent_attachment' then "name" is not null and "tool_call_id" is null
+					and "uploader_id" is null and "message_id" is not null
+					and "position" is not null
+				else "name" is null and "uploader_id" is null and "message_id" is null
+					and "position" is null
+			end);--> statement-breakpoint
+-- Edited by hand, keep when regenerating: drops the DEFAULT the first statement
+-- added to fill in existing rows, so every new row says its kind.
+ALTER TABLE "thread_file" ALTER COLUMN "kind" DROP DEFAULT;