feat: add conversation schemas

packages/freya-core/src/conversation.test.ts

@@ -4,7 +4,11 @@ import {
 	AttachmentType,
 	AttachmentPayload,
 	ContextSummaryPayload,
+	Conversation,
+	ConversationEntry,
+	ConversationEntryKind,
 	ConversationEntryMetadata,
+	ConversationEntryVisibility,
 	GenericObjectPayload,
 	UserMessagePayload,
 } from "./conversation"
@@ -143,4 +147,99 @@ describe("conversation entry schemas", () => {
 			}),
 		).toThrow()
 	})
+
+	test("parses conversation summaries", () => {
+		const conversation = Conversation.assert({
+			id: "11111111-1111-4111-8111-111111111111",
+			createdAt: "2026-06-17T09:30:00.000Z",
+			updatedAt: "2026-06-17T09:35:00.000Z",
+		})
+
+		expect(conversation.id).toBe("11111111-1111-4111-8111-111111111111")
+	})
+
+	test("parses kind-specific conversation entries", () => {
+		const userMessageEntry = ConversationEntry.assert({
+			id: "22222222-2222-4222-8222-222222222222",
+			conversationId: "11111111-1111-4111-8111-111111111111",
+			sequence: 1,
+			kind: ConversationEntryKind.UserMessage,
+			visibility: ConversationEntryVisibility.UserVisible,
+			fileId: null,
+			payload: {
+				role: "user",
+				parts: [{ type: "text", text: "hello" }],
+			},
+			metadata: {},
+			createdAt: "2026-06-17T09:30:00.000Z",
+		})
+		const attachmentEntry = ConversationEntry.assert({
+			id: "33333333-3333-4333-8333-333333333333",
+			conversationId: "11111111-1111-4111-8111-111111111111",
+			sequence: 2,
+			kind: ConversationEntryKind.Attachment,
+			visibility: ConversationEntryVisibility.UserVisible,
+			fileId: "44444444-4444-4444-8444-444444444444",
+			payload: {
+				role: "user",
+				name: "photo.png",
+				mimeType: "image/png",
+				attachmentType: AttachmentType.Image,
+			},
+			metadata: {},
+			createdAt: "2026-06-17T09:31:00.000Z",
+		})
+
+		expect(userMessageEntry.kind).toBe(ConversationEntryKind.UserMessage)
+		expect(attachmentEntry.kind).toBe(ConversationEntryKind.Attachment)
+	})
+
+	test("rejects conversation entries whose payload does not match the kind", () => {
+		expect(() =>
+			ConversationEntry.assert({
+				id: "22222222-2222-4222-8222-222222222222",
+				conversationId: "11111111-1111-4111-8111-111111111111",
+				sequence: 1,
+				kind: ConversationEntryKind.UserMessage,
+				visibility: ConversationEntryVisibility.UserVisible,
+				fileId: null,
+				payload: {
+					role: "assistant",
+					parts: [{ type: "text", text: "hello" }],
+				},
+				metadata: {},
+				createdAt: "2026-06-17T09:30:00.000Z",
+			}),
+		).toThrow()
+	})
+
+	test("rejects serialized conversations with extra fields", () => {
+		expect(() =>
+			Conversation.assert({
+				id: "11111111-1111-4111-8111-111111111111",
+				createdAt: "2026-06-17T09:30:00.000Z",
+				updatedAt: "2026-06-17T09:35:00.000Z",
+				title: "not yet part of the schema",
+			}),
+		).toThrow()
+	})
+
+	test("rejects file ids on non-attachment entries", () => {
+		expect(() =>
+			ConversationEntry.assert({
+				id: "22222222-2222-4222-8222-222222222222",
+				conversationId: "11111111-1111-4111-8111-111111111111",
+				sequence: 1,
+				kind: ConversationEntryKind.UserMessage,
+				visibility: ConversationEntryVisibility.UserVisible,
+				fileId: "44444444-4444-4444-8444-444444444444",
+				payload: {
+					role: "user",
+					parts: [{ type: "text", text: "hello" }],
+				},
+				metadata: {},
+				createdAt: "2026-06-17T09:30:00.000Z",
+			}),
+		).toThrow()
+	})
 })

packages/freya-core/src/conversation.ts

