feat: add eas-cli to flake (#146)

AGENTS.md

@@ -39,4 +39,13 @@ Use Bun exclusively. Do not use npm or yarn.
 
 - Branch: `feat/<task>`, `fix/<task>`, `ci/<task>`, etc.
 - Commits: conventional commit format, title <= 50 chars
-- Signing: If `GPG_PRIVATE_KEY_PASSPHRASE` env var is available, use it to sign commits with `git commit -S`
+
+## Nix
+
+Use the Nix dev shell for project commands by default.
+
+- Run repo tooling through `nix develop -c`, e.g. `nix develop -c bun test`.
+- Use Bun exclusively inside the Nix shell.
+- Do not use host `bun`, `node`, `tsc`, or package binaries for project tasks unless explicitly checking host behavior.
+- Simple inspection commands like `rg`, `sed`, `ls`, and `git status` may run outside Nix.
+- While `flake.nix` is untracked, use `nix develop path:. -c <command>`.

apps/agent-test-cli/package.json

@@ -7,5 +7,9 @@
 		"format": "oxfmt --write .",
 		"start": "bun run src/agent-test-cli.ts",
 		"typecheck": "bun tsc --noEmit"
+	},
+	"dependencies": {
+		"@freya/agent-protocol": "workspace:*",
+		"@nym.sh/jrpc": "^0.1.0"
 	}
 }

apps/agent-test-cli/src/agent-test-cli.ts

@@ -1,3 +1,13 @@
+import type {
+	AgentClientApi,
+	AgentEvent,
+	AgentServerApi,
+	SendMessageResult,
+} from "@freya/agent-protocol"
+import type { JrpcChannel, JrpcMessage, JsonRpcMessage } from "@nym.sh/jrpc"
+
+import { JsonRpcClient, JsonRpcServer } from "@nym.sh/jrpc"
+
 type JsonObject = Record<string, unknown>
 
 interface AuthUser {
@@ -15,10 +25,6 @@ interface AuthSession {
 	}
 }
 
-interface QueryResponse {
-	message: string
-}
-
 interface QueryToolDefinition {
 	name: string
 	label: string
@@ -60,6 +66,219 @@ class CookieJar {
 	}
 }
 
