refactor: rename arktype schemas to match types

Co-authored-by: Ona <no-reply@ona.com>

apps/aris-backend/.env.example

@@ -7,6 +7,11 @@ BETTER_AUTH_SECRET=
 # Base URL of the backend
 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=
 WEATHERKIT_KEY_ID=

apps/aris-backend/package.json

@@ -10,9 +10,12 @@
 	},
 	"dependencies": {
 		"@aris/core": "workspace:*",
+		"@aris/source-caldav": "workspace:*",
+		"@aris/source-google-calendar": "workspace:*",
 		"@aris/source-location": "workspace:*",
 		"@aris/source-tfl": "workspace:*",
 		"@aris/source-weatherkit": "workspace:*",
+		"@openrouter/sdk": "^0.9.11",
 		"arktype": "^2.1.29",
 		"better-auth": "^1",
 		"hono": "^4",

apps/aris-backend/src/enhancement/enhance-feed.ts

@@ -0,0 +1,51 @@
+import type { FeedItem } from "@aris/core"
+
+import type { LlmClient } from "./llm-client.ts"
+
+import { mergeEnhancement } from "./merge.ts"
+import { buildPrompt, hasUnfilledSlots } from "./prompt-builder.ts"
+
+/** Takes feed items, returns enhanced feed items. */
+export type FeedEnhancer = (items: FeedItem[]) => Promise<FeedItem[]>
+
+export interface FeedEnhancerConfig {
+	client: LlmClient
+	/** Defaults to Date.now — override for testing */
+	clock?: () => Date
+}
+
+/**
+ * Creates a FeedEnhancer that uses the provided LlmClient.
+ *
+ * Skips the LLM call when no items have unfilled slots.
+ * Returns items unchanged on LLM failure.
+ */
+export function createFeedEnhancer(config: FeedEnhancerConfig): FeedEnhancer {
+	const { client } = config
+	const clock = config.clock ?? (() => new Date())
+
+	return async function enhanceFeed(items) {
+		if (!hasUnfilledSlots(items)) {
+			return items
+		}
+
+		const currentTime = clock()
+		const { systemPrompt, userMessage } = buildPrompt(items, currentTime)
+
+		let result
+		try {
+			result = await client.enhance({ systemPrompt, userMessage })
+		} catch (err) {
+			console.error("[enhancement] LLM call failed:", err)
+			result = null
+		}
+
+		if (!result) {
+			return items
+		}
+
+		return mergeEnhancement(items, result, currentTime)
+	}
+}
+
+

apps/aris-backend/src/enhancement/llm-client.ts

@@ -0,0 +1,71 @@
+import { OpenRouter } from "@openrouter/sdk"
+
+import type { EnhancementResult } from "./schema.ts"
+
+import { enhancementResultJsonSchema, parseEnhancementResult } from "./schema.ts"
+
+const DEFAULT_MODEL = "openai/gpt-4.1-mini"
+const DEFAULT_TIMEOUT_MS = 30_000
+
+export interface LlmClientConfig {
+	apiKey: string
+	model?: string
+	timeoutMs?: number
+}
+
+export interface LlmClientRequest {
+	systemPrompt: string
+	userMessage: string
+}
+
+export interface LlmClient {
+	enhance(request: LlmClientRequest): Promise<EnhancementResult | null>
+}
+
+/**
+ * Creates a reusable LLM client backed by OpenRouter.
+ * The OpenRouter SDK instance is created once and reused across calls.
+ */
+export function createLlmClient(config: LlmClientConfig): LlmClient {
+	const client = new OpenRouter({
+		apiKey: config.apiKey,
+		timeoutMs: config.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+	})
+	const model = config.model ?? DEFAULT_MODEL
+
+	return {
+		async enhance(request) {
+			const response = await client.chat.send({
+				chatGenerationParams: {
+					model,
+					messages: [
+						{ role: "system" as const, content: request.systemPrompt },
+						{ role: "user" as const, content: request.userMessage },
+					],
+					responseFormat: {
+						type: "json_schema" as const,
+						jsonSchema: {
+							name: "enhancement_result",
+							strict: true,
+							schema: enhancementResultJsonSchema,
+						},
+					},
+					stream: false,
+				},
+			})
+
+			const content = response.choices?.[0]?.message?.content
+			if (typeof content !== "string") {
+				console.warn("[enhancement] LLM returned no content in response")
+				return null
+			}
+
+			const result = parseEnhancementResult(content)
+			if (!result) {
+				console.warn("[enhancement] Failed to parse LLM response:", content)
+			}
+
+			return result
+		},
+	}
+}

apps/aris-backend/src/enhancement/merge.test.ts

@@ -0,0 +1,150 @@
+import type { FeedItem } from "@aris/core"
+
+import { describe, expect, test } from "bun:test"
+
+import type { EnhancementResult } from "./schema.ts"
+
+import { mergeEnhancement } from "./merge.ts"
+
+function makeItem(overrides: Partial<FeedItem> = {}): FeedItem {
+	return {
+		id: "item-1",
+		type: "test",
+		timestamp: new Date("2025-01-01T00:00:00Z"),
+		data: { value: 42 },
+		...overrides,
+	}
+}
+
+const now = new Date("2025-06-01T12:00:00Z")
+
+describe("mergeEnhancement", () => {
+	test("fills matching slots", () => {
+		const item = makeItem({
+			slots: {
+				insight: { description: "Weather insight", content: null },
+			},
+		})
+		const result: EnhancementResult = {
+			slotFills: {
+				"item-1": { insight: "Rain after 3pm" },
+			},
+			syntheticItems: [],
+		}
+
+		const merged = mergeEnhancement([item], result, now)
+
+		expect(merged).toHaveLength(1)
+		expect(merged[0]!.slots!.insight!.content).toBe("Rain after 3pm")
+		// Description preserved
+		expect(merged[0]!.slots!.insight!.description).toBe("Weather insight")
+	})
+
+	test("does not mutate original items", () => {
+		const item = makeItem({
+			slots: {
+				insight: { description: "test", content: null },
+			},
+		})
+		const result: EnhancementResult = {
+			slotFills: { "item-1": { insight: "filled" } },
+			syntheticItems: [],
+		}
+
+		mergeEnhancement([item], result, now)
+
+		expect(item.slots!.insight!.content).toBeNull()
+	})
+
+	test("ignores fills for non-existent items", () => {
+		const item = makeItem()
+		const result: EnhancementResult = {
+			slotFills: { "non-existent": { insight: "text" } },
+			syntheticItems: [],
+		}
+
+		const merged = mergeEnhancement([item], result, now)
+
+		expect(merged).toHaveLength(1)
+		expect(merged[0]!.id).toBe("item-1")
+	})
+
+	test("ignores fills for non-existent slots", () => {
+		const item = makeItem({
+			slots: {
+				insight: { description: "test", content: null },
+			},
+		})
+		const result: EnhancementResult = {
+			slotFills: { "item-1": { "non-existent-slot": "text" } },
+			syntheticItems: [],
+		}
+
+		const merged = mergeEnhancement([item], result, now)
+
+		expect(merged[0]!.slots!.insight!.content).toBeNull()
+	})
+
+	test("skips null fills", () => {
+		const item = makeItem({
+			slots: {
+				insight: { description: "test", content: null },
+			},
+		})
+		const result: EnhancementResult = {
+			slotFills: { "item-1": { insight: null } },
+			syntheticItems: [],
+		}
+
+		const merged = mergeEnhancement([item], result, now)
+
+		expect(merged[0]!.slots!.insight!.content).toBeNull()
+	})
+
+	test("passes through items without slots unchanged", () => {
+		const item = makeItem()
+		const result: EnhancementResult = {
+			slotFills: {},
+			syntheticItems: [],
+		}
+
+		const merged = mergeEnhancement([item], result, now)
+
+		expect(merged[0]).toBe(item)
+	})
+
+	test("appends synthetic items with backfilled fields", () => {
+		const item = makeItem()
+		const result: EnhancementResult = {
+			slotFills: {},
+			syntheticItems: [
+				{
+					id: "briefing-morning",
+					type: "briefing",
+					text: "Light afternoon ahead.",
+				},
+			],
+		}
+
+		const merged = mergeEnhancement([item], result, now)
+
+		expect(merged).toHaveLength(2)
+		expect(merged[1]!.id).toBe("briefing-morning")
+		expect(merged[1]!.type).toBe("briefing")
+		expect(merged[1]!.timestamp).toEqual(now)
+		expect(merged[1]!.data).toEqual({ text: "Light afternoon ahead." })
+	})
+
+	test("handles empty enhancement result", () => {
+		const item = makeItem()
+		const result: EnhancementResult = {
+			slotFills: {},
+			syntheticItems: [],
+		}
+
+		const merged = mergeEnhancement([item], result, now)
+
+		expect(merged).toHaveLength(1)
+		expect(merged[0]).toBe(item)
+	})
+})

apps/aris-backend/src/enhancement/merge.ts

@@ -0,0 +1,41 @@
+import type { FeedItem } from "@aris/core"
+
+import type { EnhancementResult } from "./schema.ts"
+
+/**
+ * Merges an EnhancementResult into feed items.
+ *
+ * - Writes slot content from slotFills into matching items
+ * - Appends synthetic items to the list
+ * - Returns a new array (no mutation)
+ * - Ignores fills for items/slots that don't exist
+ */
+export function mergeEnhancement(items: FeedItem[], result: EnhancementResult, currentTime: Date): FeedItem[] {
+	const merged = items.map((item) => {
+		const fills = result.slotFills[item.id]
+		if (!fills || !item.slots) return item
+
+		const mergedSlots = { ...item.slots }
+		let changed = false
+
+		for (const [slotName, content] of Object.entries(fills)) {
+			if (slotName in mergedSlots && content !== null) {
+				mergedSlots[slotName] = { ...mergedSlots[slotName]!, content }
+				changed = true
+			}
+		}
+
+		return changed ? { ...item, slots: mergedSlots } : item
+	})
+
+	for (const synthetic of result.syntheticItems) {
+		merged.push({
+			id: synthetic.id,
+			type: synthetic.type,
+			timestamp: currentTime,
+			data: { text: synthetic.text },
+		})
+	}
+
+	return merged
+}

apps/aris-backend/src/enhancement/prompt-builder.test.ts

@@ -0,0 +1,167 @@
+import type { FeedItem } from "@aris/core"
+
+import { describe, expect, test } from "bun:test"
+
+import { buildPrompt, hasUnfilledSlots } from "./prompt-builder.ts"
+
+function makeItem(overrides: Partial<FeedItem> = {}): FeedItem {
+	return {
+		id: "item-1",
+		type: "test",
+		timestamp: new Date("2025-01-01T00:00:00Z"),
+		data: { value: 42 },
+		...overrides,
+	}
+}
+
+function parseUserMessage(userMessage: string): Record<string, unknown> {
+	return JSON.parse(userMessage)
+}
+
+describe("hasUnfilledSlots", () => {
+	test("returns false for items without slots", () => {
+		expect(hasUnfilledSlots([makeItem()])).toBe(false)
+	})
+
+	test("returns false for items with all slots filled", () => {
+		const item = makeItem({
+			slots: {
+				insight: { description: "test", content: "filled" },
+			},
+		})
+		expect(hasUnfilledSlots([item])).toBe(false)
+	})
+
+	test("returns true when at least one slot is unfilled", () => {
+		const item = makeItem({
+			slots: {
+				insight: { description: "test", content: null },
+			},
+		})
+		expect(hasUnfilledSlots([item])).toBe(true)
+	})
+
+	test("returns false for empty array", () => {
+		expect(hasUnfilledSlots([])).toBe(false)
+	})
+})
+
+describe("buildPrompt", () => {
+	test("puts items with unfilled slots in items", () => {
+		const item = makeItem({
+			slots: {
+				insight: { description: "Weather insight", content: null },
+				filled: { description: "Already done", content: "done" },
+			},
+		})
+
+		const { userMessage } = buildPrompt([item], new Date("2025-06-01T12:00:00Z"))
+		const parsed = parseUserMessage(userMessage)
+
+		expect(parsed.items).toHaveLength(1)
+		expect((parsed.items as Array<Record<string, unknown>>)[0]!.id).toBe("item-1")
+		expect((parsed.items as Array<Record<string, unknown>>)[0]!.slots).toEqual({ insight: "Weather insight" })
+		expect((parsed.items as Array<Record<string, unknown>>)[0]!.type).toBeUndefined()
+		expect(parsed.context).toHaveLength(0)
+	})
+
+	test("puts slotless items in context", () => {
+		const withSlots = makeItem({
+			id: "with-slots",
+			slots: { insight: { description: "test", content: null } },
+		})
+		const withoutSlots = makeItem({ id: "no-slots" })
+
+		const { userMessage } = buildPrompt([withSlots, withoutSlots], new Date("2025-06-01T12:00:00Z"))
+		const parsed = parseUserMessage(userMessage)
+
+		expect(parsed.items).toHaveLength(1)
+		expect((parsed.items as Array<Record<string, unknown>>)[0]!.id).toBe("with-slots")
+		expect(parsed.context).toHaveLength(1)
+		expect((parsed.context as Array<Record<string, unknown>>)[0]!.id).toBe("no-slots")
+	})
+
+	test("includes time in ISO format", () => {
+		const { userMessage } = buildPrompt([], new Date("2025-06-01T12:00:00Z"))
+		const parsed = parseUserMessage(userMessage)
+
+		expect(parsed.time).toBe("2025-06-01T12:00:00.000Z")
+	})
+
+	test("system prompt is non-empty", () => {
+		const { systemPrompt } = buildPrompt([], new Date())
+		expect(systemPrompt.length).toBeGreaterThan(0)
+	})
+
+	test("includes schedule in system prompt", () => {
+		const calEvent = makeItem({
+			id: "cal-1",
+			type: "caldav-event",
+			data: {
+				title: "Team standup",
+				startDate: "2025-06-01T10:00:00Z",
+				endDate: "2025-06-01T10:30:00Z",
+				isAllDay: false,
+				location: null,
+			},
+			slots: {
+				insight: { description: "test", content: null },
+			},
+		})
+
+		const { systemPrompt } = buildPrompt([calEvent], new Date("2025-06-01T12:00:00Z"))
+
+		expect(systemPrompt).toContain("Schedule:\n")
+		expect(systemPrompt).toContain("Team standup")
+		expect(systemPrompt).toContain("10:00")
+	})
+
+	test("includes location in schedule", () => {
+		const calEvent = makeItem({
+			id: "cal-1",
+			type: "caldav-event",
+			data: {
+				title: "Therapy",
+				startDate: "2025-06-02T18:00:00Z",
+				endDate: "2025-06-02T19:00:00Z",
+				isAllDay: false,
+				location: "92 Tooley Street, London",
+			},
+		})
+
+		const { systemPrompt } = buildPrompt([calEvent], new Date("2025-06-01T12:00:00Z"))
+
+		expect(systemPrompt).toContain("Therapy @ 92 Tooley Street, London")
+	})
+
+	test("includes week calendar but omits schedule when no calendar items", () => {
+		const weatherItem = makeItem({
+			type: "weather-current",
+			data: { temperature: 14 },
+		})
+
+		const { systemPrompt } = buildPrompt([weatherItem], new Date("2025-06-01T12:00:00Z"))
+
+		expect(systemPrompt).toContain("Week:")
+		expect(systemPrompt).not.toContain("Schedule:")
+	})
+
+	test("user message is pure JSON", () => {
+		const calEvent = makeItem({
+			id: "cal-1",
+			type: "caldav-event",
+			data: {
+				title: "Budget Review",
+				startTime: "2025-06-01T14:00:00Z",
+				endTime: "2025-06-01T15:00:00Z",
+				isAllDay: false,
+				location: "https://meet.google.com/abc",
+			},
+		})
+
+		const { userMessage } = buildPrompt([calEvent], new Date("2025-06-01T12:00:00Z"))
+
+		expect(userMessage.startsWith("{")).toBe(true)
+		expect(() => JSON.parse(userMessage)).not.toThrow()
+	})
+})

apps/aris-backend/src/enhancement/prompt-builder.ts

@@ -0,0 +1,218 @@
+import type { FeedItem } from "@aris/core"
+
+import { CalDavFeedItemType } from "@aris/source-caldav"
+import { CalendarFeedItemType } from "@aris/source-google-calendar"
+
+import systemPromptBase from "./prompts/system.txt"
+
+const CALENDAR_ITEM_TYPES = new Set<string>([
+	CalDavFeedItemType.Event,
+	CalendarFeedItemType.Event,
+	CalendarFeedItemType.AllDay,
+])
+
+/**
+ * Builds the system prompt and user message for the enhancement harness.
+ *
+ * Includes a pre-computed mini calendar so the LLM doesn't have to
+ * parse timestamps to understand the user's schedule.
+ */
+export function buildPrompt(
+	items: FeedItem[],
+	currentTime: Date,
+): { systemPrompt: string; userMessage: string } {
+	const schedule = buildSchedule(items, currentTime)
+
+	const enhanceItems: Array<{
+		id: string
+		data: Record<string, unknown>
+		slots: Record<string, string>
+	}> = []
+	const contextItems: Array<{
+		id: string
+		type: string
+		data: Record<string, unknown>
+	}> = []
+
+	for (const item of items) {
+		const hasUnfilledSlots =
+			item.slots &&
+			Object.values(item.slots).some((slot) => slot.content === null)
+
+		if (hasUnfilledSlots) {
+			enhanceItems.push({
+				id: item.id,
+				data: item.data,
+				slots: Object.fromEntries(
+					Object.entries(item.slots!)
+						.filter(([, slot]) => slot.content === null)
+						.map(([name, slot]) => [name, slot.description]),
+				),
+			})
+		} else {
+			contextItems.push({
+				id: item.id,
+				type: item.type,
+				data: item.data,
+			})
+		}
+	}
+
+	const userMessage = JSON.stringify({
+		time: currentTime.toISOString(),
+		items: enhanceItems,
+		context: contextItems,
+	})
+
+	const weekCalendar = buildWeekCalendar(currentTime)
+	let systemPrompt = systemPromptBase
+	systemPrompt += `\n\nWeek:\n${weekCalendar}`
+	if (schedule) {
+		systemPrompt += `\n\nSchedule:\n${schedule}`
+	}
+
+	return { systemPrompt, userMessage }
+}
+
+/**
+ * Returns true if any item has at least one unfilled slot.
+ */
+export function hasUnfilledSlots(items: FeedItem[]): boolean {
+	return items.some(
+		(item) =>
+			item.slots &&
+			Object.values(item.slots).some((slot) => slot.content === null),
+	)
+}
+
+// -- Helpers --
+
+interface CalendarEntry {
+	date: Date
+	title: string
+	location: string | null
+	isAllDay: boolean
+	startTime: Date
+	endTime: Date
+}
+
+function toValidDate(value: unknown): Date | null {
+	if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value
+	if (typeof value === "string" || typeof value === "number") {
+		const date = new Date(value)
+		return Number.isNaN(date.getTime()) ? null : date
+	}
+	return null
+}
+
+function extractCalendarEntry(item: FeedItem): CalendarEntry | null {
+	if (!CALENDAR_ITEM_TYPES.has(item.type)) return null
+
+	const d = item.data
+	const title = d.title
+	if (typeof title !== "string" || !title) return null
+
+	// CalDAV uses startDate/endDate, Google Calendar uses startTime/endTime
+	const startTime = toValidDate(d.startDate ?? d.startTime)
+	if (!startTime) return null
+
+	const endTime = toValidDate(d.endDate ?? d.endTime) ?? startTime
+
+	return {
+		date: startTime,
+		title,
+		location: typeof d.location === "string" ? d.location : null,
+		isAllDay: typeof d.isAllDay === "boolean" ? d.isAllDay : false,
+		startTime,
+		endTime,
+	}
+}
+
+const DAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"] as const
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"] as const
+
+function pad2(n: number): string {
+	return n.toString().padStart(2, "0")
+}
+
+function formatTime(date: Date): string {
+	return `${pad2(date.getUTCHours())}:${pad2(date.getUTCMinutes())}`
+}
+
+function formatDayShort(date: Date): string {
+	return `${DAYS[date.getUTCDay()]}, ${date.getUTCDate()} ${MONTHS[date.getUTCMonth()]}`
+}
+
+function formatDayLabel(date: Date, currentTime: Date): string {
+	const currentDay = Date.UTC(currentTime.getUTCFullYear(), currentTime.getUTCMonth(), currentTime.getUTCDate())
+	const targetDay = Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate())
+	const diffDays = Math.round((targetDay - currentDay) / (1000 * 60 * 60 * 24))
+
+	const dayName = formatDayShort(date)
+
+	if (diffDays === 0) return `Today: ${dayName}`
+	if (diffDays === 1) return `Tomorrow: ${dayName}`
+	return dayName
+}
+
+/**
+ * Builds a week overview mapping day names to dates,
+ * so the LLM can easily match ISO timestamps to days.
+ */
+function buildWeekCalendar(currentTime: Date): string {
+	const lines: string[] = []
+	for (let i = 0; i < 7; i++) {
+		const date = new Date(currentTime)
+		date.setUTCDate(date.getUTCDate() + i)
+		const label = i === 0 ? "Today" : i === 1 ? "Tomorrow" : ""
+		const dayStr = formatDayShort(date)
+		const iso = date.toISOString().slice(0, 10)
+		const prefix = label ? `${label}: ` : ""
+		lines.push(`${prefix}${dayStr} = ${iso}`)
+	}
+	return lines.join("\n")
+}
+
+/**
+ * Builds a compact text calendar from all calendar-type items.
+ * Groups events by day relative to currentTime.
+ */
+function buildSchedule(items: FeedItem[], currentTime: Date): string {
+	const entries: CalendarEntry[] = []
+	for (const item of items) {
+		const entry = extractCalendarEntry(item)
+		if (entry) entries.push(entry)
+	}
+
+	if (entries.length === 0) return ""
+
+	entries.sort((a, b) => a.startTime.getTime() - b.startTime.getTime())
+
+	const byDay = new Map<string, CalendarEntry[]>()
+	for (const entry of entries) {
+		const key = entry.date.toISOString().slice(0, 10)
+		const group = byDay.get(key)
+		if (group) {
+			group.push(entry)
+		} else {
+			byDay.set(key, [entry])
+		}
+	}
+
+	const lines: string[] = []
+	for (const [, dayEntries] of byDay) {
+		lines.push(formatDayLabel(dayEntries[0]!.startTime, currentTime))
+		for (const entry of dayEntries) {
+			if (entry.isAllDay) {
+				const loc = entry.location ? ` @ ${entry.location}` : ""
+				lines.push(`  all day  ${entry.title}${loc}`)
+			} else {
+				const timeRange = `${formatTime(entry.startTime)}–${formatTime(entry.endTime)}`
+				const loc = entry.location ? ` @ ${entry.location}` : ""
+				lines.push(`  ${timeRange}  ${entry.title}${loc}`)
+			}
+		}
+	}
+
+	return lines.join("\n")
+}

