fix: upgrade client to expo 56

Upgrade the React Native client through Expo SDK 56, align workspace React versions, switch Bun installs to the hoisted linker for Expo compatibility, and fix the Metro proxy to handle localhost/IPv6 loopback after the SDK upgrade.

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/admin-dashboard/package.json

@@ -21,8 +21,8 @@
 		"lucide-react": "^0.577.0",
 		"next-themes": "^0.4.6",
 		"radix-ui": "^1.4.3",
-		"react": "^19.2.0",
-		"react-dom": "^19.2.0",
+		"react": "19.2.3",
+		"react-dom": "19.2.3",
 		"shadcn": "^4.0.8",
 		"sonner": "^2.0.7",
 		"tailwind-merge": "^3.5.0",

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/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/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/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

@@ -101,6 +101,14 @@ export function conversations(db: Database, userId: string) {
 			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)

apps/freya-backend/src/server.ts

@@ -1,9 +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 { 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"
@@ -81,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({
@@ -127,6 +138,12 @@ function main() {
 	}
 	registerAdminHttpHandlers(app, { sessionManager, adminMiddleware, db })
 
+	registerAgentWebSocketHandlers(app, {
+		sessionManager,
+		authSessionMiddleware,
+		corsMiddleware: agentWebSocketCorsMiddleware,
+	})
+
 	process.on("SIGTERM", async () => {
 		sessionManager.dispose()
 		await closeDb()
@@ -142,4 +159,5 @@ export default {
 	port: 3000,
 	hostname: "0.0.0.0",
 	fetch: app.fetch,
+	websocket: agentWebSocket,
 }

apps/freya-client/app.json

@@ -1,13 +1,12 @@
 {
 	"expo": {
 		"name": "Freya",
-		"slug": "freya-client",
+		"slug": "freya",
 		"version": "1.0.0",
 		"orientation": "portrait",
 		"icon": "./assets/images/icon.png",
 		"scheme": "freya",
 		"userInterfaceStyle": "automatic",
-		"newArchEnabled": true,
 		"ios": {
 			"infoPlist": {
 				"NSAppTransportSecurity": {
@@ -24,7 +23,6 @@
 				"backgroundImage": "./assets/images/android-icon-background.png",
 				"monochromeImage": "./assets/images/android-icon-monochrome.png"
 			},
-			"edgeToEdgeEnabled": true,
 			"predictiveBackGestureEnabled": false,
 			"package": "sh.nym.freya"
 		},
@@ -54,55 +52,82 @@
 							{
 								"fontFamily": "Inter",
 								"fontDefinitions": [
-									{ "path": "./assets/fonts/Inter_100Thin.ttf", "weight": 100 },
+									{
+										"path": "./assets/fonts/Inter_100Thin.ttf",
+										"weight": 100
+									},
 									{
 										"path": "./assets/fonts/Inter_100Thin_Italic.ttf",
 										"weight": 100,
 										"style": "italic"
 									},
-									{ "path": "./assets/fonts/Inter_200ExtraLight.ttf", "weight": 200 },
+									{
+										"path": "./assets/fonts/Inter_200ExtraLight.ttf",
+										"weight": 200
+									},
 									{
 										"path": "./assets/fonts/Inter_200ExtraLight_Italic.ttf",
 										"weight": 200,
 										"style": "italic"
 									},
-									{ "path": "./assets/fonts/Inter_300Light.ttf", "weight": 300 },
+									{
+										"path": "./assets/fonts/Inter_300Light.ttf",
+										"weight": 300
+									},
 									{
 										"path": "./assets/fonts/Inter_300Light_Italic.ttf",
 										"weight": 300,
 										"style": "italic"
 									},
-									{ "path": "./assets/fonts/Inter_400Regular.ttf", "weight": 400 },
+									{
+										"path": "./assets/fonts/Inter_400Regular.ttf",
+										"weight": 400
+									},
 									{
 										"path": "./assets/fonts/Inter_400Regular_Italic.ttf",
 										"weight": 400,
 										"style": "italic"
 									},
-									{ "path": "./assets/fonts/Inter_500Medium.ttf", "weight": 500 },
+									{
+										"path": "./assets/fonts/Inter_500Medium.ttf",
+										"weight": 500
+									},
 									{
 										"path": "./assets/fonts/Inter_500Medium_Italic.ttf",
 										"weight": 500,
 										"style": "italic"
 									},
-									{ "path": "./assets/fonts/Inter_600SemiBold.ttf", "weight": 600 },
+									{
+										"path": "./assets/fonts/Inter_600SemiBold.ttf",
+										"weight": 600
+									},
 									{
 										"path": "./assets/fonts/Inter_600SemiBold_Italic.ttf",
 										"weight": 600,
 										"style": "italic"
 									},
-									{ "path": "./assets/fonts/Inter_700Bold.ttf", "weight": 700 },
+									{
+										"path": "./assets/fonts/Inter_700Bold.ttf",
+										"weight": 700
+									},
 									{
 										"path": "./assets/fonts/Inter_700Bold_Italic.ttf",
 										"weight": 700,
 										"style": "italic"
 									},
-									{ "path": "./assets/fonts/Inter_800ExtraBold.ttf", "weight": 800 },
+									{
+										"path": "./assets/fonts/Inter_800ExtraBold.ttf",
+										"weight": 800
+									},
 									{
 										"path": "./assets/fonts/Inter_800ExtraBold_Italic.ttf",
 										"weight": 800,
 										"style": "italic"
 									},
-									{ "path": "./assets/fonts/Inter_900Black.ttf", "weight": 900 },
+									{
+										"path": "./assets/fonts/Inter_900Black.ttf",
+										"weight": 900
+									},
 									{
 										"path": "./assets/fonts/Inter_900Black_Italic.ttf",
 										"weight": 900,
@@ -113,49 +138,73 @@
 							{
 								"fontFamily": "Source Serif 4",
 								"fontDefinitions": [
-									{ "path": "./assets/fonts/SourceSerif4_200ExtraLight.ttf", "weight": 200 },
+									{
+										"path": "./assets/fonts/SourceSerif4_200ExtraLight.ttf",
+										"weight": 200
+									},
 									{
 										"path": "./assets/fonts/SourceSerif4_200ExtraLight_Italic.ttf",
 										"weight": 200,
 										"style": "italic"
 									},
-									{ "path": "./assets/fonts/SourceSerif4_300Light.ttf", "weight": 300 },
+									{
+										"path": "./assets/fonts/SourceSerif4_300Light.ttf",
+										"weight": 300
+									},
 									{
 										"path": "./assets/fonts/SourceSerif4_300Light_Italic.ttf",
 										"weight": 300,
 										"style": "italic"
 									},
-									{ "path": "./assets/fonts/SourceSerif4_400Regular.ttf", "weight": 400 },
+									{
+										"path": "./assets/fonts/SourceSerif4_400Regular.ttf",
+										"weight": 400
+									},
 									{
 										"path": "./assets/fonts/SourceSerif4_400Regular_Italic.ttf",
 										"weight": 400,
 										"style": "italic"
 									},
-									{ "path": "./assets/fonts/SourceSerif4_500Medium.ttf", "weight": 500 },
+									{
+										"path": "./assets/fonts/SourceSerif4_500Medium.ttf",
+										"weight": 500
+									},
 									{
 										"path": "./assets/fonts/SourceSerif4_500Medium_Italic.ttf",
 										"weight": 500,
 										"style": "italic"
 									},
-									{ "path": "./assets/fonts/SourceSerif4_600SemiBold.ttf", "weight": 600 },
+									{
+										"path": "./assets/fonts/SourceSerif4_600SemiBold.ttf",
+										"weight": 600
+									},
 									{
 										"path": "./assets/fonts/SourceSerif4_600SemiBold_Italic.ttf",
 										"weight": 600,
 										"style": "italic"
 									},
-									{ "path": "./assets/fonts/SourceSerif4_700Bold.ttf", "weight": 700 },
+									{
+										"path": "./assets/fonts/SourceSerif4_700Bold.ttf",
+										"weight": 700
+									},
 									{
 										"path": "./assets/fonts/SourceSerif4_700Bold_Italic.ttf",
 										"weight": 700,
 										"style": "italic"
 									},
-									{ "path": "./assets/fonts/SourceSerif4_800ExtraBold.ttf", "weight": 800 },
+									{
+										"path": "./assets/fonts/SourceSerif4_800ExtraBold.ttf",
+										"weight": 800
+									},
 									{
 										"path": "./assets/fonts/SourceSerif4_800ExtraBold_Italic.ttf",
 										"weight": 800,
 										"style": "italic"
 									},
-									{ "path": "./assets/fonts/SourceSerif4_900Black.ttf", "weight": 900 },
+									{
+										"path": "./assets/fonts/SourceSerif4_900Black.ttf",
+										"weight": 900
+									},
 									{
 										"path": "./assets/fonts/SourceSerif4_900Black_Italic.ttf",
 										"weight": 900,
@@ -204,7 +253,9 @@
 						]
 					}
 				}
-			]
+			],
+			"expo-web-browser",
+			"expo-image"
 		],
 		"experiments": {
 			"typedRoutes": true,
@@ -213,7 +264,7 @@
 		"extra": {
 			"router": {},
 			"eas": {
-				"projectId": "61092d23-36aa-418e-929d-ea40dc912e8f"
+				"projectId": "c54ea4e5-27da-4066-b081-db8005ecf70a"
 			}
 		}
 	}

apps/freya-client/package.json

@@ -10,8 +10,8 @@
 		"ios": "expo start --ios",
 		"web": "expo start --web",
 		"lint": "expo lint",
-		"build:ios": "eas build --profile development --platform ios --non-interactive",
-		"build:ios-simulator": "eas build --profile development-simulator --platform ios --non-interactive",
+		"build:ios": "bunx eas-cli build --profile development --platform ios --non-interactive",
+		"build:ios-simulator": "bunx eas-cli build --profile development-simulator --platform ios --non-interactive",
 		"debugger": "bun run scripts/open-debugger.ts"
 	},
 	"dependencies": {
@@ -19,42 +19,38 @@
 		"@expo-google-fonts/source-serif-4": "^0.4.1",
 		"@expo/vector-icons": "^15.0.3",
 		"@json-render/react-native": "^0.13.0",
-		"@react-navigation/bottom-tabs": "^7.4.0",
-		"@react-navigation/elements": "^2.6.3",
-		"@react-navigation/native": "^7.1.8",
 		"@tanstack/react-query": "^5.90.21",
-		"expo": "~54.0.33",
-		"expo-constants": "~18.0.13",
-		"expo-dev-client": "~6.0.20",
-		"expo-font": "~14.0.11",
-		"expo-haptics": "~15.0.8",
-		"expo-image": "~3.0.11",
-		"expo-linking": "~8.0.11",
-		"expo-location": "~19.0.8",
-		"expo-router": "~6.0.23",
-		"expo-splash-screen": "~31.0.13",
-		"expo-status-bar": "~3.0.9",
-		"expo-symbols": "~1.0.8",
-		"expo-system-ui": "~6.0.9",
-		"expo-web-browser": "~15.0.10",
-		"react": "19.1.0",
-		"react-dom": "19.1.0",
-		"react-native": "0.81.5",
-		"react-native-gesture-handler": "~2.28.0",
-		"react-native-reanimated": "~4.1.1",
-		"react-native-safe-area-context": "~5.6.0",
-		"react-native-screens": "~4.16.0",
-		"react-native-svg": "15.12.1",
+		"expo": "^56.0.0",
+		"expo-constants": "~56.0.18",
+		"expo-dev-client": "~56.0.20",
+		"expo-font": "~56.0.7",
+		"expo-haptics": "~56.0.3",
+		"expo-image": "~56.0.11",
+		"expo-linking": "~56.0.14",
+		"expo-location": "~56.0.18",
+		"expo-router": "~56.2.11",
+		"expo-splash-screen": "~56.0.10",
+		"expo-status-bar": "~56.0.4",
+		"expo-symbols": "~56.0.6",
+		"expo-system-ui": "~56.0.5",
+		"expo-web-browser": "~56.0.5",
+		"react": "19.2.3",
+		"react-dom": "19.2.3",
+		"react-native": "0.85.3",
+		"react-native-gesture-handler": "~2.31.1",
+		"react-native-reanimated": "4.3.1",
+		"react-native-safe-area-context": "~5.7.0",
+		"react-native-screens": "4.25.2",
+		"react-native-svg": "15.15.4",
 		"react-native-web": "~0.21.0",
-		"react-native-worklets": "0.5.1",
+		"react-native-worklets": "0.8.3",
 		"twrnc": "^4.16.0",
 		"zod": "^4.3.6"
 	},
 	"devDependencies": {
-		"@types/react": "~19.1.0",
-		"eas-cli": "^18.0.1",
+		"@types/react": "~19.2.10",
 		"eslint": "^9.25.0",
-		"eslint-config-expo": "~10.0.0",
-		"typescript": "^6"
+		"eslint-config-expo": "~56.0.4",
+		"typescript": "~6.0.3"
 	}
 }

apps/freya-client/scripts/dev-proxy.ts

@@ -8,14 +8,16 @@ import type { ServerWebSocket } from "bun"
 
 const PROXY_PORT = parseInt(process.env.PROXY_PORT || "8080", 10)
 const PROXY_HOST = process.env.PROXY_HOST || "0.0.0.0"
+const METRO_HOST = process.env.METRO_HOST || "localhost"
 const METRO_PORT = parseInt(process.env.METRO_PORT || "8081", 10)
-const METRO_BASE = `http://127.0.0.1:${METRO_PORT}`
+const METRO_BASE = `http://${METRO_HOST}:${METRO_PORT}`
+const METRO_WS_BASE = `ws://${METRO_HOST}:${METRO_PORT}`
 
 function forwardHeaders(headers: Headers): Headers {
 	const result = new Headers(headers)
 	result.delete("origin")
 	result.delete("referer")
-	result.set("host", `127.0.0.1:${METRO_PORT}`)
+	result.set("host", `${METRO_HOST}:${METRO_PORT}`)
 	return result
 }
 
@@ -40,7 +42,7 @@ Bun.serve<WsData>({
 
 		// WebSocket upgrade — bridge to Metro's ws endpoint
 		if (req.headers.get("upgrade")?.toLowerCase() === "websocket") {
-			const wsUrl = `ws://127.0.0.1:${METRO_PORT}${url.pathname}${url.search}`
+			const wsUrl = `${METRO_WS_BASE}${url.pathname}${url.search}`
 			const upstream = new WebSocket(wsUrl)
 
 			// Wait for upstream to connect before upgrading the client
@@ -65,12 +67,12 @@ Bun.serve<WsData>({
 		// HTTP proxy
 		const upstream = `${METRO_BASE}${url.pathname}${url.search}`
 		const body = req.body ? await req.arrayBuffer() : undefined
-		const res = await fetch(upstream, {
-			method: req.method,
-			headers: forwardHeaders(req.headers),
-			body,
-			redirect: "manual",
-		})
+		const res = await fetchUpstream(upstream, req.method, forwardHeaders(req.headers), body)
+		if (res == null) {
+			return new Response(`Metro is not reachable on ${METRO_HOST}. Restart the Expo dev server.`, {
+				status: 502,
+			})
+		}
 
 		return new Response(res.body, {
 			status: res.status,
@@ -121,9 +123,7 @@ async function printDebuggerUrl() {
 	const target = targets.find((t) => t.reactNative?.capabilities?.prefersFuseboxFrontend)
 	if (!target) return
 
-	const wsPath = target.webSocketDebuggerUrl
-		.replace(/^ws:\/\//, "")
-		.replace(`127.0.0.1:${METRO_PORT}`, `${tsIp}:${PROXY_PORT}`)
+	const wsPath = getProxyWebSocketPath(target.webSocketDebuggerUrl)
 
 	console.log(
 		`\n  React Native DevTools:\n  ${base}/debugger-frontend/rn_fusebox.html?ws=${encodeURIComponent(wsPath)}&sources.hide_add_folder=true&unstable_enableNetworkPanel=true\n`,
@@ -131,9 +131,28 @@ async function printDebuggerUrl() {
 }
 
 console.log(
-	`[proxy] listening on ${PROXY_HOST}:${PROXY_PORT}, forwarding to 127.0.0.1:${METRO_PORT}`,
+	`[proxy] listening on ${PROXY_HOST}:${PROXY_PORT}, forwarding to ${METRO_HOST}:${METRO_PORT}`,
 )
 
+async function fetchUpstream(
+	upstream: string,
+	method: string,
+	headers: Headers,
+	body: ArrayBuffer | undefined,
+) {
+	try {
+		return await fetch(upstream, {
+			method,
+			headers,
+			body,
+			redirect: "manual",
+		})
+	} catch {
+		console.error(`[proxy] ${method} ${upstream} failed; Metro is not reachable`)
+		return null
+	}
+}
+
 function isDebugTarget(value: unknown): value is DebugTarget {
 	if (!isRecord(value) || typeof value.webSocketDebuggerUrl !== "string") return false
 
@@ -149,6 +168,11 @@ function isDebugTarget(value: unknown): value is DebugTarget {
 	return prefersFuseboxFrontend === undefined || typeof prefersFuseboxFrontend === "boolean"
 }
 
+function getProxyWebSocketPath(webSocketDebuggerUrl: string) {
+	const url = new URL(webSocketDebuggerUrl)
+	return `${tsIp}:${PROXY_PORT}${url.pathname}${url.search}`
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null
 }

apps/freya-client/scripts/open-debugger.ts

@@ -4,7 +4,6 @@
 import { $ } from "bun"
 
 const PROXY_PORT = process.env.PROXY_PORT || "8080"
-const METRO_PORT = process.env.METRO_PORT || "8081"
 const tsIp = (await $`tailscale ip -4`.text()).trim()
 const base = `http://${tsIp}:${PROXY_PORT}`
 
@@ -37,9 +36,7 @@ if (!target) {
 	process.exit(1)
 }
 
-const wsUrl = target.webSocketDebuggerUrl
-	.replace(/^ws:\/\//, "")
-	.replace(`127.0.0.1:${METRO_PORT}`, `${tsIp}:${PROXY_PORT}`)
+const wsUrl = getProxyWebSocketPath(target.webSocketDebuggerUrl)
 
 const url = `${base}/debugger-frontend/rn_fusebox.html?ws=${encodeURIComponent(wsUrl)}&sources.hide_add_folder=true&unstable_enableNetworkPanel=true`
 
@@ -71,6 +68,11 @@ function isDebugTarget(value: unknown): value is DebugTarget {
 	return prefersFuseboxFrontend === undefined || typeof prefersFuseboxFrontend === "boolean"
 }
 
+function getProxyWebSocketPath(webSocketDebuggerUrl: string) {
+	const url = new URL(webSocketDebuggerUrl)
+	return `${tsIp}:${PROXY_PORT}${url.pathname}${url.search}`
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null
 }

apps/freya-client/scripts/run-dev-server.sh

@@ -1,14 +1,47 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-PROXY_PORT=8080
-METRO_PORT=8081
+PROXY_PORT=${PROXY_PORT:-8080}
+METRO_HOST=${METRO_HOST:-localhost}
+METRO_PORT=${METRO_PORT:-8081}
 TS_IP=$(tailscale ip -4)
 
-# Start a reverse proxy so Metro sees all requests as loopback.
-# This makes debugger endpoints (/debugger-frontend, /json, /open-debugger)
-# accessible through the Tailscale IP.
-PROXY_PORT=$PROXY_PORT METRO_PORT=$METRO_PORT bun run scripts/dev-proxy.ts &
+port_is_open() {
+	(: >"/dev/tcp/$1/$2") >/dev/null 2>&1
+}
+
+ensure_port_available() {
+	local port=$1
+	local name=$2
+
+	if port_is_open localhost "$port"; then
+		echo "$name port $port is already in use." >&2
+		echo "Stop the existing process or set ${name}_PORT to another value." >&2
+		exit 1
+	fi
+}
+
+wait_for_metro() {
+	for _ in {1..120}; do
+		if port_is_open "$METRO_HOST" "$METRO_PORT"; then
+			return 0
+		fi
+		sleep 0.5
+	done
+
+	echo "Metro did not start on ${METRO_HOST}:${METRO_PORT}." >&2
+	return 1
+}
+
+ensure_port_available "$PROXY_PORT" PROXY
+ensure_port_available "$METRO_PORT" METRO
+
+# Start the proxy only after Metro is listening. Otherwise an iOS client can hit
+# the proxy during Expo startup and get a misleading upstream connection error.
+(
+	wait_for_metro
+	exec env PROXY_PORT=$PROXY_PORT METRO_HOST=$METRO_HOST METRO_PORT=$METRO_PORT bun run scripts/dev-proxy.ts
+) &
 PROXY_PID=$!
 trap "kill $PROXY_PID 2>/dev/null" EXIT
 

apps/freya-client/src/components/ui/button.tsx

@@ -1,5 +1,5 @@
 import Feather from "@expo/vector-icons/Feather"
-import { type PressableProps, Pressable, View } from "react-native"
+import { type PressableProps, Pressable, type StyleProp, View, type ViewStyle } from "react-native"
 import tw from "twrnc"
 
 import { SansSerifText } from "./sans-serif-text"
@@ -14,9 +14,10 @@ function ButtonIcon({ name }: ButtonIconProps) {
 	return <Feather name={name} size={18} color={tw.color("text-stone-100 dark:text-stone-200")} />
 }
 
-type ButtonProps = Omit<PressableProps, "children"> & {
+type ButtonProps = Omit<PressableProps, "children" | "style"> & {
 	label: string
 	leadingIcon?: React.ReactNode
+	style?: StyleProp<ViewStyle>
 	trailingIcon?: React.ReactNode
 }
 

apps/waitlist-website/package.json

@@ -16,9 +16,9 @@
 		"lottie-react": "^2.4.1",
 		"lucide-react": "^0.577.0",
 		"motion": "^12.35.0",
-		"react": "^19.2.4",
+		"react": "19.2.3",
 		"react-aria-components": "^1.16.0",
-		"react-dom": "^19.2.4",
+		"react-dom": "19.2.3",
 		"react-router": "7.12.0",
 		"resend": "^6.9.3",
 		"streamdown": "^2.4.0"

bunfig.toml

@@ -0,0 +1,2 @@
+[install]
+linker = "hoisted"

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,282 @@
+{
+  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-8uhlaQAFfCgGdUlrz8sqhtIkC/WfdasbTCi3p/NkU/w=";
+      };
+      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" || file.name == "bunfig.toml"
+        ) ./.;
+      };
+
+      # 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);
+    };
+}

package.json

@@ -10,6 +10,7 @@
 		"expo": "cd apps/freya-client && bun run start",
 		"drizzle-studio": "TS_IP=$(tailscale ip -4); echo \"Drizzle Studio: https://local.drizzle.studio/?host=${TS_IP}&port=4983\"; cd apps/freya-backend && bunx drizzle-kit studio --host 0.0.0.0 --port 4983",
 		"freya-backend": "TS_IP=$(tailscale ip -4); echo \"Freya Backend: http://${TS_IP}:3000\"; echo \"\"; echo \"------------------ Bun Debugger ------------------\"; echo \"https://debug.bun.sh/#${TS_IP}:6499\"; echo \"------------------ Bun Debugger ------------------\"; echo \"\"; cd apps/freya-backend && bun run dev",
+		"client": "bun run --elide-lines=0 --filter freya-client start",
 		"admin-dashboard": "TS_IP=$(tailscale ip -4); echo \"Admin Dashboard: http://${TS_IP}:5174\"; cd apps/admin-dashboard && bun run dev --host 0.0.0.0",
 		"agent-test-cli": "cd apps/agent-test-cli && bun run start",
 		"test": "bun run --filter '*' test",

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()
+			}
 		})
 	})