+class AgentWebSocketSession implements AgentClientApi {
+	private readonly channel: WebSocketJrpcChannel
+	private readonly client: JsonRpcClient<AgentServerApi>
+	private readonly server: JsonRpcServer<AgentClientApi>
+	private conversationId: string | undefined
+	private responseHadText = false
+
+	private constructor(channel: WebSocketJrpcChannel) {
+		this.channel = channel
+		this.client = new JsonRpcClient<AgentServerApi>(channel)
+		this.server = new JsonRpcServer<AgentClientApi>(
+			{
+				notify: this.notify.bind(this),
+			},
+			channel,
+		)
+	}
+
+	static async connect(backendUrl: string, cookies: CookieJar): Promise<AgentWebSocketSession> {
+		const channel = new WebSocketJrpcChannel(agentWebSocketUrl(backendUrl), cookies.header())
+		const session = new AgentWebSocketSession(channel)
+
+		try {
+			await channel.waitUntilOpen()
+			void session.server.start().catch((err: unknown) => {
+				if (!channel.isClosed()) {
+					console.error(`\nWebSocket JSON-RPC failed: ${formatError(err)}\n`)
+				}
+			})
+			await session.client.call("ping")
+		} catch (err) {
+			channel.close()
+			throw err
+		}
+
+		return session
+	}
+
+	async ask(message: string): Promise<void> {
+		this.responseHadText = false
+
+		const result = await this.sendMessage(message)
+		if (result.conversationId) {
+			this.conversationId = result.conversationId
+		}
+
+		if (!this.responseHadText) {
+			console.log(`\nagent> ${result.message || "(no message)"}`)
+		}
+		console.log("")
+	}
+
+	notify(event: AgentEvent): void {
+		switch (event.type) {
+			case "conversation_started":
+				this.conversationId = event.conversationId
+				break
+			case "message_created":
+				this.printMessage(event.text)
+				break
+			case "tool_started":
+				console.log(`\ntool> ${event.toolName} started`)
+				break
+			case "tool_finished":
+				console.log(`tool> ${event.toolName} ${event.ok ? "finished" : "failed"}`)
+				break
+			case "message_finished":
+				break
+			case "message_failed":
+				console.log(`\nagent! ${event.error}`)
+				break
+		}
+	}
+
+	describeConversation(): string {
+		return this.conversationId ? `Conversation: ${this.conversationId}` : "No conversation yet."
+	}
+
+	close(): void {
+		this.channel.close()
+	}
+
+	private async sendMessage(message: string): Promise<SendMessageResult> {
+		return this.client.call("sendMessage", message)
+	}
+
+	private printMessage(text: string): void {
+		if (text === "") return
+
+		console.log(`\nagent> ${text}`)
+		this.responseHadText = true
+	}
+}
+
+class WebSocketJrpcChannel implements JrpcChannel {
+	private readonly ws: WebSocket
+	private readonly opened: Promise<void>
+	private closed = false
+	private openedOnce = false
+	private queue: JrpcMessage[] = []
+	private waiters: Array<(result: IteratorResult<JrpcMessage, void>) => void> = []
+
+	constructor(url: string, cookieHeader?: string) {
+		this.ws = new WebSocket(url, createWebSocketOptions(cookieHeader))
+		this.opened = new Promise((resolve, reject) => {
+			this.ws.onopen = () => {
+				this.openedOnce = true
+				resolve()
+			}
+			this.ws.onerror = () => {
+				if (!this.openedOnce) {
+					reject(new Error(`Could not connect to ${url}`))
+				}
+			}
+			this.ws.onclose = (event) => {
+				if (!this.openedOnce) {
+					reject(new Error(formatWebSocketClose(url, event)))
+				}
+				this.close()
+			}
+		})
+		this.ws.onmessage = (event) => {
+			this.receive(event.data)
+		}
+	}
+
+	waitUntilOpen(): Promise<void> {
+		return this.opened
+	}
+
+	isClosed(): boolean {
+		return this.closed
+	}
+
+	async send(msg: JsonRpcMessage): Promise<void> {
+		await this.opened
+		if (this.closed || this.ws.readyState !== WebSocket.OPEN) {
+			throw new Error("JSON-RPC WebSocket channel is closed")
+		}
+
+		this.ws.send(JSON.stringify(msg))
+	}
+
+	async next(): Promise<IteratorResult<JrpcMessage, void>> {
+		const msg = this.queue.shift()
+		if (msg) {
+			return { done: false, value: msg }
+		}
+
+		if (this.closed) {
+			return { done: true, value: undefined }
+		}
+
+		return new Promise((resolve) => {
+			this.waiters.push(resolve)
+		})
+	}
+
+	async return(): Promise<IteratorResult<JrpcMessage, void>> {
+		this.close()
+		return { done: true, value: undefined }
+	}
+
+	async throw(error?: unknown): Promise<IteratorResult<JrpcMessage, void>> {
+		this.close()
+		throw error
+	}
+
+	async [Symbol.asyncDispose](): Promise<void> {
+		await this.return()
+	}
+
+	close(): void {
+		if (this.closed) return
+
+		this.closed = true
+		for (const resolve of this.waiters.splice(0)) {
+			resolve({ done: true, value: undefined })
+		}
+
+		if (this.ws.readyState === WebSocket.CONNECTING || this.ws.readyState === WebSocket.OPEN) {
+			this.ws.close()
+		}
+	}
+
+	[Symbol.asyncIterator](): AsyncGenerator<JrpcMessage, void, unknown> {
+		return this
+	}
+
+	private receive(message: unknown): void {
+		const parsed = parseJrpcMessage(message)
+		if (!parsed) {
+			this.ws.close(1003, "Invalid JSON-RPC message")
+			this.close()
+			return
+		}
+
+		this.push(parsed)
+	}
+
+	private push(msg: JrpcMessage): void {
+		if (this.closed) return
+
+		const resolve = this.waiters.shift()
+		if (resolve) {
+			resolve({ done: false, value: msg })
+			return
+		}
+
+		this.queue.push(msg)
+	}
+}
+
 async function main(): Promise<void> {
 	if (wantsHelp()) {
 		printUsage()
@@ -111,73 +330,72 @@ async function runChatLoop(
 	cookies: CookieJar,
 	session: AuthSession,
 ): Promise<void> {
+	const agent = await AgentWebSocketSession.connect(backendUrl, cookies)
+	console.log("Connected to /api/agent/ws")
 	printHelp()
 
-	for (;;) {
-		const input = askOptional("you> ")?.trim()
-		if (!input) continue
+	try {
+		for (;;) {
+			const input = askOptional("you> ")?.trim()
+			if (!input) continue
 
-		if (input === "/quit" || input === "/exit") {
-			console.log("Bye.")
-			return
-		}
+			if (input === "/quit" || input === "/exit") {
+				console.log("Bye.")
+				return
+			}
 
-		if (input === "/help") {
-			printHelp()
-			continue
-		}
+			if (input === "/help") {
+				printHelp()
+				continue
+			}
 
-		if (input === "/session") {
-			console.log(`${session.user.name || session.user.email} (${session.user.id})`)
-			continue
-		}
+			if (input === "/session") {
+				console.log(`${session.user.name || session.user.email} (${session.user.id})`)
+				continue
+			}
 
-		if (input === "/tools") {
-			await runCliCommand(() => listQueryTools(backendUrl, cookies))
-			continue
-		}
+			if (input === "/conversation") {
+				console.log(agent.describeConversation())
+				continue
+			}
 
-		if (input.startsWith("/tool ")) {
-			await runCliCommand(() => executeQueryTool(backendUrl, cookies, input.slice("/tool ".length)))
-			continue
-		}
+			if (input === "/tools") {
+				await runCliCommand(() => listQueryTools(backendUrl, cookies))
+				continue
+			}
 
-		if (input.startsWith("/actions ")) {
-			await runCliCommand(() =>
-				listSourceActions(backendUrl, cookies, input.slice("/actions ".length)),
-			)
-			continue
-		}
+			if (input.startsWith("/tool ")) {
+				await runCliCommand(() =>
+					executeQueryTool(backendUrl, cookies, input.slice("/tool ".length)),
+				)
+				continue
+			}
 
-		if (input.startsWith("/action ")) {
-			await runCliCommand(() =>
-				executeSourceAction(backendUrl, cookies, input.slice("/action ".length)),
-			)
-			continue
-		}
+			if (input.startsWith("/actions ")) {
+				await runCliCommand(() =>
+					listSourceActions(backendUrl, cookies, input.slice("/actions ".length)),
+				)
+				continue
+			}
 
-		try {
-			await askAgent(backendUrl, cookies, input)
-		} catch (err) {
-			console.error(`\n${formatError(err)}\n`)
+			if (input.startsWith("/action ")) {
+				await runCliCommand(() =>
+					executeSourceAction(backendUrl, cookies, input.slice("/action ".length)),
+				)
+				continue
+			}
+
+			try {
+				await agent.ask(input)
+			} catch (err) {
+				console.error(`\n${formatError(err)}\n`)
+			}
 		}
+	} finally {
+		agent.close()
 	}
 }
 
-async function askAgent(backendUrl: string, cookies: CookieJar, message: string): Promise<void> {
-	const data = await requestJson(backendUrl, cookies, "/api/agent", {
-		method: "POST",
-		body: { message },
-	})
-
-	if (!isQueryResponse(data)) {
-		throw new Error("Query returned an unexpected response shape")
-	}
-
-	console.log(`\nagent> ${data.message || "(no message)"}`)
-	console.log("")
-}
-
 async function runCliCommand(command: () => Promise<void>): Promise<void> {
 	try {
 		await command()
@@ -327,7 +545,7 @@ async function requestJson(
 
 function printIntro(): void {
 	console.log("FREYA agent test CLI")
-	console.log("Connect to a backend, sign in, then send test messages to /api/agent.\n")
+	console.log("Connect to a backend, sign in, then send test messages to /api/agent/ws.\n")
 }
 
 function printUsage(): void {
@@ -348,6 +566,7 @@ function printHelp(): void {
 	console.log("  /tool        Execute an agent debug tool with JSON params")
 	console.log("  /actions     List source actions: /actions <source-id>")
 	console.log("  /action      Execute source action: /action <source-id> <action-id> <json-params>")
+	console.log("  /conversation  Show the current websocket conversation")
 	console.log("  /session     Show the signed-in user")
 	console.log("  /help        Show commands")
 	console.log("  /quit        Exit\n")
@@ -417,6 +636,33 @@ function normalizeBackendUrl(value: string): string {
 	}
 }
 
+function agentWebSocketUrl(backendUrl: string): string {
+	const url = new URL(backendUrl)
+	url.protocol = url.protocol === "https:" ? "wss:" : "ws:"
+	url.pathname = "/api/agent/ws"
+	url.search = ""
+	url.hash = ""
+	return url.toString()
+}
+
+function createWebSocketOptions(cookieHeader?: string): Bun.WebSocketOptions | undefined {
+	if (!cookieHeader) return undefined
+
+	return {
+		headers: {
+			Cookie: cookieHeader,
+		},
+	}
+}
+
+function formatWebSocketClose(
+	url: string,
+	event: { code: number; reason: string; wasClean: boolean },
+): string {
+	const reason = event.reason ? `: ${event.reason}` : ""
+	return `Could not connect to ${url} (${event.code}${reason})`
+}
+
 function formatPromptLabel(label: string, defaultValue?: string): string {
 	return defaultValue ? `${label} (${defaultValue}): ` : `${label}: `
 }
@@ -511,6 +757,25 @@ function splitSetCookieHeader(header: string): string[] {
 	return parts.filter(Boolean)
 }
 
+function parseJrpcMessage(message: unknown): JrpcMessage | null {
+	const text = webSocketMessageText(message)
+	if (!text) return null
+
+	try {
+		const value: unknown = JSON.parse(text)
+		return isJrpcMessage(value) ? value : null
+	} catch {
+		return null
+	}
+}
+
+function webSocketMessageText(message: unknown): string | null {
+	if (typeof message === "string") return message
+	if (message instanceof Uint8Array) return Buffer.from(message).toString("utf8")
+	if (message instanceof ArrayBuffer) return Buffer.from(message).toString("utf8")
+	return null
+}
+
 async function readResponseError(response: Response, path: string): Promise<string> {
 	const text = await response.text()
 	if (response.status === 404 && path === "/api/agent") {
@@ -548,11 +813,6 @@ function isAuthSession(value: unknown): value is AuthSession {
 	)
 }
 
-function isQueryResponse(value: unknown): value is QueryResponse {
-	if (!isJsonObject(value)) return false
-	return typeof value.message === "string"
-}
-
 function isQueryToolsResponse(value: unknown): value is QueryToolsResponse {
 	if (!isJsonObject(value) || !Array.isArray(value.tools)) return false
 	return value.tools.every(isQueryToolDefinition)
@@ -585,6 +845,33 @@ function isSourceActionDefinition(value: unknown): value is { id: string; descri
 	)
 }
 
+function isJrpcMessage(value: unknown): value is JrpcMessage {
+	if (!isJsonObject(value) || value.jsonrpc !== "2.0" || typeof value.id !== "number") {
+		return false
+	}
+
+	if ("method" in value) {
+		return (
+			typeof value.method === "string" &&
+			(value.params === undefined || Array.isArray(value.params))
+		)
+	}
+
+	if ("result" in value) {
+		return true
+	}
+
+	if ("error" in value) {
+		return isJsonRpcErrorObject(value.error)
+	}
+
+	return false
+}
+
+function isJsonRpcErrorObject(value: unknown): boolean {
+	return isJsonObject(value) && typeof value.code === "number" && typeof value.message === "string"
+}
+
 function isJsonObject(value: unknown): value is JsonObject {
 	return typeof value === "object" && value !== null && !Array.isArray(value)
 }

apps/freya-backend/.env.example

@@ -12,8 +12,6 @@ BETTER_AUTH_URL=http://localhost:3000
 
 # OpenRouter (LLM feed enhancement)
 OPENROUTER_API_KEY=
-# Optional: override the default model (default: openai/gpt-4.1-mini)
-# OPENROUTER_MODEL=openai/gpt-4.1-mini
 
 # Apple WeatherKit credentials
 WEATHERKIT_PRIVATE_KEY=

apps/freya-backend/drizzle/0001_misty_white_tiger.sql

@@ -1 +1,49 @@
-CREATE INDEX "user_sources_user_id_enabled_idx" ON "user_sources" USING btree ("user_id","enabled");
+CREATE INDEX "user_sources_user_id_enabled_idx" ON "user_sources" USING btree ("user_id","enabled");--> statement-breakpoint
+CREATE TABLE "conversation_entries" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"conversation_id" uuid NOT NULL,
+	"sequence" integer NOT NULL,
+	"kind" text NOT NULL,
+	"visibility" text DEFAULT 'internal' NOT NULL,
+	"file_id" uuid,
+	"payload" jsonb NOT NULL,
+	"metadata" jsonb DEFAULT '{}'::jsonb NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	CONSTRAINT "conversation_entries_conversation_id_sequence_unique" UNIQUE("conversation_id","sequence")
+);
+--> statement-breakpoint
+CREATE TABLE "conversations" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"user_id" text NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "files" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"user_id" text NOT NULL,
+	"storage_key" text NOT NULL,
+	"original_name" text,
+	"mime_type" text NOT NULL,
+	"size_bytes" integer NOT NULL,
+	"metadata" jsonb DEFAULT '{}'::jsonb NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	CONSTRAINT "files_storage_key_unique" UNIQUE("storage_key")
+);
+--> statement-breakpoint
+ALTER TABLE "session" ADD COLUMN "impersonated_by" text;--> statement-breakpoint
+ALTER TABLE "user" ADD COLUMN "role" text;--> statement-breakpoint
+ALTER TABLE "user" ADD COLUMN "banned" boolean DEFAULT false;--> statement-breakpoint
+ALTER TABLE "user" ADD COLUMN "ban_reason" text;--> statement-breakpoint
+ALTER TABLE "user" ADD COLUMN "ban_expires" timestamp;--> statement-breakpoint
+ALTER TABLE "conversation_entries" ADD CONSTRAINT "conversation_entries_conversation_id_conversations_id_fk" FOREIGN KEY ("conversation_id") REFERENCES "public"."conversations"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "conversation_entries" ADD CONSTRAINT "conversation_entries_file_id_files_id_fk" FOREIGN KEY ("file_id") REFERENCES "public"."files"("id") ON DELETE restrict ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "conversation_entries" ADD CONSTRAINT "conversation_entries_attachment_file_id_check" CHECK (("conversation_entries"."kind" = 'attachment' and "conversation_entries"."file_id" is not null) or ("conversation_entries"."kind" <> 'attachment' and "conversation_entries"."file_id" is null));--> statement-breakpoint
+ALTER TABLE "conversations" ADD CONSTRAINT "conversations_user_id_user_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."user"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "files" ADD CONSTRAINT "files_user_id_user_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."user"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "conversation_entries_conversation_id_sequence_idx" ON "conversation_entries" USING btree ("conversation_id","sequence");--> statement-breakpoint
+CREATE INDEX "conversation_entries_conversation_id_visibility_sequence_idx" ON "conversation_entries" USING btree ("conversation_id","visibility","sequence");--> statement-breakpoint
+CREATE INDEX "conversation_entries_kind_idx" ON "conversation_entries" USING btree ("kind");--> statement-breakpoint
+CREATE INDEX "conversation_entries_file_id_idx" ON "conversation_entries" USING btree ("file_id");--> statement-breakpoint
+CREATE INDEX "conversations_user_id_updated_at_idx" ON "conversations" USING btree ("user_id","updated_at");--> statement-breakpoint
+CREATE INDEX "files_user_id_created_at_idx" ON "files" USING btree ("user_id","created_at");

apps/freya-backend/package.json

@@ -16,6 +16,7 @@
 	},
 	"dependencies": {
 		"@earendil-works/pi-coding-agent": "^0.79.1",
+		"@freya/agent-protocol": "workspace:*",
 		"@freya/core": "workspace:*",
 		"@freya/source-caldav": "workspace:*",
 		"@freya/source-google-calendar": "workspace:*",
@@ -25,6 +26,7 @@
 		"@freya/source-tfl": "workspace:*",
 		"@freya/source-weatherkit": "workspace:*",
 		"@freya/source-web-search": "workspace:*",
+		"@nym.sh/jrpc": "^0.1.0",
 		"@openrouter/sdk": "^0.9.11",
 		"arktype": "^2.1.29",
 		"better-auth": "^1",

apps/freya-backend/src/admin/http.test.ts

@@ -44,6 +44,20 @@ mock.module("../sources/user-sources.ts", () => ({
 	}),
 }))
 
+mock.module("../conversations/storage.ts", () => ({
+	conversations: (_db: Database, userId: string) => ({
+		async getOrCreateConversation() {
+			return { id: `conversation-${userId}` }
+		},
+		async listEntries() {
+			return []
+		},
+		async appendEntry() {
+			return { id: "entry-1", sequence: 1 }
+		},
+	}),
+}))
+
 function createStubSource(id: string): FeedSource {
 	return {
 		id,

apps/freya-backend/src/agent/conversation-recording-query-agent.test.ts

@@ -0,0 +1,347 @@
+import { describe, expect, test } from "bun:test"
+
+import type { AppendConversationEntryInput } from "../conversations/storage.ts"
+import type {
+	ConversationStorage,
+	ConversationStorageEntry,
+} from "./conversation-recording-query-agent.ts"
+
+import { ConversationEntryKind } from "../conversations/types.ts"
+import { ConversationRecordingQueryAgent } from "./conversation-recording-query-agent.ts"
+import {
+	createQueryAgentEventListeners,
+	QueryAgentEvent,
+	type QueryAgent,
+	type QueryAgentAsk,
+	type QueryAgentCompactionEvent,
+	type QueryAgentEventListeners,
+	type QueryAgentEventListener,
+	type QueryAgentEventMap,
+	type QueryAgentStreamEvent,
+} from "./query-agent.ts"
+
+interface RecordedEntry {
+	conversationId: string
+	input: AppendConversationEntryInput
+}
+
+class FakeQueryAgent implements QueryAgent {
+	readonly inputs: QueryAgentAsk[] = []
+	private readonly events: QueryAgentStreamEvent[]
+	private readonly eventListeners = createQueryAgentEventListeners()
+
+	constructor(events: QueryAgentStreamEvent[]) {
+		this.events = events
+	}
+
+	async *ask(input: QueryAgentAsk): AsyncIterable<QueryAgentStreamEvent> {
+		this.inputs.push(input)
+		for (const event of this.events) {
+			yield event
+		}
+	}
+
+	addEventListener<T extends QueryAgentEvent>(
+		type: T,
+		listener: QueryAgentEventListener<T>,
+	): () => void {
+		const listeners = this.listenersFor(type)
+		listeners.add(listener)
+		return () => {
+			listeners.delete(listener)
+		}
+	}
+
+	async emitCompaction(event: QueryAgentCompactionEvent): Promise<void> {
+		await this.emitEvent(event)
+	}
+
+	private async emitEvent<T extends QueryAgentEvent>(event: QueryAgentEventMap[T]): Promise<void> {
+		const listeners = this.listenersFor(event.type)
+		for (const listener of listeners) {
+			await listener(event)
+		}
+	}
+
+	private listenersFor<T extends QueryAgentEvent>(type: T): QueryAgentEventListeners[T] {
+		return this.eventListeners[type]
+	}
+
+	dispose(): void {}
+}
+
+class FakeConversationStorage implements ConversationStorage {
+	getOrCreateCount = 0
+	readonly entries: RecordedEntry[] = []
+	conversationId = "conversation-1"
+
+	async getOrCreateConversation(): Promise<{ id: string }> {
+		this.getOrCreateCount += 1
+		return { id: this.conversationId }
+	}
+
+	async appendEntry(
+		conversationId: string,
+		input: AppendConversationEntryInput,
+	): Promise<ConversationStorageEntry> {
+		this.entries.push({ conversationId, input })
+		return {
+			id: `entry-${this.entries.length}`,
+			sequence: this.entries.length,
+			kind: input.kind,
+			payload: input.payload,
+			metadata: input.metadata ?? {},
+			createdAt: new Date("2026-06-15T00:00:00.000Z"),
+		}
+	}
+
+	async listEntries(_conversationId: string): Promise<ConversationStorageEntry[]> {
+		return this.entries.map((entry, index) => ({
+			id: `entry-${index + 1}`,
+			sequence: index + 1,
+			kind: entry.input.kind,
+			payload: entry.input.payload,
+			metadata: entry.input.metadata ?? {},
+			createdAt: new Date("2026-06-15T00:00:00.000Z"),
+		}))
+	}
+}
+
+describe("ConversationRecordingQueryAgent", () => {
+	test("records user and assistant messages in the conversation timeline", async () => {
+		const queryAgent = new FakeQueryAgent([
+			{ type: "text_delta", text: "Hello " },
+			{ type: "text_delta", text: "there." },
+			{ type: "done" },
+		])
+		const storage = new FakeConversationStorage()
+		const agent = new ConversationRecordingQueryAgent({
+			agent: queryAgent,
+			storage,
+			modelProvider: "openrouter",
+			modelId: "test-model",
+		})
+
+		const events = await collectEvents(
+			agent.ask({
+				message: "hi",
+			}),
+		)
+
+		expect(events[0]).toEqual({ type: "conversation", conversationId: "conversation-1" })
+		expect(queryAgent.inputs[0]?.conversationId).toBe("conversation-1")
+		expect(storage.getOrCreateCount).toBe(1)
+		expect(storage.entries).toHaveLength(2)
+
+		const userEntry = storage.entries[0]!.input
+		if (userEntry.kind !== ConversationEntryKind.UserMessage) {
+			throw new Error("Expected user message entry")
+		}
+		expect(userEntry.payload.parts).toEqual([{ type: "text", text: "hi" }])
+
+		const assistantEntry = storage.entries[1]!.input
+		if (assistantEntry.kind !== ConversationEntryKind.AssistantMessage) {
+			throw new Error("Expected assistant message entry")
+		}
+		expect(assistantEntry.payload.parts).toEqual([{ type: "text", text: "Hello there." }])
+		expect(assistantEntry.metadata?.modelRun?.provider).toBe("openrouter")
+		expect(assistantEntry.metadata?.modelRun?.model).toBe("test-model")
+	})
+
+	test("uses a provided conversation id without creating a default conversation", async () => {
+		const queryAgent = new FakeQueryAgent([{ type: "done" }])
+		const storage = new FakeConversationStorage()
+		const agent = new ConversationRecordingQueryAgent({
+			agent: queryAgent,
+			storage,
+			modelProvider: "openrouter",
+			modelId: "test-model",
+		})
+
+		const events = await collectEvents(
+			agent.ask({
+				conversationId: "conversation-existing",
+				message: "continue",
+			}),
+		)
+
+		expect(events[0]).toEqual({
+			type: "conversation",
+			conversationId: "conversation-existing",
+		})
+		expect(storage.getOrCreateCount).toBe(0)
+		expect(storage.entries[0]?.conversationId).toBe("conversation-existing")
+		expect(queryAgent.inputs[0]?.conversationId).toBe("conversation-existing")
+	})
+
+	test("uses the eager default conversation id without reading storage on ask", async () => {
+		const queryAgent = new FakeQueryAgent([{ type: "done" }])
+		const storage = new FakeConversationStorage()
+		const agent = new ConversationRecordingQueryAgent({
+			agent: queryAgent,
+			storage,
+			defaultConversationId: "conversation-eager",
+			modelProvider: "openrouter",
+			modelId: "test-model",
+		})
+
+		const events = await collectEvents(
+			agent.ask({
+				message: "continue",
+			}),
+		)
+
+		expect(events[0]).toEqual({
+			type: "conversation",
+			conversationId: "conversation-eager",
+		})
+		expect(storage.getOrCreateCount).toBe(0)
+		expect(storage.entries[0]?.conversationId).toBe("conversation-eager")
+		expect(queryAgent.inputs[0]?.conversationId).toBe("conversation-eager")
+	})
+
+	test("rejects switching away from the eager default conversation", async () => {
+		const queryAgent = new FakeQueryAgent([{ type: "done" }])
+		const storage = new FakeConversationStorage()
+		const agent = new ConversationRecordingQueryAgent({
+			agent: queryAgent,
+			storage,
+			defaultConversationId: "conversation-eager",
+			modelProvider: "openrouter",
+			modelId: "test-model",
+		})
+
+		const events = await collectEvents(
+			agent.ask({
+				conversationId: "conversation-other",
+				message: "continue",
+			}),
+		)
+
+		expect(events).toEqual([
+			{
+				type: "error",
+				message: "Conversation switching is not supported for this session",
+			},
+		])
+		expect(storage.entries).toHaveLength(0)
+		expect(queryAgent.inputs).toHaveLength(0)
+	})
+
+	test("records tool activity and agent errors as internal entries", async () => {
+		const queryAgent = new FakeQueryAgent([
+			{ type: "tool_start", toolName: "freya_get_feed" },
+			{ type: "tool_end", toolName: "freya_get_feed", ok: true },
+			{ type: "error", message: "model unavailable" },
+		])
+		const storage = new FakeConversationStorage()
+		const agent = new ConversationRecordingQueryAgent({
+			agent: queryAgent,
+			storage,
+			modelProvider: "openrouter",
+			modelId: "test-model",
+		})
+
+		await collectEvents(
+			agent.ask({
+				message: "what now?",
+			}),
+		)
+
+		expect(storage.entries.map((entry) => entry.input.kind)).toEqual([
+			ConversationEntryKind.UserMessage,
+			ConversationEntryKind.ToolCall,
+			ConversationEntryKind.ToolResult,
+			ConversationEntryKind.SystemNote,
+		])
+
+		const toolCall = storage.entries[1]!.input
+		if (toolCall.kind !== ConversationEntryKind.ToolCall) {
+			throw new Error("Expected tool call entry")
+		}
+		expect(toolCall.payload.toolName).toBe("freya_get_feed")
+
+		const toolResult = storage.entries[2]!.input
+		if (toolResult.kind !== ConversationEntryKind.ToolResult) {
+			throw new Error("Expected tool result entry")
+		}
+		expect(toolResult.payload.ok).toBe(true)
+
+		const systemNote = storage.entries[3]!.input
+		if (systemNote.kind !== ConversationEntryKind.SystemNote) {
+			throw new Error("Expected system note entry")
+		}
+		expect(systemNote.payload).toMatchObject({
+			type: "agent_error",
+			message: "model unavailable",
+		})
+	})
+
+	test("records compaction events as context summaries", async () => {
+		const queryAgent = new FakeQueryAgent([
+			{ type: "text_delta", text: "Kept answer." },
+			{ type: "done" },
+		])
+		const storage = new FakeConversationStorage()
+		const agent = new ConversationRecordingQueryAgent({
+			agent: queryAgent,
+			storage,
+			defaultConversationId: "conversation-1",
+			modelProvider: "openrouter",
+			modelId: "test-model",
+		})
+		const forwardedCompactions: QueryAgentCompactionEvent[] = []
+		agent.addEventListener(QueryAgentEvent.Compaction, (event) => {
+			forwardedCompactions.push(event)
+		})
+
+		await collectEvents(
+			agent.ask({
+				message: "remember this",
+			}),
+		)
+
+		await queryAgent.emitCompaction({
+			type: QueryAgentEvent.Compaction,
+			conversationId: "conversation-1",
+			summary: "The user prefers compact summaries.",
+			firstKeptEntryId: "pi-entry-7",
+			compactedEntryRange: {
+				startSequence: 1,
+				endSequence: 1,
+			},
+			tokensBefore: 1234,
+			details: { reason: "threshold" },
+			fromExtension: false,
+		})
+
+		const summaryEntry = storage.entries.at(-1)?.input
+		if (summaryEntry?.kind !== ConversationEntryKind.ContextSummary) {
+			throw new Error("Expected context summary entry")
+		}
+		expect(summaryEntry.payload.covers).toEqual({
+			startSequence: 1,
+			endSequence: 1,
+		})
+		expect(summaryEntry.payload.summary.importantDetails).toEqual([
+			"The user prefers compact summaries.",
+		])
+		expect(summaryEntry.metadata?.piCompaction).toMatchObject({
+			firstKeptEntryId: "pi-entry-7",
+			tokensBefore: 1234,
+			fromExtension: false,
+			details: { reason: "threshold" },
+		})
+		expect(forwardedCompactions).toHaveLength(1)
+	})
+})
+
+async function collectEvents(
+	events: AsyncIterable<QueryAgentStreamEvent>,
+): Promise<QueryAgentStreamEvent[]> {
+	const result: QueryAgentStreamEvent[] = []
+	for await (const event of events) {
+		result.push(event)
+	}
+	return result
+}

apps/freya-backend/src/agent/conversation-recording-query-agent.ts

@@ -0,0 +1,252 @@
+import { randomUUID } from "node:crypto"
+
+import type {
+	AppendConversationEntryInput,
+	ConversationEntryRow,
+} from "../conversations/storage.ts"
+import type { ConversationEntryMetadata } from "../conversations/types.ts"
+
+import { ConversationEntryKind } from "../conversations/types.ts"
+import {
+	createQueryAgentEventListeners,
+	QueryAgentEvent,
+	type QueryAgent,
+	type QueryAgentAsk,
+	type QueryAgentCompactionEvent,
+	type QueryAgentEventListeners,
+	type QueryAgentEventListener,
+	type QueryAgentEventMap,
+	type QueryAgentStreamEvent,
+} from "./query-agent.ts"
+
+export interface ConversationStorage {
+	getOrCreateConversation(): Promise<{ id: string }>
+	appendEntry(
+		conversationId: string,
+		input: AppendConversationEntryInput,
+	): Promise<ConversationStorageEntry>
+	listEntries(conversationId: string): Promise<ConversationStorageEntry[]>
+}
+
+export type ConversationStorageEntry = Pick<
+	ConversationEntryRow,
+	"id" | "sequence" | "kind" | "payload" | "metadata" | "createdAt"
+>
+
+export interface ConversationRecordingQueryAgentConfig {
+	agent: QueryAgent
+	storage: ConversationStorage
+	defaultConversationId?: string
+	route?: string
+	modelProvider: string
+	modelId: string
+}
+
+const DefaultRoute = "agent_query"
+
+export class ConversationRecordingQueryAgent implements QueryAgent {
+	private readonly agent: QueryAgent
+	private readonly storage: ConversationStorage
+	private readonly defaultConversationId: string | undefined
+	private readonly route: string
+	private readonly modelProvider: string
+	private readonly modelId: string
+	private readonly eventListeners = createQueryAgentEventListeners()
+	private readonly removeAgentCompactionListener: () => void
+
+	constructor(config: ConversationRecordingQueryAgentConfig) {
+		this.agent = config.agent
+		this.storage = config.storage
+		this.defaultConversationId = config.defaultConversationId
+		this.route = config.route ?? DefaultRoute
+		this.modelProvider = config.modelProvider
+		this.modelId = config.modelId
+		this.removeAgentCompactionListener = this.agent.addEventListener(
+			QueryAgentEvent.Compaction,
+			async (event) => {
+				await this.appendCompactionSummary(event)
+				await this.emitEvent(event)
+			},
+		)
+	}
+
+	async *ask(input: QueryAgentAsk): AsyncIterable<QueryAgentStreamEvent> {
+		if (
+			this.defaultConversationId &&
+			input.conversationId &&
+			input.conversationId !== this.defaultConversationId
+		) {
+			yield {
+				type: "error",
+				message: "Conversation switching is not supported for this session",
+			}
+			return
+		}
+
+		const conversationId =
+			input.conversationId ??
+			this.defaultConversationId ??
+			(await this.storage.getOrCreateConversation()).id
+		const runId = randomUUID()
+
+		const userEntry = await this.storage.appendEntry(conversationId, {
+			kind: ConversationEntryKind.UserMessage,
+			payload: {
+				role: "user",
+				parts: [{ type: "text", text: input.message }],
+			},
+			metadata: { runId },
+		})
+
+		yield { type: "conversation", conversationId }
+
+		const assistantText: string[] = []
+		for await (const event of this.agent.ask({
+			...input,
+			conversationId,
+			userMessageEntry: {
+				id: userEntry.id,
+				sequence: userEntry.sequence,
+			},
+		})) {
+			switch (event.type) {
+				case "conversation":
+					break
+				case "text_delta":
+					assistantText.push(event.text)
+					yield event
+					break
+				case "tool_start":
+					await this.storage.appendEntry(conversationId, {
+						kind: ConversationEntryKind.ToolCall,
+						payload: {
+							toolName: event.toolName,
+							runId,
+						},
+						metadata: { runId },
+					})
+					yield event
+					break
+				case "tool_end":
+					await this.storage.appendEntry(conversationId, {
+						kind: ConversationEntryKind.ToolResult,
+						payload: {
+							toolName: event.toolName,
+							ok: event.ok,
+							runId,
+						},
+						metadata: { runId },
+					})
+					yield event
+					break
+				case "error":
+					await this.storage.appendEntry(conversationId, {
+						kind: ConversationEntryKind.SystemNote,
+						payload: {
+							type: "agent_error",
+							message: event.message,
+							runId,
+						},
+						metadata: { runId },
+					})
+					yield event
+					return
+				case "done":
+					await this.appendAssistantMessage(conversationId, assistantText, runId)
+					yield event
+					return
+			}
+		}
+
+		await this.appendAssistantMessage(conversationId, assistantText, runId)
+	}
+
+	dispose(): void {
+		this.removeAgentCompactionListener()
+		this.clearEventListeners()
+		this.agent.dispose()
+	}
+
+	addEventListener<T extends QueryAgentEvent>(
+		type: T,
+		listener: QueryAgentEventListener<T>,
+	): () => void {
+		const listeners = this.listenersFor(type)
+		listeners.add(listener)
+		return () => {
+			listeners.delete(listener)
+		}
+	}
+
+	private async appendAssistantMessage(
+		conversationId: string,
+		assistantText: string[],
+		runId: string,
+	): Promise<void> {
+		const text = assistantText.join("")
+		if (text.length === 0) return
+
+		await this.storage.appendEntry(conversationId, {
+			kind: ConversationEntryKind.AssistantMessage,
+			payload: {
+				role: "assistant",
+				parts: [{ type: "text", text }],
+			},
+			metadata: this.modelRunMetadata(runId),
+		})
+	}
+
+	private modelRunMetadata(runId: string): ConversationEntryMetadata {
+		const metadata: ConversationEntryMetadata = { runId }
+		metadata.modelRun = {
+			route: this.route,
+			provider: this.modelProvider,
+			model: this.modelId,
+		}
+		return metadata
+	}
+
+	private async appendCompactionSummary(event: QueryAgentCompactionEvent): Promise<void> {
+		if (event.compactedEntryRange === null) return
+
+		await this.storage.appendEntry(event.conversationId, {
+			kind: ConversationEntryKind.ContextSummary,
+			payload: {
+				covers: event.compactedEntryRange,
+				summary: {
+					durableFacts: [],
+					preferences: [],
+					decisions: [],
+					openTasks: [],
+					importantDetails: [event.summary],
+				},
+				promptVersion: "pi-sdk-compaction-v1",
+			},
+			metadata: {
+				piCompaction: {
+					firstKeptEntryId: event.firstKeptEntryId,
+					tokensBefore: event.tokensBefore,
+					fromExtension: event.fromExtension,
+					details: event.details,
+				},
+			},
+		})
+	}
+
+	private async emitEvent<T extends QueryAgentEvent>(event: QueryAgentEventMap[T]): Promise<void> {
+		const listeners = this.listenersFor(event.type)
+		for (const listener of listeners) {
+			await listener(event)
+		}
+	}
+
+	private listenersFor<T extends QueryAgentEvent>(type: T): QueryAgentEventListeners[T] {
+		return this.eventListeners[type]
+	}
+
+	private clearEventListeners(): void {
+		for (const listeners of Object.values(this.eventListeners)) {
+			listeners.clear()
+		}
+	}
+}

apps/freya-backend/src/agent/http.test.ts

@@ -1,8 +1,15 @@
 import { describe, expect, test } from "bun:test"
 import { Hono } from "hono"
 
+import type { UserSessionManager } from "../session/index.ts"
 import type { QueryDebugTools, QueryDebugToolDefinition } from "./debug-tools.ts"
-import type { QueryAgent, QueryAgentAsk, QueryAgentEvent } from "./query-agent.ts"
+import type {
+	QueryAgent,
+	QueryAgentAsk,
+	QueryAgentEventListener,
+	QueryAgentStreamEvent,
+	QueryAgentEvent,
+} from "./query-agent.ts"
 
 import { mockAuthSessionMiddleware } from "../auth/session-middleware.ts"
 import { registerAgentHttpHandlers, registerDebugAgentHttpHandlers } from "./http.ts"
@@ -11,20 +18,25 @@ const MockUserId = "k7Gx2mPqRvNwYs9TdLfA4bHcJeUo1iZn"
 
 class FakeQueryAgent implements QueryAgent {
 	readonly inputs: QueryAgentAsk[] = []
-	private readonly events: QueryAgentEvent[]
+	private readonly events: QueryAgentStreamEvent[]
 
-	constructor(events: QueryAgentEvent[]) {
+	constructor(events: QueryAgentStreamEvent[]) {
 		this.events = events
 	}
 
-	async *ask(input: QueryAgentAsk): AsyncIterable<QueryAgentEvent> {
+	async *ask(input: QueryAgentAsk): AsyncIterable<QueryAgentStreamEvent> {
 		this.inputs.push(input)
 		for (const event of this.events) {
 			yield event
 		}
 	}
 
-	disposeUser(): void {}
+	addEventListener<T extends QueryAgentEvent>(
+		_type: T,
+		_listener: QueryAgentEventListener<T>,
+	): () => void {
+		return () => {}
+	}
 
 	dispose(): void {}
 }
@@ -52,8 +64,14 @@ class FakeDebugTools implements QueryDebugTools {
 
 function buildTestApp(queryAgent: QueryAgent, userId?: string) {
 	const app = new Hono()
+	const sessionManager = {
+		async getOrCreate() {
+			return { agent: queryAgent }
+		},
+	} as unknown as UserSessionManager
+
 	registerAgentHttpHandlers(app, {
-		queryAgent,
+		sessionManager,
 		authSessionMiddleware: mockAuthSessionMiddleware(userId),
 	})
 	return app
@@ -105,6 +123,27 @@ describe("POST /api/agent", () => {
 		expect(body.message).toBe("You should leave at 8:30.")
 	})
 
+	test("passes conversation id to the query agent", async () => {
+		const agent = new FakeQueryAgent([
+			{ type: "conversation", conversationId: "conversation-1" },
+			{ type: "done" },
+		])
+		const app = buildTestApp(agent, "user-1")
+
+		const res = await app.request("/api/agent", {
+			method: "POST",
+			body: JSON.stringify({
+				message: "Continue this chat.",
+				conversationId: "conversation-1",
+			}),
+		})
+
+		expect(res.status).toBe(200)
+		expect(agent.inputs[0]?.conversationId).toBe("conversation-1")
+		const body = (await res.json()) as { conversationId?: string }
+		expect(body.conversationId).toBe("conversation-1")
+	})
+
 	test("returns 400 for invalid body", async () => {
 		const app = buildTestApp(new FakeQueryAgent([]), "user-1")
 

apps/freya-backend/src/agent/http.ts

@@ -4,14 +4,14 @@ import { type } from "arktype"
 import { createMiddleware } from "hono/factory"
 
 import type { AuthSessionMiddleware } from "../auth/session-middleware.ts"
+import type { UserSessionManager } from "../session/index.ts"
 import type { QueryDebugTools } from "./debug-tools.ts"
-import type { QueryAgent } from "./query-agent.ts"
 
 import { collectQueryAgentResponse, QueryAgentError } from "./query-agent.ts"
 
 type Env = {
 	Variables: {
-		queryAgent: QueryAgent
+		sessionManager: UserSessionManager
 	}
 }
 
@@ -22,7 +22,7 @@ type DebugEnv = {
 }
 
 interface AgentHttpHandlersDeps {
-	queryAgent: QueryAgent
+	sessionManager: UserSessionManager
 	authSessionMiddleware: AuthSessionMiddleware
 }
 
@@ -35,14 +35,15 @@ interface AgentDebugHttpHandlersDeps {
 const AgentAskRequestBody = type({
 	"+": "reject",
 	message: "string",
+	"conversationId?": "string",
 })
 
 export function registerAgentHttpHandlers(
 	app: Hono,
-	{ queryAgent, authSessionMiddleware }: AgentHttpHandlersDeps,
+	{ sessionManager, authSessionMiddleware }: AgentHttpHandlersDeps,
 ) {
 	const inject = createMiddleware<Env>(async (c, next) => {
-		c.set("queryAgent", queryAgent)
+		c.set("sessionManager", sessionManager)
 		await next()
 	})
 
@@ -76,12 +77,13 @@ async function handleAgentAsk(c: Context<Env>) {
 	}
 
 	const user = c.get("user")!
-	const queryAgent = c.get("queryAgent")
+	const sessionManager = c.get("sessionManager")
 
 	try {
-		const response = await collectQueryAgentResponse(queryAgent, {
-			userId: user.id,
+		const session = await sessionManager.getOrCreate(user.id)
+		const response = await collectQueryAgentResponse(session.agent, {
 			message: parsed.message,
+			conversationId: parsed.conversationId,
 		})
 		return c.json(response)
 	} catch (err) {

apps/freya-backend/src/agent/in-memory-resource-loader.ts

@@ -1,43 +0,0 @@
-import { createExtensionRuntime, type ResourceLoader } from "@earendil-works/pi-coding-agent"
-
-export class InMemoryResourceLoader implements ResourceLoader {
-	private readonly extensions: ReturnType<ResourceLoader["getExtensions"]> = {
-		extensions: [],
-		errors: [],
-		runtime: createExtensionRuntime(),
-	}
-
-	constructor(private readonly systemPrompt: string) {}
-
-	getExtensions(): ReturnType<ResourceLoader["getExtensions"]> {
-		return this.extensions
-	}
-
-	getSkills(): ReturnType<ResourceLoader["getSkills"]> {
-		return { skills: [], diagnostics: [] }
-	}
-
-	getPrompts(): ReturnType<ResourceLoader["getPrompts"]> {
-		return { prompts: [], diagnostics: [] }
-	}
-
-	getThemes(): ReturnType<ResourceLoader["getThemes"]> {
-		return { themes: [], diagnostics: [] }
-	}
-
-	getAgentsFiles(): ReturnType<ResourceLoader["getAgentsFiles"]> {
-		return { agentsFiles: [] }
-	}
-
-	getSystemPrompt(): string {
-		return this.systemPrompt
-	}
-
-	getAppendSystemPrompt(): string[] {
-		return []
-	}
-
-	extendResources(_paths: Parameters<ResourceLoader["extendResources"]>[0]): void {}
-
-	async reload(_options?: Parameters<ResourceLoader["reload"]>[0]): Promise<void> {}
-}

apps/freya-backend/src/agent/pi-query-agent.test.ts

@@ -1,7 +1,10 @@
 import { beforeEach, describe, expect, mock, test } from "bun:test"
 
-import type { UserSessionManager } from "../session/index.ts"
-import type { QueryAgentEvent } from "./query-agent.ts"
+import type { QueryAgentToolbox } from "./query-agent-toolbox.ts"
+import type { QueryAgentStreamEvent } from "./query-agent.ts"
+
+import { ConversationEntryKind } from "../conversations/types.ts"
+import { QueryAgentEvent } from "./query-agent.ts"
 
 interface FakePiSession {
 	subscribe(listener: (event: unknown) => void): () => void
@@ -9,8 +12,65 @@ interface FakePiSession {
 	dispose(): void
 }
 
+type CapturedExtensionHandler = (event: unknown) => Promise<unknown> | unknown
+
+interface CapturedExtensionApi {
+	on(event: string, handler: CapturedExtensionHandler): void
+}
+
+type CapturedExtensionFactory = (pi: CapturedExtensionApi) => Promise<void> | void
+
+interface CapturedExtension {
+	handlers: Map<string, CapturedExtensionHandler[]>
+}
+
+interface CapturedResourceLoader {
+	getExtensions(): unknown
+}
+
+interface CapturedDefaultResourceLoaderOptions {
+	extensionFactories?: CapturedExtensionFactory[]
+}
+
+class FakeDefaultResourceLoader implements CapturedResourceLoader {
+	private readonly extensionFactories: CapturedExtensionFactory[]
+	private extensionsResult: { extensions: CapturedExtension[] }
+
+	constructor(options: unknown) {
+		this.extensionFactories = isDefaultResourceLoaderOptions(options)
+			? (options.extensionFactories ?? [])
+			: []
+		this.extensionsResult = { extensions: [] }
+	}
+
+	async reload(): Promise<void> {
+		const handlers: CapturedExtension["handlers"] = new Map()
+		const api: CapturedExtensionApi = {
+			on(event: string, handler: CapturedExtensionHandler): void {
+				const existing = handlers.get(event) ?? []
+				existing.push(handler)
+				handlers.set(event, existing)
+			},
+		}
+
+		for (const factory of this.extensionFactories) {
+			await factory(api)
+		}
+
+		this.extensionsResult = {
+			extensions: [{ handlers }],
+		}
+	}
+
+	getExtensions(): unknown {
+		return this.extensionsResult
+	}
+}
+
 let createAgentSessionCalls = 0
 let createAgentSessionOptions: unknown
+let runtimeApiKeyCalls: Array<{ provider: string; apiKey: string }> = []
+let modelFindCalls: Array<{ provider: string; modelId: string }> = []
 let promptCalls = 0
 let unsubscribeCalls = 0
 let sessionListeners: Array<(event: unknown) => void> = []
@@ -49,11 +109,51 @@ const fakeSession: FakePiSession = {
 	dispose(): void {},
 }
 
+class FakeSessionManager {
+	private messages: unknown[] = []
+	private compaction: { summary: string; tokensBefore: number; timestamp: number } | null = null
+
+	appendMessage(message: unknown): string {
+		this.messages.push(message)
+		return `message-${this.messages.length}`
+	}
+
+	appendCompaction(summary: string, _firstKeptEntryId: string, tokensBefore: number): string {
+		this.compaction = {
+			summary,
+			tokensBefore,
+			timestamp: Date.now(),
+		}
+		this.messages = []
+		return "compaction-1"
+	}
+
+	buildSessionContext(): unknown {
+		const messages = [...this.messages]
+		if (this.compaction) {
+			messages.unshift({
+				role: "compactionSummary",
+				summary: this.compaction.summary,
+				tokensBefore: this.compaction.tokensBefore,
+				timestamp: this.compaction.timestamp,
+			})
+		}
+
+		return {
+			messages,
+			thinkingLevel: "off",
+			model: modelFromMessages(messages),
+		}
+	}
+}
+
 mock.module("@earendil-works/pi-coding-agent", () => ({
 	AuthStorage: {
 		inMemory() {
 			return {
-				setRuntimeApiKey(_provider: string, _apiKey: string): void {},
+				setRuntimeApiKey(provider: string, apiKey: string): void {
+					runtimeApiKeyCalls.push({ provider, apiKey })
+				},
 			}
 		},
 	},
@@ -67,13 +167,15 @@ mock.module("@earendil-works/pi-coding-agent", () => ({
 	createExtensionRuntime() {
 		return {}
 	},
+	DefaultResourceLoader: FakeDefaultResourceLoader,
 	defineTool(tool: unknown): unknown {
 		return tool
 	},
 	ModelRegistry: {
 		inMemory(_authStorage: unknown) {
 			return {
-				find(_provider: string, _modelId: string): unknown {
+				find(provider: string, modelId: string): unknown {
+					modelFindCalls.push({ provider, modelId })
 					return { id: "mock-model" }
 				},
 			}
@@ -81,7 +183,7 @@ mock.module("@earendil-works/pi-coding-agent", () => ({
 	},
 	SessionManager: {
 		inMemory(_cwd: string): unknown {
-			return {}
+			return new FakeSessionManager()
 		},
 	},
 	SettingsManager: {
@@ -94,6 +196,8 @@ mock.module("@earendil-works/pi-coding-agent", () => ({
 beforeEach(() => {
 	createAgentSessionCalls = 0
 	createAgentSessionOptions = undefined
+	runtimeApiKeyCalls = []
+	modelFindCalls = []
 	promptCalls = 0
 	unsubscribeCalls = 0
 	sessionListeners = []
@@ -124,16 +228,14 @@ describe("PiQueryAgent", () => {
 	test("rejects a concurrent first query while the Pi session is being created", async () => {
 		const { PiQueryAgent } = await import("./pi-query-agent.ts")
 		const agent = new PiQueryAgent({
-			sessionManager: createStubSessionManager(),
-			modelProvider: "mock",
-			modelId: "mock-model",
+			toolbox: createStubToolbox(),
+			apiKey: "test-api-key",
 			cwd: "/tmp/freya-pi-query-agent-test",
 			systemPrompt: "test",
 		})
 
 		const firstEvents = collectEvents(
 			agent.ask({
-				userId: "user-1",
 				message: "first",
 			}),
 		)
@@ -142,7 +244,6 @@ describe("PiQueryAgent", () => {
 
 		const secondEvents = await collectEvents(
 			agent.ask({
-				userId: "user-1",
 				message: "second",
 			}),
 		)
@@ -150,10 +251,12 @@ describe("PiQueryAgent", () => {
 		expect(secondEvents).toEqual([
 			{
 				type: "error",
-				message: "A query is already running for this user",
+				message: "A query is already running",
 			},
 		])
 		expect(createAgentSessionCalls).toBe(1)
+		expect(runtimeApiKeyCalls).toEqual([{ provider: "openrouter", apiKey: "test-api-key" }])
+		expect(modelFindCalls).toEqual([{ provider: "openrouter", modelId: "z-ai/glm-4.7-flash" }])
 		expect(promptCalls).toBe(0)
 
 		releaseSessionCreation()
@@ -168,6 +271,228 @@ describe("PiQueryAgent", () => {
 		}
 		expect("agentDir" in createAgentSessionOptions).toBe(false)
 		expect(createAgentSessionOptions.resourceLoader).toBeDefined()
+		expect(typeof sessionCompactHandlerFromCapturedOptions()).toBe("function")
+
+		agent.dispose()
+	})
+
+	test("hydrates initial entries into the Pi session manager", async () => {
+		const { PiQueryAgent } = await import("./pi-query-agent.ts")
+		const agent = new PiQueryAgent({
+			toolbox: createStubToolbox(),
+			cwd: "/tmp/freya-pi-query-agent-test",
+			systemPrompt: "test",
+			initialEntries: [
+				{
+					id: "entry-1",
+					sequence: 1,
+					kind: ConversationEntryKind.UserMessage,
+					payload: {
+						role: "user",
+						parts: [{ type: "text", text: "stored hello" }],
+					},
+					metadata: {},
+					createdAt: new Date("2026-06-15T00:00:00.000Z"),
+				},
+				{
+					id: "entry-2",
+					sequence: 2,
+					kind: ConversationEntryKind.AssistantMessage,
+					payload: {
+						role: "assistant",
+						parts: [{ type: "text", text: "stored reply" }],
+					},
+					metadata: {},
+					createdAt: new Date("2026-06-15T00:00:01.000Z"),
+				},
+			],
+		})
+
+		const events = collectEvents(
+			agent.ask({
+				message: "hello",
+			}),
+		)
+
+		await sessionCreationStarted
+		if (!isRecord(createAgentSessionOptions)) {
+			throw new Error("createAgentSession options were not captured")
+		}
+		const sessionManager = createAgentSessionOptions.sessionManager
+		if (!(sessionManager instanceof FakeSessionManager)) {
+			throw new Error("session manager was not hydrated by PiQueryAgent")
+		}
+		const context = sessionManager.buildSessionContext()
+		if (!isRecord(context) || !Array.isArray(context.messages)) {
+			throw new Error("session context messages were not captured")
+		}
+		expect(context.messages[0]).toEqual({
+			role: "user",
+			content: "stored hello",
+			timestamp: new Date("2026-06-15T00:00:00.000Z").getTime(),
+		})
+		expect(context.messages[1]).toMatchObject({
+			role: "assistant",
+			provider: "openrouter",
+			model: "z-ai/glm-4.7-flash",
+			stopReason: "stop",
+			timestamp: new Date("2026-06-15T00:00:01.000Z").getTime(),
+		})
+
+		releaseSessionCreation()
+		await promptStarted
+		releasePrompt()
+
+		expect(await events).toEqual([{ type: "done" }])
+
+		agent.dispose()
+	})
+
+	test("emits Pi compaction events for the active conversation", async () => {
+		const recordedCompactions: unknown[] = []
+		const { PiQueryAgent } = await import("./pi-query-agent.ts")
+		const agent = new PiQueryAgent({
+			toolbox: createStubToolbox(),
+			cwd: "/tmp/freya-pi-query-agent-test",
+			systemPrompt: "test",
+		})
+		agent.addEventListener(QueryAgentEvent.Compaction, (event) => {
+			recordedCompactions.push(event)
+		})
+
+		const events = collectEvents(
+			agent.ask({
+				conversationId: "conversation-1",
+				message: "hello",
+			}),
+		)
+
+		await sessionCreationStarted
+		releaseSessionCreation()
+		await promptStarted
+
+		const handler = sessionCompactHandlerFromCapturedOptions()
+		await handler({
+			type: "session_compact",
+			fromExtension: false,
+			compactionEntry: {
+				type: "compaction",
+				id: "pi-compaction-1",
+				timestamp: "2026-06-15T00:00:00.000Z",
+				summary: "The user prefers concise updates.",
+				firstKeptEntryId: "pi-entry-7",
+				tokensBefore: 1234,
+				details: { reason: "threshold" },
+			},
+		})
+
+		expect(recordedCompactions).toEqual([
+			{
+				type: QueryAgentEvent.Compaction,
+				conversationId: "conversation-1",
+				summary: "The user prefers concise updates.",
+				firstKeptEntryId: "pi-entry-7",
+				compactedEntryRange: null,
+				tokensBefore: 1234,
+				details: { reason: "threshold" },
+				fromExtension: false,
+			},
+		])
+
+		releasePrompt()
+
+		expect(await events).toEqual([{ type: "done" }])
+		expect(unsubscribeCalls).toBe(1)
+
+		agent.dispose()
+	})
+
+	test("emits Freya coverage through the entry before Pi's kept boundary", async () => {
+		const recordedCompactions: unknown[] = []
+		const { PiQueryAgent } = await import("./pi-query-agent.ts")
+		const agent = new PiQueryAgent({
+			toolbox: createStubToolbox(),
+			cwd: "/tmp/freya-pi-query-agent-test",
+			systemPrompt: "test",
+			initialEntries: [
+				{
+					id: "entry-1",
+					sequence: 1,
+					kind: ConversationEntryKind.UserMessage,
+					payload: {
+						role: "user",
+						parts: [{ type: "text", text: "old hello" }],
+					},
+					metadata: {},
+					createdAt: new Date("2026-06-15T00:00:00.000Z"),
+				},
+				{
+					id: "entry-2",
+					sequence: 2,
+					kind: ConversationEntryKind.AssistantMessage,
+					payload: {
+						role: "assistant",
+						parts: [{ type: "text", text: "kept reply" }],
+					},
+					metadata: {},
+					createdAt: new Date("2026-06-15T00:00:01.000Z"),
+				},
+			],
+		})
+		agent.addEventListener(QueryAgentEvent.Compaction, (event) => {
+			recordedCompactions.push(event)
+		})
+
+		const events = collectEvents(
+			agent.ask({
+				conversationId: "conversation-1",
+				message: "hello",
+			}),
+		)
+
+		await sessionCreationStarted
+
+		await extensionHandlerFromCapturedOptions("session_before_compact")({
+			type: "session_before_compact",
+			preparation: {
+				firstKeptEntryId: "message-2",
+			},
+			branchEntries: [{ id: "message-1" }, { id: "message-2" }],
+		})
+		await extensionHandlerFromCapturedOptions("session_compact")({
+			type: "session_compact",
+			fromExtension: false,
+			compactionEntry: {
+				type: "compaction",
+				id: "pi-compaction-1",
+				timestamp: "2026-06-15T00:00:00.000Z",
+				summary: "Old hello was discussed.",
+				firstKeptEntryId: "message-2",
+				tokensBefore: 1234,
+			},
+		})
+
+		expect(recordedCompactions).toEqual([
+			{
+				type: QueryAgentEvent.Compaction,
+				conversationId: "conversation-1",
+				summary: "Old hello was discussed.",
+				firstKeptEntryId: "message-2",
+				compactedEntryRange: {
+					startSequence: 1,
+					endSequence: 1,
+				},
+				tokensBefore: 1234,
+				details: undefined,
+				fromExtension: false,
+			},
+		])
+
+		releaseSessionCreation()
+		await promptStarted
+		releasePrompt()
+
+		expect(await events).toEqual([{ type: "done" }])
 
 		agent.dispose()
 	})
@@ -175,9 +500,7 @@ describe("PiQueryAgent", () => {
 	test("surfaces Pi message_end provider errors instead of done", async () => {
 		const { PiQueryAgent } = await import("./pi-query-agent.ts")
 		const agent = new PiQueryAgent({
-			sessionManager: createStubSessionManager(),
-			modelProvider: "mock",
-			modelId: "mock-model",
+			toolbox: createStubToolbox(),
 			cwd: "/tmp/freya-pi-query-agent-test",
 			systemPrompt: "test",
 		})
@@ -195,7 +518,6 @@ describe("PiQueryAgent", () => {
 
 		const events = collectEvents(
 			agent.ask({
-				userId: "user-1",
 				message: "hello",
 			}),
 		)
@@ -214,9 +536,7 @@ describe("PiQueryAgent", () => {
 	test("surfaces Pi agent_end provider errors instead of done", async () => {
 		const { PiQueryAgent } = await import("./pi-query-agent.ts")
 		const agent = new PiQueryAgent({
-			sessionManager: createStubSessionManager(),
-			modelProvider: "mock",
-			modelId: "mock-model",
+			toolbox: createStubToolbox(),
 			cwd: "/tmp/freya-pi-query-agent-test",
 			systemPrompt: "test",
 		})
@@ -236,7 +556,6 @@ describe("PiQueryAgent", () => {
 
 		const events = collectEvents(
 			agent.ask({
-				userId: "user-1",
 				message: "hello",
 			}),
 		)
@@ -253,20 +572,113 @@ describe("PiQueryAgent", () => {
 	})
 })
 
-async function collectEvents(events: AsyncIterable<QueryAgentEvent>): Promise<QueryAgentEvent[]> {
-	const result: QueryAgentEvent[] = []
+async function collectEvents(
+	events: AsyncIterable<QueryAgentStreamEvent>,
+): Promise<QueryAgentStreamEvent[]> {
+	const result: QueryAgentStreamEvent[] = []
 	for await (const event of events) {
 		result.push(event)
 	}
 	return result
 }
 
-function createStubSessionManager(): UserSessionManager {
+function createStubToolbox(): QueryAgentToolbox {
 	return {
-		async getOrCreate(): Promise<never> {
+		async listSources(): Promise<never> {
 			throw new Error("not used")
 		},
-	} as unknown as UserSessionManager
+		async getContext(): Promise<never> {
+			throw new Error("not used")
+		},
+		async getFeedItem(): Promise<never> {
+			throw new Error("not used")
+		},
+		async queryContext(): Promise<never> {
+			throw new Error("not used")
+		},
+		async listContext(): Promise<never> {
+			throw new Error("not used")
+		},
+		async getSourceData(): Promise<never> {
+			throw new Error("not used")
+		},
+		async executeAction(): Promise<never> {
+			throw new Error("not used")
+		},
+	}
+}
+
+function sessionCompactHandlerFromCapturedOptions(): CapturedExtensionHandler {
+	return extensionHandlerFromCapturedOptions("session_compact")
+}
+
+function extensionHandlerFromCapturedOptions(eventName: string): CapturedExtensionHandler {
+	if (!isRecord(createAgentSessionOptions)) {
+		throw new Error("createAgentSession options were not captured")
+	}
+
+	const resourceLoader = createAgentSessionOptions.resourceLoader
+	if (!isCapturedResourceLoader(resourceLoader)) {
+		throw new Error("resourceLoader was not captured")
+	}
+
+	const extensionsResult = resourceLoader.getExtensions()
+	if (!isRecord(extensionsResult) || !Array.isArray(extensionsResult.extensions)) {
+		throw new Error("extensions were not captured")
+	}
+
+	const extension = extensionsResult.extensions[0]
+	if (!isCapturedExtension(extension)) {
+		throw new Error("compaction extension was not captured")
+	}
+
+	const handlers = extension.handlers.get(eventName)
+	const handler = handlers?.[0]
+	if (!handler) {
+		throw new Error(`${eventName} handler was not captured`)
+	}
+
+	return handler
+}
+
+function isCapturedResourceLoader(value: unknown): value is CapturedResourceLoader {
+	return isRecord(value) && typeof value.getExtensions === "function"
+}
+
+function isCapturedExtension(value: unknown): value is CapturedExtension {
+	return isRecord(value) && value.handlers instanceof Map
+}
+
+function isDefaultResourceLoaderOptions(
+	value: unknown,
+): value is CapturedDefaultResourceLoaderOptions {
+	return (
+		isRecord(value) &&
+		(value.extensionFactories === undefined ||
+			(Array.isArray(value.extensionFactories) &&
+				value.extensionFactories.every(isCapturedExtensionFactory)))
+	)
+}
+
+function isCapturedExtensionFactory(value: unknown): value is CapturedExtensionFactory {
+	return typeof value === "function"
+}
+
+function modelFromMessages(messages: unknown[]): { provider: string; modelId: string } | null {
+	let model: { provider: string; modelId: string } | null = null
+
+	for (const message of messages) {
+		if (!isRecord(message)) continue
+		if (message.role !== "assistant") continue
+		if (typeof message.provider !== "string" || typeof message.model !== "string") continue
+
+		model = {
+			provider: message.provider,
+			modelId: message.model,
+		}
+	}
+
+	return model
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {

apps/freya-backend/src/agent/pi-query-agent.ts

@@ -1,72 +1,119 @@
-import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent"
+import type {
+	AgentSessionEvent,
+	ExtensionFactory,
+	SessionEntry,
+} from "@earendil-works/pi-coding-agent"
 
 import {
 	AuthStorage,
 	createAgentSession,
+	DefaultResourceLoader,
 	ModelRegistry,
-	SessionManager,
 	SettingsManager,
 } from "@earendil-works/pi-coding-agent"
 import { tmpdir } from "node:os"
 
-import type { UserSessionManager } from "../session/index.ts"
-import type { QueryAgent, QueryAgentAsk, QueryAgentEvent } from "./query-agent.ts"
+import type { ConversationStorageEntry } from "./conversation-recording-query-agent.ts"
+import type { QueryAgentToolbox } from "./query-agent-toolbox.ts"
 
-import { InMemoryResourceLoader } from "./in-memory-resource-loader.ts"
 import defaultSystemPrompt from "./prompts/system.txt"
+import {
+	createQueryAgentEventListeners,
+	QueryAgentEvent,
+	type QueryAgent,
+	type QueryAgentAsk,
+	type QueryAgentCompactedEntryRange,
+	type QueryAgentCompactionEvent,
+	type QueryAgentConversationEntryRef,
+	type QueryAgentEventListeners,
+	type QueryAgentEventListener,
+	type QueryAgentEventMap,
+	type QueryAgentStreamEvent,
+} from "./query-agent.ts"
+import { createSessionManager } from "./session-manager.ts"
 import { createFreyaAgentTools, FREYA_AGENT_TOOL_NAMES } from "./tools.ts"
 
 type PiSession = Awaited<ReturnType<typeof createAgentSession>>["session"]
 type PiMessageEndEvent = Extract<AgentSessionEvent, { type: "message_end" }>
 type PiAgentMessage = PiMessageEndEvent["message"]
 type PiAgentEndEvent = Extract<AgentSessionEvent, { type: "agent_end" }>
+type PiSessionManager = ReturnType<typeof createSessionManager>
+type PiSessionMessage = Parameters<PiSessionManager["appendMessage"]>[0]
 
 export interface PiQueryAgentConfig {
-	sessionManager: UserSessionManager
-	modelProvider: string
-	modelId: string
+	toolbox: QueryAgentToolbox
 	apiKey?: string
 	cwd?: string
 	systemPrompt?: string
+	initialEntries?: ConversationStorageEntry[]
 }
 
+export const PI_MODEL_PROVIDER = "openrouter"
+export const PI_MODEL_ID = "z-ai/glm-4.7-flash"
+
 export class PiQueryAgent implements QueryAgent {
-	private readonly sessionManager: UserSessionManager
+	private readonly toolbox: QueryAgentToolbox
 	private readonly cwd: string
 	private readonly systemPrompt: string
-	private readonly modelProvider: string
-	private readonly modelId: string
 	private readonly apiKey: string | undefined
-	private readonly sessions = new Map<string, PiSession>()
-	private readonly pendingSessions = new Map<string, Promise<PiSession>>()
-	private readonly activeRuns = new Map<string, symbol>()
+	private readonly initialEntries: ConversationStorageEntry[]
+	private readonly eventListeners = createQueryAgentEventListeners()
+	private session: PiSession | null = null
+	private pendingSession: Promise<PiSession> | null = null
+	/**
+	 * Conversation currently receiving Pi events for an active ask().
+	 *
+	 * Pi's compaction hook fires from the SDK session rather than from our
+	 * QueryAgent call stack, so the hook reads this value to attach the
+	 * compaction summary to the right Freya conversation. null means no active
+	 * run; "" means a run is active but no Freya conversation id was supplied.
+	 */
+	private activeConversationId: string | null = null
+	/**
+	 * Freya entry for the user message currently being handed to Pi.
+	 *
+	 * ConversationRecordingQueryAgent appends the user message before calling
+	 * PiQueryAgent. Pi later persists its own copy of that user message into its
+	 * SessionManager, and this one-shot reference lets us map Pi's generated
+	 * session entry id back to the Freya sequence.
+	 */
+	private activeUserMessageEntry: QueryAgentConversationEntryRef | null = null
+	/**
+	 * Maps Pi SessionManager entry ids to Freya conversation sequences.
+	 *
+	 * Pi compaction reports boundaries with Pi entry ids, while our DB replay
+	 * logic uses monotonically increasing Freya sequences. This map is the bridge
+	 * that lets us translate Pi's firstKeptEntryId into a compacted entry range.
+	 */
+	private readonly piEntryConversationSequences = new Map<string, number>()
+	private disposed = false
 
 	constructor(config: PiQueryAgentConfig) {
-		this.sessionManager = config.sessionManager
-		this.modelProvider = config.modelProvider
-		this.modelId = config.modelId
+		this.toolbox = config.toolbox
 		this.apiKey = config.apiKey
 		this.cwd = config.cwd ?? tmpdir()
 		this.systemPrompt = config.systemPrompt ?? defaultSystemPrompt
+		this.initialEntries = config.initialEntries ?? []
 	}
 
-	async *ask(input: QueryAgentAsk): AsyncIterable<QueryAgentEvent> {
-		if (this.activeRuns.has(input.userId)) {
+	async *ask(input: QueryAgentAsk): AsyncIterable<QueryAgentStreamEvent> {
+		if (this.activeConversationId !== null) {
 			yield {
 				type: "error",
-				message: "A query is already running for this user",
+				message: "A query is already running",
 			}
 			return
 		}
 
-		const run = Symbol(input.userId)
-		this.activeRuns.set(input.userId, run)
+		this.activeConversationId = input.conversationId ?? ""
+		this.activeUserMessageEntry = input.userMessageEntry ?? null
 
 		let session: PiSession
 		try {
-			session = await this.getOrCreateSession(input.userId)
+			session = await this.getOrCreateSession()
 		} catch (err) {
-			this.clearActiveRun(input.userId, run)
+			this.activeConversationId = null
+			this.activeUserMessageEntry = null
 			yield {
 				type: "error",
 				message: `Failed to create query session: ${errorMessage(err)}`,
@@ -74,11 +121,11 @@ export class PiQueryAgent implements QueryAgent {
 			return
 		}
 
-		const events: QueryAgentEvent[] = []
+		const events: QueryAgentStreamEvent[] = []
 		let closed = false
 		let wake: (() => void) | null = null
 
-		function push(event: QueryAgentEvent): void {
+		function push(event: QueryAgentStreamEvent): void {
 			events.push(event)
 			if (wake) {
 				wake()
@@ -87,7 +134,7 @@ export class PiQueryAgent implements QueryAgent {
 		}
 
 		let runFailed = false
-		function pushRunEvent(event: QueryAgentEvent): void {
+		function pushRunEvent(event: QueryAgentStreamEvent): void {
 			if (event.type === "error") {
 				if (runFailed) return
 				runFailed = true
@@ -107,7 +154,8 @@ export class PiQueryAgent implements QueryAgent {
 			this.handlePiEvent(event, pushRunEvent)
 		})
 
-		void this.runPrompt(session, input)
+		session
+			.prompt(input.message)
 			.then(() => {
 				if (runFailed) return
 				pushRunEvent({ type: "done" })
@@ -117,7 +165,8 @@ export class PiQueryAgent implements QueryAgent {
 			})
 			.finally(() => {
 				unsubscribe()
-				this.clearActiveRun(input.userId, run)
+				this.activeConversationId = null
+				this.activeUserMessageEntry = null
 				close()
 			})
 
@@ -134,88 +183,256 @@ export class PiQueryAgent implements QueryAgent {
 		}
 	}
 
-	disposeUser(userId: string): void {
-		const session = this.sessions.get(userId)
-		session?.dispose()
-		this.sessions.delete(userId)
-		this.pendingSessions.delete(userId)
-		this.activeRuns.delete(userId)
-	}
-
 	dispose(): void {
-		for (const session of this.sessions.values()) {
-			session.dispose()
-		}
-		this.sessions.clear()
-		this.pendingSessions.clear()
-		this.activeRuns.clear()
+		this.disposed = true
+		this.session?.dispose()
+		this.session = null
+		this.pendingSession = null
+		this.activeConversationId = null
+		this.activeUserMessageEntry = null
+		this.clearEventListeners()
 	}
 
-	private clearActiveRun(userId: string, run: symbol): void {
-		if (this.activeRuns.get(userId) === run) {
-			this.activeRuns.delete(userId)
+	addEventListener<T extends QueryAgentEvent>(
+		type: T,
+		listener: QueryAgentEventListener<T>,
+	): () => void {
+		const listeners = this.listenersFor(type)
+		listeners.add(listener)
+		return () => {
+			listeners.delete(listener)
 		}
 	}
 
-	private async getOrCreateSession(userId: string): Promise<PiSession> {
-		const existing = this.sessions.get(userId)
-		if (existing) return existing
+	private async getOrCreateSession(): Promise<PiSession> {
+		if (this.disposed) {
+			throw new Error("Query agent is disposed")
+		}
 
-		const pending = this.pendingSessions.get(userId)
+		if (this.session) return this.session
+
+		const pending = this.pendingSession
 		if (pending) return pending
 
-		const promise = this.createSession(userId)
-		this.pendingSessions.set(userId, promise)
+		const promise = this.createSession()
+		this.pendingSession = promise
 
 		try {
 			const session = await promise
-			this.sessions.set(userId, session)
+			if (this.disposed) {
+				session.dispose()
+				throw new Error("Query agent is disposed")
+			}
+			this.session = session
 			return session
 		} finally {
-			this.pendingSessions.delete(userId)
+			if (this.pendingSession === promise) {
+				this.pendingSession = null
+			}
 		}
 	}
 
-	private async createSession(userId: string): Promise<PiSession> {
+	private async createSession(): Promise<PiSession> {
 		const settingsManager = SettingsManager.inMemory({
 			compaction: { enabled: true },
 			retry: { enabled: true, maxRetries: 2 },
 		})
 		const authStorage = AuthStorage.inMemory()
 		if (this.apiKey) {
-			authStorage.setRuntimeApiKey(this.modelProvider, this.apiKey)
+			authStorage.setRuntimeApiKey(PI_MODEL_PROVIDER, this.apiKey)
 		}
 
 		const modelRegistry = ModelRegistry.inMemory(authStorage)
-		const model = modelRegistry.find(this.modelProvider, this.modelId)
+		const model = modelRegistry.find(PI_MODEL_PROVIDER, PI_MODEL_ID)
 		if (!model) {
-			throw new Error(`Pi model not found: ${this.modelProvider}/${this.modelId}`)
+			throw new Error(`Pi model not found: ${PI_MODEL_PROVIDER}/${PI_MODEL_ID}`)
 		}
 
+		const resourceLoader = new DefaultResourceLoader({
+			cwd: this.cwd,
+			agentDir: this.cwd,
+			settingsManager,
+			systemPrompt: this.systemPrompt,
+			extensionFactories: [this.createCompactionExtension()],
+			noExtensions: true,
+			noSkills: true,
+			noPromptTemplates: true,
+			noThemes: true,
+			noContextFiles: true,
+		})
+		await resourceLoader.reload()
+
+		const sessionManager = this.createMappedSessionManager()
+
 		const { session } = await createAgentSession({
 			cwd: this.cwd,
 			authStorage,
 			modelRegistry,
 			model,
-			resourceLoader: new InMemoryResourceLoader(this.systemPrompt),
+			resourceLoader,
 			settingsManager,
-			sessionManager: SessionManager.inMemory(this.cwd),
+			sessionManager,
 			noTools: "builtin",
 			customTools: createFreyaAgentTools({
-				userId,
-				sessionManager: this.sessionManager,
+				toolbox: this.toolbox,
 			}),
-			tools: [...FREYA_AGENT_TOOL_NAMES],
+			tools: FREYA_AGENT_TOOL_NAMES,
 		})
 
 		return session
 	}
 
-	private async runPrompt(session: PiSession, input: QueryAgentAsk): Promise<void> {
-		await session.prompt(input.message)
+	/**
+	 * Creates Pi's SessionManager and records Pi-id -> Freya-sequence mappings.
+	 *
+	 * Hydrated DB messages are mapped through createSessionManager's callback.
+	 * Live user messages are mapped by wrapping appendMessage(), because Pi owns
+	 * the generated session entry id for messages written during prompt handling.
+	 */
+	private createMappedSessionManager(): PiSessionManager {
+		this.piEntryConversationSequences.clear()
+		const sessionManager = createSessionManager({
+			cwd: this.cwd,
+			entries: this.initialEntries,
+			modelProvider: PI_MODEL_PROVIDER,
+			modelId: PI_MODEL_ID,
+			onMessageEntryAppended: (piEntryId, entry) => {
+				this.piEntryConversationSequences.set(piEntryId, entry.sequence)
+			},
+		})
+		const appendMessage = sessionManager.appendMessage.bind(sessionManager)
+
+		sessionManager.appendMessage = (message: PiSessionMessage): string => {
+			const piEntryId = appendMessage(message)
+			const sequence = this.liveConversationSequenceForMessage(message)
+			if (sequence !== null) {
+				this.piEntryConversationSequences.set(piEntryId, sequence)
+			}
+			return piEntryId
+		}
+
+		return sessionManager
 	}
 
-	private handlePiEvent(event: AgentSessionEvent, push: (event: QueryAgentEvent) => void): void {
+	/**
+	 * Returns the Freya sequence for Pi's persisted live user message.
+	 *
+	 * We only map user messages here because they are the messages Freya writes
+	 * before invoking Pi. Assistant/tool entries are recorded from the stream
+	 * outside Pi's SessionManager and do not have a stable live Pi id available
+	 * at the storage boundary.
+	 */
+	private liveConversationSequenceForMessage(message: PiSessionMessage): number | null {
+		if (message.role !== "user") return null
+
+		const entry = this.activeUserMessageEntry
+		this.activeUserMessageEntry = null
+		if (!entry) return null
+
+		return entry.sequence
+	}
+
+	/**
+	 * Installs the minimal Pi extension used to observe compaction.
+	 *
+	 * session_before_compact gives us the full branch plus firstKeptEntryId, so
+	 * we translate that boundary before Pi writes the compaction entry. The later
+	 * session_compact event carries the saved summary, which we forward with the
+	 * cached Freya compacted entry range.
+	 */
+	private createCompactionExtension(): ExtensionFactory {
+		return (pi) => {
+			/**
+			 * Temporary handoff between Pi's before/after compaction hooks.
+			 *
+			 * session_compact receives the saved compaction entry, not the original
+			 * branch entries needed for boundary translation.
+			 */
+			let pendingCompactedEntryRange: QueryAgentCompactedEntryRange | null = null
+
+			pi.on("session_before_compact", async (event) => {
+				pendingCompactedEntryRange = this.compactedEntryRangeBeforePiEntry(
+					event.branchEntries,
+					event.preparation.firstKeptEntryId,
+				)
+			})
+
+			pi.on("session_compact", async (event) => {
+				const conversationId = this.activeConversationId
+				if (!conversationId) return
+
+				const entry = event.compactionEntry
+				const compactedEntryRange = pendingCompactedEntryRange
+				pendingCompactedEntryRange = null
+				const compactionEvent: QueryAgentCompactionEvent = {
+					type: QueryAgentEvent.Compaction,
+					conversationId,
+					summary: entry.summary,
+					firstKeptEntryId: entry.firstKeptEntryId,
+					compactedEntryRange,
+					tokensBefore: entry.tokensBefore,
+					details: entry.details,
+					fromExtension: event.fromExtension,
+				}
+
+				await this.emitEvent(compactionEvent)
+			})
+		}
+	}
+
+	/**
+	 * Returns the Freya entry range compacted before a Pi session entry.
+	 *
+	 * Pi keeps firstKeptEntryId and everything after it as raw context. Therefore
+	 * the summary covers only mapped entries before that Pi entry. If none of
+	 * those entries map back to Freya, we return null so storage can avoid
+	 * recording a summary with an unsafe coverage range.
+	 */
+	private compactedEntryRangeBeforePiEntry(
+		branchEntries: SessionEntry[],
+		piEntryId: string,
+	): QueryAgentCompactedEntryRange | null {
+		let endSequence: number | null = null
+		for (const entry of branchEntries) {
+			if (entry.id === piEntryId) {
+				if (endSequence === null) return null
+
+				return {
+					startSequence: 1,
+					endSequence,
+				}
+			}
+
+			const sequence = this.piEntryConversationSequences.get(entry.id)
+			if (typeof sequence === "number") {
+				endSequence = sequence
+			}
+		}
+
+		return null
+	}
+
+	private async emitEvent<T extends QueryAgentEvent>(event: QueryAgentEventMap[T]): Promise<void> {
+		const listeners = this.listenersFor(event.type)
+		for (const listener of listeners) {
+			await listener(event)
+		}
+	}
+
+	private listenersFor<T extends QueryAgentEvent>(type: T): QueryAgentEventListeners[T] {
+		return this.eventListeners[type]
+	}
+
+	private clearEventListeners(): void {
+		for (const listeners of Object.values(this.eventListeners)) {
+			listeners.clear()
+		}
+	}
+
+	private handlePiEvent(
+		event: AgentSessionEvent,
+		push: (event: QueryAgentStreamEvent) => void,
+	): void {
 		switch (event.type) {
 			case "message_end": {
 				const message = piAssistantMessageError(event.message)
@@ -283,7 +500,6 @@ function piAssistantMessageError(message: PiAgentMessage): string | null {
 				case "toolUse":
 					return null
 			}
-			return null
 		default:
 			return null
 	}

apps/freya-backend/src/agent/query-agent-toolbox.ts

@@ -0,0 +1,93 @@
+import type { ContextKeyPart } from "@freya/core"
+
+export interface QueryAgentToolResult {
+	content: Array<{ type: "text"; text: string }>
+	details: Record<string, unknown>
+}
+
+/**
+ * Implementation boundary for FREYA query-agent tools.
+ *
+ * The Pi-facing tool definitions in `tools.ts` should stay thin: they declare
+ * schemas, validate and narrow raw model-provided parameters, then delegate to
+ * this toolbox. Concrete implementations own the actual data gathering,
+ * source/action lookups, result shaping, and any session-specific behavior.
+ */
+export interface QueryAgentToolbox {
+	/**
+	 * Summarizes every source currently visible to the user's session.
+	 *
+	 * Implementations should refresh or read the current feed as needed, then
+	 * return a compact source inventory including feed item counts, context
+	 * entry counts, available action IDs/descriptions, and source errors. This
+	 * is the broad discovery tool an agent can use before deciding which more
+	 * targeted tool call to make.
+	 */
+	listSources(): Promise<QueryAgentToolResult>
+
+	/**
+	 * Reads context entries from the current FREYA context graph.
+	 *
+	 * `key` is a tuple-style context key. With `match: "exact"`, the implementation
+	 * should return only the value at that exact key and indicate whether it was
+	 * found. With `match: "prefix"`, it should return all entries whose keys
+	 * begin with the provided key parts, plus a count. Implementations may refresh
+	 * the feed first so the context reflects the latest source data.
+	 */
+	getContext(key: ContextKeyPart[], match: "exact" | "prefix"): Promise<QueryAgentToolResult>
+
+	/**
+	 * Reads one feed item by ID and includes source-local diagnostics.
+	 *
+	 * Implementations should search the current feed for `feedItemId`. When found,
+	 * the result should include the item plus related context entries, source
+	 * action summaries, and source errors. When missing, the result should clearly
+	 * report `found: false` and return `item: null`.
+	 */
+	getFeedItem(feedItemId: string): Promise<QueryAgentToolResult>
+
+	/**
+	 * Returns the broad context bundle needed to answer a natural-language query.
+	 *
+	 * `question` is included in the result for traceability. If `feedItemId` is
+	 * provided, implementations should also include the matching selected item
+	 * when present. The result should expose the current feed items, context graph
+	 * entries, available source actions, and source errors so the agent can
+	 * synthesize an answer from the user's personal data.
+	 */
+	queryContext(question: string, feedItemId?: string): Promise<QueryAgentToolResult>
+
+	/**
+	 * Lists every current context graph entry.
+	 *
+	 * This is a lower-level inspection tool than `queryContext`: it should return
+	 * all context entries and a count, without feed items or action summaries.
+	 * Implementations may refresh the feed first to ensure source-provided
+	 * context has been materialized.
+	 */
+	listContext(): Promise<QueryAgentToolResult>
+
+	/**
+	 * Returns all currently available data for one source.
+	 *
+	 * Implementations should include whether the source is enabled, all feed
+	 * items from `sourceId`, context entries owned by that source, available
+	 * action summaries, and errors from that source. If `feedItemId` is provided,
+	 * the result should also include the matching selected item from that source
+	 * when present.
+	 */
+	getSourceData(sourceId: string, feedItemId?: string): Promise<QueryAgentToolResult>
+
+	/**
+	 * Executes a source action and returns a serializable execution result.
+	 *
+	 * `sourceId` identifies the source, `actionId` identifies the action within
+	 * that source, and `params` is the source-specific action payload. Tool
+	 * wrappers validate the action envelope, while the source action schema owns
+	 * payload validation. Implementations should let source/action validation
+	 * errors propagate, and on success should return an `ok: true` result plus
+	 * `details.actionExecution` for callers that need a structured record of
+	 * what ran.
+	 */
+	executeAction(sourceId: string, actionId: string, params?: unknown): Promise<QueryAgentToolResult>
+}

apps/freya-backend/src/agent/query-agent.ts

@@ -1,23 +1,74 @@
 export interface QueryAgentAsk {
-	userId: string
 	message: string
+	conversationId?: string
+	userMessageEntry?: QueryAgentConversationEntryRef
 }
 
-export type QueryAgentEvent =
+export type QueryAgentStreamEvent =
+	| { type: "conversation"; conversationId: string }
 	| { type: "text_delta"; text: string }
 	| { type: "tool_start"; toolName: string }
 	| { type: "tool_end"; toolName: string; ok: boolean }
 	| { type: "done" }
 	| { type: "error"; message: string }
 
+export const QueryAgentEvent = {
+	Compaction: "compaction",
+} as const
+
+export type QueryAgentEvent = (typeof QueryAgentEvent)[keyof typeof QueryAgentEvent]
+
+export interface QueryAgentConversationEntryRef {
+	id: string
+	sequence: number
+}
+
+export interface QueryAgentCompactedEntryRange {
+	startSequence: number
+	endSequence: number
+}
+
+export interface QueryAgentCompactionEvent {
+	type: typeof QueryAgentEvent.Compaction
+	conversationId: string
+	summary: string
+	firstKeptEntryId: string
+	compactedEntryRange: QueryAgentCompactedEntryRange | null
+	tokensBefore: number
+	details?: unknown
+	fromExtension: boolean
+}
+
+export interface QueryAgentEventMap {
+	[QueryAgentEvent.Compaction]: QueryAgentCompactionEvent
+}
+
+export type QueryAgentEventListener<T extends QueryAgentEvent> = (
+	event: QueryAgentEventMap[T],
+) => void | Promise<void>
+
+export type QueryAgentEventListeners = {
+	[T in QueryAgentEvent]: Set<QueryAgentEventListener<T>>
+}
+
+export function createQueryAgentEventListeners(): QueryAgentEventListeners {
+	return {
+		[QueryAgentEvent.Compaction]: new Set(),
+	}
+}
+
 export interface QueryAgent {
-	ask(input: QueryAgentAsk): AsyncIterable<QueryAgentEvent>
-	disposeUser(userId: string): void
+	ask(input: QueryAgentAsk): AsyncIterable<QueryAgentStreamEvent>
+	addEventListener<T extends QueryAgentEvent>(
+		type: T,
+		listener: QueryAgentEventListener<T>,
+	): () => void
 	dispose(): void
 }
 
 export interface QueryAgentResponse {
 	message: string
+	conversationId?: string
 }
 
 export class QueryAgentError extends Error {
@@ -32,9 +83,13 @@ export async function collectQueryAgentResponse(
 	input: QueryAgentAsk,
 ): Promise<QueryAgentResponse> {
 	let message = ""
+	let conversationId: string | undefined
 
 	for await (const event of agent.ask(input)) {
 		switch (event.type) {
+			case "conversation":
+				conversationId = event.conversationId
+				break
 			case "text_delta":
 				message += event.text
 				break
@@ -47,5 +102,5 @@ export async function collectQueryAgentResponse(
 		}
 	}
 
-	return { message }
+	return { message, conversationId }
 }

apps/freya-backend/src/agent/session-manager.test.ts

@@ -0,0 +1,156 @@
+import { describe, expect, test } from "bun:test"
+
+import type { ConversationStorageEntry } from "./conversation-recording-query-agent.ts"
+
+import { ConversationEntryKind } from "../conversations/types.ts"
+import { createSessionManager } from "./session-manager.ts"
+
+describe("createSessionManager", () => {
+	test("hydrates user and assistant entries into Pi session context", () => {
+		const sessionManager = createSessionManager({
+			entries: [
+				entry({
+					id: "entry-1",
+					sequence: 1,
+					kind: ConversationEntryKind.UserMessage,
+					payload: {
+						role: "user",
+						parts: [{ type: "text", text: "hello" }],
+					},
+				}),
+				entry({
+					id: "entry-2",
+					sequence: 2,
+					kind: ConversationEntryKind.AssistantMessage,
+					payload: {
+						role: "assistant",
+						parts: [{ type: "text", text: "hi there" }],
+					},
+					metadata: {
+						modelRun: {
+							route: "agent_query",
+							provider: "openrouter",
+							model: "stored-model",
+						},
+					},
+				}),
+			],
+			modelProvider: "openrouter",
+			modelId: "fallback-model",
+		})
+
+		const context = sessionManager.buildSessionContext()
+
+		expect(context.messages.map(roleOf)).toEqual(["user", "assistant"])
+		expect(textFromMessage(context.messages[0])).toBe("hello")
+		expect(textFromMessage(context.messages[1])).toBe("hi there")
+		expect(context.model).toEqual({
+			provider: "openrouter",
+			modelId: "stored-model",
+		})
+	})
+
+	test("uses the latest context summary and replays only uncovered raw entries", () => {
+		const sessionManager = createSessionManager({
+			entries: [
+				entry({
+					id: "entry-1",
+					sequence: 1,
+					kind: ConversationEntryKind.UserMessage,
+					payload: {
+						role: "user",
+						parts: [{ type: "text", text: "old question" }],
+					},
+				}),
+				entry({
+					id: "entry-2",
+					sequence: 2,
+					kind: ConversationEntryKind.AssistantMessage,
+					payload: {
+						role: "assistant",
+						parts: [{ type: "text", text: "old answer" }],
+					},
+				}),
+				entry({
+					id: "entry-3",
+					sequence: 3,
+					kind: ConversationEntryKind.ContextSummary,
+					payload: {
+						covers: {
+							startSequence: 1,
+							endSequence: 2,
+						},
+						summary: {
+							durableFacts: ["The user is designing conversation storage."],
+							preferences: [],
+							decisions: ["Context compaction is stored as a conversation entry."],
+							openTasks: [],
+							importantDetails: [],
+						},
+						promptVersion: "test-v1",
+					},
+				}),
+				entry({
+					id: "entry-4",
+					sequence: 4,
+					kind: ConversationEntryKind.UserMessage,
+					payload: {
+						role: "user",
+						parts: [{ type: "text", text: "new question" }],
+					},
+				}),
+			],
+			modelProvider: "openrouter",
+			modelId: "fallback-model",
+		})
+
+		const context = sessionManager.buildSessionContext()
+
+		expect(context.messages.map(roleOf)).toEqual(["compactionSummary", "user"])
+		expect(textFromMessage(context.messages[0])).toContain(
+			"The user is designing conversation storage.",
+		)
+		expect(textFromMessage(context.messages[0])).toContain(
+			"Context compaction is stored as a conversation entry.",
+		)
+		expect(textFromMessage(context.messages[1])).toBe("new question")
+	})
+})
+
+function entry(
+	input: Omit<ConversationStorageEntry, "createdAt" | "metadata"> & {
+		createdAt?: Date
+		metadata?: ConversationStorageEntry["metadata"]
+	},
+): ConversationStorageEntry {
+	return {
+		...input,
+		metadata: input.metadata ?? {},
+		createdAt: input.createdAt ?? new Date("2026-06-15T00:00:00.000Z"),
+	}
+}
+
+function roleOf(message: unknown): string | undefined {
+	if (!isRecord(message)) return undefined
+	return typeof message.role === "string" ? message.role : undefined
+}
+
+function textFromMessage(message: unknown): string {
+	if (!isRecord(message)) return ""
+	if (typeof message.summary === "string") return message.summary
+
+	const content = message.content
+	if (typeof content === "string") return content
+	if (!Array.isArray(content)) return ""
+
+	return content.map(textFromContentPart).join("")
+}
+
+function textFromContentPart(part: unknown): string {
+	if (!isRecord(part)) return ""
+	return typeof part.text === "string" ? part.text : ""
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null
+}

apps/freya-backend/src/agent/session-manager.ts

@@ -0,0 +1,188 @@
+import { SessionManager } from "@earendil-works/pi-coding-agent"
+import { tmpdir } from "node:os"
+
+import type { ConversationStorageEntry } from "./conversation-recording-query-agent.ts"
+
+import {
+	AssistantMessagePayload,
+	ContextSummaryPayload,
+	ConversationEntryKind,
+	UserMessagePayload,
+} from "../conversations/types.ts"
+
+type PiMessage = Parameters<SessionManager["appendMessage"]>[0]
+type PiAssistantMessage = Extract<PiMessage, { role: "assistant" }>
+
+export interface CreateSessionManagerInput {
+	cwd?: string
+	entries: ConversationStorageEntry[]
+	modelProvider: string
+	modelId: string
+	onMessageEntryAppended?: (piEntryId: string, entry: ConversationStorageEntry) => void
+}
+
+export function createSessionManager(input: CreateSessionManagerInput): SessionManager {
+	const sessionManager = SessionManager.inMemory(input.cwd ?? tmpdir())
+	const context = buildContextFromEntries(input.entries)
+
+	if (context.summary) {
+		sessionManager.appendCompaction(
+			context.summary.text,
+			"freya-db-context-start",
+			0,
+			{
+				conversationEntryId: context.summary.entry.id,
+				covers: context.summary.covers,
+			},
+			true,
+		)
+	}
+
+	for (const entry of context.entries) {
+		const message = messageForEntry(entry, input.modelProvider, input.modelId)
+		if (message) {
+			const piEntryId = sessionManager.appendMessage(message)
+			input.onMessageEntryAppended?.(piEntryId, entry)
+		}
+	}
+
+	return sessionManager
+}
+
+function buildContextFromEntries(entries: ConversationStorageEntry[]): {
+	summary?: { entry: ConversationStorageEntry; text: string; covers: unknown }
+	entries: ConversationStorageEntry[]
+} {
+	const orderedEntries = [...entries].sort((left, right) => left.sequence - right.sequence)
+	const summaryEntry = latestContextSummaryEntry(orderedEntries)
+	if (!summaryEntry || summaryEntry.kind !== ConversationEntryKind.ContextSummary) {
+		return { entries: orderedEntries }
+	}
+
+	const payload = ContextSummaryPayload.assert(summaryEntry.payload)
+	const text = contextSummaryText(payload.summary)
+	const rawStartSequence = payload.covers.endSequence + 1
+
+	return {
+		summary: {
+			entry: summaryEntry,
+			text,
+			covers: payload.covers,
+		},
+		entries: orderedEntries.filter((entry) => entry.sequence >= rawStartSequence),
+	}
+}
+
+function latestContextSummaryEntry(
+	entries: ConversationStorageEntry[],
+): ConversationStorageEntry | undefined {
+	let latest: ConversationStorageEntry | undefined
+
+	for (const entry of entries) {
+		if (entry.kind !== ConversationEntryKind.ContextSummary) continue
+		if (!latest || entry.sequence > latest.sequence) {
+			latest = entry
+		}
+	}
+
+	return latest
+}
+
+function messageForEntry(
+	entry: ConversationStorageEntry,
+	modelProvider: string,
+	modelId: string,
+): PiMessage | null {
+	switch (entry.kind) {
+		case ConversationEntryKind.UserMessage: {
+			const payload = UserMessagePayload.assert(entry.payload)
+			return {
+				role: "user",
+				content: messagePartsText(payload.parts),
+				timestamp: entry.createdAt.getTime(),
+			}
+		}
+		case ConversationEntryKind.AssistantMessage: {
+			const payload = AssistantMessagePayload.assert(entry.payload)
+			return {
+				role: "assistant",
+				content: [{ type: "text", text: messagePartsText(payload.parts) }],
+				api: "anthropic-messages",
+				provider: entry.metadata.modelRun?.provider ?? modelProvider,
+				model: entry.metadata.modelRun?.model ?? modelId,
+				usage: zeroUsage(),
+				stopReason: "stop",
+				timestamp: entry.createdAt.getTime(),
+			} satisfies PiAssistantMessage
+		}
+		case ConversationEntryKind.Attachment:
+		case ConversationEntryKind.ContextSummary:
+		case ConversationEntryKind.SystemNote:
+		case ConversationEntryKind.ToolCall:
+		case ConversationEntryKind.ToolResult:
+			return null
+	}
+}
+
+function messagePartsText(
+	parts: Array<{ type: "text"; text: string } | { type: "json"; value: unknown }>,
+): string {
+	return parts.map(messagePartText).join("\n")
+}
+
+function messagePartText(
+	part: { type: "text"; text: string } | { type: "json"; value: unknown },
+): string {
+	switch (part.type) {
+		case "text":
+			return part.text
+		case "json":
+			return stringifyJson(part.value)
+	}
+}
+
+function contextSummaryText(summary: {
+	userIntent?: string
+	durableFacts: string[]
+	preferences: string[]
+	decisions: string[]
+	openTasks: string[]
+	importantDetails: string[]
+}): string {
+	const sections: string[] = []
+	pushSection(sections, "User intent", summary.userIntent ? [summary.userIntent] : [])
+	pushSection(sections, "Durable facts", summary.durableFacts)
+	pushSection(sections, "Preferences", summary.preferences)
+	pushSection(sections, "Decisions", summary.decisions)
+	pushSection(sections, "Open tasks", summary.openTasks)
+	pushSection(sections, "Important details", summary.importantDetails)
+	return sections.join("\n\n")
+}
+
+function pushSection(sections: string[], title: string, values: string[]): void {
+	const trimmedValues = values.map((value) => value.trim()).filter(Boolean)
+	if (trimmedValues.length === 0) return
+
+	sections.push(`${title}:\n${trimmedValues.map((value) => `- ${value}`).join("\n")}`)
+}
+
+function stringifyJson(value: unknown): string {
+	return JSON.stringify(value, null, 2) ?? String(value)
+}
+
+function zeroUsage(): PiAssistantMessage["usage"] {
+	return {
+		input: 0,
+		output: 0,
+		cacheRead: 0,
+		cacheWrite: 0,
+		totalTokens: 0,
+		cost: {
+			input: 0,
+			output: 0,
+			cacheRead: 0,
+			cacheWrite: 0,
+			total: 0,
+		},
+	}
+}

apps/freya-backend/src/agent/streaming.test.ts

@@ -0,0 +1,149 @@
+import type { AgentEvent } from "@freya/agent-protocol"
+
+import { describe, expect, test } from "bun:test"
+
+import type {
+	QueryAgent,
+	QueryAgentAsk,
+	QueryAgentEvent,
+	QueryAgentEventListener,
+	QueryAgentStreamEvent,
+} from "./query-agent.ts"
+import type { AgentResponseStreamItem } from "./streaming.ts"
+
+import { streamAgentResponse } from "./streaming.ts"
+
+class FakeQueryAgent implements QueryAgent {
+	readonly inputs: QueryAgentAsk[] = []
+	private readonly events: QueryAgentStreamEvent[]
+
+	constructor(events: QueryAgentStreamEvent[]) {
+		this.events = events
+	}
+
+	async *ask(input: QueryAgentAsk): AsyncIterable<QueryAgentStreamEvent> {
+		this.inputs.push(input)
+		for (const event of this.events) {
+			yield event
+		}
+	}
+
+	addEventListener<T extends QueryAgentEvent>(
+		_type: T,
+		_listener: QueryAgentEventListener<T>,
+	): () => void {
+		return () => {}
+	}
+
+	dispose(): void {}
+}
+
+describe("streamAgentResponse", () => {
+	test("emits one message event per completed newline", async () => {
+		const agent = new FakeQueryAgent([
+			{ type: "conversation", conversationId: "conversation-1" },
+			{ type: "text_delta", text: "First message\nSec" },
+			{ type: "text_delta", text: "ond message\nThird message" },
+			{ type: "done" },
+		])
+
+		const { events, result } = await collectStreamAgentResponse(
+			streamAgentResponse({
+				agent,
+				input: { message: "hello" },
+			}),
+		)
+
+		expect(result).toEqual({
+			conversationId: "conversation-1",
+			message: "First message\nSecond message\nThird message",
+		})
+		expect(events).toEqual([
+			{ type: "conversation_started", conversationId: "conversation-1" },
+			{ type: "message_created", text: "First message" },
+			{ type: "message_created", text: "Second message" },
+			{ type: "message_created", text: "Third message" },
+			{ type: "message_finished" },
+		])
+	})
+
+	test("preserves whitespace without emitting empty message events", async () => {
+		const agent = new FakeQueryAgent([
+			{ type: "conversation", conversationId: "conversation-1" },
+			{ type: "text_delta", text: "  const value = 1  \n\n  return value" },
+			{ type: "done" },
+		])
+
+		const { events, result } = await collectStreamAgentResponse(
+			streamAgentResponse({
+				agent,
+				input: { message: "hello" },
+			}),
+		)
+
+		expect(result).toEqual({
+			conversationId: "conversation-1",
+			message: "  const value = 1  \n\n  return value",
+		})
+		expect(events).toEqual([
+			{ type: "conversation_started", conversationId: "conversation-1" },
+			{ type: "message_created", text: "  const value = 1  " },
+			{ type: "message_created", text: "  return value" },
+			{ type: "message_finished" },
+		])
+	})
+
+	test("emits tool and failure events", async () => {
+		const agent = new FakeQueryAgent([
+			{ type: "conversation", conversationId: "conversation-1" },
+			{ type: "text_delta", text: "I'll check" },
+			{ type: "tool_start", toolName: "calendar" },
+			{ type: "tool_end", toolName: "calendar", ok: false },
+			{ type: "text_delta", text: "That failed" },
+			{ type: "error", message: "model unavailable" },
+		])
+		const stream = streamAgentResponse({
+			agent,
+			input: { message: "hello" },
+		})
+		const events: AgentEvent[] = []
+
+		await expect(collectStreamAgentResponse(stream, events)).rejects.toThrow("model unavailable")
+
+		expect(events).toEqual([
+			{ type: "conversation_started", conversationId: "conversation-1" },
+			{ type: "message_created", text: "I'll check" },
+			{ type: "tool_started", toolName: "calendar" },
+			{ type: "tool_finished", toolName: "calendar", ok: false },
+			{ type: "message_created", text: "That failed" },
+			{ type: "message_failed", error: "model unavailable" },
+		])
+	})
+})
+
+async function collectStreamAgentResponse(
+	stream: AsyncIterable<AgentResponseStreamItem>,
+	events: AgentEvent[] = [],
+): Promise<{
+	events: AgentEvent[]
+	result: { message: string; conversationId: string }
+}> {
+	let result: { message: string; conversationId: string } | null = null
+
+	for await (const item of stream) {
+		switch (item.type) {
+			case "event":
+				events.push(item.event)
+				break
+			case "result":
+				result = item.result
+				break
+		}
+	}
+
+	if (!result) {
+		throw new Error("Expected stream result")
+	}
+
+	return { events, result }
+}

apps/freya-backend/src/agent/streaming.ts

@@ -0,0 +1,125 @@
+import type { AgentEvent, SendMessageResult } from "@freya/agent-protocol"
+
+import type { QueryAgent, QueryAgentAsk } from "./query-agent.ts"
+
+export type AgentResponseStreamItem =
+	| { type: "event"; event: AgentEvent }
+	| { type: "result"; result: SendMessageResult }
+
+export async function* streamAgentResponse({
+	agent,
+	input,
+}: {
+	agent: QueryAgent
+	input: QueryAgentAsk
+}): AsyncGenerator<AgentResponseStreamItem, void, void> {
+	let message = ""
+	let conversationId: string | null = null
+	const splitter = new AgentMessageSplitter()
+
+	function messageEvent(text: string): AgentResponseStreamItem | null {
+		if (text.trim() === "") return null
+
+		return { type: "event", event: { type: "message_created", text } }
+	}
+
+	function flushPendingMessage(): AgentResponseStreamItem | null {
+		const text = splitter.flush()
+		if (text === null) return null
+
+		return messageEvent(text)
+	}
+
+	for await (const event of agent.ask(input)) {
+		switch (event.type) {
+			case "conversation":
+				conversationId = event.conversationId
+				yield { type: "event", event: { type: "conversation_started", conversationId } }
+				break
+
+			case "text_delta":
+				message += event.text
+				for (const line of splitter.push(event.text)) {
+					const item = messageEvent(line)
+					if (item) yield item
+				}
+				break
+
+			case "tool_start":
+				{
+					const item = flushPendingMessage()
+					if (item) yield item
+				}
+				yield { type: "event", event: { type: "tool_started", toolName: event.toolName } }
+				break
+
+			case "tool_end":
+				{
+					const item = flushPendingMessage()
+					if (item) yield item
+				}
+				yield {
+					type: "event",
+					event: {
+						type: "tool_finished",
+						toolName: event.toolName,
+						ok: event.ok,
+					},
+				}
+				break
+
+			case "error":
+				{
+					const item = flushPendingMessage()
+					if (item) yield item
+				}
+				yield { type: "event", event: { type: "message_failed", error: event.message } }
+				throw new Error(event.message)
+
+			case "done":
+				{
+					const item = flushPendingMessage()
+					if (item) yield item
+				}
+				const result = createResult(message, conversationId)
+				yield { type: "event", event: { type: "message_finished" } }
+				yield { type: "result", result }
+				return
+		}
+	}
+
+	const item = flushPendingMessage()
+	if (item) yield item
+	const result = createResult(message, conversationId)
+	yield { type: "event", event: { type: "message_finished" } }
+	yield { type: "result", result }
+}
+
+function createResult(message: string, conversationId: string | null): SendMessageResult {
+	if (!conversationId) {
+		throw new Error("Agent response stream ended without a conversation id")
+	}
+
+	return { message, conversationId }
+}
+
+class AgentMessageSplitter {
+	private pending = ""
+
+	push(text: string): string[] {
+		this.pending += text
+
+		const lines = this.pending.split(/\r?\n/)
+		this.pending = lines.pop() ?? ""
+
+		return lines
+	}
+
+	flush(): string | null {
+		if (this.pending === "") return null
+
+		const text = this.pending
+		this.pending = ""
+		return text
+	}
+}

apps/freya-backend/src/agent/tools.test.ts

@@ -0,0 +1,116 @@
+import { describe, expect, mock, test } from "bun:test"
+
+import type { QueryAgentToolResult, QueryAgentToolbox } from "./query-agent-toolbox.ts"
+
+mock.module("@earendil-works/pi-coding-agent", () => ({
+	defineTool(tool: unknown): unknown {
+		return tool
+	},
+}))
+
+interface TestTool {
+	name: string
+	parameters: unknown
+	execute(toolCallId: string, params: unknown): Promise<unknown>
+}
+
+describe("FREYA agent tools", () => {
+	test("rejects unknown top-level params", async () => {
+		const { createFreyaAgentTools, FREYA_GET_CONTEXT_TOOL } = await import("./tools.ts")
+		const tool = expectTool(
+			createFreyaAgentTools({ toolbox: createStubToolbox() }),
+			FREYA_GET_CONTEXT_TOOL,
+		)
+
+		await expect(
+			tool.execute("tool-call-1", {
+				key: ["freya.location"],
+				extra: true,
+			}),
+		).rejects.toThrow("extra")
+	})
+
+	test("rejects invalid context keys", async () => {
+		const { createFreyaAgentTools, FREYA_GET_CONTEXT_TOOL } = await import("./tools.ts")
+		const tool = expectTool(
+			createFreyaAgentTools({ toolbox: createStubToolbox() }),
+			FREYA_GET_CONTEXT_TOOL,
+		)
+
+		await expect(tool.execute("tool-call-1", { key: [] })).rejects.toThrow("key")
+		await expect(tool.execute("tool-call-1", { key: [["freya.location"]] })).rejects.toThrow("key")
+		await expect(
+			tool.execute("tool-call-1", { key: [{ nested: { invalid: true } }] }),
+		).rejects.toThrow("nested")
+	})
+
+	test("marks tool schemas as closed objects", async () => {
+		const { createFreyaAgentTools } = await import("./tools.ts")
+		const tools = createFreyaAgentTools({ toolbox: createStubToolbox() })
+
+		for (const tool of tools.map(expectTestTool)) {
+			expect(expectRecord(tool.parameters).additionalProperties).toBe(false)
+		}
+	})
+})
+
+function createStubToolbox(): QueryAgentToolbox {
+	return {
+		async listSources() {
+			return toolResult({ sources: [] })
+		},
+		async getContext(key, match) {
+			return toolResult({ key, match })
+		},
+		async getFeedItem(feedItemId) {
+			return toolResult({ feedItemId })
+		},
+		async queryContext(question, feedItemId) {
+			return toolResult({ question, feedItemId })
+		},
+		async listContext() {
+			return toolResult({ entries: [] })
+		},
+		async getSourceData(sourceId, feedItemId) {
+			return toolResult({ sourceId, feedItemId })
+		},
+		async executeAction(sourceId, actionId, params) {
+			return toolResult({ sourceId, actionId, params })
+		},
+	}
+}
+
+function toolResult(result: unknown): QueryAgentToolResult {
+	return {
+		content: [{ type: "text", text: JSON.stringify(result) }],
+		details: {},
+	}
+}
+
+function expectTool(tools: unknown[], name: string): TestTool {
+	const tool = tools.map(expectTestTool).find((candidate) => candidate.name === name)
+	if (!tool) {
+		throw new Error(`Missing test tool: ${name}`)
+	}
+	return tool
+}
+
+function expectTestTool(value: unknown): TestTool {
+	const record = expectRecord(value)
+	const execute = record.execute
+	if (typeof record.name !== "string" || typeof execute !== "function") {
+		throw new Error("Expected test tool")
+	}
+	return {
+		name: record.name,
+		parameters: record.parameters,
+		execute: execute as TestTool["execute"],
+	}
+}
+
+function expectRecord(value: unknown): Record<string, unknown> {
+	expect(typeof value).toBe("object")
+	expect(value).not.toBeNull()
+	expect(Array.isArray(value)).toBe(false)
+	return value as Record<string, unknown>
+}

apps/freya-backend/src/agent/tools.ts

@@ -1,14 +1,11 @@
 import { defineTool } from "@earendil-works/pi-coding-agent"
+import { type } from "arktype"
 import { Type } from "typebox"
 
-import type { UserSessionManager } from "../session/index.ts"
-import type { QueryDebugTools } from "./debug-tools.ts"
-
-import { createQueryDebugTools } from "./debug-tools.ts"
+import type { QueryAgentToolbox } from "./query-agent-toolbox.ts"
 
 interface CreateFreyaAgentToolsConfig {
-	userId: string
-	sessionManager: UserSessionManager
+	toolbox: QueryAgentToolbox
 }
 
 export const FREYA_QUERY_CONTEXT_TOOL = "freya_query_context"
@@ -19,6 +16,41 @@ export const FREYA_GET_SOURCE_DATA_TOOL = "freya_get_source_data"
 export const FREYA_GET_FEED_ITEM_TOOL = "freya_get_feed_item"
 export const FREYA_EXECUTE_ACTION_TOOL = "freya_execute_action"
 
+const ContextKeyObjectPart = type("Record<string, string | number | boolean>").narrow(
+	(value) => !Array.isArray(value),
+)
+const ContextKeyPart = type("string | number").or(ContextKeyObjectPart)
+
+const GetContextToolParams = type({
+	"+": "reject",
+	key: ContextKeyPart.array().atLeastLength(1),
+	"match?": "'exact' | 'prefix'",
+})
+
+const GetFeedItemToolParams = type({
+	"+": "reject",
+	feedItemId: type.string.atLeastLength(1),
+})
+
+const QueryContextToolParams = type({
+	"+": "reject",
+	question: type.string.atLeastLength(1),
+	"feedItemId?": "string",
+})
+
+const GetSourceDataToolParams = type({
+	"+": "reject",
+	sourceId: type.string.atLeastLength(1),
+	"feedItemId?": "string",
+})
+
+const ExecuteActionToolParams = type({
+	"+": "reject",
+	sourceId: type.string.atLeastLength(1),
+	actionId: type.string.atLeastLength(1),
+	"params?": "unknown",
+})
+
 export const FREYA_AGENT_TOOL_NAMES = [
 	FREYA_LIST_SOURCES_TOOL,
 	FREYA_GET_CONTEXT_TOOL,
@@ -30,16 +62,13 @@ export const FREYA_AGENT_TOOL_NAMES = [
 ]
 
 export function createFreyaAgentTools(config: CreateFreyaAgentToolsConfig) {
-	const { userId } = config
-	const debugTools = createQueryDebugTools(config.sessionManager)
-
 	const listSourcesTool = defineTool({
 		name: FREYA_LIST_SOURCES_TOOL,
 		label: "List FREYA Sources",
 		description:
 			"List enabled FREYA source IDs and summarize available feed items, context entries, actions, and errors.",
-		parameters: Type.Object({}),
-		execute: async () => executeDebugTool(debugTools, userId, FREYA_LIST_SOURCES_TOOL, {}),
+		parameters: Type.Object({}, { additionalProperties: false }),
+		execute: async () => executeListSourcesTool(config.toolbox),
 	})
 
 	const getContextTool = defineTool({
@@ -47,30 +76,34 @@ export function createFreyaAgentTools(config: CreateFreyaAgentToolsConfig) {
 		label: "Get FREYA Context",
 		description:
 			"Read specific FREYA context entries by key. Use prefix matching to discover entries under a source ID, or exact matching when you know the full key.",
-		parameters: Type.Object({
-			key: Type.Array(Type.Unknown(), {
-				description:
-					'Context key array, for example ["freya.location"] or ["freya.location", "location"].',
-			}),
-			match: Type.Optional(
-				Type.Union([Type.Literal("exact"), Type.Literal("prefix")], {
-					description: "Match mode. Defaults to prefix.",
+		parameters: Type.Object(
+			{
+				key: Type.Array(Type.Unknown(), {
+					description:
+						'Context key array, for example ["freya.location"] or ["freya.location", "location"].',
 				}),
-			),
-		}),
-		execute: async (_toolCallId, params) =>
-			executeDebugTool(debugTools, userId, FREYA_GET_CONTEXT_TOOL, params),
+				match: Type.Optional(
+					Type.Union([Type.Literal("exact"), Type.Literal("prefix")], {
+						description: "Match mode. Defaults to prefix.",
+					}),
+				),
+			},
+			{ additionalProperties: false },
+		),
+		execute: async (_toolCallId, params) => executeGetContextTool(config.toolbox, params),
 	})
 
 	const getFeedItemTool = defineTool({
 		name: FREYA_GET_FEED_ITEM_TOOL,
 		label: "Get FREYA Feed Item",
 		description: "Read one feed item by ID, including related source context, actions, and errors.",
-		parameters: Type.Object({
-			feedItemId: Type.String({ description: "Feed item ID to inspect." }),
-		}),
-		execute: async (_toolCallId, params) =>
-			executeDebugTool(debugTools, userId, FREYA_GET_FEED_ITEM_TOOL, params),
+		parameters: Type.Object(
+			{
+				feedItemId: Type.String({ description: "Feed item ID to inspect." }),
+			},
+			{ additionalProperties: false },
+		),
+		execute: async (_toolCallId, params) => executeGetFeedItemTool(config.toolbox, params),
 	})
 
 	const queryContextTool = defineTool({
@@ -78,17 +111,20 @@ export function createFreyaAgentTools(config: CreateFreyaAgentToolsConfig) {
 		label: "Query FREYA Context",
 		description:
 			"Read the user's current FREYA feed, source graph context, source errors, and available actions.",
-		parameters: Type.Object({
-			question: Type.String({
-				description: "The specific personal-context question to answer.",
-			}),
-			feedItemId: Type.Optional(
-				Type.String({
-					description: "Optional feed item ID when the user is asking about a specific card.",
+		parameters: Type.Object(
+			{
+				question: Type.String({
+					description: "The specific personal-context question to answer.",
 				}),
-			),
-		}),
-		execute: async (_toolCallId, params) => executeQueryContextTool(config, params),
+				feedItemId: Type.Optional(
+					Type.String({
+						description: "Optional feed item ID when the user is asking about a specific card.",
+					}),
+				),
+			},
+			{ additionalProperties: false },
+		),
+		execute: async (_toolCallId, params) => executeQueryContextTool(config.toolbox, params),
 	})
 
 	const listContextTool = defineTool({
@@ -96,8 +132,8 @@ export function createFreyaAgentTools(config: CreateFreyaAgentToolsConfig) {
 		label: "List FREYA Context",
 		description:
 			"List all current FREYA context graph entries for the user. Use this to inspect what personal context is available.",
-		parameters: Type.Object({}),
-		execute: async () => executeListContextTool(config),
+		parameters: Type.Object({}, { additionalProperties: false }),
+		execute: async () => executeListContextTool(config.toolbox),
 	})
 
 	const getSourceDataTool = defineTool({
@@ -105,17 +141,20 @@ export function createFreyaAgentTools(config: CreateFreyaAgentToolsConfig) {
 		label: "Get FREYA Source Data",
 		description:
 			"Get current feed items, context entries, actions, and errors for a specific FREYA source ID.",
-		parameters: Type.Object({
-			sourceId: Type.String({
-				description: "Source ID, for example freya.location, freya.tfl, or freya.weather.",
-			}),
-			feedItemId: Type.Optional(
-				Type.String({
-					description: "Optional feed item ID to select one item from the source.",
+		parameters: Type.Object(
+			{
+				sourceId: Type.String({
+					description: "Source ID, for example freya.location, freya.tfl, or freya.weather.",
 				}),
-			),
-		}),
-		execute: async (_toolCallId, params) => executeGetSourceDataTool(config, params),
+				feedItemId: Type.Optional(
+					Type.String({
+						description: "Optional feed item ID to select one item from the source.",
+					}),
+				),
+			},
+			{ additionalProperties: false },
+		),
+		execute: async (_toolCallId, params) => executeGetSourceDataTool(config.toolbox, params),
 	})
 
 	const executeActionTool = defineTool({
@@ -123,16 +162,19 @@ export function createFreyaAgentTools(config: CreateFreyaAgentToolsConfig) {
 		label: "Execute FREYA Action",
 		description:
 			"Execute an available FREYA source action immediately without creating a proposal.",
-		parameters: Type.Object({
-			sourceId: Type.String({ description: "Source ID that should execute the action." }),
-			actionId: Type.String({ description: "Source action ID to execute." }),
-			params: Type.Optional(
-				Type.Unknown({
-					description: "Parameters to pass to the source action.",
-				}),
-			),
-		}),
-		execute: async (_toolCallId, params) => executeActionToolCall(config, params),
+		parameters: Type.Object(
+			{
+				sourceId: Type.String({ description: "Source ID that should execute the action." }),
+				actionId: Type.String({ description: "Source action ID to execute." }),
+				params: Type.Optional(
+					Type.Unknown({
+						description: "Parameters to pass to the source action.",
+					}),
+				),
+			},
+			{ additionalProperties: false },
+		),
+		execute: async (_toolCallId, params) => executeActionToolCall(config.toolbox, params),
 	})
 
 	return [
@@ -146,166 +188,57 @@ export function createFreyaAgentTools(config: CreateFreyaAgentToolsConfig) {
 	]
 }
 
-async function executeDebugTool(
-	debugTools: QueryDebugTools,
-	userId: string,
-	toolName: string,
-	params: unknown,
-) {
-	const result = await debugTools.execute(userId, toolName, params)
-
-	return {
-		content: [
-			{
-				type: "text" as const,
-				text: JSON.stringify(result),
-			},
-		],
-		details: {},
-	}
+async function executeListSourcesTool(toolbox: QueryAgentToolbox) {
+	return toolbox.listSources()
 }
 
-async function executeQueryContextTool(
-	config: CreateFreyaAgentToolsConfig,
-	params: { question: string; feedItemId?: string },
-) {
-	const userSession = await config.sessionManager.getOrCreate(config.userId)
-	const feed = await userSession.feed()
-	const context = userSession.engine.currentContext()
-	const feedItemId = params.feedItemId
-	const selectedItem =
-		typeof feedItemId === "string" ? feed.items.find((item) => item.id === feedItemId) : undefined
-	const actions = await userSession.listActions()
-
-	return {
-		content: [
-			{
-				type: "text" as const,
-				text: JSON.stringify({
-					time: context.time.toISOString(),
-					question: params.question,
-					feedItemId: feedItemId ?? null,
-					selectedItem: selectedItem ?? null,
-					items: feed.items,
-					context: context.entries(),
-					availableActions: actions.map((entry) => ({
-						sourceId: entry.sourceId,
-						actions: Object.values(entry.actions).map((action) => ({
-							id: action.id,
-							description: action.description ?? null,
-						})),
-					})),
-					errors: feed.errors.map((error) => ({
-						sourceId: error.sourceId,
-						message: error.error.message,
-					})),
-				}),
-			},
-		],
-		details: {},
+async function executeGetContextTool(toolbox: QueryAgentToolbox, rawParams: unknown) {
+	const params = GetContextToolParams(rawParams)
+	if (params instanceof type.errors) {
+		throw new Error(params.summary)
 	}
+
+	const match = params.match ?? "prefix"
+
+	return toolbox.getContext(params.key, match)
 }
 
-async function executeListContextTool(config: CreateFreyaAgentToolsConfig) {
-	const userSession = await config.sessionManager.getOrCreate(config.userId)
-	await userSession.feed()
-	const context = userSession.engine.currentContext()
-	const entries = context.entries()
-
-	return {
-		content: [
-			{
-				type: "text" as const,
-				text: JSON.stringify({
-					time: context.time.toISOString(),
-					count: entries.length,
-					entries,
-				}),
-			},
-		],
-		details: {},
+async function executeGetFeedItemTool(toolbox: QueryAgentToolbox, rawParams: unknown) {
+	const params = GetFeedItemToolParams(rawParams)
+	if (params instanceof type.errors) {
+		throw new Error(params.summary)
 	}
+
+	return toolbox.getFeedItem(params.feedItemId)
 }
 
-async function executeGetSourceDataTool(
-	config: CreateFreyaAgentToolsConfig,
-	params: { sourceId: string; feedItemId?: string },
-) {
-	const userSession = await config.sessionManager.getOrCreate(config.userId)
-	const feed = await userSession.feed()
-	const context = userSession.engine.currentContext()
-	const sourceActions = userSession.hasSource(params.sourceId)
-		? await userSession.engine.listActions(params.sourceId)
-		: {}
-
-	const items = feed.items.filter((item) => item.sourceId === params.sourceId)
-	const selectedItem =
-		params.feedItemId !== undefined
-			? items.find((item) => item.id === params.feedItemId)
-			: undefined
-	const contextEntries = context.entries().filter((entry) => entry.key[0] === params.sourceId)
-	const errors = feed.errors
-		.filter((error) => error.sourceId === params.sourceId)
-		.map((error) => ({
-			sourceId: error.sourceId,
-			message: error.error.message,
-		}))
-
-	return {
-		content: [
-			{
-				type: "text" as const,
-				text: JSON.stringify({
-					time: context.time.toISOString(),
-					sourceId: params.sourceId,
-					hasSource: userSession.hasSource(params.sourceId),
-					feedItemId: params.feedItemId ?? null,
-					selectedItem: selectedItem ?? null,
-					items,
-					context: contextEntries,
-					actions: Object.values(sourceActions).map((action) => ({
-						id: action.id,
-						description: action.description ?? null,
-					})),
-					errors,
-				}),
-			},
-		],
-		details: {},
+async function executeQueryContextTool(toolbox: QueryAgentToolbox, rawParams: unknown) {
+	const params = QueryContextToolParams(rawParams)
+	if (params instanceof type.errors) {
+		throw new Error(params.summary)
 	}
+
+	return toolbox.queryContext(params.question, params.feedItemId)
 }
 
-async function executeActionToolCall(
-	config: CreateFreyaAgentToolsConfig,
-	params: {
-		sourceId: string
-		actionId: string
-		params?: unknown
-	},
-) {
-	const userSession = await config.sessionManager.getOrCreate(config.userId)
-	const result = await userSession.engine.executeAction(
-		params.sourceId,
-		params.actionId,
-		params.params,
-	)
-
-	const actionExecution = {
-		sourceId: params.sourceId,
-		actionId: params.actionId,
-		result: result ?? null,
-	}
-
-	return {
-		content: [
-			{
-				type: "text" as const,
-				text: JSON.stringify({
-					ok: true,
-					...actionExecution,
-				}),
-			},
-		],
-		details: { actionExecution },
-	}
+async function executeListContextTool(toolbox: QueryAgentToolbox) {
+	return toolbox.listContext()
+}
+
+async function executeGetSourceDataTool(toolbox: QueryAgentToolbox, rawParams: unknown) {
+	const params = GetSourceDataToolParams(rawParams)
+	if (params instanceof type.errors) {
+		throw new Error(params.summary)
+	}
+
+	return toolbox.getSourceData(params.sourceId, params.feedItemId)
+}
+
+async function executeActionToolCall(toolbox: QueryAgentToolbox, rawParams: unknown) {
+	const params = ExecuteActionToolParams(rawParams)
+	if (params instanceof type.errors) {
+		throw new Error(params.summary)
+	}
+
+	return toolbox.executeAction(params.sourceId, params.actionId, params.params)
 }

apps/freya-backend/src/agent/user-session-query-agent-toolbox.ts

@@ -0,0 +1,253 @@
+import { contextKey, type ContextKeyPart } from "@freya/core"
+
+import type { UserSession } from "../session/user-session.ts"
+import type { QueryAgentToolResult, QueryAgentToolbox } from "./query-agent-toolbox.ts"
+
+export class UserSessionQueryAgentToolbox implements QueryAgentToolbox {
+	constructor(private readonly session: UserSession) {}
+
+	async listSources(): Promise<QueryAgentToolResult> {
+		const feed = await this.session.feed()
+		const context = this.session.engine.currentContext()
+		const contextEntries = context.entries()
+		const actions = await this.session.listActions()
+
+		const feedCounts = countBy(feed.items.map((item) => item.sourceId))
+		const contextCounts = countBy(
+			contextEntries
+				.map((entry) => entry.key[0])
+				.filter((part): part is string => typeof part === "string"),
+		)
+		const errors = groupErrorsBySource(
+			feed.errors.map((error) => ({
+				sourceId: error.sourceId,
+				message: error.error.message,
+			})),
+		)
+		const actionEntries = new Map(actions.map((entry) => [entry.sourceId, entry.actions]))
+		const sourceIds = new Set<string>([
+			...actionEntries.keys(),
+			...feedCounts.keys(),
+			...contextCounts.keys(),
+			...errors.keys(),
+		])
+
+		return toolResult({
+			time: context.time.toISOString(),
+			sources: [...sourceIds].sort().map((sourceId) => {
+				const sourceActions = actionEntries.get(sourceId) ?? {}
+				const feedItemCount = feedCounts.get(sourceId) ?? 0
+				const contextEntryCount = contextCounts.get(sourceId) ?? 0
+
+				return {
+					sourceId,
+					hasFeedItems: feedItemCount > 0,
+					feedItemCount,
+					hasContext: contextEntryCount > 0,
+					contextEntryCount,
+					actions: Object.values(sourceActions).map((action) => ({
+						id: action.id,
+						description: action.description ?? null,
+					})),
+					errors: errors.get(sourceId) ?? [],
+				}
+			}),
+		})
+	}
+
+	async getContext(
+		key: ContextKeyPart[],
+		match: "exact" | "prefix",
+	): Promise<QueryAgentToolResult> {
+		await this.session.feed()
+		const context = this.session.engine.currentContext()
+		const keyObject = contextKey(...key)
+
+		if (match === "exact") {
+			const value = context.get(keyObject)
+			return toolResult({
+				time: context.time.toISOString(),
+				match,
+				key,
+				found: value !== undefined,
+				value: value ?? null,
+			})
+		}
+
+		const entries = context.find(keyObject)
+		return toolResult({
+			time: context.time.toISOString(),
+			match,
+			key,
+			count: entries.length,
+			entries,
+		})
+	}
+
+	async getFeedItem(feedItemId: string): Promise<QueryAgentToolResult> {
+		const feed = await this.session.feed()
+		const context = this.session.engine.currentContext()
+		const item = feed.items.find((candidate) => candidate.id === feedItemId)
+
+		if (!item) {
+			return toolResult({
+				time: context.time.toISOString(),
+				feedItemId,
+				found: false,
+				item: null,
+			})
+		}
+
+		const sourceActions = this.session.hasSource(item.sourceId)
+			? await this.session.engine.listActions(item.sourceId)
+			: {}
+		const errors = feed.errors
+			.filter((error) => error.sourceId === item.sourceId)
+			.map((error) => ({
+				sourceId: error.sourceId,
+				message: error.error.message,
+			}))
+
+		return toolResult({
+			time: context.time.toISOString(),
+			feedItemId,
+			found: true,
+			item,
+			source: {
+				sourceId: item.sourceId,
+				hasSource: this.session.hasSource(item.sourceId),
+				context: context.entries().filter((entry) => entry.key[0] === item.sourceId),
+				actions: Object.values(sourceActions).map((action) => ({
+					id: action.id,
+					description: action.description ?? null,
+				})),
+				errors,
+			},
+		})
+	}
+
+	async queryContext(question: string, feedItemId?: string): Promise<QueryAgentToolResult> {
+		const feed = await this.session.feed()
+		const context = this.session.engine.currentContext()
+		const selectedItem = feedItemId ? feed.items.find((item) => item.id === feedItemId) : undefined
+		const actions = await this.session.listActions()
+
+		return toolResult({
+			time: context.time.toISOString(),
+			question,
+			feedItemId: feedItemId ?? null,
+			selectedItem: selectedItem ?? null,
+			items: feed.items,
+			context: context.entries(),
+			availableActions: actions.map((entry) => ({
+				sourceId: entry.sourceId,
+				actions: Object.values(entry.actions).map((action) => ({
+					id: action.id,
+					description: action.description ?? null,
+				})),
+			})),
+			errors: feed.errors.map((error) => ({
+				sourceId: error.sourceId,
+				message: error.error.message,
+			})),
+		})
+	}
+
+	async listContext(): Promise<QueryAgentToolResult> {
+		await this.session.feed()
+		const context = this.session.engine.currentContext()
+		const entries = context.entries()
+
+		return toolResult({
+			time: context.time.toISOString(),
+			count: entries.length,
+			entries,
+		})
+	}
+
+	async getSourceData(sourceId: string, feedItemId?: string): Promise<QueryAgentToolResult> {
+		const feed = await this.session.feed()
+		const context = this.session.engine.currentContext()
+		const sourceActions = this.session.hasSource(sourceId)
+			? await this.session.engine.listActions(sourceId)
+			: {}
+
+		const items = feed.items.filter((item) => item.sourceId === sourceId)
+		const selectedItem = feedItemId ? items.find((item) => item.id === feedItemId) : undefined
+		const contextEntries = context.entries().filter((entry) => entry.key[0] === sourceId)
+		const errors = feed.errors
+			.filter((error) => error.sourceId === sourceId)
+			.map((error) => ({
+				sourceId: error.sourceId,
+				message: error.error.message,
+			}))
+
+		return toolResult({
+			time: context.time.toISOString(),
+			sourceId,
+			hasSource: this.session.hasSource(sourceId),
+			feedItemId: feedItemId ?? null,
+			selectedItem: selectedItem ?? null,
+			items,
+			context: contextEntries,
+			actions: Object.values(sourceActions).map((action) => ({
+				id: action.id,
+				description: action.description ?? null,
+			})),
+			errors,
+		})
+	}
+
+	async executeAction(
+		sourceId: string,
+		actionId: string,
+		params?: unknown,
+	): Promise<QueryAgentToolResult> {
+		const result = await this.session.engine.executeAction(sourceId, actionId, params)
+		const actionExecution = {
+			sourceId,
+			actionId,
+			result: result ?? null,
+		}
+
+		return toolResult(
+			{
+				ok: true,
+				...actionExecution,
+			},
+			{ actionExecution },
+		)
+	}
+}
+
+function toolResult(result: unknown, details: Record<string, unknown> = {}): QueryAgentToolResult {
+	return {
+		content: [
+			{
+				type: "text" as const,
+				text: JSON.stringify(result),
+			},
+		],
+		details,
+	}
+}
+
+function countBy(values: string[]): Map<string, number> {
+	const result = new Map<string, number>()
+	for (const value of values) {
+		result.set(value, (result.get(value) ?? 0) + 1)
+	}
+	return result
+}
+
+function groupErrorsBySource(
+	errors: Array<{ sourceId: string; message: string }>,
+): Map<string, Array<{ sourceId: string; message: string }>> {
+	const result = new Map<string, Array<{ sourceId: string; message: string }>>()
+	for (const error of errors) {
+		const group = result.get(error.sourceId) ?? []
+		group.push(error)
+		result.set(error.sourceId, group)
+	}
+	return result
+}

apps/freya-backend/src/agent/ws.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, test } from "bun:test"
+import { Hono } from "hono"
+
+import type { UserSessionManager } from "../session/index.ts"
+
+import { registerAgentWebSocketHandlers } from "./ws.ts"
+
+describe("agent websocket handler", () => {
+	test("rejects disallowed browser origins before authenticating", async () => {
+		let sessionChecked = false
+		const app = new Hono()
+
+		registerAgentWebSocketHandlers(app, {
+			sessionManager: {} as UserSessionManager,
+			corsMiddleware: async (c, next) => {
+				const origin = c.req.header("origin")
+				if (origin && origin !== "https://app.freya.test") {
+					return c.text("Forbidden", 403)
+				}
+
+				await next()
+			},
+			authSessionMiddleware: async (c) => {
+				sessionChecked = true
+				return c.json({ error: "Unauthorized" }, 401)
+			},
+		})
+
+		const res = await app.fetch(
+			new Request("https://api.freya.test/api/agent/ws", {
+				headers: {
+					origin: "https://evil.test",
+					upgrade: "websocket",
+				},
+			}),
+		)
+
+		expect(res.status).toBe(403)
+		expect(sessionChecked).toBe(false)
+	})
+
+	test("allows requests without an origin header", async () => {
+		let sessionChecked = false
+		const app = new Hono()
+
+		registerAgentWebSocketHandlers(app, {
+			sessionManager: {} as UserSessionManager,
+			corsMiddleware: async (_c, next) => {
+				await next()
+			},
+			authSessionMiddleware: async (c) => {
+				sessionChecked = true
+				return c.json({ error: "Unauthorized" }, 401)
+			},
+		})
+
+		const res = await app.fetch(
+			new Request("https://api.freya.test/api/agent/ws", {
+				headers: {
+					upgrade: "websocket",
+				},
+			}),
+		)
+
+		expect(res.status).toBe(401)
+		expect(sessionChecked).toBe(true)
+	})
+})

apps/freya-backend/src/agent/ws.ts

@@ -0,0 +1,287 @@
+import type { AgentClientApi, AgentServerApi, SendMessageResult } from "@freya/agent-protocol"
+import type { JrpcChannel, JrpcMessage, JsonRpcMessage } from "@nym.sh/jrpc"
+import type { Hono, MiddlewareHandler } from "hono"
+import type { WSContext } from "hono/ws"
+
+import { JsonRpcClient, JsonRpcServer } from "@nym.sh/jrpc"
+import { type } from "arktype"
+import { upgradeWebSocket, websocket } from "hono/bun"
+
+import type { AuthSessionMiddleware } from "../auth/session-middleware.ts"
+import type { UserSessionManager } from "../session/index.ts"
+
+import { streamAgentResponse } from "./streaming.ts"
+
+interface AgentWebSocketHandlerDeps {
+	sessionManager: UserSessionManager
+	authSessionMiddleware: AuthSessionMiddleware
+	corsMiddleware: MiddlewareHandler
+}
+
+interface ValidSendMessageInput {
+	message: string
+}
+
+export const agentWebSocket = websocket
+
+const SendMessageInputBody = type({
+	"+": "reject",
+	message: "string",
+})
+
+export function registerAgentWebSocketHandlers(
+	app: Hono,
+	{ sessionManager, authSessionMiddleware, corsMiddleware }: AgentWebSocketHandlerDeps,
+): void {
+	app.get(
+		"/api/agent/ws",
+		corsMiddleware,
+		authSessionMiddleware,
+		upgradeWebSocket((c) => {
+			const user = c.get("user")
+			if (!user) {
+				throw new Error("Authenticated WebSocket user missing")
+			}
+
+			const channel = new HonoWebSocketJrpcChannel()
+			const connection = new AgentRpcConnection({
+				channel,
+				sessionManager,
+				userId: user.id,
+			})
+
+			return {
+				onOpen(_event, ws) {
+					channel.attach(ws)
+					void connection.start().catch((err: unknown) => {
+						console.error("[query] Agent WebSocket JSON-RPC failed:", errorMessage(err))
+						ws.close(1011, "Agent RPC connection failed")
+					})
+				},
+
+				onMessage(event) {
+					channel.receive(event.data)
+				},
+
+				onClose() {
+					channel.close()
+				},
+			}
+		}),
+	)
+}
+
+class AgentRpcConnection implements AgentServerApi {
+	private readonly client: JsonRpcClient<AgentClientApi>
+	private readonly server: JsonRpcServer<AgentServerApi>
+	private activeMessage: Promise<SendMessageResult> | null = null
+	private readonly sessionManager: UserSessionManager
+	private readonly userId: string
+
+	constructor({
+		channel,
+		sessionManager,
+		userId,
+	}: {
+		channel: JrpcChannel
+		sessionManager: UserSessionManager
+		userId: string
+	}) {
+		this.sessionManager = sessionManager
+		this.userId = userId
+		this.client = new JsonRpcClient<AgentClientApi>(channel)
+		this.server = new JsonRpcServer<AgentServerApi>(
+			{
+				sendMessage: this.sendMessage.bind(this),
+				ping: this.ping.bind(this),
+			},
+			channel,
+		)
+	}
+
+	start(): Promise<void> {
+		return this.server.start()
+	}
+
+	async sendMessage(message: string): Promise<SendMessageResult> {
+		const parsed = SendMessageInputBody({ message })
+		if (parsed instanceof type.errors) {
+			throw new Error(parsed.summary)
+		}
+
+		if (this.activeMessage) {
+			throw new Error("A message is already running")
+		}
+
+		const run = this.runMessage(parsed)
+		this.activeMessage = run
+
+		try {
+			return await run
+		} finally {
+			if (this.activeMessage === run) {
+				this.activeMessage = null
+			}
+		}
+	}
+
+	ping(): "pong" {
+		return "pong"
+	}
+
+	private async runMessage(input: ValidSendMessageInput): Promise<SendMessageResult> {
+		const session = await this.sessionManager.getOrCreate(this.userId)
+		let result: SendMessageResult | null = null
+
+		for await (const item of streamAgentResponse({ agent: session.agent, input })) {
+			switch (item.type) {
+				case "event":
+					await this.client.call("notify", item.event)
+					break
+				case "result":
+					result = item.result
+					break
+			}
+		}
+
+		if (!result) {
+			throw new Error("Agent response stream ended without a result")
+		}
+
+		return result
+	}
+}
+
+class HonoWebSocketJrpcChannel implements JrpcChannel {
+	private closed = false
+	private queue: JrpcMessage[] = []
+	private waiters: Array<(result: IteratorResult<JrpcMessage, void>) => void> = []
+	private ws: WSContext | null = null
+
+	attach(ws: WSContext): void {
+		this.ws = ws
+	}
+
+	async send(msg: JsonRpcMessage): Promise<void> {
+		if (this.closed || !this.ws) {
+			throw new Error("JSON-RPC WebSocket channel is closed")
+		}
+
+		this.ws.send(JSON.stringify(msg))
+	}
+
+	receive(message: unknown): void {
+		const parsed = parseJrpcMessage(message)
+		if (!parsed) {
+			this.ws?.close(1003, "Invalid JSON-RPC message")
+			return
+		}
+
+		this.push(parsed)
+	}
+
+	async next(): Promise<IteratorResult<JrpcMessage, void>> {
+		const msg = this.queue.shift()
+		if (msg) {
+			return { done: false, value: msg }
+		}
+
+		if (this.closed) {
+			return { done: true, value: undefined }
+		}
+
+		return new Promise((resolve) => {
+			this.waiters.push(resolve)
+		})
+	}
+
+	async return(): Promise<IteratorResult<JrpcMessage, void>> {
+		this.close()
+		this.ws?.close()
+		return { done: true, value: undefined }
+	}
+
+	async throw(error?: unknown): Promise<IteratorResult<JrpcMessage, void>> {
+		this.close()
+		throw error
+	}
+
+	async [Symbol.asyncDispose](): Promise<void> {
+		await this.return()
+	}
+
+	close(): void {
+		if (this.closed) return
+
+		this.closed = true
+		for (const resolve of this.waiters.splice(0)) {
+			resolve({ done: true, value: undefined })
+		}
+	}
+
+	[Symbol.asyncIterator](): AsyncGenerator<JrpcMessage, void, unknown> {
+		return this
+	}
+
+	private push(msg: JrpcMessage): void {
+		if (this.closed) return
+
+		const resolve = this.waiters.shift()
+		if (resolve) {
+			resolve({ done: false, value: msg })
+			return
+		}
+
+		this.queue.push(msg)
+	}
+}
+
+function parseJrpcMessage(message: unknown): JrpcMessage | null {
+	const text = webSocketMessageText(message)
+	if (text === null) return null
+
+	try {
+		const value: unknown = JSON.parse(text)
+		return isJrpcMessage(value) ? value : null
+	} catch {
+		return null
+	}
+}
+
+function webSocketMessageText(message: unknown): string | null {
+	if (typeof message === "string") return message
+	if (message instanceof ArrayBuffer) return Buffer.from(message).toString("utf8")
+	if (ArrayBuffer.isView(message)) {
+		return Buffer.from(message.buffer, message.byteOffset, message.byteLength).toString("utf8")
+	}
+
+	return null
+}
+
+function isJrpcMessage(value: unknown): value is JrpcMessage {
+	if (typeof value !== "object" || value === null) return false
+	if (!("jsonrpc" in value) || value.jsonrpc !== "2.0") return false
+
+	if ("method" in value) {
+		return "id" in value && typeof value.id === "number" && typeof value.method === "string"
+	}
+
+	if ("result" in value) {
+		return "id" in value && typeof value.id === "number"
+	}
+
+	if ("error" in value) {
+		return (
+			"id" in value &&
+			typeof value.id === "number" &&
+			typeof value.error === "object" &&
+			value.error !== null
+		)
+	}
+
+	return false
+}
+
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error)
+}

apps/freya-backend/src/auth/session-middleware.ts

@@ -53,16 +53,6 @@ export function createRequireSession(auth: Auth): AuthSessionMiddleware {
 	}
 }
 
-/**
- * Creates a function to get session from headers. Useful for WebSocket upgrade validation.
- */
-export function createGetSessionFromHeaders(auth: Auth) {
-	return async (headers: Headers): Promise<{ user: AuthUser; session: AuthSession } | null> => {
-		const session = await auth.api.getSession({ headers })
-		return session
-	}
-}
-
 /**
  * Dev/test middleware that injects a fake user and session.
  * Pass userId to simulate an authenticated request, or omit to get 401.

apps/freya-backend/src/conversations/http.test.ts

@@ -0,0 +1,110 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test"
+import { Hono } from "hono"
+
+import type { Database } from "../db/index.ts"
+import type { ConversationRow } from "./storage.ts"
+
+import { mockAuthSessionMiddleware } from "../auth/session-middleware.ts"
+import { registerConversationsHttpHandlers } from "./http.ts"
+
+const MockUserId = "k7Gx2mPqRvNwYs9TdLfA4bHcJeUo1iZn"
+
+const conversationRowsByUser = new Map<string, ConversationRow[]>()
+
+mock.module("./storage.ts", () => ({
+	conversations: (_db: Database, userId: string) => ({
+		async listConversations(): Promise<ConversationRow[]> {
+			return conversationRowsByUser.get(userId) ?? []
+		},
+	}),
+}))
+
+const fakeDb = {} as Database
+
+function buildTestApp(userId?: string) {
+	const app = new Hono()
+	registerConversationsHttpHandlers(app, {
+		db: fakeDb,
+		authSessionMiddleware: mockAuthSessionMiddleware(userId),
+	})
+	return app
+}
+
+function createConversationRow(
+	id: string,
+	createdAt: string,
+	updatedAt: string,
+	userId = MockUserId,
+): ConversationRow {
+	return {
+		id,
+		userId,
+		createdAt: new Date(createdAt),
+		updatedAt: new Date(updatedAt),
+	}
+}
+
+describe("GET /api/conversations", () => {
+	beforeEach(() => {
+		conversationRowsByUser.clear()
+	})
+
+	test("returns 401 without auth", async () => {
+		const app = buildTestApp()
+
+		const res = await app.request("/api/conversations")
+
+		expect(res.status).toBe(401)
+	})
+
+	test("returns conversation summaries for the authenticated user", async () => {
+		conversationRowsByUser.set(MockUserId, [
+			createConversationRow(
+				"conversation-newer",
+				"2026-06-16T10:00:00.000Z",
+				"2026-06-17T09:30:00.000Z",
+			),
+			createConversationRow(
+				"conversation-older",
+				"2026-06-15T10:00:00.000Z",
+				"2026-06-16T09:30:00.000Z",
+			),
+		])
+		const app = buildTestApp("user-1")
+
+		const res = await app.request("/api/conversations")
+
+		expect(res.status).toBe(200)
+		const body = (await res.json()) as {
+			conversations: Array<{ id: string; createdAt: string; updatedAt: string }>
+		}
+		expect(body).toEqual({
+			conversations: [
+				{
+					id: "conversation-newer",
+					createdAt: "2026-06-16T10:00:00.000Z",
+					updatedAt: "2026-06-17T09:30:00.000Z",
+				},
+				{
+					id: "conversation-older",
+					createdAt: "2026-06-15T10:00:00.000Z",
+					updatedAt: "2026-06-16T09:30:00.000Z",
+				},
+			],
+		})
+	})
+
+	test("returns an empty list when no conversations exist", async () => {
+		const app = buildTestApp("user-1")
+
+		const res = await app.request("/api/conversations")
+
+		expect(res.status).toBe(200)
+		const body = (await res.json()) as {
+			conversations: Array<{ id: string; createdAt: string; updatedAt: string }>
+		}
+		expect(body).toEqual({
+			conversations: [],
+		})
+	})
+})

apps/freya-backend/src/conversations/http.ts

@@ -0,0 +1,44 @@
+import type { Context, Hono } from "hono"
+
+import { createMiddleware } from "hono/factory"
+
+import type { AuthSessionMiddleware } from "../auth/session-middleware.ts"
+import type { Database } from "../db/index.ts"
+
+import { conversations } from "./storage.ts"
+
+type Env = {
+	Variables: {
+		db: Database
+	}
+}
+
+interface ConversationsHttpHandlersDeps {
+	db: Database
+	authSessionMiddleware: AuthSessionMiddleware
+}
+
+export function registerConversationsHttpHandlers(
+	app: Hono,
+	{ db, authSessionMiddleware }: ConversationsHttpHandlersDeps,
+) {
+	const inject = createMiddleware<Env>(async (c, next) => {
+		c.set("db", db)
+		await next()
+	})
+
+	app.get("/api/conversations", inject, authSessionMiddleware, handleListConversations)
+}
+
+async function handleListConversations(c: Context<Env>) {
+	const user = c.get("user")!
+	const db = c.get("db")
+
+	return c.json({
+		conversations: (await conversations(db, user.id).listConversations()).map((row) => ({
+			id: row.id,
+			createdAt: row.createdAt.toISOString(),
+			updatedAt: row.updatedAt.toISOString(),
+		})),
+	})
+}

apps/freya-backend/src/conversations/storage.ts

@@ -0,0 +1,381 @@
+import { and, asc, desc, eq } from "drizzle-orm"
+
+import type { Database } from "../db/index.ts"
+import type {
+	AssistantMessagePayload,
+	AttachmentPayload,
+	ContextSummaryPayload,
+	ConversationEntryKind as ConversationEntryKindType,
+	ConversationEntryMetadata,
+	ConversationEntryPayload,
+	ConversationEntryVisibility as ConversationEntryVisibilityType,
+	GenericObjectPayload,
+	UserMessagePayload,
+} from "./types.ts"
+
+import {
+	conversationEntries,
+	conversations as conversationsTable,
+	files,
+	user,
+} from "../db/schema.ts"
+import {
+	ConversationEntryMetadata as ConversationEntryMetadataSchema,
+	AssistantMessagePayload as AssistantMessagePayloadSchema,
+	AttachmentPayload as AttachmentPayloadSchema,
+	ConversationEntryKind,
+	ConversationEntryKindInput,
+	ConversationEntryVisibility,
+	ConversationEntryVisibilityInput,
+	ContextSummaryPayload as ContextSummaryPayloadSchema,
+	GenericObjectPayload as GenericObjectPayloadSchema,
+	UserMessagePayload as UserMessagePayloadSchema,
+} from "./types.ts"
+
+export type ConversationRow = typeof conversationsTable.$inferSelect
+export type ConversationEntryRow = typeof conversationEntries.$inferSelect
+export type FileRow = typeof files.$inferSelect
+
+export interface CreateFileInput {
+	storageKey: string
+	originalName?: string
+	mimeType: string
+	sizeBytes: number
+	metadata?: Record<string, unknown>
+}
+
+export interface AppendAttachmentEntryInput {
+	file: CreateFileInput
+	payload: AttachmentPayload
+	visibility?: ConversationEntryVisibilityType
+	metadata?: ConversationEntryMetadata
+}
+
+export interface AppendAttachmentEntryResult {
+	file: FileRow
+	entry: ConversationEntryRow
+}
+
+interface AppendConversationEntryBase {
+	visibility?: ConversationEntryVisibilityType
+	metadata?: ConversationEntryMetadata
+}
+
+export type AppendConversationEntryInput =
+	| (AppendConversationEntryBase & {
+			kind: typeof ConversationEntryKind.UserMessage
+			payload: UserMessagePayload
+			fileId?: never
+	  })
+	| (AppendConversationEntryBase & {
+			kind: typeof ConversationEntryKind.AssistantMessage
+			payload: AssistantMessagePayload
+			fileId?: never
+	  })
+	| (AppendConversationEntryBase & {
+			kind: typeof ConversationEntryKind.Attachment
+			payload: AttachmentPayload
+			fileId: string
+	  })
+	| (AppendConversationEntryBase & {
+			kind: typeof ConversationEntryKind.ContextSummary
+			payload: ContextSummaryPayload
+			fileId?: never
+	  })
+	| (AppendConversationEntryBase & {
+			kind:
+				| typeof ConversationEntryKind.ToolCall
+				| typeof ConversationEntryKind.ToolResult
+				| typeof ConversationEntryKind.SystemNote
+			payload: GenericObjectPayload
+			fileId?: never
+	  })
+
+export interface ListConversationEntriesParams {
+	visibility?: ConversationEntryVisibilityType
+}
+
+export function conversations(db: Database, userId: string) {
+	return {
+		async createConversation(): Promise<ConversationRow> {
+			return insertConversation(db, userId)
+		},
+
+		async listConversations(): Promise<ConversationRow[]> {
+			return db
+				.select()
+				.from(conversationsTable)
+				.where(eq(conversationsTable.userId, userId))
+				.orderBy(desc(conversationsTable.updatedAt), desc(conversationsTable.createdAt))
+		},
+
+		async getOrCreateConversation(): Promise<ConversationRow> {
+			return db.transaction(async (tx) => {
+				await requireUserForUpdate(tx, userId)
+				const existing = await latestConversation(tx, userId)
+				if (existing) return existing
+
+				return insertConversation(tx, userId)
+			})
+		},
+
+		async createFile(input: CreateFileInput): Promise<FileRow> {
+			return insertFile(db, userId, input)
+		},
+
+		async appendEntry(
+			conversationId: string,
+			input: AppendConversationEntryInput,
+		): Promise<ConversationEntryRow> {
+			const kind = ConversationEntryKindInput.assert(input.kind)
+			const visibility = ConversationEntryVisibilityInput.assert(
+				input.visibility ?? defaultVisibilityForKind(kind),
+			)
+			const payload = payloadForKind(kind, input.payload)
+			const metadata = ConversationEntryMetadataSchema.assert(input.metadata ?? {})
+			let fileId: string | null = null
+
+			if (input.kind === ConversationEntryKind.Attachment) {
+				fileId = input.fileId
+				await requireFile(db, userId, fileId)
+			}
+
+			const rows = await db.transaction(async (tx) => {
+				await requireConversationForUpdate(tx, userId, conversationId)
+				const sequence = await nextSequence(tx, conversationId)
+
+				const rows = await tx
+					.insert(conversationEntries)
+					.values({
+						conversationId,
+						sequence,
+						kind,
+						visibility,
+						fileId,
+						payload,
+						metadata,
+					})
+					.returning()
+
+				await touchConversation(tx, userId, conversationId)
+				return rows
+			})
+
+			return requireRow(rows)
+		},
+
+		async appendAttachmentEntry(
+			conversationId: string,
+			input: AppendAttachmentEntryInput,
+		): Promise<AppendAttachmentEntryResult> {
+			const payload = AttachmentPayloadSchema.assert(input.payload)
+			const visibility = ConversationEntryVisibilityInput.assert(
+				input.visibility ?? defaultVisibilityForKind(ConversationEntryKind.Attachment),
+			)
+			const metadata = ConversationEntryMetadataSchema.assert(input.metadata ?? {})
+
+			return db.transaction(async (tx) => {
+				await requireConversationForUpdate(tx, userId, conversationId)
+
+				const file = await insertFile(tx, userId, input.file)
+				const sequence = await nextSequence(tx, conversationId)
+				const rows = await tx
+					.insert(conversationEntries)
+					.values({
+						conversationId,
+						sequence,
+						kind: ConversationEntryKind.Attachment,
+						visibility,
+						fileId: file.id,
+						payload,
+						metadata,
+					})
+					.returning()
+
+				await touchConversation(tx, userId, conversationId)
+				return {
+					file,
+					entry: requireRow(rows),
+				}
+			})
+		},
+
+		async listEntries(
+			conversationId: string,
+			params: ListConversationEntriesParams = {},
+		): Promise<ConversationEntryRow[]> {
+			await requireConversation(db, userId, conversationId)
+
+			if (params.visibility) {
+				return db
+					.select()
+					.from(conversationEntries)
+					.where(
+						and(
+							eq(conversationEntries.conversationId, conversationId),
+							eq(conversationEntries.visibility, params.visibility),
+						),
+					)
+					.orderBy(asc(conversationEntries.sequence))
+			}
+
+			return db
+				.select()
+				.from(conversationEntries)
+				.where(eq(conversationEntries.conversationId, conversationId))
+				.orderBy(asc(conversationEntries.sequence))
+		},
+	}
+}
+
+function payloadForKind(
+	kind: ConversationEntryKindType,
+	payload: AppendConversationEntryInput["payload"],
+): ConversationEntryPayload {
+	switch (kind) {
+		case ConversationEntryKind.UserMessage:
+			return UserMessagePayloadSchema.assert(payload)
+		case ConversationEntryKind.AssistantMessage:
+			return AssistantMessagePayloadSchema.assert(payload)
+		case ConversationEntryKind.Attachment:
+			return AttachmentPayloadSchema.assert(payload)
+		case ConversationEntryKind.ContextSummary:
+			return ContextSummaryPayloadSchema.assert(payload)
+		case ConversationEntryKind.ToolCall:
+		case ConversationEntryKind.ToolResult:
+		case ConversationEntryKind.SystemNote:
+			return GenericObjectPayloadSchema.assert(payload)
+	}
+}
+
+async function requireUserForUpdate(db: Database, userId: string): Promise<void> {
+	const rows = await db
+		.select({ id: user.id })
+		.from(user)
+		.where(eq(user.id, userId))
+		.limit(1)
+		.for("update")
+
+	requireRow(rows, `User not found: ${userId}`)
+}
+
+async function requireConversation(
+	db: Database,
+	userId: string,
+	conversationId: string,
+): Promise<ConversationRow> {
+	const rows = await db
+		.select()
+		.from(conversationsTable)
+		.where(and(eq(conversationsTable.id, conversationId), eq(conversationsTable.userId, userId)))
+		.limit(1)
+
+	return requireRow(rows, `Conversation not found: ${conversationId}`)
+}
+
+async function requireConversationForUpdate(
+	db: Database,
+	userId: string,
+	conversationId: string,
+): Promise<ConversationRow> {
+	const rows = await db
+		.select()
+		.from(conversationsTable)
+		.where(and(eq(conversationsTable.id, conversationId), eq(conversationsTable.userId, userId)))
+		.limit(1)
+		.for("update")
+
+	return requireRow(rows, `Conversation not found: ${conversationId}`)
+}
+
+async function latestConversation(db: Database, userId: string): Promise<ConversationRow | null> {
+	const rows = await db
+		.select()
+		.from(conversationsTable)
+		.where(eq(conversationsTable.userId, userId))
+		.orderBy(desc(conversationsTable.updatedAt), desc(conversationsTable.createdAt))
+		.limit(1)
+
+	return rows[0] ?? null
+}
+
+async function insertConversation(db: Database, userId: string): Promise<ConversationRow> {
+	const rows = await db
+		.insert(conversationsTable)
+		.values({
+			userId,
+		})
+		.returning()
+
+	return requireRow(rows)
+}
+
+async function requireFile(db: Database, userId: string, fileId: string): Promise<FileRow> {
+	const rows = await db
+		.select()
+		.from(files)
+		.where(and(eq(files.id, fileId), eq(files.userId, userId)))
+		.limit(1)
+
+	return requireRow(rows, `File not found: ${fileId}`)
+}
+
+async function insertFile(db: Database, userId: string, input: CreateFileInput): Promise<FileRow> {
+	const rows = await db
+		.insert(files)
+		.values({
+			userId,
+			storageKey: input.storageKey,
+			originalName: input.originalName ?? null,
+			mimeType: input.mimeType,
+			sizeBytes: input.sizeBytes,
+			metadata: input.metadata ?? {},
+		})
+		.returning()
+
+	return requireRow(rows)
+}
+
+async function touchConversation(
+	db: Database,
+	userId: string,
+	conversationId: string,
+): Promise<void> {
+	await db
+		.update(conversationsTable)
+		.set({ updatedAt: new Date() })
+		.where(and(eq(conversationsTable.id, conversationId), eq(conversationsTable.userId, userId)))
+}
+
+async function nextSequence(db: Database, conversationId: string): Promise<number> {
+	const rows = await db
+		.select({ sequence: conversationEntries.sequence })
+		.from(conversationEntries)
+		.where(eq(conversationEntries.conversationId, conversationId))
+		.orderBy(desc(conversationEntries.sequence))
+		.limit(1)
+
+	return (rows[0]?.sequence ?? 0) + 1
+}
+
+function requireRow<T>(rows: T[], message = "Expected database row"): T {
+	const row = rows[0]
+	if (!row) throw new Error(message)
+	return row
+}
+
+function defaultVisibilityForKind(
+	kind: ConversationEntryKindType,
+): ConversationEntryVisibilityType {
+	switch (kind) {
+		case ConversationEntryKind.UserMessage:
+		case ConversationEntryKind.AssistantMessage:
+		case ConversationEntryKind.Attachment:
+			return ConversationEntryVisibility.UserVisible
+		case ConversationEntryKind.ToolCall:
+		case ConversationEntryKind.ToolResult:
+		case ConversationEntryKind.ContextSummary:
+		case ConversationEntryKind.SystemNote:
+			return ConversationEntryVisibility.Internal
+	}
+}

apps/freya-backend/src/conversations/types.test.ts

@@ -0,0 +1,146 @@
+import { describe, expect, test } from "bun:test"
+
+import {
+	AttachmentType,
+	AttachmentPayload,
+	ContextSummaryPayload,
+	ConversationEntryMetadata,
+	GenericObjectPayload,
+	UserMessagePayload,
+} from "./types.ts"
+
+describe("conversation entry schemas", () => {
+	test("parses valid user message payloads", () => {
+		const payload = UserMessagePayload.assert({
+			role: "user",
+			parts: [{ type: "text", text: "hello" }],
+		})
+
+		expect(payload).toEqual({
+			role: "user",
+			parts: [{ type: "text", text: "hello" }],
+		})
+	})
+
+	test("rejects user message payloads with the wrong role", () => {
+		expect(() =>
+			UserMessagePayload.assert({
+				role: "assistant",
+				parts: [{ type: "text", text: "hello" }],
+			}),
+		).toThrow()
+	})
+
+	test("rejects user message payloads with no parts", () => {
+		expect(() =>
+			UserMessagePayload.assert({
+				role: "user",
+				parts: [],
+			}),
+		).toThrow()
+	})
+
+	test("parses valid attachment payloads", () => {
+		const payload = AttachmentPayload.assert({
+			role: "user",
+			name: "whiteboard.png",
+			mimeType: "image/png",
+			attachmentType: AttachmentType.Image,
+			caption: "whiteboard sketch",
+		})
+
+		expect(payload).toEqual({
+			role: "user",
+			name: "whiteboard.png",
+			mimeType: "image/png",
+			attachmentType: AttachmentType.Image,
+			caption: "whiteboard sketch",
+		})
+	})
+
+	test("rejects extra fields on structured payloads", () => {
+		expect(() =>
+			AttachmentPayload.assert({
+				role: "user",
+				name: "whiteboard.png",
+				mimeType: "image/png",
+				attachmentType: AttachmentType.Image,
+				fileId: "file-1",
+			}),
+		).toThrow()
+	})
+
+	test("parses context summary payloads", () => {
+		const payload = ContextSummaryPayload.assert({
+			covers: {
+				startSequence: 1,
+				endSequence: 12,
+			},
+			summary: {
+				userIntent: "Design message storage.",
+				durableFacts: [],
+				preferences: ["Keep the schema simple."],
+				decisions: ["Use conversation_entries as the timeline."],
+				openTasks: [],
+				importantDetails: [],
+			},
+			promptVersion: "conversation-summary-v1",
+			sourceEntryIds: ["entry-1", "entry-2"],
+		})
+
+		expect(payload).toMatchObject({
+			covers: {
+				startSequence: 1,
+				endSequence: 12,
+			},
+			promptVersion: "conversation-summary-v1",
+		})
+	})
+
+	test("allows generic object payloads for tool entries", () => {
+		const payload = GenericObjectPayload.assert({
+			toolCallId: "call-1",
+			toolName: "calendar.search",
+			input: { date: "2026-06-15" },
+		})
+
+		expect(payload).toEqual({
+			toolCallId: "call-1",
+			toolName: "calendar.search",
+			input: { date: "2026-06-15" },
+		})
+	})
+
+	test("rejects non-object generic payloads", () => {
+		expect(() => GenericObjectPayload.assert("done")).toThrow()
+	})
+
+	test("parses model run metadata and allows extra top-level metadata", () => {
+		const metadata = ConversationEntryMetadata.assert({
+			modelRun: {
+				route: "default-chat",
+				provider: "pi",
+				model: "pi-model",
+				inputTokens: 120,
+				outputTokens: 24,
+			},
+			traceId: "trace-1",
+		})
+
+		expect(metadata.modelRun?.model).toBe("pi-model")
+		expect(metadata.traceId).toBe("trace-1")
+	})
+
+	test("rejects invalid model run metadata", () => {
+		expect(() =>
+			ConversationEntryMetadata.assert({
+				modelRun: {
+					route: "default-chat",
+					provider: "pi",
+					model: "pi-model",
+					inputTokens: -1,
+				},
+			}),
+		).toThrow()
+	})
+})

apps/freya-backend/src/conversations/types.ts

@@ -0,0 +1,136 @@
+import { type } from "arktype"
+
+export const ConversationEntryKind = {
+	UserMessage: "user_message",
+	AssistantMessage: "assistant_message",
+	Attachment: "attachment",
+	ToolCall: "tool_call",
+	ToolResult: "tool_result",
+	ContextSummary: "context_summary",
+	SystemNote: "system_note",
+} as const
+
+export type ConversationEntryKind =
+	(typeof ConversationEntryKind)[keyof typeof ConversationEntryKind]
+
+export const ConversationEntryVisibility = {
+	UserVisible: "user_visible",
+	Internal: "internal",
+} as const
+
+export type ConversationEntryVisibility =
+	(typeof ConversationEntryVisibility)[keyof typeof ConversationEntryVisibility]
+
+export const AttachmentType = {
+	Image: "image",
+	Audio: "audio",
+	Video: "video",
+	Document: "document",
+	Other: "other",
+} as const
+
+export type AttachmentType = (typeof AttachmentType)[keyof typeof AttachmentType]
+
+export const ConversationEntryKindInput = type.enumerated(...Object.values(ConversationEntryKind))
+export const ConversationEntryVisibilityInput = type.enumerated(
+	...Object.values(ConversationEntryVisibility),
+)
+export const AttachmentTypeInput = type.enumerated(...Object.values(AttachmentType))
+
+const TextMessagePart = type({
+	"+": "reject",
+	type: "'text'",
+	text: "string",
+})
+
+const JsonMessagePart = type({
+	"+": "reject",
+	type: "'json'",
+	value: "unknown",
+})
+
+export const MessagePart = type.or(TextMessagePart, JsonMessagePart)
+export type MessagePart = typeof MessagePart.infer
+
+export const UserMessagePayload = type({
+	"+": "reject",
+	role: "'user'",
+	parts: MessagePart.array().atLeastLength(1),
+})
+
+export type UserMessagePayload = typeof UserMessagePayload.infer
+
+export const AssistantMessagePayload = type({
+	"+": "reject",
+	role: "'assistant'",
+	parts: MessagePart.array().atLeastLength(1),
+})
+
+export type AssistantMessagePayload = typeof AssistantMessagePayload.infer
+
+export const AttachmentPayload = type({
+	"+": "reject",
+	role: type.enumerated("user", "assistant"),
+	name: "string",
+	mimeType: "string",
+	attachmentType: AttachmentTypeInput,
+	"caption?": "string",
+})
+
+export type AttachmentPayload = typeof AttachmentPayload.infer
+
+const ContextSummary = type({
+	"+": "reject",
+	"userIntent?": "string",
+	durableFacts: type.string.array(),
+	preferences: type.string.array(),
+	decisions: type.string.array(),
+	openTasks: type.string.array(),
+	importantDetails: type.string.array(),
+})
+
+export const ContextSummaryPayload = type({
+	"+": "reject",
+	covers: type({
+		"+": "reject",
+		startSequence: "number.integer >= 1",
+		endSequence: "number.integer >= 1",
+	}),
+	summary: ContextSummary,
+	promptVersion: "string",
+	"sourceEntryIds?": type.string.array(),
+})
+
+export type ContextSummaryPayload = typeof ContextSummaryPayload.infer
+
+export const ModelRunMetadata = type({
+	"+": "reject",
+	route: "string",
+	provider: "string",
+	model: "string",
+	"contextSummaryEntryId?": "string",
+	"rawEntriesStartSequence?": "number.integer >= 1",
+	"rawEntriesEndSequence?": "number.integer >= 1",
+	"inputTokens?": "number.integer >= 0",
+	"outputTokens?": "number.integer >= 0",
+	"providerRequestId?": "string",
+})
+
+export type ModelRunMetadata = typeof ModelRunMetadata.infer
+
+export const ConversationEntryMetadata = type({
+	"modelRun?": ModelRunMetadata,
+	"[string]": "unknown",
+})
+
+export type ConversationEntryMetadata = typeof ConversationEntryMetadata.infer
+
+export const GenericObjectPayload = type("Record<string, unknown>")
+export type GenericObjectPayload = typeof GenericObjectPayload.infer
+
+export type ConversationEntryPayload =
+	| UserMessagePayload
+	| AssistantMessagePayload
+	| AttachmentPayload
+	| ContextSummaryPayload
+	| GenericObjectPayload

apps/freya-backend/src/db/schema.ts

@@ -1,6 +1,9 @@
+import { sql } from "drizzle-orm"
 import {
 	boolean,
+	check,
 	customType,
+	integer,
 	index,
 	jsonb,
 	pgTable,
@@ -10,6 +13,14 @@ import {
 	uuid,
 } from "drizzle-orm/pg-core"
 
+import {
+	ConversationEntryVisibility,
+	type ConversationEntryKind,
+	type ConversationEntryMetadata,
+	type ConversationEntryPayload,
+	type ConversationEntryVisibility as ConversationEntryVisibilityType,
+} from "../conversations/types.ts"
+
 // ---------------------------------------------------------------------------
 // Better Auth core tables
 // Re-exported from CLI-generated schema.
@@ -61,6 +72,81 @@ export const userSources = pgTable(
 	],
 )
 
+// ---------------------------------------------------------------------------
+// FREYA — conversations
+// ---------------------------------------------------------------------------
+
+export const conversations = pgTable(
+	"conversations",
+	{
+		id: uuid("id").primaryKey().defaultRandom(),
+		userId: text("user_id")
+			.notNull()
+			.references(() => user.id, { onDelete: "cascade" }),
+		createdAt: timestamp("created_at").notNull().defaultNow(),
+		updatedAt: timestamp("updated_at")
+			.notNull()
+			.defaultNow()
+			.$onUpdate(() => new Date()),
+	},
+	(t) => [index("conversations_user_id_updated_at_idx").on(t.userId, t.updatedAt)],
+)
+
+export const files = pgTable(
+	"files",
+	{
+		id: uuid("id").primaryKey().defaultRandom(),
+		userId: text("user_id")
+			.notNull()
+			.references(() => user.id, { onDelete: "cascade" }),
+		storageKey: text("storage_key").notNull(),
+		originalName: text("original_name"),
+		mimeType: text("mime_type").notNull(),
+		sizeBytes: integer("size_bytes").notNull(),
+		metadata: jsonb("metadata").$type<Record<string, unknown>>().notNull().default({}),
+		createdAt: timestamp("created_at").notNull().defaultNow(),
+	},
+	(t) => [
+		unique("files_storage_key_unique").on(t.storageKey),
+		index("files_user_id_created_at_idx").on(t.userId, t.createdAt),
+	],
+)
+
+export const conversationEntries = pgTable(
+	"conversation_entries",
+	{
+		id: uuid("id").primaryKey().defaultRandom(),
+		conversationId: uuid("conversation_id")
+			.notNull()
+			.references(() => conversations.id, { onDelete: "cascade" }),
+		sequence: integer("sequence").notNull(),
+		kind: text("kind").$type<ConversationEntryKind>().notNull(),
+		visibility: text("visibility")
+			.$type<ConversationEntryVisibilityType>()
+			.notNull()
+			.default(ConversationEntryVisibility.Internal),
+		fileId: uuid("file_id").references(() => files.id, { onDelete: "restrict" }),
+		payload: jsonb("payload").$type<ConversationEntryPayload>().notNull(),
+		metadata: jsonb("metadata").$type<ConversationEntryMetadata>().notNull().default({}),
+		createdAt: timestamp("created_at").notNull().defaultNow(),
+	},
+	(t) => [
+		unique("conversation_entries_conversation_id_sequence_unique").on(t.conversationId, t.sequence),
+		index("conversation_entries_conversation_id_sequence_idx").on(t.conversationId, t.sequence),
+		index("conversation_entries_conversation_id_visibility_sequence_idx").on(
+			t.conversationId,
+			t.visibility,
+			t.sequence,
+		),
+		index("conversation_entries_kind_idx").on(t.kind),
+		index("conversation_entries_file_id_idx").on(t.fileId),
+		check(
+			"conversation_entries_attachment_file_id_check",
+			sql`(${t.kind} = 'attachment' and ${t.fileId} is not null) or (${t.kind} <> 'attachment' and ${t.fileId} is null)`,
+		),
+	],
+)
+
 // ---------------------------------------------------------------------------
 // FREYA — reminders source storage
 // ---------------------------------------------------------------------------

apps/freya-backend/src/engine/http.test.ts

@@ -85,6 +85,20 @@ mock.module("../sources/user-sources.ts", () => ({
 	}),
 }))
 
+mock.module("../conversations/storage.ts", () => ({
+	conversations: (_db: Database, userId: string) => ({
+		async getOrCreateConversation() {
+			return { id: `conversation-${userId}` }
+		},
+		async listEntries() {
+			return []
+		},
+		async appendEntry() {
+			return { id: "entry-1", sequence: 1 }
+		},
+	}),
+}))
+
 const fakeDb = {} as Database
 
 describe("GET /api/feed", () => {

apps/freya-backend/src/lib/env.test.ts

@@ -11,7 +11,6 @@ describe("ensureEnv", () => {
 			EXA_API_KEY: " exa-key ",
 			GOOGLE_MAPS_API_KEY: " google-maps-key ",
 			OPENROUTER_API_KEY: " openrouter-key ",
-			OPENROUTER_MODEL: " model-name ",
 			TFL_API_KEY: " tfl-key ",
 			WEATHERKIT_KEY_ID: " weather-key-id ",
 			WEATHERKIT_PRIVATE_KEY: " weather-private-key ",
@@ -26,7 +25,6 @@ describe("ensureEnv", () => {
 			exaApiKey: "exa-key",
 			googleMapsApiKey: "google-maps-key",
 			openrouterApiKey: "openrouter-key",
-			openrouterModel: "model-name",
 			tflApiKey: "tfl-key",
 			weatherkitKeyId: "weather-key-id",
 			weatherkitPrivateKey: "weather-private-key",
@@ -53,25 +51,6 @@ describe("ensureEnv", () => {
 		).toThrow("Missing required environment variables: GOOGLE_MAPS_API_KEY")
 	})
 
-	test("allows openrouter model to be omitted", () => {
-		const env = ensureEnv({
-			BETTER_AUTH_SECRET: "auth-secret",
-			CREDENTIAL_ENCRYPTION_KEY: "credential-key",
-			DATABASE_URL: "postgres://example",
-			EXA_API_KEY: "exa-key",
-			GOOGLE_MAPS_API_KEY: "google-maps-key",
-			OPENROUTER_API_KEY: "openrouter-key",
-			TFL_API_KEY: "tfl-key",
-			WEATHERKIT_KEY_ID: "weather-key-id",
-			WEATHERKIT_PRIVATE_KEY: "weather-private-key",
-			WEATHERKIT_SERVICE_ID: "weather-service-id",
-			WEATHERKIT_TEAM_ID: "weather-team-id",
-		})
-
-		expect(env.googleMapsApiKey).toBe("google-maps-key")
-		expect(env.openrouterModel).toBeUndefined()
-	})
-
 	test("throws with all missing required env names", () => {
 		expect(() => ensureEnv({})).toThrow(
 			"Missing required environment variables: BETTER_AUTH_SECRET, CREDENTIAL_ENCRYPTION_KEY, DATABASE_URL, EXA_API_KEY, OPENROUTER_API_KEY, TFL_API_KEY, WEATHERKIT_PRIVATE_KEY, WEATHERKIT_KEY_ID, WEATHERKIT_TEAM_ID, WEATHERKIT_SERVICE_ID, GOOGLE_MAPS_API_KEY",

apps/freya-backend/src/lib/env.ts

@@ -5,7 +5,6 @@ export interface ServerEnv {
 	exaApiKey: string
 	googleMapsApiKey: string
 	openrouterApiKey: string
-	openrouterModel: string | undefined
 	tflApiKey: string
 	weatherkitKeyId: string
 	weatherkitPrivateKey: string
@@ -39,7 +38,6 @@ export function ensureEnv(env: Record<string, string | undefined>): ServerEnv {
 		exaApiKey,
 		googleMapsApiKey,
 		openrouterApiKey,
-		openrouterModel: readOptionalEnv(env, "OPENROUTER_MODEL"),
 		tflApiKey,
 		weatherkitKeyId,
 		weatherkitPrivateKey,

apps/freya-backend/src/server.ts

@@ -1,10 +1,11 @@
 import { Hono } from "hono"
 import { cors } from "hono/cors"
+import { createMiddleware } from "hono/factory"
 
 import { registerAdminHttpHandlers } from "./admin/http.ts"
 import { createQueryDebugTools } from "./agent/debug-tools.ts"
 import { registerAgentHttpHandlers, registerDebugAgentHttpHandlers } from "./agent/http.ts"
-import { PiQueryAgent } from "./agent/pi-query-agent.ts"
+import { agentWebSocket, registerAgentWebSocketHandlers } from "./agent/ws.ts"
 import { createRequireAdmin } from "./auth/admin-middleware.ts"
 import { registerAuthHandlers } from "./auth/http.ts"
 import { createAuth } from "./auth/index.ts"
@@ -35,11 +36,11 @@ function main() {
 	const feedEnhancer = createFeedEnhancer({
 		client: createLlmClient({
 			apiKey: env.openrouterApiKey,
-			model: env.openrouterModel,
 		}),
 	})
 
 	const credentialEncryptor = new CredentialEncryptor(env.credentialEncryptionKey)
+	const piApiKey = process.env.PI_API_KEY ?? env.openrouterApiKey
 
 	const sessionManager = new UserSessionManager({
 		db,
@@ -63,13 +64,9 @@ function main() {
 		],
 		feedEnhancer,
 		credentialEncryptor,
-	})
-	const piApiKey = process.env.PI_API_KEY ?? env.openrouterApiKey
-	const queryAgent = new PiQueryAgent({
-		sessionManager,
-		modelProvider: process.env.PI_MODEL_PROVIDER ?? "openrouter",
-		modelId: process.env.PI_MODEL ?? env.openrouterModel ?? "z-ai/glm-4.7-flash",
-		apiKey: piApiKey,
+		queryAgent: {
+			apiKey: piApiKey,
+		},
 	})
 	if (!piApiKey) {
 		console.warn("[query] PI_API_KEY or OPENROUTER_API_KEY not set — query agent unavailable")
@@ -86,6 +83,15 @@ function main() {
 		return allowedOrigins.includes(origin) ? origin : undefined
 	}
 
+	const agentWebSocketCorsMiddleware = createMiddleware(async (c, next) => {
+		const origin = c.req.header("origin")
+		if (origin && resolveOrigin(origin) === undefined) {
+			return c.text("Forbidden", 403)
+		}
+
+		await next()
+	})
+
 	app.use(
 		"/api/auth/*",
 		cors({
@@ -120,7 +126,7 @@ function main() {
 	registerLocationHttpHandlers(app, { sessionManager, authSessionMiddleware })
 	registerSourcesHttpHandlers(app, { sessionManager, authSessionMiddleware })
 	registerAgentHttpHandlers(app, {
-		queryAgent,
+		sessionManager,
 		authSessionMiddleware,
 	})
 	if (isDebugMode) {
@@ -132,8 +138,14 @@ function main() {
 	}
 	registerAdminHttpHandlers(app, { sessionManager, adminMiddleware, db })
 
+	registerAgentWebSocketHandlers(app, {
+		sessionManager,
+		authSessionMiddleware,
+		corsMiddleware: agentWebSocketCorsMiddleware,
+	})
+
 	process.on("SIGTERM", async () => {
-		queryAgent.dispose()
+		sessionManager.dispose()
 		await closeDb()
 		process.exit(0)
 	})
@@ -147,4 +159,5 @@ export default {
 	port: 3000,
 	hostname: "0.0.0.0",
 	fetch: app.fetch,
+	websocket: agentWebSocket,
 }

apps/freya-backend/src/session/feed-source-provider.ts

@@ -1,7 +1,6 @@
 import type { FeedSource } from "@freya/core"
-import type { type } from "arktype"
 
-export type ConfigSchema = ReturnType<typeof type>
+export type ConfigSchema = (value: unknown) => unknown
 
 export interface FeedSourceProvider {
 	/** The source ID this provider is responsible for (e.g., "freya.location"). */

apps/freya-backend/src/session/user-session-manager.test.ts

@@ -4,9 +4,12 @@ import { LocationSource } from "@freya/source-location"
 import { WeatherSource } from "@freya/source-weatherkit"
 import { beforeEach, describe, expect, mock, spyOn, test } from "bun:test"
 
+import type { ConversationStorageEntry } from "../agent/conversation-recording-query-agent.ts"
+import type { AppendConversationEntryInput } from "../conversations/storage.ts"
 import type { Database } from "../db/index.ts"
 import type { FeedSourceProvider } from "./feed-source-provider.ts"
 
+import { ConversationEntryKind } from "../conversations/types.ts"
 import { CredentialEncryptor } from "../lib/crypto.ts"
 import {
 	CredentialStorageUnavailableError,
@@ -21,6 +24,8 @@ import { UserSessionManager } from "./user-session-manager.ts"
  * Key = userId (or "*" for a default), value = array of enabled sourceIds.
  */
 const enabledByUser = new Map<string, string[]>()
+const conversationEntriesByUser = new Map<string, ConversationStorageEntry[]>()
+const mockConversationCalls: Array<{ type: "getOrCreate" | "listEntries"; userId: string }> = []
 
 /** Set which sourceIds are enabled for all users. */
 function setEnabledSources(sourceIds: string[]) {
@@ -37,6 +42,10 @@ function getEnabledSourceIds(userId: string): string[] {
 	return enabledByUser.get(userId) ?? enabledByUser.get("*") ?? []
 }
 
+function setConversationEntriesForUser(userId: string, entries: ConversationStorageEntry[]) {
+	conversationEntriesByUser.set(userId, entries)
+}
+
 /**
  * Controls what `find()` returns in the mock. When `undefined` (the default),
  * `find()` returns a standard enabled row. Set to a specific value (including
@@ -111,6 +120,35 @@ mock.module("../sources/user-sources.ts", () => ({
 	}),
 }))
 
+mock.module("../conversations/storage.ts", () => ({
+	conversations: (_db: Database, userId: string) => ({
+		async getOrCreateConversation(): Promise<{ id: string }> {
+			mockConversationCalls.push({ type: "getOrCreate", userId })
+			return { id: `conversation-${userId}` }
+		},
+		async listEntries(_conversationId: string): Promise<ConversationStorageEntry[]> {
+			mockConversationCalls.push({ type: "listEntries", userId })
+			return conversationEntriesByUser.get(userId) ?? []
+		},
+		async appendEntry(
+			_conversationId: string,
+			input: AppendConversationEntryInput,
+		): Promise<ConversationStorageEntry> {
+			const entries = conversationEntriesByUser.get(userId) ?? []
+			const row: ConversationStorageEntry = {
+				id: `entry-${entries.length + 1}`,
+				sequence: entries.length + 1,
+				kind: input.kind,
+				payload: input.payload,
+				metadata: input.metadata ?? {},
+				createdAt: new Date("2026-06-15T00:00:00.000Z"),
+			}
+			conversationEntriesByUser.set(userId, [...entries, row])
+			return row
+		},
+	}),
+}))
+
 const fakeDb = {
 	transaction: <T>(fn: (tx: unknown) => Promise<T>) => fn(fakeDb),
 } as unknown as Database
@@ -160,6 +198,8 @@ const weatherProvider: FeedSourceProvider = {
 
 beforeEach(() => {
 	enabledByUser.clear()
+	conversationEntriesByUser.clear()
+	mockConversationCalls.length = 0
 	mockFindResult = undefined
 	mockUpdateCredentialsCalls.length = 0
 	mockUpdateCredentialsError = null
@@ -176,6 +216,31 @@ describe("UserSessionManager", () => {
 		expect(session.engine).toBeDefined()
 	})
 
+	test("getOrCreate eagerly loads conversation entries for the user session", async () => {
+		setEnabledSources([])
+		setConversationEntriesForUser("user-1", [
+			{
+				id: "entry-1",
+				sequence: 1,
+				kind: ConversationEntryKind.UserMessage,
+				payload: {
+					role: "user",
+					parts: [{ type: "text", text: "stored hello" }],
+				},
+				metadata: {},
+				createdAt: new Date("2026-06-15T00:00:00.000Z"),
+			},
+		])
+		const manager = new UserSessionManager({ db: fakeDb, providers: [] })
+
+		await manager.getOrCreate("user-1")
+
+		expect(mockConversationCalls).toEqual([
+			{ type: "getOrCreate", userId: "user-1" },
+			{ type: "listEntries", userId: "user-1" },
+		])
+	})
+
 	test("getOrCreate returns same session for same user", async () => {
 		setEnabledSources(["freya.location"])
 		const manager = new UserSessionManager({ db: fakeDb, providers: [locationProvider] })

apps/freya-backend/src/session/user-session-manager.ts

@@ -8,19 +8,21 @@ import type { FeedEnhancer } from "../enhancement/enhance-feed.ts"
 import type { CredentialEncryptor } from "../lib/crypto.ts"
 import type { FeedSourceProvider } from "./feed-source-provider.ts"
 
+import { conversations } from "../conversations/storage.ts"
 import {
 	CredentialStorageUnavailableError,
 	InvalidSourceConfigError,
 	SourceNotFoundError,
 } from "../sources/errors.ts"
 import { sources } from "../sources/user-sources.ts"
-import { UserSession } from "./user-session.ts"
+import { UserSession, type UserSessionAgentConfig } from "./user-session.ts"
 
 export interface UserSessionManagerConfig {
 	db: Database
 	providers: FeedSourceProvider[]
 	feedEnhancer?: FeedEnhancer | null
 	credentialEncryptor?: CredentialEncryptor | null
+	queryAgent?: UserSessionAgentConfig
 }
 
 export class UserSessionManager {
@@ -30,6 +32,7 @@ export class UserSessionManager {
 	private readonly providers = new Map<string, FeedSourceProvider>()
 	private readonly feedEnhancer: FeedEnhancer | null
 	private readonly encryptor: CredentialEncryptor | null
+	private readonly queryAgentConfig: UserSessionAgentConfig | undefined
 
 	constructor(config: UserSessionManagerConfig) {
 		this.db = config.db
@@ -38,6 +41,7 @@ export class UserSessionManager {
 		}
 		this.feedEnhancer = config.feedEnhancer ?? null
 		this.encryptor = config.credentialEncryptor ?? null
+		this.queryAgentConfig = config.queryAgent
 	}
 
 	getProvider(sourceId: string): FeedSourceProvider | undefined {
@@ -99,6 +103,14 @@ export class UserSessionManager {
 		this.pending.delete(userId)
 	}
 
+	dispose(): void {
+		for (const session of this.sessions.values()) {
+			session.destroy()
+		}
+		this.sessions.clear()
+		this.pending.clear()
+	}
+
 	/**
 	 * Merges, validates, and persists a user's source config and/or enabled
 	 * state, then invalidates the cached session.
@@ -351,6 +363,7 @@ export class UserSessionManager {
 
 	private async createSession(userId: string): Promise<UserSession> {
 		const enabledRows = await sources(this.db, userId).enabled()
+		const agentConfig = this.queryAgentConfigForUser(userId)
 
 		const promises: Promise<FeedSource>[] = []
 		for (const row of enabledRows) {
@@ -362,7 +375,7 @@ export class UserSessionManager {
 		}
 
 		if (promises.length === 0) {
-			return new UserSession(userId, [], this.feedEnhancer)
+			return this.initializedSession(userId, [], agentConfig)
 		}
 
 		const results = await Promise.allSettled(promises)
@@ -386,7 +399,29 @@ export class UserSessionManager {
 			console.error("[UserSessionManager] Feed source provider failed:", error)
 		}
 
-		return new UserSession(userId, feedSources, this.feedEnhancer)
+		return this.initializedSession(userId, feedSources, agentConfig)
+	}
+
+	private queryAgentConfigForUser(userId: string): UserSessionAgentConfig {
+		return {
+			...(this.queryAgentConfig ?? {}),
+			conversationStorage: conversations(this.db, userId),
+		}
+	}
+
+	private async initializedSession(
+		userId: string,
+		sources: FeedSource[],
+		agentConfig: UserSessionAgentConfig,
+	): Promise<UserSession> {
+		const session = new UserSession(userId, sources, this.feedEnhancer, agentConfig)
+		try {
+			await session.initialize()
+			return session
+		} catch (err) {
+			session.destroy()
+			throw err
+		}
 	}
 
 	/**

apps/freya-backend/src/session/user-session.test.ts

@@ -3,6 +3,13 @@ import type { ActionDefinition, ContextEntry, FeedItem, FeedSource } from "@frey
 import { LocationSource } from "@freya/source-location"
 import { describe, expect, spyOn, test } from "bun:test"
 
+import type {
+	ConversationStorage,
+	ConversationStorageEntry,
+} from "../agent/conversation-recording-query-agent.ts"
+import type { AppendConversationEntryInput } from "../conversations/storage.ts"
+
+import { ConversationEntryKind } from "../conversations/types.ts"
 import { UserSession } from "./user-session.ts"
 
 function createStubSource(id: string, items: FeedItem[] = []): FeedSource {
@@ -23,6 +30,40 @@ function createStubSource(id: string, items: FeedItem[] = []): FeedSource {
 	}
 }
 
+class FakeConversationStorage implements ConversationStorage {
+	readonly calls: string[] = []
+	private readonly entries: ConversationStorageEntry[]
+
+	constructor(entries: ConversationStorageEntry[] = []) {
+		this.entries = entries
+	}
+
+	async getOrCreateConversation(): Promise<{ id: string }> {
+		this.calls.push("getOrCreateConversation")
+		return { id: "conversation-1" }
+	}
+
+	async appendEntry(
+		_conversationId: string,
+		input: AppendConversationEntryInput,
+	): Promise<ConversationStorageEntry> {
+		this.calls.push("appendEntry")
+		return {
+			id: "entry-appended",
+			sequence: 1,
+			kind: input.kind,
+			payload: input.payload,
+			metadata: input.metadata ?? {},
+			createdAt: new Date("2026-06-15T00:00:00.000Z"),
+		}
+	}
+
+	async listEntries(_conversationId: string): Promise<ConversationStorageEntry[]> {
+		this.calls.push("listEntries")
+		return this.entries
+	}
+}
+
 describe("UserSession", () => {
 	test("registers sources and starts engine", async () => {
 		const session = new UserSession("test-user", [
@@ -58,6 +99,41 @@ describe("UserSession", () => {
 		expect(session.getSource("test")).toBeUndefined()
 	})
 
+	test("destroy disposes query agent", () => {
+		const session = new UserSession("test-user", [createStubSource("test")])
+		const disposeSpy = spyOn(session.agent, "dispose")
+
+		session.destroy()
+
+		expect(disposeSpy).toHaveBeenCalled()
+	})
+
+	test("initialize loads conversation entries before exposing stored agent", async () => {
+		const storage = new FakeConversationStorage([
+			{
+				id: "entry-1",
+				sequence: 1,
+				kind: ConversationEntryKind.UserMessage,
+				payload: {
+					role: "user",
+					parts: [{ type: "text", text: "stored hello" }],
+				},
+				metadata: {},
+				createdAt: new Date("2026-06-15T00:00:00.000Z"),
+			},
+		])
+		const session = new UserSession("test-user", [createStubSource("test")], null, {
+			conversationStorage: storage,
+		})
+
+		expect(() => session.agent).toThrow("UserSession has not been initialized")
+
+		await session.initialize()
+
+		expect(storage.calls).toEqual(["getOrCreateConversation", "listEntries"])
+		expect(session.agent).toBeDefined()
+	})
+
 	test("engine.executeAction routes to correct source", async () => {
 		const location = new LocationSource()
 		const session = new UserSession("test-user", [location])

apps/freya-backend/src/session/user-session.ts

@@ -6,23 +6,50 @@ import {
 	type FeedSource,
 } from "@freya/core"
 
+import type { QueryAgentToolbox } from "../agent/query-agent-toolbox.ts"
+import type { QueryAgent } from "../agent/query-agent.ts"
 import type { FeedEnhancer } from "../enhancement/enhance-feed.ts"
 
+import {
+	ConversationRecordingQueryAgent,
+	type ConversationStorage,
+} from "../agent/conversation-recording-query-agent.ts"
+import { PiQueryAgent, PI_MODEL_ID, PI_MODEL_PROVIDER } from "../agent/pi-query-agent.ts"
+import { UserSessionQueryAgentToolbox } from "../agent/user-session-query-agent-toolbox.ts"
+
+export interface UserSessionAgentConfig {
+	apiKey?: string
+	cwd?: string
+	systemPrompt?: string
+	conversationStorage?: ConversationStorage
+}
+
 export class UserSession {
 	readonly userId: string
 	readonly engine: FeedEngine
+	readonly toolbox: QueryAgentToolbox
 	private sources = new Map<string, FeedSource>()
 	private readonly enhancer: FeedEnhancer | null
+	private readonly agentConfig: UserSessionAgentConfig | undefined
+	private queryAgent: QueryAgent | null = null
+	private initializePromise: Promise<void> | null = null
+	private initialized = false
 	private enhancedItems: FeedItem[] | null = null
 	/** The FeedResult that enhancedItems was derived from. */
 	private enhancedSource: FeedResult | null = null
 	private enhancingPromise: Promise<void> | null = null
 	private unsubscribe: (() => void) | null = null
 
-	constructor(userId: string, sources: FeedSource[], enhancer?: FeedEnhancer | null) {
+	constructor(
+		userId: string,
+		sources: FeedSource[],
+		enhancer?: FeedEnhancer | null,
+		agentConfig?: UserSessionAgentConfig,
+	) {
 		this.userId = userId
 		this.engine = new FeedEngine()
 		this.enhancer = enhancer ?? null
+		this.agentConfig = agentConfig
 		for (const source of sources) {
 			this.sources.set(source.id, source)
 			this.engine.register(source)
@@ -35,9 +62,44 @@ export class UserSession {
 			})
 		}
 
+		this.toolbox = new UserSessionQueryAgentToolbox(this)
+		if (!agentConfig?.conversationStorage) {
+			this.queryAgent = new PiQueryAgent({
+				toolbox: this.toolbox,
+				apiKey: this.agentConfig?.apiKey,
+				cwd: this.agentConfig?.cwd,
+				systemPrompt: this.agentConfig?.systemPrompt,
+			})
+			this.initialized = true
+		}
+
 		this.engine.start()
 	}
 
+	get agent(): QueryAgent {
+		if (!this.queryAgent) {
+			throw new Error("UserSession has not been initialized")
+		}
+		return this.queryAgent
+	}
+
+	async initialize(): Promise<void> {
+		if (this.initialized) return
+		if (this.initializePromise) return this.initializePromise
+
+		const promise = this.initializeAgent()
+		this.initializePromise = promise
+
+		try {
+			await promise
+			this.initialized = true
+		} finally {
+			if (this.initializePromise === promise) {
+				this.initializePromise = null
+			}
+		}
+	}
+
 	/**
 	 * Returns the current feed, refreshing if the engine cache expired.
 	 * Enhancement runs eagerly on engine updates; this method awaits
@@ -174,6 +236,8 @@ export class UserSession {
 	}
 
 	destroy(): void {
+		this.queryAgent?.dispose()
+		this.queryAgent = null
 		this.unsubscribe?.()
 		this.unsubscribe = null
 		this.engine.stop()
@@ -182,6 +246,38 @@ export class UserSession {
 		this.enhancingPromise = null
 	}
 
+	private async initializeAgent(): Promise<void> {
+		if (this.queryAgent) return
+
+		const conversationStorage = this.agentConfig?.conversationStorage
+		if (!conversationStorage) {
+			this.queryAgent = new PiQueryAgent({
+				toolbox: this.toolbox,
+				apiKey: this.agentConfig?.apiKey,
+				cwd: this.agentConfig?.cwd,
+				systemPrompt: this.agentConfig?.systemPrompt,
+			})
+			return
+		}
+
+		const conversation = await conversationStorage.getOrCreateConversation()
+		const entries = await conversationStorage.listEntries(conversation.id)
+
+		this.queryAgent = new ConversationRecordingQueryAgent({
+			agent: new PiQueryAgent({
+				toolbox: this.toolbox,
+				apiKey: this.agentConfig?.apiKey,
+				cwd: this.agentConfig?.cwd,
+				systemPrompt: this.agentConfig?.systemPrompt,
+				initialEntries: entries,
+			}),
+			storage: conversationStorage,
+			defaultConversationId: conversation.id,
+			modelProvider: PI_MODEL_PROVIDER,
+			modelId: PI_MODEL_ID,
+		})
+	}
+
 	private invalidateEnhancement(): void {
 		this.enhancedItems = null
 		this.enhancedSource = null

apps/freya-backend/src/sources/default-sources.test.ts

@@ -1,4 +1,5 @@
 import { LocationSource } from "@freya/source-location"
+import { ReminderSource } from "@freya/source-reminders"
 import { WebSearchSource } from "@freya/source-web-search"
 import { describe, expect, test } from "bun:test"
 
@@ -55,8 +56,12 @@ function createRecordingDb(): RecordingDb {
 }
 
 describe("default user sources", () => {
-	test("defines location and web search as default enabled sources", () => {
-		expect(DEFAULT_ENABLED_SOURCE_IDS).toEqual([LocationSource.id, WebSearchSource.id])
+	test("defines default enabled sources", () => {
+		expect(DEFAULT_ENABLED_SOURCE_IDS).toEqual([
+			LocationSource.id,
+			ReminderSource.id,
+			WebSearchSource.id,
+		])
 	})
 
 	test("inserts default enabled source rows for a user", async () => {
@@ -70,7 +75,7 @@ describe("default user sources", () => {
 		}
 
 		expect(recording.table()).toBe(userSources)
-		expect(rows).toHaveLength(2)
+		expect(rows).toHaveLength(3)
 		expect(rows.map((row) => row.sourceId)).toEqual([...DEFAULT_ENABLED_SOURCE_IDS])
 		expect(recording.conflictTarget()).toEqual([userSources.userId, userSources.sourceId])
 

apps/freya-backend/src/sources/default-sources.ts

@@ -1,11 +1,16 @@
 import { LocationSource } from "@freya/source-location"
+import { ReminderSource } from "@freya/source-reminders"
 import { WebSearchSource } from "@freya/source-web-search"
 
 import type { Database } from "../db/index.ts"
 
 import { userSources } from "../db/schema.ts"
 
-export const DEFAULT_ENABLED_SOURCE_IDS = [LocationSource.id, WebSearchSource.id] as const
+export const DEFAULT_ENABLED_SOURCE_IDS = [
+	LocationSource.id,
+	ReminderSource.id,
+	WebSearchSource.id,
+] as const
 
 export type DefaultEnabledSourceId = (typeof DEFAULT_ENABLED_SOURCE_IDS)[number]
 

apps/freya-backend/src/sources/http.test.ts

@@ -128,6 +128,20 @@ mock.module("../sources/user-sources.ts", () => ({
 	},
 }))
 
+mock.module("../conversations/storage.ts", () => ({
+	conversations: (_db: Database, userId: string) => ({
+		async getOrCreateConversation() {
+			return { id: `conversation-${userId}` }
+		},
+		async listEntries() {
+			return []
+		},
+		async appendEntry() {
+			return { id: "entry-1", sequence: 1 }
+		},
+	}),
+}))
+
 const fakeDb = {
 	transaction: <T>(fn: (tx: unknown) => Promise<T>) => fn(fakeDb),
 } as unknown as Database

apps/waitlist-website/app/routes/home.tsx

@@ -37,13 +37,13 @@ export function meta({}: Route.MetaArgs) {
 		},
 		{ property: "og:title", content: PAGE_TITLE },
 		{ property: "og:description", content: PAGE_DESCRIPTION },
-		{ property: "og:image", content: "https://ael.is/social-media-preview.png" },
-		{ property: "og:url", content: "https://ael.is" },
+		{ property: "og:image", content: "https://freya.chat/social-media-preview.jpg" },
+		{ property: "og:url", content: "https://freya.chat" },
 		{ property: "og:type", content: "website" },
 		{ name: "twitter:card", content: "summary_large_image" },
 		{ name: "twitter:title", content: PAGE_TITLE },
 		{ name: "twitter:description", content: PAGE_DESCRIPTION },
-		{ name: "twitter:image", content: "https://ael.is/social-media-preview.png" },
+		{ name: "twitter:image", content: "https://freya.chat/social-media-preview.jpg" },
 	]
 }
 
@@ -84,7 +84,7 @@ export async function action({ request }: Route.ActionArgs) {
 	await new Promise((resolve) => setTimeout(resolve, 1000))
 
 	const emailRes = await resend.emails.send({
-		from: "Freya <no-reply@ael.is>",
+		from: "Freya <no-reply@freya.chat>",
 		to: email,
 		template: {
 			id: "waitlist-confirmation",
@@ -380,7 +380,6 @@ function SystemMessageBubble({
 				isAnimating={isStreaming}
 				linkSafety={{ enabled: false }}
 				components={{
-					// @ts-expect-error
 					a: ({ className, ...props }) => <a className={`underline ${className}`} {...props} />,
 				}}
 			>

apps/waitlist-website/app/routes/privacy-policy.tsx

@@ -40,7 +40,7 @@ const POLICY = `# Privacy Policy
 
 **Last updated:** March 5, 2026
 
-This Privacy Policy describes how **Freya** ("we", "us", or "our") collects, uses, and protects your personal information when you visit **https://ael.is** or interact with our services.
+This Privacy Policy describes how **Freya** ("we", "us", or "our") collects, uses, and protects your personal information when you visit **https://freya.chat** or interact with our services.
 
 If you do not agree with this Privacy Policy, please do not use the website.
 

apps/waitlist-website/public/robots.txt

@@ -1,4 +1,4 @@
 User-agent: *
 Allow: /
 
-Sitemap: https://ael.is/sitemap.xml
+Sitemap: https://freya.chat/sitemap.xml

apps/waitlist-website/public/sitemap.xml

@@ -1,9 +1,9 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
 	<url>
-		<loc>https://ael.is/</loc>
+		<loc>https://freya.chat/</loc>
 	</url>
 	<url>
-		<loc>https://ael.is/privacy</loc>
+		<loc>https://freya.chat/privacy</loc>
 	</url>
 </urlset>

bun.lock

@@ -49,12 +49,17 @@
     "apps/agent-test-cli": {
       "name": "@freya/agent-test-cli",
       "version": "0.0.0",
+      "dependencies": {
+        "@freya/agent-protocol": "workspace:*",
+        "@nym.sh/jrpc": "^0.1.0",
+      },
     },
     "apps/freya-backend": {
       "name": "@freya/backend",
       "version": "0.0.0",
       "dependencies": {
         "@earendil-works/pi-coding-agent": "^0.79.1",
+        "@freya/agent-protocol": "workspace:*",
         "@freya/core": "workspace:*",
         "@freya/source-caldav": "workspace:*",
         "@freya/source-google-calendar": "workspace:*",
@@ -64,6 +69,7 @@
         "@freya/source-tfl": "workspace:*",
         "@freya/source-weatherkit": "workspace:*",
         "@freya/source-web-search": "workspace:*",
+        "@nym.sh/jrpc": "^0.1.0",
         "@openrouter/sdk": "^0.9.11",
         "arktype": "^2.1.29",
         "better-auth": "^1",
@@ -153,6 +159,10 @@
         "vite-tsconfig-paths": "^5.1.4",
       },
     },
+    "packages/freya-agent-protocol": {
+      "name": "@freya/agent-protocol",
+      "version": "0.0.0",
+    },
     "packages/freya-components": {
       "name": "@freya/components",
       "version": "0.0.0",
@@ -749,6 +759,8 @@
 
     "@formatjs/intl-localematcher": ["@formatjs/intl-localematcher@0.6.2", "", { "dependencies": { "tslib": "^2.8.0" } }, "sha512-XOMO2Hupl0wdd172Y06h6kLpBz6Dv+J4okPLl4LPtzbr8f66WbIoy4ev98EBuZ6ZK4h5ydTN6XneT4QVpD7cdA=="],
 
+    "@freya/agent-protocol": ["@freya/agent-protocol@workspace:packages/freya-agent-protocol"],
+
     "@freya/agent-test-cli": ["@freya/agent-test-cli@workspace:apps/agent-test-cli"],
 
     "@freya/backend": ["@freya/backend@workspace:apps/freya-backend"],
@@ -901,6 +913,8 @@
 
     "@nolyfill/is-core-module": ["@nolyfill/is-core-module@1.0.39", "", {}, "sha512-nn5ozdjYQpUCZlWGuxcJY/KpxkWQs4DcbMCmKojjyrYDEAGy4Ce19NN4v5MduafTwJlbKc99UA8YhSVqq9yPZA=="],
 
+    "@nym.sh/jrpc": ["@nym.sh/jrpc@0.1.0", "", {}, "sha512-qH+vqKojPrX4RkW67U2R4J98uWHxZOwYxX2J5GLZcfm/yjklCcN5zTfDNLfgAa9jAoOFVscC3DFWhvdZOmN3fA=="],
+
     "@nym.sh/jrx": ["@nym.sh/jrx@0.2.0", "", { "peerDependencies": { "@json-render/core": ">=0.10.0" } }, "sha512-jd7Z1Q6T21366MtSUnwCFiu6Yl1AdNc9s5m6HxeUg265P+0enZCiyyxOuHsFwvpUcSEs/2DVBsqfMptdca44lA=="],
 
     "@oclif/core": ["@oclif/core@4.8.4", "", { "dependencies": { "ansi-escapes": "^4.3.2", "ansis": "^3.17.0", "clean-stack": "^3.0.1", "cli-spinners": "^2.9.2", "debug": "^4.4.3", "ejs": "^3.1.10", "get-package-type": "^0.1.0", "indent-string": "^4.0.0", "is-wsl": "^2.2.0", "lilconfig": "^3.1.3", "minimatch": "^10.2.4", "semver": "^7.7.3", "string-width": "^4.2.3", "supports-color": "^8", "tinyglobby": "^0.2.14", "widest-line": "^3.1.0", "wordwrap": "^1.0.0", "wrap-ansi": "^7.0.0" } }, "sha512-UTAqwXJJyRvLBvosL+1uPZYSpr8lEHgUb/EVGbPXo5WZqUIBHfJ0sR2bkBEsrj00/ar4IegKxx4YK0wn2c8SQg=="],

flake.lock

@@ -0,0 +1,27 @@
+{
+  "nodes": {
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1781577229,
+        "narHash": "sha256-lrp67w8AulE9Ks53n27I45ADSzbOCn4H+CNW1Ck8B+8=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "567a49d1913ce81ac6e9582e3553dd90a955875f",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "nixpkgs": "nixpkgs"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

flake.nix

@@ -0,0 +1,280 @@
+{
+  description = "FREYA development shell";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+  };
+
+  outputs =
+    { nixpkgs, ... }:
+    let
+      systems = [
+        "x86_64-linux"
+        "aarch64-linux"
+        "x86_64-darwin"
+        "aarch64-darwin"
+      ];
+
+      lib = nixpkgs.lib;
+      forEachSystem = lib.genAttrs systems;
+      pkgsFor = forEachSystem (system: import nixpkgs { inherit system; });
+
+      # App outputs are for long-running local tools and dev servers.
+      appScripts = {
+        expo = "expo";
+        drizzle-studio = "drizzle-studio";
+        freya-backend = "freya-backend";
+        admin-dashboard = "admin-dashboard";
+        agent-test-cli = "agent-test-cli";
+      };
+
+      # Check outputs are the CI-like validation commands run by `nix flake check`.
+      checkCommands = {
+        format-check = "bun run format:check";
+        lint = "bun run lint";
+        test = "bun run test";
+      };
+
+      # Dev-shell conveniences mirror the common app/check commands.
+      shellScripts = appScripts // {
+        freya-test = "test";
+        lint = "lint";
+        format-check = "format:check";
+      };
+
+      # node_modules is content-addressed. If bun.lock or package manifests
+      # change, Nix will report the new hash to put here.
+      nodeModulesHashes = {
+        x86_64-linux = "sha256-apVZaFGf9OKpil1WdcQ1CJODsIdjLWlBBZErHg5mjZA=";
+      };
+      checkSystems = lib.attrNames nodeModulesHashes;
+
+      # Dependency derivations only need the lockfile and workspace manifests,
+      # so source-only edits do not force Bun to reinstall.
+      dependencySource = lib.fileset.toSource {
+        root = ./.;
+        fileset = lib.fileset.fileFilter (file: file.name == "bun.lock" || file.name == "package.json") ./.;
+      };
+
+      # Checks run against a clean source tree, even when using `path:.`.
+      # Without this filter, local node_modules can sneak into the Nix sandbox.
+      projectSource = builtins.path {
+        name = "freya-source";
+        path = ./.;
+        filter =
+          path: type:
+          let
+            name = builtins.baseNameOf path;
+          in
+          !(type == "directory" && (name == ".git" || name == "node_modules")) && name != "result";
+      };
+
+      mkBunScriptCommands =
+        pkgs: scripts:
+        let
+          mkBunScript =
+            name: script:
+            pkgs.writeShellApplication {
+              inherit name;
+              runtimeInputs = with pkgs; [
+                bun
+                git
+              ];
+              text = ''
+                repo_root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+                cd "$repo_root"
+                exec bun run ${lib.escapeShellArg script} "$@"
+              '';
+            };
+        in
+        lib.mapAttrs mkBunScript scripts;
+      mkBunApps =
+        commands:
+        lib.mapAttrs (name: command: {
+          type = "app";
+          program = "${command}/bin/${name}";
+        }) commands;
+      mkBunNodeModules =
+        system: pkgs:
+        pkgs.stdenvNoCC.mkDerivation {
+          pname = "freya-node-modules";
+          version = "1";
+          __structuredAttrs = true;
+
+          src = dependencySource;
+          nativeBuildInputs = with pkgs; [
+            bun
+            cacert
+            nodejs
+          ];
+
+          SSL_CERT_FILE = "${pkgs.cacert}/etc/ssl/certs/ca-bundle.crt";
+          GIT_SSL_CAINFO = "${pkgs.cacert}/etc/ssl/certs/ca-bundle.crt";
+
+          outputHashAlgo = "sha256";
+          outputHashMode = "recursive";
+          outputHash = nodeModulesHashes.${system};
+
+          # `patchShebangs` embeds Nix store interpreters in package bins. The
+          # check derivations also depend on bun/node, so this dependency blob
+          # can safely drop those references after its hash is verified.
+          unsafeDiscardReferences.out = true;
+
+          dontConfigure = true;
+          # Workspace package links are completed inside each check's source tree,
+          # so they are intentionally dangling in this dependency-only output.
+          dontFixup = true;
+
+          buildPhase = ''
+            runHook preBuild
+
+            export HOME="$TMPDIR/home"
+            mkdir -p "$HOME"
+
+            # Keep the real workspace manifest for `--frozen-lockfile`, but
+            # filter out frontend workspaces that do not participate in checks.
+            # `--force` matters in the Nix sandbox: without it, Bun can accept
+            # manifest-only cached packages and leave tool binaries missing.
+            bun install \
+              --force \
+              --frozen-lockfile \
+              --ignore-scripts \
+              --backend copyfile \
+              --filter freya \
+              --filter '@freya/*' \
+              --filter '@freya/backend' \
+              --no-progress
+
+            patchShebangs node_modules
+
+            runHook postBuild
+          '';
+
+          installPhase = ''
+            runHook preInstall
+
+            mkdir -p "$out"
+
+            # Keep the root install in the store; checks symlink this directly.
+            cp -a node_modules "$out/node_modules"
+
+            # Bun also creates per-workspace node_modules directories. These are
+            # mostly relative symlinks, so checks copy the symlink entries into
+            # their writable source tree instead of symlinking the directory.
+            find apps packages -mindepth 2 -maxdepth 2 -type d -name node_modules -print |
+              while IFS= read -r node_modules_dir; do
+                mkdir -p "$out/$(dirname "$node_modules_dir")"
+                cp -a "$node_modules_dir" "$out/$node_modules_dir"
+              done
+
+            runHook postInstall
+          '';
+        };
+      mkBunCheck =
+        pkgs: nodeModules: name: command:
+        pkgs.stdenvNoCC.mkDerivation {
+          pname = "freya-${name}";
+          version = "1";
+
+          src = projectSource;
+          nativeBuildInputs = with pkgs; [
+            bun
+            nodejs
+          ];
+
+          dontConfigure = true;
+
+          buildPhase = ''
+            runHook preBuild
+
+            export HOME="$TMPDIR/home"
+            mkdir -p "$HOME"
+
+            # Root dependencies are read-only and shared across checks.
+            ln -s "${nodeModules}/node_modules" node_modules
+
+            # Workspace node_modules contain relative symlinks back to packages/
+            # and apps/, so copy just those symlink entries into this source tree.
+            for node_modules_dir in "${nodeModules}"/apps/*/node_modules "${nodeModules}"/packages/*/node_modules; do
+              if [ -d "$node_modules_dir" ]; then
+                relative_path="''${node_modules_dir#"${nodeModules}/"}"
+                mkdir -p "$relative_path"
+                cp -a "$node_modules_dir/." "$relative_path/"
+              fi
+            done
+
+            ${command}
+
+            runHook postBuild
+          '';
+
+          installPhase = ''
+            runHook preInstall
+
+            mkdir -p "$out"
+            touch "$out/${name}"
+
+            runHook postInstall
+          '';
+        };
+    in
+    {
+      apps = forEachSystem (
+        system:
+        let
+          pkgs = pkgsFor.${system};
+        in
+        mkBunApps (mkBunScriptCommands pkgs appScripts)
+      );
+
+      checks = lib.genAttrs checkSystems (
+        system:
+        let
+          pkgs = pkgsFor.${system};
+          nodeModules = mkBunNodeModules system pkgs;
+        in
+        lib.mapAttrs (mkBunCheck pkgs nodeModules) checkCommands
+      );
+
+      devShells = forEachSystem (
+        system:
+        let
+          pkgs = pkgsFor.${system};
+          bunScriptCommands = lib.attrValues (mkBunScriptCommands pkgs shellScripts);
+          commonPackages = with pkgs; [
+            bun
+            eas-cli
+            git
+            gh
+            gnumake
+            nixfmt
+            nodejs
+            openssl
+            pkg-config
+            postgresql
+            python3
+            watchman
+          ];
+          linuxPackages = with pkgs; [
+            gcc
+            inotify-tools
+            tailscale
+          ];
+        in
+        {
+          default = pkgs.mkShell {
+            packages =
+              commonPackages ++ bunScriptCommands ++ pkgs.lib.optionals pkgs.stdenv.isLinux linuxPackages;
+
+            SSL_CERT_FILE = "${pkgs.cacert}/etc/ssl/certs/ca-bundle.crt";
+
+            shellHook = ''
+              export PATH="$PWD/node_modules/.bin:$PATH"
+            '';
+          };
+        }
+      );
+
+      formatter = forEachSystem (system: pkgsFor.${system}.nixfmt);
+    };
+}

packages/freya-agent-protocol/package.json

@@ -0,0 +1,10 @@
+{
+	"name": "@freya/agent-protocol",
+	"version": "0.0.0",
+	"type": "module",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"scripts": {
+		"test": "bun test ./src"
+	}
+}

packages/freya-agent-protocol/src/index.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, test } from "bun:test"
+
+import type { AgentEvent, AgentServerApi } from "./index"
+
+describe("agent protocol", () => {
+	test("defines server methods and agent events", () => {
+		const server: AgentServerApi = {
+			async sendMessage(message) {
+				return { message, conversationId: "conversation-1" }
+			},
+			ping() {
+				return "pong"
+			},
+		}
+		const event: AgentEvent = { type: "message_finished" }
+
+		expect(server.ping()).toBe("pong")
+		expect(event.type).toBe("message_finished")
+	})
+})

packages/freya-agent-protocol/src/index.ts

@@ -0,0 +1,21 @@
+export interface SendMessageResult {
+	message: string
+	conversationId: string
+}
+
+export type AgentEvent =
+	| { type: "conversation_started"; conversationId: string }
+	| { type: "message_created"; text: string }
+	| { type: "tool_started"; toolName: string }
+	| { type: "tool_finished"; toolName: string; ok: boolean }
+	| { type: "message_finished" }
+	| { type: "message_failed"; error: string }
+
+export interface AgentServerApi {
+	sendMessage(message: string): Promise<SendMessageResult>
+	ping(): "pong"
+}
+
+export interface AgentClientApi {
+	notify(event: AgentEvent): void
+}

packages/freya-agent-protocol/tsconfig.json

@@ -0,0 +1,4 @@
+{
+	"extends": "../../tsconfig.json",
+	"include": ["src"]
+}

packages/freya-core/src/feed-engine.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test } from "bun:test"
+import { describe, expect, spyOn, test } from "bun:test"
 
 import type { ActionDefinition, ContextEntry, ContextKey, FeedItem, FeedSource } from "./index"
 
@@ -145,6 +145,16 @@ function createAlertSource(): FeedSource<AlertFeedItem> {
 	}
 }
 
+async function waitForCondition(predicate: () => boolean, timeoutMs = 2_000): Promise<void> {
+	const deadline = Date.now() + timeoutMs
+	while (!predicate()) {
+		if (Date.now() > deadline) {
+			throw new Error("Timed out waiting for condition")
+		}
+		await new Promise((resolve) => setTimeout(resolve, 10))
+	}
+}
+
 // =============================================================================
 // TESTS
 // =============================================================================
@@ -807,28 +817,35 @@ describe("FeedEngine", () => {
 		})
 
 		test("TTL resets after reactive update", async () => {
+			let now = 1_000
+			const nowSpy = spyOn(Date, "now").mockImplementation(() => now)
 			const location = createLocationSource()
 			const weather = createWeatherSource()
 
 			const engine = new FeedEngine({ cacheTtlMs: 100 }).register(location).register(weather)
 
-			engine.start()
+			try {
+				engine.start()
 
-			// Initial reactive update
-			location.simulateUpdate({ lat: 51.5, lng: -0.1 })
-			await new Promise((resolve) => setTimeout(resolve, 50))
+				// Initial reactive update
+				location.simulateUpdate({ lat: 51.5, lng: -0.1 })
+				await new Promise((resolve) => setTimeout(resolve, 50))
 
-			expect(engine.lastFeed()).not.toBeNull()
+				expect(engine.lastFeed()).not.toBeNull()
 
-			// Wait 70ms (total 120ms from first update, past original TTL)
-			// but trigger another update at 50ms to reset TTL
-			location.simulateUpdate({ lat: 52.0, lng: -0.2 })
-			await new Promise((resolve) => setTimeout(resolve, 50))
+				// Move past the original TTL, then trigger another update to reset it.
+				now += 120
+				location.simulateUpdate({ lat: 52.0, lng: -0.2 })
+				await new Promise((resolve) => setTimeout(resolve, 50))
 
-			// Should still be cached because TTL was reset by second update
-			expect(engine.lastFeed()).not.toBeNull()
+				// Should still be cached because TTL was reset by second update.
+				expect(engine.lastFeed()).not.toBeNull()
 
-			engine.stop()
+				engine.stop()
+			} finally {
+				engine.stop()
+				nowSpy.mockRestore()
+			}
 		})
 
 		test("cacheTtlMs is configurable", async () => {
@@ -869,17 +886,21 @@ describe("FeedEngine", () => {
 				},
 			}
 
-			const engine = new FeedEngine({ cacheTtlMs: 50 }).register(source)
-			engine.start()
+			const engine = new FeedEngine({ cacheTtlMs: 20 }).register(source)
+			await engine.refresh()
 
-			// Wait for two TTL intervals to elapse
-			await new Promise((resolve) => setTimeout(resolve, 120))
+			expect(fetchCount).toBe(1)
 
-			// Should have auto-refreshed at least twice
-			expect(fetchCount).toBeGreaterThanOrEqual(2)
-			expect(engine.lastFeed()).not.toBeNull()
+			try {
+				engine.start()
 
-			engine.stop()
+				await waitForCondition(() => fetchCount >= 2)
+
+				expect(fetchCount).toBeGreaterThanOrEqual(2)
+				expect(engine.lastFeed()).not.toBeNull()
+			} finally {
+				engine.stop()
+			}
 		})
 
 		test("stop cancels periodic refresh", async () => {
@@ -935,28 +956,25 @@ describe("FeedEngine", () => {
 				},
 			}
 
-			const engine = new FeedEngine({ cacheTtlMs: 100 })
+			const engine = new FeedEngine({ cacheTtlMs: 10_000 })
 				.register(location)
 				.register(countingWeather)
+			const clearTimeoutSpy = spyOn(globalThis, "clearTimeout")
 
-			engine.start()
+			try {
+				engine.start()
 
-			// At 40ms, push a reactive update — this resets the timer
-			await new Promise((resolve) => setTimeout(resolve, 40))
-			const countBeforeUpdate = fetchCount
-			location.simulateUpdate({ lat: 51.5, lng: -0.1 })
-			await new Promise((resolve) => setTimeout(resolve, 20))
+				const countBeforeUpdate = fetchCount
+				location.simulateUpdate({ lat: 51.5, lng: -0.1 })
+				await waitForCondition(() => fetchCount > countBeforeUpdate && engine.lastFeed() !== null)
 
-			// Reactive update triggered a fetch
-			expect(fetchCount).toBeGreaterThan(countBeforeUpdate)
-			const countAfterUpdate = fetchCount
-
-			// At 100ms from start (60ms after reactive update), the original
-			// timer would have fired, but it was reset. No extra fetch yet.
-			await new Promise((resolve) => setTimeout(resolve, 40))
-			expect(fetchCount).toBe(countAfterUpdate)
-
-			engine.stop()
+				// Reactive updates refresh the cache and reset the pending periodic timer.
+				expect(fetchCount).toBeGreaterThan(countBeforeUpdate)
+				expect(clearTimeoutSpy).toHaveBeenCalled()
+			} finally {
+				engine.stop()
+				clearTimeoutSpy.mockRestore()
+			}
 		})
 	})
 

packages/freya-source-reminders/src/reminder-source.ts

@@ -84,7 +84,9 @@ const ONE_DAY_MS = 24 * 60 * 60 * 1000
  * It owns recurrence expansion, edit-scope semantics, and feed item signals.
  */
 export class ReminderSource implements FeedSource<ReminderFeedItem> {
-	readonly id = "freya.reminders"
+	static readonly id = "freya.reminders"
+
+	readonly id = ReminderSource.id
 
 	private readonly storage: ReminderStorage
 	private readonly lookAheadMs: number