@@ -146,6 +146,19 @@ export const ConversationEntryMetadata = type({
 /** Metadata bag attached to a conversation entry. */
 export type ConversationEntryMetadata = typeof ConversationEntryMetadata.infer
 
+export const ToolCallPayload = type({
+	toolName: "string",
+})
+
+export type ToolCallPayload = typeof ToolCallPayload.infer
+
+export const ToolResultPayload = type({
+	toolName: "string",
+	ok: "boolean",
+})
+
+export type ToolResultPayload = typeof ToolResultPayload.infer
+
 /** Generic object payload used by operational entries. */
 export const GenericObjectPayload = type("Record<string, unknown>")
 
@@ -157,6 +170,8 @@ export const ConversationEntryPayload = type.or(
 	AssistantMessagePayload,
 	AttachmentPayload,
 	ContextSummaryPayload,
+	ToolCallPayload,
+	ToolResultPayload,
 	GenericObjectPayload,
 )
 
@@ -166,4 +181,118 @@ export type ConversationEntryPayload =
 	| AssistantMessagePayload
 	| AttachmentPayload
 	| ContextSummaryPayload
+	| ToolCallPayload
+	| ToolResultPayload
 	| GenericObjectPayload
+
+export const Conversation = type({
+	"+": "reject",
+	id: "string.uuid",
+	createdAt: "string.date.iso",
+	updatedAt: "string.date.iso",
+})
+
+export type Conversation = typeof Conversation.infer
+
+export const UserMessageConversationEntry = type({
+	"+": "reject",
+	id: "string.uuid",
+	conversationId: "string.uuid",
+	sequence: "number.integer >= 1",
+	kind: "'user_message'",
+	visibility: type.enumerated(...Object.values(ConversationEntryVisibility)),
+	fileId: "null",
+	payload: UserMessagePayload,
+	metadata: ConversationEntryMetadata,
+	createdAt: "string.date.iso",
+})
+
+export const AssistantMessageConversationEntry = type({
+	"+": "reject",
+	id: "string.uuid",
+	conversationId: "string.uuid",
+	sequence: "number.integer >= 1",
+	kind: "'assistant_message'",
+	visibility: type.enumerated(...Object.values(ConversationEntryVisibility)),
+	fileId: "null",
+	payload: AssistantMessagePayload,
+	metadata: ConversationEntryMetadata,
+	createdAt: "string.date.iso",
+})
+
+export const AttachmentConversationEntry = type({
+	"+": "reject",
+	id: "string.uuid",
+	conversationId: "string.uuid",
+	sequence: "number.integer >= 1",
+	kind: "'attachment'",
+	visibility: type.enumerated(...Object.values(ConversationEntryVisibility)),
+	fileId: "string.uuid",
+	payload: AttachmentPayload,
+	metadata: ConversationEntryMetadata,
+	createdAt: "string.date.iso",
+})
+
+export const ToolCallConversationEntry = type({
+	"+": "reject",
+	id: "string.uuid",
+	conversationId: "string.uuid",
+	sequence: "number.integer >= 1",
+	kind: "'tool_call'",
+	visibility: type.enumerated(...Object.values(ConversationEntryVisibility)),
+	fileId: "null",
+	payload: ToolCallPayload,
+	metadata: ConversationEntryMetadata,
+	createdAt: "string.date.iso",
+})
+
+export const ToolResultConversationEntry = type({
+	"+": "reject",
+	id: "string.uuid",
+	conversationId: "string.uuid",
+	sequence: "number.integer >= 1",
+	kind: "'tool_result'",
+	visibility: type.enumerated(...Object.values(ConversationEntryVisibility)),
+	fileId: "null",
+	payload: ToolResultPayload,
+	metadata: ConversationEntryMetadata,
+	createdAt: "string.date.iso",
+})
+
+export const ContextSummaryConversationEntry = type({
+	"+": "reject",
+	id: "string.uuid",
+	conversationId: "string.uuid",
+	sequence: "number.integer >= 1",
+	kind: "'context_summary'",
+	visibility: type.enumerated(...Object.values(ConversationEntryVisibility)),
+	fileId: "null",
+	payload: ContextSummaryPayload,
+	metadata: ConversationEntryMetadata,
+	createdAt: "string.date.iso",
+})
+
+export const SystemNoteConversationEntry = type({
+	"+": "reject",
+	id: "string.uuid",
+	conversationId: "string.uuid",
+	sequence: "number.integer >= 1",
+	kind: "'system_note'",
+	visibility: type.enumerated(...Object.values(ConversationEntryVisibility)),
+	fileId: "null",
+	payload: GenericObjectPayload,
+	metadata: ConversationEntryMetadata,
+	createdAt: "string.date.iso",
+})
+
+export const ConversationEntry = type.or(
+	UserMessageConversationEntry,
+	AssistantMessageConversationEntry,
+	AttachmentConversationEntry,
+	ToolCallConversationEntry,
+	ToolResultConversationEntry,
+	ContextSummaryConversationEntry,
+	SystemNoteConversationEntry,
+)
+
+export type ConversationEntry = typeof ConversationEntry.infer

packages/freya-core/src/index.ts

@@ -9,10 +9,15 @@ export { UnknownActionError } from "./action";
 // Conversation
 export {
   AssistantMessagePayload,
+  AssistantMessageConversationEntry,
   AttachmentPayload,
+  AttachmentConversationEntry,
   AttachmentType,
+  ContextSummaryConversationEntry,
   ContextSummary,
   ContextSummaryPayload,
+  Conversation,
+  ConversationEntry,
   ConversationEntryKind,
   ConversationEntryMetadata,
   ConversationEntryVisibility,
@@ -20,9 +25,15 @@ export {
   JsonMessagePart,
   MessagePart,
   ModelRunMetadata,
+  SystemNoteConversationEntry,
   TextMessagePart,
+  ToolCallConversationEntry,
+  ToolCallPayload,
+  ToolResultConversationEntry,
+  ToolResultPayload,
   UserMessagePayload,
   ConversationEntryPayload,
+  UserMessageConversationEntry,
 } from "./conversation";
 
 // Feed