apps/aris-backend/src/enhancement/prompts/system.txt

@@ -0,0 +1,21 @@
+You are ARIS, a personal assistant. You enhance a user's feed by filling slots and optionally generating synthetic items.
+
+The user message is a JSON object with:
+- "items": feed items with data and named slots to fill. Each slot has a description of what to write.
+- "context": other feed items (no slots) for cross-source reasoning.
+- "time": current ISO timestamp.
+
+Your output has two fields:
+- "slotFills": map of item ID → slot name → short text (or null if you can't fill it or cannot provide answer). Each item ID appears ONCE with ALL its slots in a single object.
+- "syntheticItems": array of { id, type, text } for new items (briefings, nudges, insights). Only when genuinely useful and when not redundant.
+
+Rules:
+- DO NOT USE EMDASH OR DASH OR ATTEMPT TO USE SYMBOLS TO CIRCUMVENT THIS RULE.
+- One sentence per slot. Two max if absolutely necessary. Be direct.
+- Say "I" not "we."
+- Hedge when inferring. Don't state guesses as facts.
+- Use the week and schedule below to understand when events happen. Match weather data to the correct date.
+- Look for connections across items.
+- Don't pad — return null for slots you can't meaningfully fill, and skip synthetic items if there's nothing useful to add.
+- Never fabricate information not present in the feed. If you don't have data to support a fill, return null.
+- Read each slot's description carefully — it defines when to return null.

apps/aris-backend/src/enhancement/schema.test.ts

@@ -0,0 +1,176 @@
+import { describe, expect, test } from "bun:test"
+
+import {
+	emptyEnhancementResult,
+	enhancementResultJsonSchema,
+	parseEnhancementResult,
+} from "./schema.ts"
+
+describe("parseEnhancementResult", () => {
+	test("parses valid result", () => {
+		const input = JSON.stringify({
+			slotFills: {
+				"weather-1": {
+					insight: "Rain after 3pm",
+					"cross-source": null,
+				},
+			},
+			syntheticItems: [
+				{
+					id: "briefing-morning",
+					type: "briefing",
+					text: "Light afternoon ahead.",
+				},
+			],
+		})
+
+		const result = parseEnhancementResult(input)
+
+		expect(result).not.toBeNull()
+		expect(result!.slotFills["weather-1"]!.insight).toBe("Rain after 3pm")
+		expect(result!.slotFills["weather-1"]!["cross-source"]).toBeNull()
+		expect(result!.syntheticItems).toHaveLength(1)
+		expect(result!.syntheticItems[0]!.id).toBe("briefing-morning")
+		expect(result!.syntheticItems[0]!.text).toBe("Light afternoon ahead.")
+	})
+
+	test("parses empty result", () => {
+		const input = JSON.stringify({
+			slotFills: {},
+			syntheticItems: [],
+		})
+
+		const result = parseEnhancementResult(input)
+
+		expect(result).not.toBeNull()
+		expect(Object.keys(result!.slotFills)).toHaveLength(0)
+		expect(result!.syntheticItems).toHaveLength(0)
+	})
+
+	test("returns null for invalid JSON", () => {
+		expect(parseEnhancementResult("not json")).toBeNull()
+	})
+
+	test("returns null for non-object", () => {
+		expect(parseEnhancementResult('"hello"')).toBeNull()
+		expect(parseEnhancementResult("42")).toBeNull()
+		expect(parseEnhancementResult("null")).toBeNull()
+	})
+
+	test("returns null when slotFills is missing", () => {
+		const input = JSON.stringify({ syntheticItems: [] })
+		expect(parseEnhancementResult(input)).toBeNull()
+	})
+
+	test("returns null when syntheticItems is missing", () => {
+		const input = JSON.stringify({ slotFills: {} })
+		expect(parseEnhancementResult(input)).toBeNull()
+	})
+
+	test("returns null when slotFills has non-string values", () => {
+		const input = JSON.stringify({
+			slotFills: { "item-1": { slot: 42 } },
+			syntheticItems: [],
+		})
+		expect(parseEnhancementResult(input)).toBeNull()
+	})
+
+	test("returns null when syntheticItem is missing required fields", () => {
+		const input = JSON.stringify({
+			slotFills: {},
+			syntheticItems: [{ id: "x" }],
+		})
+		expect(parseEnhancementResult(input)).toBeNull()
+	})
+})
+
+describe("emptyEnhancementResult", () => {
+	test("returns empty slotFills and syntheticItems", () => {
+		const result = emptyEnhancementResult()
+		expect(result.slotFills).toEqual({})
+		expect(result.syntheticItems).toEqual([])
+	})
+})
+
+describe("schema sync", () => {
+	const referencePayloads = [
+		{
+			name: "full payload with null slot fill",
+			payload: {
+				slotFills: {
+					"weather-1": { insight: "Rain after 3pm", crossSource: null },
+					"cal-2": { summary: "Busy morning" },
+				},
+				syntheticItems: [
+					{ id: "briefing-morning", type: "briefing", text: "Light day ahead." },
+					{ id: "nudge-umbrella", type: "nudge", text: "Bring an umbrella." },
+				],
+			},
+		},
+		{
+			name: "empty collections",
+			payload: { slotFills: {}, syntheticItems: [] },
+		},
+		{
+			name: "slot fills only",
+			payload: {
+				slotFills: { "item-1": { slot: "filled" } },
+				syntheticItems: [],
+			},
+		},
+		{
+			name: "synthetic items only",
+			payload: {
+				slotFills: {},
+				syntheticItems: [{ id: "insight-1", type: "insight", text: "Something." }],
+			},
+		},
+	]
+
+	for (const { name, payload } of referencePayloads) {
+		test(`arktype and JSON Schema agree on: ${name}`, () => {
+			// arktype accepts it
+			const parsed = parseEnhancementResult(JSON.stringify(payload))
+			expect(parsed).not.toBeNull()
+
+			// JSON Schema structure matches
+			const jsonSchema = enhancementResultJsonSchema
+			expect(Object.keys(jsonSchema.properties).sort()).toEqual(
+				Object.keys(payload).sort(),
+			)
+			expect([...jsonSchema.required].sort()).toEqual(Object.keys(payload).sort())
+
+			// syntheticItems item schema has the right required fields
+			const itemSchema = jsonSchema.properties.syntheticItems.items
+			expect([...itemSchema.required].sort()).toEqual(["id", "text", "type"])
+
+			// Verify each synthetic item has exactly the fields the JSON Schema expects
+			for (const item of payload.syntheticItems) {
+				expect(Object.keys(item).sort()).toEqual([...itemSchema.required].sort())
+			}
+		})
+	}
+
+	test("JSON Schema rejects what arktype rejects: missing required field", () => {
+		// Missing syntheticItems
+		expect(parseEnhancementResult(JSON.stringify({ slotFills: {} }))).toBeNull()
+
+		// JSON Schema also requires it
+		expect(enhancementResultJsonSchema.required).toContain("syntheticItems")
+	})
+
+	test("JSON Schema rejects what arktype rejects: wrong slot fill value type", () => {
+		const bad = { slotFills: { "item-1": { slot: 42 } }, syntheticItems: [] }
+
+		// arktype rejects it
+		expect(parseEnhancementResult(JSON.stringify(bad))).toBeNull()
+
+		// JSON Schema only allows string or null for slot values
+		const slotValueTypes =
+			enhancementResultJsonSchema.properties.slotFills.additionalProperties
+				.additionalProperties.type
+		expect(slotValueTypes).toContain("string")
+		expect(slotValueTypes).toContain("null")
+		expect(slotValueTypes).not.toContain("number")
+	})
+})

apps/aris-backend/src/enhancement/schema.ts

@@ -0,0 +1,89 @@
+import { type } from "arktype"
+
+const SyntheticItem = type({
+	id: "string",
+	type: "string",
+	text: "string",
+})
+
+const EnhancementResult = type({
+	slotFills: "Record<string, Record<string, string | null>>",
+	syntheticItems: SyntheticItem.array(),
+})
+
+export type SyntheticItem = typeof SyntheticItem.infer
+export type EnhancementResult = typeof EnhancementResult.infer
+
+/**
+ * JSON Schema passed to OpenRouter's structured output.
+ * OpenRouter doesn't support arktype, so this is maintained separately.
+ *
+ * ⚠️  Must stay in sync with EnhancementResult above.
+ * If you add/remove fields, update both schemas.
+ */
+export const enhancementResultJsonSchema = {
+	type: "object",
+	properties: {
+		slotFills: {
+			type: "object",
+			description:
+				"Map of feed item ID to an object of slot name to filled text content. Use null for slots that cannot be meaningfully filled.",
+			additionalProperties: {
+				type: "object",
+				additionalProperties: {
+					type: ["string", "null"],
+				},
+			},
+		},
+		syntheticItems: {
+			type: "array",
+			description:
+				"New feed items to inject (briefings, nudges, cross-source insights). Keep these short and actionable.",
+			items: {
+				type: "object",
+				properties: {
+					id: {
+						type: "string",
+						description: "Unique ID, e.g. 'briefing-morning'",
+					},
+					type: {
+						type: "string",
+						description: "One of: 'briefing', 'nudge', 'insight'",
+					},
+					text: {
+						type: "string",
+						description: "Display text, 1-3 sentences",
+					},
+				},
+				required: ["id", "type", "text"],
+				additionalProperties: false,
+			},
+		},
+	},
+	required: ["slotFills", "syntheticItems"],
+	additionalProperties: false,
+} as const
+
+/**
+ * Parses a JSON string into an EnhancementResult.
+ * Returns null if the input is malformed.
+ */
+export function parseEnhancementResult(json: string): EnhancementResult | null {
+	let parsed: unknown
+	try {
+		parsed = JSON.parse(json)
+	} catch {
+		return null
+	}
+
+	const result = EnhancementResult(parsed)
+	if (result instanceof type.errors) {
+		return null
+	}
+
+	return result
+}
+
+export function emptyEnhancementResult(): EnhancementResult {
+	return { slotFills: {}, syntheticItems: [] }
+}

apps/aris-backend/src/feed/http.test.ts

@@ -47,7 +47,7 @@ function buildTestApp(sessionManager: UserSessionManager, userId?: string) {
 
 describe("GET /api/feed", () => {
 	test("returns 401 without auth", async () => {
-		const manager = new UserSessionManager([])
+		const manager = new UserSessionManager({ providers: [] })
 		const app = buildTestApp(manager)
 
 		const res = await app.request("/api/feed")
@@ -65,7 +65,9 @@ describe("GET /api/feed", () => {
 				data: { value: 42 },
 			},
 		]
-		const manager = new UserSessionManager([() => createStubSource("test", items)])
+		const manager = new UserSessionManager({
+			providers: [() => createStubSource("test", items)],
+		})
 		const app = buildTestApp(manager, "user-1")
 
 		// Prime the cache
@@ -95,7 +97,9 @@ describe("GET /api/feed", () => {
 				data: { fresh: true },
 			},
 		]
-		const manager = new UserSessionManager([() => createStubSource("test", items)])
+		const manager = new UserSessionManager({
+			providers: [() => createStubSource("test", items)],
+		})
 		const app = buildTestApp(manager, "user-1")
 
 		// No prior refresh — lastFeed() returns null, handler should call refresh()
@@ -125,7 +129,7 @@ describe("GET /api/feed", () => {
 				throw new Error("connection timeout")
 			},
 		}
-		const manager = new UserSessionManager([() => failingSource])
+		const manager = new UserSessionManager({ providers: [() => failingSource] })
 		const app = buildTestApp(manager, "user-1")
 
 		const res = await app.request("/api/feed")

apps/aris-backend/src/feed/http.ts

@@ -5,7 +5,11 @@ import { createMiddleware } from "hono/factory"
 import type { AuthSessionMiddleware } from "../auth/session-middleware.ts"
 import type { UserSessionManager } from "../session/index.ts"
 
-type Env = { Variables: { sessionManager: UserSessionManager } }
+type Env = {
+	Variables: {
+		sessionManager: UserSessionManager
+	}
+}
 
 interface FeedHttpHandlersDeps {
 	sessionManager: UserSessionManager
@@ -29,7 +33,7 @@ async function handleGetFeed(c: Context<Env>) {
 	const sessionManager = c.get("sessionManager")
 	const session = sessionManager.getOrCreate(user.id)
 
-	const feed = session.engine.lastFeed() ?? (await session.engine.refresh())
+	const feed = await session.feed()
 
 	return c.json({
 		items: feed.items,

apps/aris-backend/src/server.ts

@@ -3,13 +3,29 @@ import { Hono } from "hono"
 
 import { registerAuthHandlers } from "./auth/http.ts"
 import { requireSession } from "./auth/session-middleware.ts"
+import { createFeedEnhancer } from "./enhancement/enhance-feed.ts"
+import { createLlmClient } from "./enhancement/llm-client.ts"
 import { registerFeedHttpHandlers } from "./feed/http.ts"
 import { registerLocationHttpHandlers } from "./location/http.ts"
 import { UserSessionManager } from "./session/index.ts"
 import { WeatherSourceProvider } from "./weather/provider.ts"
 
 function main() {
-	const sessionManager = new UserSessionManager([
+	const openrouterApiKey = process.env.OPENROUTER_API_KEY
+	const feedEnhancer = openrouterApiKey
+		? createFeedEnhancer({
+				client: createLlmClient({
+					apiKey: openrouterApiKey,
+					model: process.env.OPENROUTER_MODEL || undefined,
+				}),
+			})
+		: null
+	if (!feedEnhancer) {
+		console.warn("[enhancement] OPENROUTER_API_KEY not set — feed enhancement disabled")
+	}
+
+	const sessionManager = new UserSessionManager({
+		providers: [
 			() => new LocationSource(),
 			new WeatherSourceProvider({
 				credentials: {
@@ -19,14 +35,19 @@ function main() {
 					serviceId: process.env.WEATHERKIT_SERVICE_ID!,
 				},
 			}),
-	])
+		],
+		feedEnhancer,
+	})
 
 	const app = new Hono()
 
 	app.get("/health", (c) => c.json({ status: "ok" }))
 
 	registerAuthHandlers(app)
-	registerFeedHttpHandlers(app, { sessionManager, authSessionMiddleware: requireSession })
+	registerFeedHttpHandlers(app, {
+		sessionManager,
+		authSessionMiddleware: requireSession,
+	})
 	registerLocationHttpHandlers(app, { sessionManager })
 
 	return app

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

@@ -12,7 +12,7 @@ const mockWeatherClient: WeatherKitClient = {
 
 describe("UserSessionManager", () => {
 	test("getOrCreate creates session on first call", () => {
-		const manager = new UserSessionManager([() => new LocationSource()])
+		const manager = new UserSessionManager({ providers: [() => new LocationSource()] })
 
 		const session = manager.getOrCreate("user-1")
 
@@ -21,7 +21,7 @@ describe("UserSessionManager", () => {
 	})
 
 	test("getOrCreate returns same session for same user", () => {
-		const manager = new UserSessionManager([() => new LocationSource()])
+		const manager = new UserSessionManager({ providers: [() => new LocationSource()] })
 
 		const session1 = manager.getOrCreate("user-1")
 		const session2 = manager.getOrCreate("user-1")
@@ -30,7 +30,7 @@ describe("UserSessionManager", () => {
 	})
 
 	test("getOrCreate returns different sessions for different users", () => {
-		const manager = new UserSessionManager([() => new LocationSource()])
+		const manager = new UserSessionManager({ providers: [() => new LocationSource()] })
 
 		const session1 = manager.getOrCreate("user-1")
 		const session2 = manager.getOrCreate("user-2")
@@ -39,7 +39,7 @@ describe("UserSessionManager", () => {
 	})
 
 	test("each user gets independent source instances", () => {
-		const manager = new UserSessionManager([() => new LocationSource()])
+		const manager = new UserSessionManager({ providers: [() => new LocationSource()] })
 
 		const session1 = manager.getOrCreate("user-1")
 		const session2 = manager.getOrCreate("user-2")
@@ -51,7 +51,7 @@ describe("UserSessionManager", () => {
 	})
 
 	test("remove destroys session and allows re-creation", () => {
-		const manager = new UserSessionManager([() => new LocationSource()])
+		const manager = new UserSessionManager({ providers: [() => new LocationSource()] })
 
 		const session1 = manager.getOrCreate("user-1")
 		manager.remove("user-1")
@@ -61,13 +61,13 @@ describe("UserSessionManager", () => {
 	})
 
 	test("remove is no-op for unknown user", () => {
-		const manager = new UserSessionManager([() => new LocationSource()])
+		const manager = new UserSessionManager({ providers: [() => new LocationSource()] })
 
 		expect(() => manager.remove("unknown")).not.toThrow()
 	})
 
 	test("accepts function providers", async () => {
-		const manager = new UserSessionManager([() => new LocationSource()])
+		const manager = new UserSessionManager({ providers: [() => new LocationSource()] })
 
 		const session = manager.getOrCreate("user-1")
 		const result = await session.engine.refresh()
@@ -77,7 +77,9 @@ describe("UserSessionManager", () => {
 
 	test("accepts object providers", () => {
 		const provider = new WeatherSourceProvider({ client: mockWeatherClient })
-		const manager = new UserSessionManager([() => new LocationSource(), provider])
+		const manager = new UserSessionManager({
+			providers: [() => new LocationSource(), provider],
+		})
 
 		const session = manager.getOrCreate("user-1")
 
@@ -86,7 +88,9 @@ describe("UserSessionManager", () => {
 
 	test("accepts mixed providers", () => {
 		const provider = new WeatherSourceProvider({ client: mockWeatherClient })
-		const manager = new UserSessionManager([() => new LocationSource(), provider])
+		const manager = new UserSessionManager({
+			providers: [() => new LocationSource(), provider],
+		})
 
 		const session = manager.getOrCreate("user-1")
 
@@ -95,7 +99,7 @@ describe("UserSessionManager", () => {
 	})
 
 	test("refresh returns feed result through session", async () => {
-		const manager = new UserSessionManager([() => new LocationSource()])
+		const manager = new UserSessionManager({ providers: [() => new LocationSource()] })
 
 		const session = manager.getOrCreate("user-1")
 		const result = await session.engine.refresh()
@@ -107,7 +111,7 @@ describe("UserSessionManager", () => {
 	})
 
 	test("location update via executeAction works", async () => {
-		const manager = new UserSessionManager([() => new LocationSource()])
+		const manager = new UserSessionManager({ providers: [() => new LocationSource()] })
 
 		const session = manager.getOrCreate("user-1")
 		await session.engine.executeAction("aris.location", "update-location", {
@@ -122,7 +126,7 @@ describe("UserSessionManager", () => {
 	})
 
 	test("subscribe receives updates after location push", async () => {
-		const manager = new UserSessionManager([() => new LocationSource()])
+		const manager = new UserSessionManager({ providers: [() => new LocationSource()] })
 		const callback = mock()
 
 		const session = manager.getOrCreate("user-1")
@@ -142,7 +146,7 @@ describe("UserSessionManager", () => {
 	})
 
 	test("remove stops reactive updates", async () => {
-		const manager = new UserSessionManager([() => new LocationSource()])
+		const manager = new UserSessionManager({ providers: [() => new LocationSource()] })
 		const callback = mock()
 
 		const session = manager.getOrCreate("user-1")

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

@@ -1,13 +1,21 @@
+import type { FeedEnhancer } from "../enhancement/enhance-feed.ts"
 import type { FeedSourceProviderInput } from "./feed-source-provider.ts"
 
 import { UserSession } from "./user-session.ts"
 
+export interface UserSessionManagerConfig {
+	providers: FeedSourceProviderInput[]
+	feedEnhancer?: FeedEnhancer | null
+}
+
 export class UserSessionManager {
 	private sessions = new Map<string, UserSession>()
 	private readonly providers: FeedSourceProviderInput[]
+	private readonly feedEnhancer: FeedEnhancer | null
 
-	constructor(providers: FeedSourceProviderInput[]) {
-		this.providers = providers
+	constructor(config: UserSessionManagerConfig) {
+		this.providers = config.providers
+		this.feedEnhancer = config.feedEnhancer ?? null
 	}
 
 	getOrCreate(userId: string): UserSession {
@@ -16,7 +24,7 @@ export class UserSessionManager {
 			const sources = this.providers.map((p) =>
 				typeof p === "function" ? p(userId) : p.feedSourceForUser(userId),
 			)
-			session = new UserSession(sources)
+			session = new UserSession(sources, this.feedEnhancer)
 			this.sessions.set(userId, session)
 		}
 		return session

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

@@ -1,11 +1,11 @@
-import type { ActionDefinition, ContextEntry, FeedSource } from "@aris/core"
+import type { ActionDefinition, ContextEntry, FeedItem, FeedSource } from "@aris/core"
 
 import { LocationSource } from "@aris/source-location"
 import { describe, expect, test } from "bun:test"
 
 import { UserSession } from "./user-session.ts"
 
-function createStubSource(id: string): FeedSource {
+function createStubSource(id: string, items: FeedItem[] = []): FeedSource {
 	return {
 		id,
 		async listActions(): Promise<Record<string, ActionDefinition>> {
@@ -18,7 +18,7 @@ function createStubSource(id: string): FeedSource {
 			return null
 		},
 		async fetchItems() {
-			return []
+			return items
 		},
 	}
 }
@@ -70,3 +70,141 @@ describe("UserSession", () => {
 		expect(location.lastLocation!.lat).toBe(51.5)
 	})
 })
+
+describe("UserSession.feed", () => {
+	test("returns feed items without enhancer", async () => {
+		const items: FeedItem[] = [
+			{
+				id: "item-1",
+				type: "test",
+				timestamp: new Date("2025-01-01T00:00:00.000Z"),
+				data: { value: 42 },
+			},
+		]
+		const session = new UserSession([createStubSource("test", items)])
+
+		const result = await session.feed()
+
+		expect(result.items).toHaveLength(1)
+		expect(result.items[0]!.id).toBe("item-1")
+	})
+
+	test("returns enhanced items when enhancer is provided", async () => {
+		const items: FeedItem[] = [
+			{
+				id: "item-1",
+				type: "test",
+				timestamp: new Date("2025-01-01T00:00:00.000Z"),
+				data: { value: 42 },
+			},
+		]
+		const enhancer = async (feedItems: FeedItem[]) =>
+			feedItems.map((item) => ({ ...item, data: { ...item.data, enhanced: true } }))
+
+		const session = new UserSession([createStubSource("test", items)], enhancer)
+
+		const result = await session.feed()
+
+		expect(result.items).toHaveLength(1)
+		expect(result.items[0]!.data.enhanced).toBe(true)
+	})
+
+	test("caches enhanced items on subsequent calls", async () => {
+		const items: FeedItem[] = [
+			{
+				id: "item-1",
+				type: "test",
+				timestamp: new Date("2025-01-01T00:00:00.000Z"),
+				data: { value: 42 },
+			},
+		]
+		let enhancerCallCount = 0
+		const enhancer = async (feedItems: FeedItem[]) => {
+			enhancerCallCount++
+			return feedItems.map((item) => ({ ...item, data: { ...item.data, enhanced: true } }))
+		}
+
+		const session = new UserSession([createStubSource("test", items)], enhancer)
+
+		const result1 = await session.feed()
+		expect(result1.items[0]!.data.enhanced).toBe(true)
+		expect(enhancerCallCount).toBe(1)
+
+		const result2 = await session.feed()
+		expect(result2.items[0]!.data.enhanced).toBe(true)
+		expect(enhancerCallCount).toBe(1)
+	})
+
+	test("re-enhances after engine refresh with new data", async () => {
+		let currentItems: FeedItem[] = [
+			{
+				id: "item-1",
+				type: "test",
+				timestamp: new Date("2025-01-01T00:00:00.000Z"),
+				data: { version: 1 },
+			},
+		]
+		const source = createStubSource("test", currentItems)
+		// Make fetchItems dynamic so refresh returns new data
+		source.fetchItems = async () => currentItems
+
+		const enhancedVersions: number[] = []
+		const enhancer = async (feedItems: FeedItem[]) => {
+			const version = feedItems[0]!.data.version as number
+			enhancedVersions.push(version)
+			return feedItems.map((item) => ({
+				...item,
+				data: { ...item.data, enhanced: true },
+			}))
+		}
+
+		const session = new UserSession([source], enhancer)
+
+		// First feed triggers refresh + enhancement
+		const result1 = await session.feed()
+		expect(result1.items[0]!.data.version).toBe(1)
+		expect(result1.items[0]!.data.enhanced).toBe(true)
+
+		// Update source data and trigger engine refresh
+		currentItems = [
+			{
+				id: "item-1",
+				type: "test",
+				timestamp: new Date("2025-01-02T00:00:00.000Z"),
+				data: { version: 2 },
+			},
+		]
+		await session.engine.refresh()
+
+		// Wait for subscriber-triggered background enhancement
+		await new Promise((resolve) => setTimeout(resolve, 10))
+
+		// feed() should now serve re-enhanced items with version 2
+		const result2 = await session.feed()
+		expect(result2.items[0]!.data.version).toBe(2)
+		expect(result2.items[0]!.data.enhanced).toBe(true)
+		expect(enhancedVersions).toEqual([1, 2])
+	})
+
+	test("falls back to unenhanced items when enhancer throws", async () => {
+		const items: FeedItem[] = [
+			{
+				id: "item-1",
+				type: "test",
+				timestamp: new Date("2025-01-01T00:00:00.000Z"),
+				data: { value: 42 },
+			},
+		]
+		const enhancer = async () => {
+			throw new Error("enhancement exploded")
+		}
+
+		const session = new UserSession([createStubSource("test", items)], enhancer)
+
+		const result = await session.feed()
+
+		expect(result.items).toHaveLength(1)
+		expect(result.items[0]!.id).toBe("item-1")
+		expect(result.items[0]!.data.value).toBe(42)
+	})
+})

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

@@ -1,24 +1,104 @@
-import { FeedEngine, type FeedSource } from "@aris/core"
+import { FeedEngine, type FeedItem, type FeedResult, type FeedSource } from "@aris/core"
+
+import type { FeedEnhancer } from "../enhancement/enhance-feed.ts"
 
 export class UserSession {
 	readonly engine: FeedEngine
 	private sources = new Map<string, FeedSource>()
+	private readonly enhancer: FeedEnhancer | null
+	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(sources: FeedSource[]) {
+	constructor(sources: FeedSource[], enhancer?: FeedEnhancer | null) {
 		this.engine = new FeedEngine()
+		this.enhancer = enhancer ?? null
 		for (const source of sources) {
 			this.sources.set(source.id, source)
 			this.engine.register(source)
 		}
+
+		if (this.enhancer) {
+			this.unsubscribe = this.engine.subscribe((result) => {
+				this.invalidateEnhancement()
+				this.runEnhancement(result)
+			})
+		}
+
 		this.engine.start()
 	}
 
+	/**
+	 * Returns the current feed, refreshing if the engine cache expired.
+	 * Enhancement runs eagerly on engine updates; this method awaits
+	 * any in-flight enhancement or triggers one if needed.
+	 */
+	async feed(): Promise<FeedResult> {
+		const cached = this.engine.lastFeed()
+		const result = cached ?? (await this.engine.refresh())
+
+		if (!this.enhancer) {
+			return result
+		}
+
+		// Wait for any in-flight background enhancement to finish
+		if (this.enhancingPromise) {
+			await this.enhancingPromise
+		}
+
+		// Serve cached enhancement only if it matches the current engine result
+		if (this.enhancedItems && this.enhancedSource === result) {
+			return { ...result, items: this.enhancedItems }
+		}
+
+		// Stale or missing — re-enhance
+		await this.runEnhancement(result)
+
+		if (this.enhancedItems) {
+			return { ...result, items: this.enhancedItems }
+		}
+
+		return result
+	}
+
 	getSource<T extends FeedSource>(sourceId: string): T | undefined {
 		return this.sources.get(sourceId) as T | undefined
 	}
 
 	destroy(): void {
+		this.unsubscribe?.()
+		this.unsubscribe = null
 		this.engine.stop()
 		this.sources.clear()
+		this.invalidateEnhancement()
+		this.enhancingPromise = null
+	}
+
+	private invalidateEnhancement(): void {
+		this.enhancedItems = null
+		this.enhancedSource = null
+	}
+
+	private runEnhancement(result: FeedResult): Promise<void> {
+		const promise = this.enhance(result)
+		this.enhancingPromise = promise
+		promise.finally(() => {
+			if (this.enhancingPromise === promise) {
+				this.enhancingPromise = null
+			}
+		})
+		return promise
+	}
+
+	private async enhance(result: FeedResult): Promise<void> {
+		try {
+			this.enhancedItems = await this.enhancer!(result.items)
+			this.enhancedSource = result
+		} catch (err) {
+			console.error("[enhancement] Unexpected error:", err)
+			this.invalidateEnhancement()
+		}
 	}
 }

bun.lock

@@ -18,9 +18,12 @@
       "version": "0.0.0",
       "dependencies": {
         "@aris/core": "workspace:*",
+        "@aris/source-caldav": "workspace:*",
+        "@aris/source-google-calendar": "workspace:*",
         "@aris/source-location": "workspace:*",
         "@aris/source-tfl": "workspace:*",
         "@aris/source-weatherkit": "workspace:*",
+        "@openrouter/sdk": "^0.9.11",
         "arktype": "^2.1.29",
         "better-auth": "^1",
         "hono": "^4",
@@ -543,6 +546,8 @@
 
     "@oclif/screen": ["@oclif/screen@3.0.8", "", {}, "sha512-yx6KAqlt3TAHBduS2fMQtJDL2ufIHnDRArrJEOoTTuizxqmjLT+psGYOHpmMl3gvQpFJ11Hs76guUUktzAF9Bg=="],
 
+    "@openrouter/sdk": ["@openrouter/sdk@0.9.11", "", { "dependencies": { "zod": "^3.25.0 || ^4.0.0" } }, "sha512-BgFu6NcIJO4a9aVjr04y3kZ8pyM71j15I+bzfVAGEvxnj+KQNIkBYQGgwrG3D+aT1QpDKLki8btcQmpaxUas6A=="],
+
     "@oxfmt/darwin-arm64": ["@oxfmt/darwin-arm64@0.24.0", "", { "os": "darwin", "cpu": "arm64" }, "sha512-aYXuGf/yq8nsyEcHindGhiz9I+GEqLkVq8CfPbd+6VE259CpPEH+CaGHEO1j6vIOmNr8KHRq+IAjeRO2uJpb8A=="],
 
     "@oxfmt/darwin-x64": ["@oxfmt/darwin-x64@0.24.0", "", { "os": "darwin", "cpu": "x64" }, "sha512-vs3b8Bs53hbiNvcNeBilzE/+IhDTWKjSBB3v/ztr664nZk65j0xr+5IHMBNz3CFppmX7o/aBta2PxY+t+4KoPg=="],

packages/aris-core/src/context.ts

@@ -61,10 +61,7 @@ function partsEqual(a: unknown, b: unknown): boolean {
 		const bKeys = Object.keys(b)
 		if (aKeys.length !== bKeys.length) return false
 		return aKeys.every((key) =>
-			partsEqual(
-				(a as Record<string, unknown>)[key],
-				(b as Record<string, unknown>)[key],
-			),
+			partsEqual((a as Record<string, unknown>)[key], (b as Record<string, unknown>)[key]),
 		)
 	}
 	return false