feat: add reminder source

apps/admin-dashboard/src/components/reminder-crud-panel.tsx

@@ -0,0 +1,639 @@
+import type { Dispatch, FormEvent, SetStateAction } from "react"
+
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query"
+import { Check, Loader2, Pencil, Plus, RefreshCw, RotateCcw, Save, Trash2, X } from "lucide-react"
+import { useMemo, useState } from "react"
+import { toast } from "sonner"
+
+import type { FeedItem } from "@/lib/api"
+
+import { Badge } from "@/components/ui/badge"
+import { Button } from "@/components/ui/button"
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card"
+import { Input } from "@/components/ui/input"
+import { Label } from "@/components/ui/label"
+import {
+	Select,
+	SelectContent,
+	SelectItem,
+	SelectTrigger,
+	SelectValue,
+} from "@/components/ui/select"
+import { Switch } from "@/components/ui/switch"
+import { executeSourceAction, fetchFeed } from "@/lib/api"
+
+const REMINDER_SOURCE_ID = "freya.reminders"
+
+type ReminderPriority = "low" | "normal" | "high"
+type ReminderFrequency = "daily" | "weekly" | "monthly" | "yearly"
+type ReminderEditScope = "this-occurrence" | "this-and-future" | "entire-series"
+
+interface ReminderRecurrence {
+	frequency: ReminderFrequency
+	interval: number
+	count?: number
+	until?: string
+}
+
+interface ReminderFeedData extends Record<string, unknown> {
+	reminderId: string
+	occurrenceId: string
+	title: string
+	notes: string | null
+	originalDueAt: string
+	dueAt: string
+	timeZone: string
+	recurrence: ReminderRecurrence | null
+	priority: ReminderPriority
+	completedAt: string | null
+}
+
+interface ReminderFormState {
+	title: string
+	notes: string
+	dueAt: string
+	priority: ReminderPriority
+	scope: ReminderEditScope
+	recurs: boolean
+	frequency: ReminderFrequency
+	interval: string
+	count: string
+	until: string
+}
+
+const emptyForm: ReminderFormState = {
+	title: "",
+	notes: "",
+	dueAt: toLocalInput(new Date()),
+	priority: "normal",
+	scope: "entire-series",
+	recurs: false,
+	frequency: "daily",
+	interval: "1",
+	count: "",
+	until: "",
+}
+
+export function ReminderCrudPanel() {
+	const queryClient = useQueryClient()
+	const [form, setForm] = useState<ReminderFormState>(emptyForm)
+	const [editing, setEditing] = useState<ReminderFeedData | null>(null)
+	const [deleteScopes, setDeleteScopes] = useState<Record<string, ReminderEditScope>>({})
+
+	const {
+		data: feed,
+		isFetching,
+		refetch,
+	} = useQuery({
+		queryKey: ["feed"],
+		queryFn: fetchFeed,
+	})
+
+	const reminders = useMemo(
+		() => (feed?.items ?? []).filter(isReminderItem).map((item) => item.data),
+		[feed],
+	)
+
+	const actionMutation = useMutation({
+		mutationFn: (input: { actionId: string; params: unknown }) =>
+			executeSourceAction(REMINDER_SOURCE_ID, input.actionId, input.params),
+	})
+
+	const busy = actionMutation.isPending
+	const canConfigureRecurrence = !editing || form.scope !== "this-occurrence"
+
+	async function runAction(actionId: string, params: unknown, success: string): Promise<boolean> {
+		try {
+			await actionMutation.mutateAsync({ actionId, params })
+			await queryClient.invalidateQueries({ queryKey: ["feed"] })
+			toast.success(success)
+			return true
+		} catch (err) {
+			toast.error(err instanceof Error ? err.message : String(err))
+			return false
+		}
+	}
+
+	async function handleSubmit(event: FormEvent<HTMLFormElement>) {
+		event.preventDefault()
+
+		if (editing) {
+			const patch = formToPatch(formFromReminder(editing), form)
+			if (Object.keys(patch).length === 0) {
+				toast.info("No changes to save")
+				return
+			}
+
+			const saved = await runAction(
+				"update-reminder",
+				{
+					reminderId: editing.reminderId,
+					scope: form.scope,
+					occurrenceDueAt: editing.originalDueAt,
+					patch,
+				},
+				"Reminder updated",
+			)
+			if (saved) resetForm()
+			return
+		} else {
+			const created = await runAction(
+				"create-reminder",
+				formToCreatePayload(form),
+				"Reminder created",
+			)
+			if (created) resetForm()
+		}
+	}
+
+	function startEdit(reminder: ReminderFeedData) {
+		setEditing(reminder)
+		setForm(formFromReminder(reminder))
+	}
+
+	function resetForm() {
+		setEditing(null)
+		setForm({ ...emptyForm, dueAt: toLocalInput(new Date()) })
+	}
+
+	function getDeleteScope(reminder: ReminderFeedData): ReminderEditScope {
+		return (
+			deleteScopes[reminderKey(reminder)] ??
+			(reminder.recurrence ? "this-occurrence" : "entire-series")
+		)
+	}
+
+	function setDeleteScope(reminder: ReminderFeedData, scope: ReminderEditScope) {
+		setDeleteScopes((prev) => ({ ...prev, [reminderKey(reminder)]: scope }))
+	}
+
+	return (
+		<Card className="-mx-4">
+			<CardHeader className="pb-4">
+				<div className="flex items-center justify-between gap-3">
+					<CardTitle className="text-sm">Reminders</CardTitle>
+					<Button size="sm" variant="outline" onClick={() => refetch()} disabled={isFetching}>
+						{isFetching ? (
+							<Loader2 className="size-3.5 animate-spin" />
+						) : (
+							<RefreshCw className="size-3.5" />
+						)}
+						Refresh
+					</Button>
+				</div>
+			</CardHeader>
+			<CardContent className="space-y-5">
+				<form className="grid gap-4" onSubmit={handleSubmit}>
+					<div className="grid gap-3 sm:grid-cols-2">
+						<div className="space-y-2 sm:col-span-2">
+							<Label htmlFor="reminder-title" className="text-xs font-medium">
+								Title
+							</Label>
+							<Input
+								id="reminder-title"
+								value={form.title}
+								onChange={(event) => setFormField(setForm, "title", event.target.value)}
+								disabled={busy}
+								required
+							/>
+						</div>
+
+						<div className="space-y-2 sm:col-span-2">
+							<Label htmlFor="reminder-notes" className="text-xs font-medium">
+								Notes
+							</Label>
+							<Input
+								id="reminder-notes"
+								value={form.notes}
+								onChange={(event) => setFormField(setForm, "notes", event.target.value)}
+								disabled={busy}
+							/>
+						</div>
+
+						<div className="space-y-2">
+							<Label htmlFor="reminder-due-at" className="text-xs font-medium">
+								Due
+							</Label>
+							<Input
+								id="reminder-due-at"
+								type="datetime-local"
+								value={form.dueAt}
+								onChange={(event) => setFormField(setForm, "dueAt", event.target.value)}
+								disabled={busy}
+								required
+							/>
+						</div>
+
+						<div className="space-y-2">
+							<Label htmlFor="reminder-priority" className="text-xs font-medium">
+								Priority
+							</Label>
+							<Select
+								value={form.priority}
+								onValueChange={(value) =>
+									setFormField(setForm, "priority", value as ReminderPriority)
+								}
+								disabled={busy}
+							>
+								<SelectTrigger id="reminder-priority">
+									<SelectValue />
+								</SelectTrigger>
+								<SelectContent>
+									<SelectItem value="low">Low</SelectItem>
+									<SelectItem value="normal">Normal</SelectItem>
+									<SelectItem value="high">High</SelectItem>
+								</SelectContent>
+							</Select>
+						</div>
+
+						{editing?.recurrence && (
+							<div className="space-y-2 sm:col-span-2">
+								<Label htmlFor="reminder-edit-scope" className="text-xs font-medium">
+									Edit scope
+								</Label>
+								<Select
+									value={form.scope}
+									onValueChange={(value) =>
+										setFormField(setForm, "scope", value as ReminderEditScope)
+									}
+									disabled={busy}
+								>
+									<SelectTrigger id="reminder-edit-scope">
+										<SelectValue />
+									</SelectTrigger>
+									<SelectContent>
+										<SelectItem value="this-occurrence">This occurrence</SelectItem>
+										<SelectItem value="this-and-future">This and future</SelectItem>
+										<SelectItem value="entire-series">Entire series</SelectItem>
+									</SelectContent>
+								</Select>
+							</div>
+						)}
+					</div>
+
+					{canConfigureRecurrence && (
+						<div className="grid gap-3 rounded-md border p-3 sm:grid-cols-4">
+							<div className="flex items-center justify-between gap-3 sm:col-span-4">
+								<Label htmlFor="reminder-recurs" className="text-xs font-medium">
+									Recurring
+								</Label>
+								<Switch
+									id="reminder-recurs"
+									checked={form.recurs}
+									onCheckedChange={(checked) => setFormField(setForm, "recurs", checked)}
+									disabled={busy}
+								/>
+							</div>
+
+							{form.recurs && (
+								<>
+									<div className="space-y-2 sm:col-span-2">
+										<Label htmlFor="reminder-frequency" className="text-xs font-medium">
+											Frequency
+										</Label>
+										<Select
+											value={form.frequency}
+											onValueChange={(value) =>
+												setFormField(setForm, "frequency", value as ReminderFrequency)
+											}
+											disabled={busy}
+										>
+											<SelectTrigger id="reminder-frequency">
+												<SelectValue />
+											</SelectTrigger>
+											<SelectContent>
+												<SelectItem value="daily">Daily</SelectItem>
+												<SelectItem value="weekly">Weekly</SelectItem>
+												<SelectItem value="monthly">Monthly</SelectItem>
+												<SelectItem value="yearly">Yearly</SelectItem>
+											</SelectContent>
+										</Select>
+									</div>
+
+									<div className="space-y-2">
+										<Label htmlFor="reminder-interval" className="text-xs font-medium">
+											Interval
+										</Label>
+										<Input
+											id="reminder-interval"
+											type="number"
+											min={1}
+											value={form.interval}
+											onChange={(event) => setFormField(setForm, "interval", event.target.value)}
+											disabled={busy}
+										/>
+									</div>
+
+									<div className="space-y-2">
+										<Label htmlFor="reminder-count" className="text-xs font-medium">
+											Count
+										</Label>
+										<Input
+											id="reminder-count"
+											type="number"
+											min={1}
+											value={form.count}
+											onChange={(event) => setFormField(setForm, "count", event.target.value)}
+											disabled={busy}
+										/>
+									</div>
+
+									<div className="space-y-2 sm:col-span-4">
+										<Label htmlFor="reminder-until" className="text-xs font-medium">
+											Until
+										</Label>
+										<Input
+											id="reminder-until"
+											type="datetime-local"
+											value={form.until}
+											onChange={(event) => setFormField(setForm, "until", event.target.value)}
+											disabled={busy}
+										/>
+									</div>
+								</>
+							)}
+						</div>
+					)}
+
+					<div className="flex justify-end gap-2">
+						{editing && (
+							<Button type="button" variant="outline" onClick={resetForm} disabled={busy}>
+								<X className="size-3.5" />
+								Cancel
+							</Button>
+						)}
+						<Button type="submit" disabled={busy || !form.title || !form.dueAt}>
+							{busy ? <Loader2 className="size-3.5 animate-spin" /> : <Save className="size-3.5" />}
+							{editing ? "Update" : "Create"}
+						</Button>
+					</div>
+				</form>
+
+				<div className="space-y-2">
+					<div className="flex items-center justify-between text-xs text-muted-foreground">
+						<span>
+							{reminders.length} {reminders.length === 1 ? "occurrence" : "occurrences"}
+						</span>
+						{!editing && (
+							<Button size="sm" variant="ghost" onClick={resetForm} disabled={busy}>
+								<Plus className="size-3.5" />
+								New
+							</Button>
+						)}
+					</div>
+
+					{reminders.length === 0 && (
+						<div className="rounded-md border border-dashed px-3 py-6 text-center text-sm text-muted-foreground">
+							No reminders in the current feed.
+						</div>
+					)}
+
+					{reminders.map((reminder) => {
+						const deleteScope = getDeleteScope(reminder)
+						return (
+							<ReminderRow
+								key={reminderKey(reminder)}
+								reminder={reminder}
+								busy={busy}
+								deleteScope={deleteScope}
+								onDeleteScopeChange={(scope) => setDeleteScope(reminder, scope)}
+								onEdit={() => startEdit(reminder)}
+								onComplete={() =>
+									runAction(
+										reminder.completedAt ? "uncomplete-reminder" : "complete-reminder",
+										{
+											reminderId: reminder.reminderId,
+											occurrenceDueAt: reminder.originalDueAt,
+										},
+										reminder.completedAt ? "Reminder reopened" : "Reminder completed",
+									)
+								}
+								onDelete={() => {
+									if (
+										!confirm(
+											`Delete ${formatScope(deleteScope).toLowerCase()} for "${reminder.title}"?`,
+										)
+									) {
+										return
+									}
+									void runAction(
+										"delete-reminder",
+										{
+											reminderId: reminder.reminderId,
+											scope: deleteScope,
+											occurrenceDueAt: reminder.originalDueAt,
+										},
+										"Reminder deleted",
+									).then((deleted) => {
+										if (deleted && editing?.reminderId === reminder.reminderId) resetForm()
+									})
+								}}
+							/>
+						)
+					})}
+				</div>
+			</CardContent>
+		</Card>
+	)
+}
+
+function ReminderRow({
+	reminder,
+	busy,
+	deleteScope,
+	onDeleteScopeChange,
+	onEdit,
+	onComplete,
+	onDelete,
+}: {
+	reminder: ReminderFeedData
+	busy: boolean
+	deleteScope: ReminderEditScope
+	onDeleteScopeChange: (scope: ReminderEditScope) => void
+	onEdit: () => void
+	onComplete: () => void
+	onDelete: () => void
+}) {
+	return (
+		<div className="flex items-start justify-between gap-3 rounded-md border px-3 py-2">
+			<div className="min-w-0 space-y-1">
+				<div className="flex flex-wrap items-center gap-2">
+					<span className="truncate text-sm font-medium">{reminder.title}</span>
+					<Badge variant={reminder.completedAt ? "secondary" : "outline"} className="text-xs">
+						{reminder.completedAt ? "Done" : reminder.priority}
+					</Badge>
+					{reminder.recurrence && (
+						<Badge variant="secondary" className="text-xs">
+							{formatRecurrence(reminder.recurrence)}
+						</Badge>
+					)}
+				</div>
+				<div className="text-xs text-muted-foreground">{formatDate(reminder.dueAt)}</div>
+				{reminder.notes && <div className="text-xs text-muted-foreground">{reminder.notes}</div>}
+			</div>
+			<div className="flex shrink-0 flex-wrap items-center justify-end gap-1">
+				{reminder.recurrence && (
+					<Select
+						value={deleteScope}
+						onValueChange={(value) => onDeleteScopeChange(value as ReminderEditScope)}
+						disabled={busy}
+					>
+						<SelectTrigger className="h-8 w-[86px] text-xs">
+							<SelectValue />
+						</SelectTrigger>
+						<SelectContent>
+							<SelectItem value="this-occurrence">This</SelectItem>
+							<SelectItem value="this-and-future">Future</SelectItem>
+							<SelectItem value="entire-series">All</SelectItem>
+						</SelectContent>
+					</Select>
+				)}
+				<Button size="sm" variant="ghost" onClick={onComplete} disabled={busy}>
+					{reminder.completedAt ? (
+						<RotateCcw className="size-3.5" />
+					) : (
+						<Check className="size-3.5" />
+					)}
+				</Button>
+				<Button size="sm" variant="ghost" onClick={onEdit} disabled={busy}>
+					<Pencil className="size-3.5" />
+				</Button>
+				<Button size="sm" variant="ghost" onClick={onDelete} disabled={busy}>
+					<Trash2 className="size-3.5 text-destructive" />
+				</Button>
+			</div>
+		</div>
+	)
+}
+
+function formToCreatePayload(form: ReminderFormState): Record<string, unknown> {
+	return {
+		title: form.title.trim(),
+		notes: form.notes.trim() || null,
+		dueAt: toIsoString(form.dueAt),
+		timeZone: localTimeZone(),
+		priority: form.priority,
+		recurrence: recurrenceValueFromForm(form),
+	}
+}
+
+function formToPatch(initial: ReminderFormState, form: ReminderFormState): Record<string, unknown> {
+	const patch: Record<string, unknown> = {}
+	const title = form.title.trim()
+	const notes = form.notes.trim() || null
+	const initialNotes = initial.notes.trim() || null
+
+	if (title !== initial.title.trim()) patch.title = title
+	if (notes !== initialNotes) patch.notes = notes
+	if (form.dueAt !== initial.dueAt) {
+		patch.dueAt = toIsoString(form.dueAt)
+		patch.timeZone = localTimeZone()
+	}
+	if (form.priority !== initial.priority) patch.priority = form.priority
+	if (form.scope !== "this-occurrence" && recurrenceChanged(initial, form)) {
+		patch.recurrence = recurrenceValueFromForm(form)
+	}
+
+	return patch
+}
+
+function recurrenceValueFromForm(form: ReminderFormState): ReminderRecurrence | null {
+	return form.recurs ? recurrenceFromForm(form) : null
+}
+
+function recurrenceFromForm(form: ReminderFormState): ReminderRecurrence {
+	const recurrence: ReminderRecurrence = {
+		frequency: form.frequency,
+		interval: Math.max(1, Number(form.interval) || 1),
+	}
+
+	const count = Number(form.count)
+	if (Number.isInteger(count) && count > 0) recurrence.count = count
+	if (form.until) recurrence.until = toIsoString(form.until)
+
+	return recurrence
+}
+
+function formFromReminder(reminder: ReminderFeedData): ReminderFormState {
+	return {
+		title: reminder.title,
+		notes: reminder.notes ?? "",
+		dueAt: toLocalInput(new Date(reminder.dueAt)),
+		priority: reminder.priority,
+		scope: reminder.recurrence ? "this-occurrence" : "entire-series",
+		recurs: reminder.recurrence !== null,
+		frequency: reminder.recurrence?.frequency ?? "daily",
+		interval: String(reminder.recurrence?.interval ?? 1),
+		count: reminder.recurrence?.count ? String(reminder.recurrence.count) : "",
+		until: reminder.recurrence?.until ? toLocalInput(new Date(reminder.recurrence.until)) : "",
+	}
+}
+
+function setFormField<TKey extends keyof ReminderFormState>(
+	setForm: Dispatch<SetStateAction<ReminderFormState>>,
+	key: TKey,
+	value: ReminderFormState[TKey],
+) {
+	setForm((prev) => ({ ...prev, [key]: value }))
+}
+
+function recurrenceChanged(initial: ReminderFormState, form: ReminderFormState): boolean {
+	return (
+		JSON.stringify(recurrenceValueFromForm(initial)) !==
+		JSON.stringify(recurrenceValueFromForm(form))
+	)
+}
+
+function reminderKey(reminder: ReminderFeedData): string {
+	return `${reminder.reminderId}:${reminder.occurrenceId}`
+}
+
+function isReminderItem(item: FeedItem): item is FeedItem & { data: ReminderFeedData } {
+	return (
+		item.sourceId === REMINDER_SOURCE_ID &&
+		typeof item.data.reminderId === "string" &&
+		typeof item.data.occurrenceId === "string" &&
+		typeof item.data.title === "string" &&
+		typeof item.data.originalDueAt === "string" &&
+		typeof item.data.dueAt === "string"
+	)
+}
+
+function toLocalInput(date: Date): string {
+	const offsetMs = date.getTimezoneOffset() * 60 * 1000
+	return new Date(date.getTime() - offsetMs).toISOString().slice(0, 16)
+}
+
+function toIsoString(value: string): string {
+	return new Date(value).toISOString()
+}
+
+function localTimeZone(): string {
+	return Intl.DateTimeFormat().resolvedOptions().timeZone
+}
+
+function formatDate(value: string): string {
+	return new Date(value).toLocaleString(undefined, {
+		month: "short",
+		day: "numeric",
+		hour: "numeric",
+		minute: "2-digit",
+	})
+}
+
+function formatRecurrence(recurrence: ReminderRecurrence): string {
+	return recurrence.interval === 1
+		? recurrence.frequency
+		: `${recurrence.frequency} / ${recurrence.interval}`
+}
+
+function formatScope(scope: ReminderEditScope): string {
+	switch (scope) {
+		case "this-occurrence":
+			return "this occurrence"
+		case "this-and-future":
+			return "this and future"
+		case "entire-series":
+			return "entire series"
+	}
+}

apps/admin-dashboard/src/components/source-config-panel.tsx

@@ -5,6 +5,7 @@ import { toast } from "sonner"
 
 import type { ConfigFieldDef, SourceDefinition } from "@/lib/api"
 
+import { ReminderCrudPanel } from "@/components/reminder-crud-panel"
 import { Badge } from "@/components/ui/badge"
 import { Button } from "@/components/ui/button"
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card"
@@ -66,6 +67,20 @@ export function SourceConfigPanel({ source, onUpdate }: SourceConfigPanelProps)
 		return creds
 	}
 
+	function hasUserConfigFields(): boolean {
+		return Object.values(source.fields).some((field) => !isCredentialField(field))
+	}
+
+	function buildReplaceBody(enabledValue: boolean): Parameters<typeof replaceSource>[1] {
+		const body: Parameters<typeof replaceSource>[1] = { enabled: enabledValue }
+
+		if (hasUserConfigFields()) {
+			body.config = getUserConfig()
+		}
+
+		return body
+	}
+
 	function invalidate() {
 		queryClient.invalidateQueries({ queryKey: ["sourceConfig", source.id] })
 		queryClient.invalidateQueries({ queryKey: ["configs"] })
@@ -79,10 +94,7 @@ export function SourceConfigPanel({ source, onUpdate }: SourceConfigPanelProps)
 				(v) => typeof v === "string" && v.length > 0,
 			)
 
-			const body: Parameters<typeof replaceSource>[1] = {
-				enabled,
-				config: getUserConfig(),
-			}
+			const body = buildReplaceBody(enabled)
 			if (hasCredentials && source.perUserCredentials) {
 				body.credentials = credentialFields
 			}
@@ -104,8 +116,7 @@ export function SourceConfigPanel({ source, onUpdate }: SourceConfigPanelProps)
 	})
 
 	const toggleMutation = useMutation({
-		mutationFn: (checked: boolean) =>
-			replaceSource(source.id, { enabled: checked, config: getUserConfig() }),
+		mutationFn: (checked: boolean) => replaceSource(source.id, buildReplaceBody(checked)),
 		onSuccess(_data, checked) {
 			invalidate()
 			toast.success(`Source ${checked ? "enabled" : "disabled"}`)
@@ -116,7 +127,7 @@ export function SourceConfigPanel({ source, onUpdate }: SourceConfigPanelProps)
 	})
 
 	const deleteMutation = useMutation({
-		mutationFn: () => replaceSource(source.id, { enabled: false, config: {} }),
+		mutationFn: () => replaceSource(source.id, buildReplaceBody(false)),
 		onSuccess() {
 			setDirty({})
 			invalidate()
@@ -257,6 +268,8 @@ export function SourceConfigPanel({ source, onUpdate }: SourceConfigPanelProps)
 			)}
 
 			{source.id === "freya.location" && <LocationCard />}
+
+			{source.id === "freya.reminders" && enabled && <ReminderCrudPanel />}
 		</div>
 	)
 }
@@ -467,6 +480,17 @@ function FieldInput({
 		)
 	}
 
+	if (field.type === "boolean") {
+		return (
+			<div className="flex items-center justify-between gap-3 rounded-md border px-3 py-2">
+				<Label htmlFor={name} className="text-xs font-medium">
+					{labelContent}
+				</Label>
+				<Switch id={name} checked={value === true} onCheckedChange={onChange} disabled={disabled} />
+			</div>
+		)
+	}
+
 	return (
 		<div className="space-y-2">
 			<Label htmlFor={name} className="text-xs font-medium">
@@ -494,6 +518,8 @@ function buildInitialValues(
 			values[name] = saved[name]
 		} else if (field.defaultValue !== undefined) {
 			values[name] = field.defaultValue
+		} else if (field.type === "boolean") {
+			values[name] = false
 		} else if (field.type === "multiselect") {
 			values[name] = []
 		} else {

apps/admin-dashboard/src/lib/api.ts

@@ -9,12 +9,12 @@ function serverBase() {
 }
 
 export interface ConfigFieldDef {
-	type: "string" | "number" | "select" | "multiselect"
+	type: "string" | "number" | "select" | "multiselect" | "boolean"
 	label: string
 	required?: boolean
 	description?: string
 	secret?: boolean
-	defaultValue?: string | number | string[]
+	defaultValue?: string | number | string[] | boolean
 	options?: { label: string; value: string }[]
 }
 
@@ -151,6 +151,49 @@ const sourceDefinitions: SourceDefinition[] = [
 			},
 		},
 	},
+	{
+		id: "freya.reminders",
+		name: "Reminders",
+		description: "One-off and recurring reminders in the contextual feed.",
+		fields: {
+			lookAheadMs: {
+				type: "number",
+				label: "Look-ahead Milliseconds",
+				defaultValue: 24 * 60 * 60 * 1000,
+				description: "How far into the future reminders should appear in the feed.",
+			},
+			lookBackMs: {
+				type: "number",
+				label: "Look-back Milliseconds",
+				defaultValue: 24 * 60 * 60 * 1000,
+				description: "How far into the past due reminders should remain visible.",
+			},
+			includeCompleted: {
+				type: "boolean",
+				label: "Include Completed",
+				defaultValue: false,
+				description: "Show completed reminder occurrences in the feed.",
+			},
+			defaultTimeZone: {
+				type: "string",
+				label: "Default Timezone",
+				defaultValue: "UTC",
+				description: "IANA timezone used when new reminders omit a timezone.",
+			},
+		},
+	},
+	{
+		id: "freya.web-search",
+		name: "Web Search",
+		description: "Exa web search action. Requires EXA_API_KEY on the backend.",
+		fields: {},
+	},
+	{
+		id: "freya.google-maps",
+		name: "Google Maps",
+		description: "Google Maps Grounding Lite MCP tools for places, weather, routes, and Place IDs.",
+		fields: {},
+	},
 ]
 
 export function fetchSources(): Promise<SourceDefinition[]> {
@@ -174,7 +217,7 @@ export async function fetchConfigs(): Promise<SourceConfig[]> {
 
 export async function replaceSource(
 	sourceId: string,
-	body: { enabled: boolean; config: unknown; credentials?: Record<string, unknown> },
+	body: { enabled: boolean; config?: unknown; credentials?: Record<string, unknown> },
 ): Promise<void> {
 	const res = await fetch(`${serverBase()}/sources/${sourceId}`, {
 		method: "PUT",
@@ -220,6 +263,25 @@ export async function updateSourceCredentials(
 	}
 }
 
+export async function executeSourceAction(
+	sourceId: string,
+	actionId: string,
+	params: unknown,
+): Promise<unknown> {
+	const res = await fetch(`${serverBase()}/sources/${sourceId}/actions/${actionId}`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		credentials: "include",
+		body: JSON.stringify(params),
+	})
+	if (!res.ok) {
+		const data = (await res.json()) as { error?: string }
+		throw new Error(data.error ?? `Failed to execute source action: ${res.status}`)
+	}
+	const data = (await res.json()) as { result: unknown }
+	return data.result
+}
+
 export interface LocationInput {
 	lat: number
 	lng: number

apps/admin-dashboard/src/routes/_dashboard.tsx

@@ -8,6 +8,7 @@ import {
 	Link,
 } from "@tanstack/react-router"
 import {
+	Bell,
 	Calendar,
 	CalendarDays,
 	CircleDot,
@@ -15,6 +16,7 @@ import {
 	Loader2,
 	TrainFront,
 	LogOut,
+	Map as MapIcon,
 	MapPin,
 	Rss,
 	Server,
@@ -49,6 +51,8 @@ const SOURCE_ICONS: Record<string, React.ComponentType<{ className?: string }>>
 	"freya.weather": CloudSun,
 	"freya.caldav": CalendarDays,
 	"freya.google-calendar": Calendar,
+	"freya.google-maps": MapIcon,
+	"freya.reminders": Bell,
 	"freya.tfl": TrainFront,
 }
 

apps/freya-backend/drizzle/0000_wakeful_scorpion.sql

@@ -49,6 +49,33 @@ CREATE TABLE "user_sources" (
 	CONSTRAINT "user_sources_user_id_source_id_unique" UNIQUE("user_id","source_id")
 );
 --> statement-breakpoint
+CREATE TABLE "reminders" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"user_id" text NOT NULL,
+	"title" text NOT NULL,
+	"notes" text,
+	"due_at" timestamp NOT NULL,
+	"time_zone" text DEFAULT 'UTC' NOT NULL,
+	"recurrence" jsonb,
+	"priority" text DEFAULT 'normal' NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "reminder_occurrence_overrides" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"user_id" text NOT NULL,
+	"reminder_id" uuid NOT NULL,
+	"occurrence_id" text NOT NULL,
+	"original_due_at" timestamp NOT NULL,
+	"patch" jsonb,
+	"completed_at" timestamp,
+	"deleted_at" timestamp,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL,
+	CONSTRAINT "reminder_occurrence_overrides_reminder_id_occurrence_id_unique" UNIQUE("reminder_id","occurrence_id")
+);
+--> statement-breakpoint
 CREATE TABLE "verification" (
 	"id" text PRIMARY KEY NOT NULL,
 	"identifier" text NOT NULL,
@@ -61,6 +88,13 @@ CREATE TABLE "verification" (
 ALTER TABLE "account" ADD CONSTRAINT "account_user_id_user_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."user"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
 ALTER TABLE "session" ADD CONSTRAINT "session_user_id_user_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."user"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
 ALTER TABLE "user_sources" ADD CONSTRAINT "user_sources_user_id_user_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."user"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "reminders" ADD CONSTRAINT "reminders_user_id_user_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."user"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "reminder_occurrence_overrides" ADD CONSTRAINT "reminder_occurrence_overrides_user_id_user_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."user"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "reminder_occurrence_overrides" ADD CONSTRAINT "reminder_occurrence_overrides_reminder_id_reminders_id_fk" FOREIGN KEY ("reminder_id") REFERENCES "public"."reminders"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
 CREATE INDEX "account_userId_idx" ON "account" USING btree ("user_id");--> statement-breakpoint
 CREATE INDEX "session_userId_idx" ON "session" USING btree ("user_id");--> statement-breakpoint
-CREATE INDEX "verification_identifier_idx" ON "verification" USING btree ("identifier");
+CREATE INDEX "reminders_user_id_due_at_idx" ON "reminders" USING btree ("user_id","due_at");--> statement-breakpoint
+CREATE INDEX "reminders_user_id_updated_at_idx" ON "reminders" USING btree ("user_id","updated_at");--> statement-breakpoint
+CREATE INDEX "reminder_occurrence_overrides_user_id_reminder_id_idx" ON "reminder_occurrence_overrides" USING btree ("user_id","reminder_id");--> statement-breakpoint
+CREATE INDEX "reminder_occurrence_overrides_user_id_original_due_at_idx" ON "reminder_occurrence_overrides" USING btree ("user_id","original_due_at");--> statement-breakpoint
+CREATE INDEX "verification_identifier_idx" ON "verification" USING btree ("identifier");

apps/freya-backend/drizzle/meta/0000_snapshot.json

@@ -441,6 +441,296 @@
       "policies": {},
       "checkConstraints": {},
       "isRLSEnabled": false
+    },
+    "public.reminders": {
+      "name": "reminders",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "title": {
+          "name": "title",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "notes": {
+          "name": "notes",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "due_at": {
+          "name": "due_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "time_zone": {
+          "name": "time_zone",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'UTC'"
+        },
+        "recurrence": {
+          "name": "recurrence",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "priority": {
+          "name": "priority",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'normal'"
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "reminders_user_id_due_at_idx": {
+          "name": "reminders_user_id_due_at_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "due_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "reminders_user_id_updated_at_idx": {
+          "name": "reminders_user_id_updated_at_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "updated_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "reminders_user_id_user_id_fk": {
+          "name": "reminders_user_id_user_id_fk",
+          "tableFrom": "reminders",
+          "tableTo": "user",
+          "columnsFrom": [
+            "user_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.reminder_occurrence_overrides": {
+      "name": "reminder_occurrence_overrides",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "reminder_id": {
+          "name": "reminder_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "occurrence_id": {
+          "name": "occurrence_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "original_due_at": {
+          "name": "original_due_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "patch": {
+          "name": "patch",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "completed_at": {
+          "name": "completed_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "deleted_at": {
+          "name": "deleted_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "reminder_occurrence_overrides_user_id_reminder_id_idx": {
+          "name": "reminder_occurrence_overrides_user_id_reminder_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "reminder_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "reminder_occurrence_overrides_user_id_original_due_at_idx": {
+          "name": "reminder_occurrence_overrides_user_id_original_due_at_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "original_due_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "reminder_occurrence_overrides_user_id_user_id_fk": {
+          "name": "reminder_occurrence_overrides_user_id_user_id_fk",
+          "tableFrom": "reminder_occurrence_overrides",
+          "tableTo": "user",
+          "columnsFrom": [
+            "user_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "reminder_occurrence_overrides_reminder_id_reminders_id_fk": {
+          "name": "reminder_occurrence_overrides_reminder_id_reminders_id_fk",
+          "tableFrom": "reminder_occurrence_overrides",
+          "tableTo": "reminders",
+          "columnsFrom": [
+            "reminder_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "reminder_occurrence_overrides_reminder_id_occurrence_id_unique": {
+          "name": "reminder_occurrence_overrides_reminder_id_occurrence_id_unique",
+          "nullsNotDistinct": false,
+          "columns": [
+            "reminder_id",
+            "occurrence_id"
+          ]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
     }
   },
   "enums": {},
@@ -454,4 +744,4 @@
     "schemas": {},
     "tables": {}
   }
-}
+}

apps/freya-backend/drizzle/meta/0001_snapshot.json

@@ -463,6 +463,296 @@
       "policies": {},
       "checkConstraints": {},
       "isRLSEnabled": false
+    },
+    "public.reminders": {
+      "name": "reminders",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "title": {
+          "name": "title",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "notes": {
+          "name": "notes",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "due_at": {
+          "name": "due_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "time_zone": {
+          "name": "time_zone",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'UTC'"
+        },
+        "recurrence": {
+          "name": "recurrence",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "priority": {
+          "name": "priority",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'normal'"
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "reminders_user_id_due_at_idx": {
+          "name": "reminders_user_id_due_at_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "due_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "reminders_user_id_updated_at_idx": {
+          "name": "reminders_user_id_updated_at_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "updated_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "reminders_user_id_user_id_fk": {
+          "name": "reminders_user_id_user_id_fk",
+          "tableFrom": "reminders",
+          "tableTo": "user",
+          "columnsFrom": [
+            "user_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.reminder_occurrence_overrides": {
+      "name": "reminder_occurrence_overrides",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "reminder_id": {
+          "name": "reminder_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "occurrence_id": {
+          "name": "occurrence_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "original_due_at": {
+          "name": "original_due_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "patch": {
+          "name": "patch",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "completed_at": {
+          "name": "completed_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "deleted_at": {
+          "name": "deleted_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "reminder_occurrence_overrides_user_id_reminder_id_idx": {
+          "name": "reminder_occurrence_overrides_user_id_reminder_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "reminder_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "reminder_occurrence_overrides_user_id_original_due_at_idx": {
+          "name": "reminder_occurrence_overrides_user_id_original_due_at_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "original_due_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "reminder_occurrence_overrides_user_id_user_id_fk": {
+          "name": "reminder_occurrence_overrides_user_id_user_id_fk",
+          "tableFrom": "reminder_occurrence_overrides",
+          "tableTo": "user",
+          "columnsFrom": [
+            "user_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "reminder_occurrence_overrides_reminder_id_reminders_id_fk": {
+          "name": "reminder_occurrence_overrides_reminder_id_reminders_id_fk",
+          "tableFrom": "reminder_occurrence_overrides",
+          "tableTo": "reminders",
+          "columnsFrom": [
+            "reminder_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "reminder_occurrence_overrides_reminder_id_occurrence_id_unique": {
+          "name": "reminder_occurrence_overrides_reminder_id_occurrence_id_unique",
+          "nullsNotDistinct": false,
+          "columns": [
+            "reminder_id",
+            "occurrence_id"
+          ]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
     }
   },
   "enums": {},
@@ -476,4 +766,4 @@
     "schemas": {},
     "tables": {}
   }
-}
+}

apps/freya-backend/drizzle/meta/_journal.json

@@ -17,4 +17,4 @@
       "breakpoints": true
     }
   ]
-}
+}

apps/freya-backend/package.json

@@ -18,9 +18,12 @@
 		"@freya/core": "workspace:*",
 		"@freya/source-caldav": "workspace:*",
 		"@freya/source-google-calendar": "workspace:*",
+		"@freya/source-google-maps": "workspace:*",
 		"@freya/source-location": "workspace:*",
+		"@freya/source-reminders": "workspace:*",
 		"@freya/source-tfl": "workspace:*",
 		"@freya/source-weatherkit": "workspace:*",
+		"@freya/source-web-search": "workspace:*",
 		"@openrouter/sdk": "^0.9.11",
 		"arktype": "^2.1.29",
 		"better-auth": "^1",

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

@@ -60,3 +60,66 @@ export const userSources = pgTable(
 		index("user_sources_user_id_enabled_idx").on(t.userId, t.enabled),
 	],
 )
+
+// ---------------------------------------------------------------------------
+// FREYA — reminders source storage
+// ---------------------------------------------------------------------------
+
+export const reminders = pgTable(
+	"reminders",
+	{
+		id: uuid("id").primaryKey().defaultRandom(),
+		userId: text("user_id")
+			.notNull()
+			.references(() => user.id, { onDelete: "cascade" }),
+		title: text("title").notNull(),
+		notes: text("notes"),
+		dueAt: timestamp("due_at").notNull(),
+		timeZone: text("time_zone").notNull().default("UTC"),
+		recurrence: jsonb("recurrence"),
+		priority: text("priority").notNull().default("normal"),
+		createdAt: timestamp("created_at").notNull().defaultNow(),
+		updatedAt: timestamp("updated_at")
+			.notNull()
+			.defaultNow()
+			.$onUpdate(() => new Date()),
+	},
+	(t) => [
+		index("reminders_user_id_due_at_idx").on(t.userId, t.dueAt),
+		index("reminders_user_id_updated_at_idx").on(t.userId, t.updatedAt),
+	],
+)
+
+export const reminderOccurrenceOverrides = pgTable(
+	"reminder_occurrence_overrides",
+	{
+		id: uuid("id").primaryKey().defaultRandom(),
+		userId: text("user_id")
+			.notNull()
+			.references(() => user.id, { onDelete: "cascade" }),
+		reminderId: uuid("reminder_id")
+			.notNull()
+			.references(() => reminders.id, { onDelete: "cascade" }),
+		occurrenceId: text("occurrence_id").notNull(),
+		originalDueAt: timestamp("original_due_at").notNull(),
+		patch: jsonb("patch"),
+		completedAt: timestamp("completed_at"),
+		deletedAt: timestamp("deleted_at"),
+		createdAt: timestamp("created_at").notNull().defaultNow(),
+		updatedAt: timestamp("updated_at")
+			.notNull()
+			.defaultNow()
+			.$onUpdate(() => new Date()),
+	},
+	(t) => [
+		unique("reminder_occurrence_overrides_reminder_id_occurrence_id_unique").on(
+			t.reminderId,
+			t.occurrenceId,
+		),
+		index("reminder_occurrence_overrides_user_id_reminder_id_idx").on(t.userId, t.reminderId),
+		index("reminder_occurrence_overrides_user_id_original_due_at_idx").on(
+			t.userId,
+			t.originalDueAt,
+		),
+	],
+)

apps/freya-backend/src/google-maps/provider.test.ts

@@ -0,0 +1,55 @@
+import type { GoogleMapsSourceOptions } from "@freya/source-google-maps"
+
+import { describe, expect, test } from "bun:test"
+
+import { GoogleMapsSourceProvider } from "./provider.ts"
+
+type McpClient = NonNullable<GoogleMapsSourceOptions["client"]>
+
+class MockMcpClient implements McpClient {
+	async listTools(): ReturnType<McpClient["listTools"]> {
+		return { tools: [] }
+	}
+
+	async readResource(
+		_params: Parameters<McpClient["readResource"]>[0],
+	): ReturnType<McpClient["readResource"]> {
+		throw new Error("unexpected resource read")
+	}
+
+	async callTool(_params: Parameters<McpClient["callTool"]>[0]): ReturnType<McpClient["callTool"]> {
+		return { structuredContent: {} }
+	}
+}
+
+describe("GoogleMapsSourceProvider", () => {
+	test("sourceId is freya.google-maps", () => {
+		const provider = new GoogleMapsSourceProvider({ apiKey: "key" })
+		expect(provider.sourceId).toBe("freya.google-maps")
+	})
+
+	test("throws when service API key is empty", () => {
+		expect(() => new GoogleMapsSourceProvider({ apiKey: "" })).toThrow(
+			"Google Maps MCP API key must be configured",
+		)
+	})
+
+	test("returns source with service API key", async () => {
+		const provider = new GoogleMapsSourceProvider({ apiKey: "key" })
+
+		const source = await provider.feedSourceForUser("user-1", {}, null)
+
+		expect(source.id).toBe("freya.google-maps")
+	})
+
+	test("allows injected test client with service API key", async () => {
+		const provider = new GoogleMapsSourceProvider({
+			apiKey: "key",
+			client: new MockMcpClient(),
+		})
+
+		const source = await provider.feedSourceForUser("user-1", {}, null)
+
+		expect(source.id).toBe("freya.google-maps")
+	})
+})

apps/freya-backend/src/google-maps/provider.ts

@@ -0,0 +1,39 @@
+import { GoogleMapsSource, type GoogleMapsSourceOptions } from "@freya/source-google-maps"
+
+import type { FeedSourceProvider } from "../session/feed-source-provider.ts"
+
+export interface GoogleMapsSourceProviderOptions {
+	readonly apiKey: string
+	readonly client?: GoogleMapsSourceOptions["client"]
+}
+
+export class GoogleMapsSourceProvider implements FeedSourceProvider {
+	readonly sourceId = "freya.google-maps"
+
+	private readonly apiKey: string
+	private readonly client: GoogleMapsSourceProviderOptions["client"]
+
+	constructor(options: GoogleMapsSourceProviderOptions) {
+		if (!nonEmptyString(options.apiKey)) {
+			throw new Error("Google Maps MCP API key must be configured")
+		}
+
+		this.apiKey = options.apiKey
+		this.client = options.client
+	}
+
+	async feedSourceForUser(
+		_userId: string,
+		_config: unknown,
+		_credentials: unknown,
+	): Promise<GoogleMapsSource> {
+		return new GoogleMapsSource({
+			apiKey: this.apiKey,
+			client: this.client,
+		})
+	}
+}
+
+function nonEmptyString(value: string): boolean {
+	return typeof value === "string" && value.trim().length > 0
+}

apps/freya-backend/src/reminders/provider.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, test } from "bun:test"
+
+import type { Database } from "../db/index.ts"
+
+import { ReminderSourceProvider } from "./provider.ts"
+
+const fakeDb = {} as Database
+
+describe("ReminderSourceProvider", () => {
+	const provider = new ReminderSourceProvider({ db: fakeDb })
+
+	test("sourceId is freya.reminders", () => {
+		expect(provider.sourceId).toBe("freya.reminders")
+	})
+
+	test("throws when config has extra keys", async () => {
+		await expect(
+			provider.feedSourceForUser("user-1", { lookAheadMs: 1000, extra: true }, null),
+		).rejects.toThrow("Invalid reminders config")
+	})
+
+	test("throws when defaultTimeZone is invalid", async () => {
+		await expect(
+			provider.feedSourceForUser("user-1", { defaultTimeZone: "Not/AZone" }, null),
+		).rejects.toThrow("Invalid reminders config")
+	})
+
+	test("returns ReminderSource with valid config", async () => {
+		const source = await provider.feedSourceForUser(
+			"user-1",
+			{
+				lookAheadMs: 48 * 60 * 60 * 1000,
+				lookBackMs: 60 * 60 * 1000,
+				includeCompleted: true,
+				defaultTimeZone: "Europe/London",
+			},
+			null,
+		)
+
+		expect(source).toBeDefined()
+		expect(source.id).toBe("freya.reminders")
+	})
+
+	test("returns ReminderSource with empty config", async () => {
+		const source = await provider.feedSourceForUser("user-1", {}, null)
+
+		expect(source).toBeDefined()
+		expect(source.id).toBe("freya.reminders")
+	})
+})

apps/freya-backend/src/reminders/provider.ts

@@ -0,0 +1,48 @@
+import { ReminderSource, ReminderTimeZoneInput } from "@freya/source-reminders"
+import { type } from "arktype"
+
+import type { Database } from "../db/index.ts"
+import type { FeedSourceProvider } from "../session/feed-source-provider.ts"
+
+import { DrizzleReminderStorage } from "./storage.ts"
+
+export interface ReminderSourceProviderOptions {
+	db: Database
+}
+
+export const reminderConfig = type({
+	"+": "reject",
+	"lookAheadMs?": "number.integer >= 0",
+	"lookBackMs?": "number.integer >= 0",
+	"includeCompleted?": "boolean",
+	"defaultTimeZone?": ReminderTimeZoneInput,
+})
+
+export class ReminderSourceProvider implements FeedSourceProvider {
+	readonly sourceId = "freya.reminders"
+	readonly configSchema = reminderConfig
+	private readonly db: Database
+
+	constructor(options: ReminderSourceProviderOptions) {
+		this.db = options.db
+	}
+
+	async feedSourceForUser(
+		userId: string,
+		config: unknown,
+		_credentials: unknown,
+	): Promise<ReminderSource> {
+		const parsed = reminderConfig(config)
+		if (parsed instanceof type.errors) {
+			throw new Error(`Invalid reminders config: ${parsed.summary}`)
+		}
+
+		return new ReminderSource({
+			storage: new DrizzleReminderStorage(this.db, userId),
+			lookAheadMs: parsed.lookAheadMs,
+			lookBackMs: parsed.lookBackMs,
+			includeCompleted: parsed.includeCompleted,
+			defaultTimeZone: parsed.defaultTimeZone,
+		})
+	}
+}

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

@@ -0,0 +1,276 @@
+import type {
+	CreateReminderInput,
+	Reminder,
+	ReminderListParams,
+	ReminderOccurrenceOverride,
+	ReminderOccurrenceOverrideInput,
+	ReminderOccurrenceOverrideListParams,
+	ReminderOccurrencePatch,
+	ReminderPatch,
+	ReminderPriority,
+	ReminderRecurrence,
+	ReminderStorage,
+} from "@freya/source-reminders"
+
+import {
+	ReminderOccurrencePatchInput,
+	ReminderPriority as ReminderPriorityValue,
+	ReminderPriorityInput,
+	ReminderRecurrenceInput,
+} from "@freya/source-reminders"
+import { type } from "arktype"
+import { and, eq, inArray } from "drizzle-orm"
+
+import type { Database } from "../db/index.ts"
+
+import { reminderOccurrenceOverrides, reminders } from "../db/schema.ts"
+
+interface ArkSchema<T> {
+	(value: unknown): T | InstanceType<typeof type.errors>
+}
+
+type ReminderRow = typeof reminders.$inferSelect
+type ReminderInsert = typeof reminders.$inferInsert
+type ReminderOccurrenceOverrideRow = typeof reminderOccurrenceOverrides.$inferSelect
+type ReminderOccurrenceOverrideInsert = typeof reminderOccurrenceOverrides.$inferInsert
+
+export class DrizzleReminderStorage implements ReminderStorage {
+	private readonly db: Database
+	private readonly userId: string
+
+	constructor(db: Database, userId: string) {
+		this.db = db
+		this.userId = userId
+	}
+
+	async listReminders(_params: ReminderListParams): Promise<Reminder[]> {
+		const rows = await this.db.select().from(reminders).where(eq(reminders.userId, this.userId))
+
+		return rows.map(rowToReminder)
+	}
+
+	async getReminder(id: string): Promise<Reminder | null> {
+		const rows = await this.db
+			.select()
+			.from(reminders)
+			.where(and(eq(reminders.userId, this.userId), eq(reminders.id, id)))
+			.limit(1)
+
+		return rows[0] ? rowToReminder(rows[0]) : null
+	}
+
+	async createReminder(input: CreateReminderInput): Promise<Reminder> {
+		const rows = await this.db
+			.insert(reminders)
+			.values({
+				userId: this.userId,
+				title: input.title,
+				notes: input.notes ?? null,
+				dueAt: input.dueAt,
+				timeZone: input.timeZone ?? "UTC",
+				recurrence: serializeRecurrence(input.recurrence ?? null),
+				priority: input.priority ?? ReminderPriorityValue.Normal,
+			})
+			.returning()
+
+		return rowToReminder(requireRow(rows))
+	}
+
+	async updateReminder(id: string, patch: ReminderPatch): Promise<Reminder> {
+		const update: Partial<ReminderInsert> = { updatedAt: new Date() }
+
+		if (hasOwn(patch, "title")) update.title = patch.title
+		if (hasOwn(patch, "notes")) update.notes = patch.notes ?? null
+		if (hasOwn(patch, "dueAt")) update.dueAt = patch.dueAt
+		if (hasOwn(patch, "timeZone")) update.timeZone = patch.timeZone
+		if (hasOwn(patch, "recurrence")) update.recurrence = serializeRecurrence(patch.recurrence)
+		if (hasOwn(patch, "priority")) update.priority = patch.priority
+
+		const rows = await this.db
+			.update(reminders)
+			.set(update)
+			.where(and(eq(reminders.userId, this.userId), eq(reminders.id, id)))
+			.returning()
+
+		return rowToReminder(requireRow(rows, `Reminder not found: ${id}`))
+	}
+
+	async deleteReminder(id: string): Promise<void> {
+		await this.db
+			.delete(reminders)
+			.where(and(eq(reminders.userId, this.userId), eq(reminders.id, id)))
+	}
+
+	async listOccurrenceOverrides(
+		params: ReminderOccurrenceOverrideListParams,
+	): Promise<ReminderOccurrenceOverride[]> {
+		if (params.reminderIds.length === 0) return []
+
+		const rows = await this.db
+			.select()
+			.from(reminderOccurrenceOverrides)
+			.where(
+				and(
+					eq(reminderOccurrenceOverrides.userId, this.userId),
+					inArray(reminderOccurrenceOverrides.reminderId, [...params.reminderIds]),
+				),
+			)
+
+		return rows.map(rowToOccurrenceOverride)
+	}
+
+	async getOccurrenceOverride(
+		reminderId: string,
+		occurrenceId: string,
+	): Promise<ReminderOccurrenceOverride | null> {
+		const rows = await this.db
+			.select()
+			.from(reminderOccurrenceOverrides)
+			.where(
+				and(
+					eq(reminderOccurrenceOverrides.userId, this.userId),
+					eq(reminderOccurrenceOverrides.reminderId, reminderId),
+					eq(reminderOccurrenceOverrides.occurrenceId, occurrenceId),
+				),
+			)
+			.limit(1)
+
+		return rows[0] ? rowToOccurrenceOverride(rows[0]) : null
+	}
+
+	async upsertOccurrenceOverride(
+		input: ReminderOccurrenceOverrideInput,
+	): Promise<ReminderOccurrenceOverride> {
+		const values: ReminderOccurrenceOverrideInsert = {
+			userId: this.userId,
+			reminderId: input.reminderId,
+			occurrenceId: input.occurrenceId,
+			originalDueAt: input.originalDueAt,
+			patch: serializeOccurrencePatch(input.patch),
+			completedAt: input.completedAt ?? null,
+			deletedAt: input.deletedAt ?? null,
+		}
+
+		const rows = await this.db
+			.insert(reminderOccurrenceOverrides)
+			.values(values)
+			.onConflictDoUpdate({
+				target: [reminderOccurrenceOverrides.reminderId, reminderOccurrenceOverrides.occurrenceId],
+				set: {
+					originalDueAt: values.originalDueAt,
+					patch: values.patch,
+					completedAt: values.completedAt,
+					deletedAt: values.deletedAt,
+					updatedAt: new Date(),
+				},
+			})
+			.returning()
+
+		return rowToOccurrenceOverride(requireRow(rows))
+	}
+
+	async deleteOccurrenceOverride(reminderId: string, occurrenceId: string): Promise<void> {
+		await this.db
+			.delete(reminderOccurrenceOverrides)
+			.where(
+				and(
+					eq(reminderOccurrenceOverrides.userId, this.userId),
+					eq(reminderOccurrenceOverrides.reminderId, reminderId),
+					eq(reminderOccurrenceOverrides.occurrenceId, occurrenceId),
+				),
+			)
+	}
+}
+
+function rowToReminder(row: ReminderRow): Reminder {
+	return {
+		id: row.id,
+		title: row.title,
+		notes: row.notes,
+		dueAt: row.dueAt,
+		timeZone: row.timeZone,
+		recurrence: parseRecurrence(row.recurrence),
+		priority: assertSchema<ReminderPriority>(ReminderPriorityInput, row.priority),
+		createdAt: row.createdAt,
+		updatedAt: row.updatedAt,
+	}
+}
+
+function rowToOccurrenceOverride(row: ReminderOccurrenceOverrideRow): ReminderOccurrenceOverride {
+	return {
+		reminderId: row.reminderId,
+		occurrenceId: row.occurrenceId,
+		originalDueAt: row.originalDueAt,
+		patch: parseOccurrencePatch(row.patch),
+		completedAt: row.completedAt,
+		deletedAt: row.deletedAt,
+		createdAt: row.createdAt,
+		updatedAt: row.updatedAt,
+	}
+}
+
+function parseRecurrence(value: unknown): ReminderRecurrence | null {
+	if (value === null || value === undefined) return null
+	return assertSchema<ReminderRecurrence>(ReminderRecurrenceInput, value)
+}
+
+function parseOccurrencePatch(value: unknown): ReminderOccurrencePatch | undefined {
+	if (value === null || value === undefined) return undefined
+	return assertSchema<ReminderOccurrencePatch>(ReminderOccurrencePatchInput, value)
+}
+
+function serializeRecurrence(recurrence: ReminderRecurrence | null | undefined): unknown {
+	if (!recurrence) return null
+
+	const value: Record<string, unknown> = {
+		frequency: recurrence.frequency,
+		interval: recurrence.interval,
+	}
+
+	if (recurrence.weekdays !== undefined) value.weekdays = recurrence.weekdays
+	if (recurrence.count !== undefined) value.count = recurrence.count
+	if (recurrence.until !== undefined) value.until = recurrence.until.toISOString()
+
+	return value
+}
+
+function serializeOccurrencePatch(patch: ReminderOccurrencePatch | undefined): unknown {
+	if (!patch) return null
+
+	const value: Record<string, unknown> = {}
+	if (hasOwn(patch, "title")) value.title = patch.title
+	if (hasOwn(patch, "notes")) value.notes = patch.notes
+	if (hasOwn(patch, "dueAt") && patch.dueAt !== undefined) {
+		value.dueAt = patch.dueAt.toISOString()
+	}
+	if (hasOwn(patch, "timeZone")) value.timeZone = patch.timeZone
+	if (hasOwn(patch, "priority")) value.priority = patch.priority
+
+	return value
+}
+
+function requireRow<TRow>(
+	rows: TRow[],
+	message = "Reminder storage mutation returned no rows",
+): TRow {
+	const row = rows[0]
+	if (!row) {
+		throw new Error(message)
+	}
+	return row
+}
+
+function assertSchema<T>(schema: ArkSchema<T>, value: unknown): T {
+	const result = schema(value)
+	if (result instanceof type.errors) {
+		throw new Error(result.summary)
+	}
+	return result
+}
+
+function hasOwn<TObject extends object, TKey extends PropertyKey>(
+	object: TObject,
+	key: TKey,
+): object is TObject & Record<TKey, unknown> {
+	return Object.prototype.hasOwnProperty.call(object, key)
+}

apps/freya-backend/src/server.ts

@@ -11,13 +11,16 @@ import { createDatabase } from "./db/index.ts"
 import { registerFeedHttpHandlers } from "./engine/http.ts"
 import { createFeedEnhancer } from "./enhancement/enhance-feed.ts"
 import { createLlmClient } from "./enhancement/llm-client.ts"
+import { GoogleMapsSourceProvider } from "./google-maps/provider.ts"
 import { CredentialEncryptor } from "./lib/crypto.ts"
 import { registerLocationHttpHandlers } from "./location/http.ts"
 import { LocationSourceProvider } from "./location/provider.ts"
+import { ReminderSourceProvider } from "./reminders/provider.ts"
 import { UserSessionManager } from "./session/index.ts"
 import { registerSourcesHttpHandlers } from "./sources/http.ts"
 import { TflSourceProvider } from "./tfl/provider.ts"
 import { WeatherSourceProvider } from "./weather/provider.ts"
+import { WebSearchSourceProvider } from "./web-search/provider.ts"
 
 function main() {
 	const { db, close: closeDb } = createDatabase(process.env.DATABASE_URL!)
@@ -46,11 +49,17 @@ function main() {
 		)
 	}
 
+	const googleMapsApiKey = process.env.GOOGLE_MAPS_API_KEY ?? process.env.GOOGLE_MAPS_MCP_API_KEY
+	if (!googleMapsApiKey) {
+		throw new Error("GOOGLE_MAPS_API_KEY or GOOGLE_MAPS_MCP_API_KEY must be set")
+	}
+
 	const sessionManager = new UserSessionManager({
 		db,
 		providers: [
 			new CalDavSourceProvider(),
 			new LocationSourceProvider(),
+			new ReminderSourceProvider({ db }),
 			new WeatherSourceProvider({
 				credentials: {
 					privateKey: process.env.WEATHERKIT_PRIVATE_KEY!,
@@ -60,6 +69,10 @@ function main() {
 				},
 			}),
 			new TflSourceProvider({ apiKey: process.env.TFL_API_KEY! }),
+			new WebSearchSourceProvider({ apiKey: process.env.EXA_API_KEY }),
+			new GoogleMapsSourceProvider({
+				apiKey: googleMapsApiKey,
+			}),
 		],
 		feedEnhancer,
 		credentialEncryptor,

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

@@ -186,6 +186,18 @@ function put(app: Hono, sourceId: string, body: unknown) {
 	})
 }
 
+function listActions(app: Hono, sourceId: string) {
+	return app.request(`/api/sources/${sourceId}/actions`, { method: "GET" })
+}
+
+function executeAction(app: Hono, sourceId: string, actionId: string, body: unknown) {
+	return app.request(`/api/sources/${sourceId}/actions/${actionId}`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify(body),
+	})
+}
+
 // ---------------------------------------------------------------------------
 // Tests
 // ---------------------------------------------------------------------------
@@ -781,6 +793,168 @@ describe("PUT /api/sources/:sourceId", () => {
 	})
 })
 
+describe("GET /api/sources/:sourceId/actions", () => {
+	test("returns 401 without auth", async () => {
+		activeStore = createInMemoryStore()
+		const { app } = createApp([createStubProvider("freya.location")])
+
+		const res = await listActions(app, "freya.location")
+
+		expect(res.status).toBe(401)
+	})
+
+	test("returns 404 for source that is not enabled in the user session", async () => {
+		activeStore = createInMemoryStore()
+		const { app } = createApp([createStubProvider("freya.location")], MOCK_USER_ID)
+
+		const res = await listActions(app, "freya.location")
+
+		expect(res.status).toBe(404)
+	})
+
+	test("returns serializable action definitions", async () => {
+		activeStore = createInMemoryStore()
+		activeStore.seed(MOCK_USER_ID, "test.actions")
+		const provider: FeedSourceProvider = {
+			sourceId: "test.actions",
+			async feedSourceForUser() {
+				return {
+					id: "test.actions",
+					async listActions() {
+						return {
+							search: {
+								id: "search",
+								description: "Search something",
+								input: tflConfig,
+							},
+						}
+					},
+					async executeAction() {
+						return undefined
+					},
+					async fetchContext() {
+						return null
+					},
+				}
+			},
+		}
+		const { app } = createApp([provider], MOCK_USER_ID)
+
+		const res = await listActions(app, "test.actions")
+
+		expect(res.status).toBe(200)
+		const body = (await res.json()) as {
+			actions: Record<string, { id: string; description?: string; input?: unknown }>
+		}
+		expect(body.actions.search).toEqual({
+			id: "search",
+			description: "Search something",
+		})
+	})
+})
+
+describe("POST /api/sources/:sourceId/actions/:actionId", () => {
+	test("returns 401 without auth", async () => {
+		activeStore = createInMemoryStore()
+		const { app } = createApp([createStubProvider("freya.location")])
+
+		const res = await executeAction(app, "freya.location", "update-location", {})
+
+		expect(res.status).toBe(401)
+	})
+
+	test("executes source action with request body as params", async () => {
+		activeStore = createInMemoryStore()
+		activeStore.seed(MOCK_USER_ID, "test.actions")
+		let receivedParams: unknown
+		const provider: FeedSourceProvider = {
+			sourceId: "test.actions",
+			async feedSourceForUser() {
+				return {
+					id: "test.actions",
+					async listActions() {
+						return {
+							search: { id: "search", description: "Search something" },
+						}
+					},
+					async executeAction(_actionId: string, params: unknown) {
+						receivedParams = params
+						return { ok: true, count: 2 }
+					},
+					async fetchContext() {
+						return null
+					},
+				}
+			},
+		}
+		const { app } = createApp([provider], MOCK_USER_ID)
+
+		const res = await executeAction(app, "test.actions", "search", { query: "exa" })
+
+		expect(res.status).toBe(200)
+		expect(receivedParams).toEqual({ query: "exa" })
+		const body = (await res.json()) as { result: unknown }
+		expect(body.result).toEqual({ ok: true, count: 2 })
+	})
+
+	test("returns 404 for unknown action", async () => {
+		activeStore = createInMemoryStore()
+		activeStore.seed(MOCK_USER_ID, "freya.location")
+		const { app } = createApp([createStubProvider("freya.location")], MOCK_USER_ID)
+
+		const res = await executeAction(app, "freya.location", "missing", {})
+
+		expect(res.status).toBe(404)
+	})
+
+	test("returns 400 for invalid JSON", async () => {
+		activeStore = createInMemoryStore()
+		activeStore.seed(MOCK_USER_ID, "freya.location")
+		const { app } = createApp([createStubProvider("freya.location")], MOCK_USER_ID)
+
+		const res = await app.request("/api/sources/freya.location/actions/search", {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: "not-json",
+		})
+
+		expect(res.status).toBe(400)
+		const body = (await res.json()) as { error: string }
+		expect(body.error).toBe("Invalid JSON")
+	})
+
+	test("returns 400 when source rejects params", async () => {
+		activeStore = createInMemoryStore()
+		activeStore.seed(MOCK_USER_ID, "test.actions")
+		const provider: FeedSourceProvider = {
+			sourceId: "test.actions",
+			async feedSourceForUser() {
+				return {
+					id: "test.actions",
+					async listActions() {
+						return {
+							search: { id: "search" },
+						}
+					},
+					async executeAction() {
+						throw new Error("query must not be empty")
+					},
+					async fetchContext() {
+						return null
+					},
+				}
+			},
+		}
+		const { app } = createApp([provider], MOCK_USER_ID)
+
+		const res = await executeAction(app, "test.actions", "search", { query: "" })
+
+		expect(res.status).toBe(400)
+		const body = (await res.json()) as { error: string }
+		expect(body.error).toBe("query must not be empty")
+	})
+})
+
 describe("PUT /api/sources/:sourceId/credentials", () => {
 	test("returns 401 without auth", async () => {
 		activeStore = createInMemoryStore()

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

@@ -1,3 +1,4 @@
+import type { ActionDefinition } from "@freya/core"
 import type { Context, Hono } from "hono"
 
 import { type } from "arktype"
@@ -55,6 +56,13 @@ export function registerSourcesHttpHandlers(
 	app.get("/api/sources/:sourceId", inject, authSessionMiddleware, handleGetSource)
 	app.patch("/api/sources/:sourceId", inject, authSessionMiddleware, handleUpdateSource)
 	app.put("/api/sources/:sourceId", inject, authSessionMiddleware, handleReplaceSource)
+	app.get("/api/sources/:sourceId/actions", inject, authSessionMiddleware, handleListActions)
+	app.post(
+		"/api/sources/:sourceId/actions/:actionId",
+		inject,
+		authSessionMiddleware,
+		handleExecuteAction,
+	)
 	app.put(
 		"/api/sources/:sourceId/credentials",
 		inject,
@@ -189,6 +197,71 @@ async function handleReplaceSource(c: Context<Env>) {
 	return c.body(null, 204)
 }
 
+async function handleListActions(c: Context<Env>) {
+	const sourceId = c.req.param("sourceId")
+	if (!sourceId) {
+		return c.body(null, 404)
+	}
+
+	const user = c.get("user")!
+	const sessionManager = c.get("sessionManager")
+
+	let session
+	try {
+		session = await sessionManager.getOrCreate(user.id)
+	} catch (err) {
+		console.error("[handleListActions] Failed to create session:", err)
+		return c.json({ error: "Service unavailable" }, 503)
+	}
+
+	try {
+		const actions = await session.engine.listActions(sourceId)
+		return c.json({ actions: serializeActions(actions) })
+	} catch (err) {
+		if (isActionNotFoundError(err)) {
+			return c.json({ error: err.message }, 404)
+		}
+		console.error(`[handleListActions] Failed to list actions for "${sourceId}":`, err)
+		return c.json({ error: "Failed to list actions" }, 500)
+	}
+}
+
+async function handleExecuteAction(c: Context<Env>) {
+	const sourceId = c.req.param("sourceId")
+	const actionId = c.req.param("actionId")
+	if (!sourceId || !actionId) {
+		return c.body(null, 404)
+	}
+
+	let params: unknown
+	try {
+		params = await c.req.json()
+	} catch {
+		return c.json({ error: "Invalid JSON" }, 400)
+	}
+
+	const user = c.get("user")!
+	const sessionManager = c.get("sessionManager")
+
+	let session
+	try {
+		session = await sessionManager.getOrCreate(user.id)
+	} catch (err) {
+		console.error("[handleExecuteAction] Failed to create session:", err)
+		return c.json({ error: "Service unavailable" }, 503)
+	}
+
+	try {
+		const result = await session.engine.executeAction(sourceId, actionId, params)
+		return c.json({ result })
+	} catch (err) {
+		if (isActionNotFoundError(err)) {
+			return c.json({ error: err.message }, 404)
+		}
+		return c.json({ error: err instanceof Error ? err.message : String(err) }, 400)
+	}
+}
+
 async function handleUpdateCredentials(c: Context<Env>) {
 	const sourceId = c.req.param("sourceId")
 	if (!sourceId) {
@@ -228,3 +301,21 @@ async function handleUpdateCredentials(c: Context<Env>) {
 
 	return c.body(null, 204)
 }
+
+function serializeActions(actions: Record<string, ActionDefinition>) {
+	const serialized: Record<string, { id: string; description?: string }> = {}
+	for (const [key, action] of Object.entries(actions)) {
+		serialized[key] = {
+			id: action.id,
+			...(action.description ? { description: action.description } : {}),
+		}
+	}
+	return serialized
+}
+
+function isActionNotFoundError(err: unknown): err is Error {
+	if (!(err instanceof Error)) {
+		return false
+	}
+	return err.message.startsWith("Source not found:") || err.message.startsWith("Action ")
+}

apps/freya-backend/src/web-search/provider.ts

@@ -0,0 +1,30 @@
+import { WebSearchSource, type WebSearchClient } from "@freya/source-web-search"
+
+import type { FeedSourceProvider } from "../session/feed-source-provider.ts"
+
+export type WebSearchSourceProviderOptions =
+	| { apiKey: string | undefined; client?: never }
+	| { apiKey?: never; client: WebSearchClient }
+
+export class WebSearchSourceProvider implements FeedSourceProvider {
+	readonly sourceId = "freya.web-search"
+
+	private readonly apiKey: string | undefined
+	private readonly client: WebSearchClient | undefined
+
+	constructor(options: WebSearchSourceProviderOptions) {
+		this.apiKey = "apiKey" in options ? options.apiKey : undefined
+		this.client = "client" in options ? options.client : undefined
+	}
+
+	async feedSourceForUser(
+		_userId: string,
+		_config: unknown,
+		_credentials: unknown,
+	): Promise<WebSearchSource> {
+		return new WebSearchSource({
+			apiKey: this.apiKey,
+			client: this.client,
+		})
+	}
+}

bun.lock

@@ -53,9 +53,12 @@
         "@freya/core": "workspace:*",
         "@freya/source-caldav": "workspace:*",
         "@freya/source-google-calendar": "workspace:*",
+        "@freya/source-google-maps": "workspace:*",
         "@freya/source-location": "workspace:*",
+        "@freya/source-reminders": "workspace:*",
         "@freya/source-tfl": "workspace:*",
         "@freya/source-weatherkit": "workspace:*",
+        "@freya/source-web-search": "workspace:*",
         "@openrouter/sdk": "^0.9.11",
         "arktype": "^2.1.29",
         "better-auth": "^1",
@@ -192,6 +195,14 @@
         "arktype": "^2.1.0",
       },
     },
+    "packages/freya-source-google-maps": {
+      "name": "@freya/source-google-maps",
+      "version": "0.0.0",
+      "dependencies": {
+        "@freya/source-mcp": "workspace:*",
+        "arktype": "^2.1.0",
+      },
+    },
     "packages/freya-source-location": {
       "name": "@freya/source-location",
       "version": "0.0.0",
@@ -200,6 +211,27 @@
         "arktype": "^2.1.0",
       },
     },
+    "packages/freya-source-mcp": {
+      "name": "@freya/source-mcp",
+      "version": "0.0.0",
+      "dependencies": {
+        "@freya/core": "workspace:*",
+        "@modelcontextprotocol/sdk": "^1.27.1",
+      },
+    },
+    "packages/freya-source-reminders": {
+      "name": "@freya/source-reminders",
+      "version": "0.0.0",
+      "dependencies": {
+        "@freya/components": "workspace:*",
+        "@freya/core": "workspace:*",
+        "arktype": "^2.1.0",
+      },
+      "peerDependencies": {
+        "@json-render/core": "*",
+        "@nym.sh/jrx": "*",
+      },
+    },
     "packages/freya-source-tfl": {
       "name": "@freya/source-tfl",
       "version": "0.0.0",
@@ -223,28 +255,18 @@
         "arktype": "^2.1.0",
       },
     },
+    "packages/freya-source-web-search": {
+      "name": "@freya/source-web-search",
+      "version": "0.0.0",
+      "dependencies": {
+        "@freya/core": "workspace:*",
+        "arktype": "^2.1.0",
+      },
+    },
   },
   "packages": {
     "@0no-co/graphql.web": ["@0no-co/graphql.web@1.2.0", "", { "peerDependencies": { "graphql": "^14.0.0 || ^15.0.0 || ^16.0.0" }, "optionalPeers": ["graphql"] }, "sha512-/1iHy9TTr63gE1YcR5idjx8UREz1s0kFhydf3bBLCXyqjhkIc6igAzTOx3zPifCwFR87tsh/4Pa9cNts6d2otw=="],
 
-    "@freya/backend": ["@freya/backend@workspace:apps/freya-backend"],
-
-    "@freya/components": ["@freya/components@workspace:packages/freya-components"],
-
-    "@freya/core": ["@freya/core@workspace:packages/freya-core"],
-
-    "@freya/feed-enhancers": ["@freya/feed-enhancers@workspace:packages/freya-feed-enhancers"],
-
-    "@freya/source-caldav": ["@freya/source-caldav@workspace:packages/freya-source-caldav"],
-
-    "@freya/source-google-calendar": ["@freya/source-google-calendar@workspace:packages/freya-source-google-calendar"],
-
-    "@freya/source-location": ["@freya/source-location@workspace:packages/freya-source-location"],
-
-    "@freya/source-tfl": ["@freya/source-tfl@workspace:packages/freya-source-tfl"],
-
-    "@freya/source-weatherkit": ["@freya/source-weatherkit@workspace:packages/freya-source-weatherkit"],
-
     "@alloc/quick-lru": ["@alloc/quick-lru@5.2.0", "", {}, "sha512-UrcABB+4bUrFABwbluTIBErXwvbsU/V7TZWfmbgJfbkwiBuziS9gxdODUyuiecfdGQ85jglMW6juS3+z5TsKLw=="],
 
     "@ark/schema": ["@ark/schema@0.56.0", "", { "dependencies": { "@ark/util": "0.56.0" } }, "sha512-ECg3hox/6Z/nLajxXqNhgPtNdHWC9zNsDyskwO28WinoFEnWow4IsERNz9AnXRhTZJnYIlAJ4uGn3nlLk65vZA=="],
@@ -661,6 +683,30 @@
 
     "@formatjs/intl-localematcher": ["@formatjs/intl-localematcher@0.6.2", "", { "dependencies": { "tslib": "^2.8.0" } }, "sha512-XOMO2Hupl0wdd172Y06h6kLpBz6Dv+J4okPLl4LPtzbr8f66WbIoy4ev98EBuZ6ZK4h5ydTN6XneT4QVpD7cdA=="],
 
+    "@freya/backend": ["@freya/backend@workspace:apps/freya-backend"],
+
+    "@freya/components": ["@freya/components@workspace:packages/freya-components"],
+
+    "@freya/core": ["@freya/core@workspace:packages/freya-core"],
+
+    "@freya/feed-enhancers": ["@freya/feed-enhancers@workspace:packages/freya-feed-enhancers"],
+
+    "@freya/source-caldav": ["@freya/source-caldav@workspace:packages/freya-source-caldav"],
+
+    "@freya/source-google-calendar": ["@freya/source-google-calendar@workspace:packages/freya-source-google-calendar"],
+
+    "@freya/source-google-maps": ["@freya/source-google-maps@workspace:packages/freya-source-google-maps"],
+
+    "@freya/source-location": ["@freya/source-location@workspace:packages/freya-source-location"],
+
+    "@freya/source-reminders": ["@freya/source-reminders@workspace:packages/freya-source-reminders"],
+
+    "@freya/source-tfl": ["@freya/source-tfl@workspace:packages/freya-source-tfl"],
+
+    "@freya/source-weatherkit": ["@freya/source-weatherkit@workspace:packages/freya-source-weatherkit"],
+
+    "@freya/source-web-search": ["@freya/source-web-search@workspace:packages/freya-source-web-search"],
+
     "@hapi/hoek": ["@hapi/hoek@9.3.0", "", {}, "sha512-/c6rf4UJlmHlC9b5BaNvzAcFv7HZ2QHaV0D4/HNlBdvFnvQq8RI4kYdhyPCl7Xj+oWvTWQ8ujhqS53LIgAe6KQ=="],
 
     "@hapi/topo": ["@hapi/topo@5.1.0", "", { "dependencies": { "@hapi/hoek": "^9.0.0" } }, "sha512-foQZKJig7Ob0BMAYBfcJk8d77QtOe7Wo4ox7ff1lQYoNNAb6jwcY1ncdoy2e9wQZzvNy7ODZCYJkK8kzmcAnAg=="],
@@ -1529,8 +1575,6 @@
 
     "admin-dashboard": ["admin-dashboard@workspace:apps/admin-dashboard"],
 
-    "freya-client": ["freya-client@workspace:apps/freya-client"],
-
     "agent-base": ["agent-base@7.1.4", "", {}, "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ=="],
 
     "ajv": ["ajv@8.11.0", "", { "dependencies": { "fast-deep-equal": "^3.1.1", "json-schema-traverse": "^1.0.0", "require-from-string": "^2.0.2", "uri-js": "^4.2.2" } }, "sha512-wGgprdCvMalC0BztXvitD2hC04YffAvtsUn93JbGXYLAtCUO4xd17mCCZQxUOItiBwZvJScWo8NIvQMQ71rdpg=="],
@@ -2167,6 +2211,8 @@
 
     "fresh": ["fresh@0.5.2", "", {}, "sha512-zJ2mQYM18rEFOudeV4GShTGIQ7RbzA7ozbU9I/XBpm7kqgMywgmylMwXHxZJmkVoYkna9d2pVXVXPdYTP9ej8Q=="],
 
+    "freya-client": ["freya-client@workspace:apps/freya-client"],
+
     "fs-extra": ["fs-extra@11.3.4", "", { "dependencies": { "graceful-fs": "^4.2.0", "jsonfile": "^6.0.1", "universalify": "^2.0.0" } }, "sha512-CTXd6rk/M3/ULNQj8FBqBWHYBVYybQ3VPBw0xGKFe3tuH7ytT6ACnvzpIQ3UZtB8yvUKC2cXn1a+x+5EVQLovA=="],
 
     "fs.realpath": ["fs.realpath@1.0.0", "", {}, "sha512-OO0pH2lK6a0hZnAdau5ItzHPI6pUlvI7jMVnxUQRtw4owF2wk8lOSabtGDCTP4Ggrg2MbGnWO9X8K1t4+fGMDw=="],
@@ -3921,12 +3967,6 @@
 
     "accepts/negotiator": ["negotiator@0.6.3", "", {}, "sha512-+EUsqGPLsM+j/zdChZjsnX51g4XrHFOIXwfnCVPGlQk/k5giakcKsuxCObBRu6DSm9opw/O6slWbJdghQM4bBg=="],
 
-    "freya-client/@types/react": ["@types/react@19.1.17", "", { "dependencies": { "csstype": "^3.0.2" } }, "sha512-Qec1E3mhALmaspIrhWt9jkQMNdw6bReVu64mjvhbhq2NFPftLPVr+l1SZgmw/66WwBNpDh7ao5AT6gF5v41PFA=="],
-
-    "freya-client/react": ["react@19.1.0", "", {}, "sha512-FS+XFBNvn3GTAWq26joslQgWNoFu08F4kl0J4CgdNKADkdSGXQyTCnKteIAJy96Br6YbpEU1LSzV5dYtjMkMDg=="],
-
-    "freya-client/react-dom": ["react-dom@19.1.0", "", { "dependencies": { "scheduler": "^0.26.0" }, "peerDependencies": { "react": "^19.1.0" } }, "sha512-Xs1hdnE+DyKgeHJeJznQmYMIBG3TKIHJJT95Q58nHLSrElKlGQqDTR2HQ9fx5CN/Gk6Vh/kupBTDLU11/nDk/g=="],
-
     "ansi-escapes/type-fest": ["type-fest@0.21.3", "", {}, "sha512-t0rzBq87m3fVcduHDUFhKmyyX+9eo6WQjZvf51Ea/M0Q7+T374Jp1aUiyUl0GKxp8M/OETVHSDvmkyPgvX+X2w=="],
 
     "anymatch/picomatch": ["picomatch@2.3.1", "", {}, "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA=="],
@@ -4069,6 +4109,12 @@
 
     "framer-motion/tslib": ["tslib@2.8.1", "", {}, "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w=="],
 
+    "freya-client/@types/react": ["@types/react@19.1.17", "", { "dependencies": { "csstype": "^3.0.2" } }, "sha512-Qec1E3mhALmaspIrhWt9jkQMNdw6bReVu64mjvhbhq2NFPftLPVr+l1SZgmw/66WwBNpDh7ao5AT6gF5v41PFA=="],
+
+    "freya-client/react": ["react@19.1.0", "", {}, "sha512-FS+XFBNvn3GTAWq26joslQgWNoFu08F4kl0J4CgdNKADkdSGXQyTCnKteIAJy96Br6YbpEU1LSzV5dYtjMkMDg=="],
+
+    "freya-client/react-dom": ["react-dom@19.1.0", "", { "dependencies": { "scheduler": "^0.26.0" }, "peerDependencies": { "react": "^19.1.0" } }, "sha512-Xs1hdnE+DyKgeHJeJznQmYMIBG3TKIHJJT95Q58nHLSrElKlGQqDTR2HQ9fx5CN/Gk6Vh/kupBTDLU11/nDk/g=="],
+
     "giget/pathe": ["pathe@2.0.3", "", {}, "sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w=="],
 
     "glob/minimatch": ["minimatch@3.1.5", "", { "dependencies": { "brace-expansion": "^1.1.7" } }, "sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w=="],
@@ -4559,8 +4605,6 @@
 
     "@typescript-eslint/typescript-estree/minimatch/brace-expansion": ["brace-expansion@5.0.4", "", { "dependencies": { "balanced-match": "^4.0.2" } }, "sha512-h+DEnpVvxmfVefa4jFbCf5HdH5YMDXRsmKflpf1pILZWRFlTbJpxeU55nJl4Smt5HQaGzg1o6RHFPJaOqnmBDg=="],
 
-    "freya-client/react-dom/scheduler": ["scheduler@0.26.0", "", {}, "sha512-NlHwttCI/l5gCPR3D1nNXtWABUmBwvZpEQiD4IXSbIDq8BzLIK/7Ir5gTFSGZDUu37K5cMNp0hFtzO38sC7gWA=="],
-
     "better-opn/open/define-lazy-prop": ["define-lazy-prop@2.0.0", "", {}, "sha512-Ds09qNh8yw3khSjiJjiUInaGX9xlqZDY7JVryGxdxV7NPeuqQfplOpQ66yJFZut3jLa5zOwkXw1g9EI2uKh4Og=="],
 
     "better-opn/open/is-docker": ["is-docker@2.2.1", "", { "bin": { "is-docker": "cli.js" } }, "sha512-F+i2BKsFrH66iaUFc0woD8sLy8getkwTwtOBjvs56Cx4CgJDeKQeqfz8wAYiSb8JOprWhHH5p77PbmYCvvUuXQ=="],
@@ -4695,6 +4739,8 @@
 
     "finalhandler/debug/ms": ["ms@2.0.0", "", {}, "sha512-Tpp60P6IUJDTuOq/5Z8cdskzJujfwqfOTkrwIwj7IRISpnkJnT6SyJ4PCPnGMoFjC9ddhal5KVIYtAt97ix05A=="],
 
+    "freya-client/react-dom/scheduler": ["scheduler@0.26.0", "", {}, "sha512-NlHwttCI/l5gCPR3D1nNXtWABUmBwvZpEQiD4IXSbIDq8BzLIK/7Ir5gTFSGZDUu37K5cMNp0hFtzO38sC7gWA=="],
+
     "glob/minimatch/brace-expansion": ["brace-expansion@1.1.12", "", { "dependencies": { "balanced-match": "^1.0.0", "concat-map": "0.0.1" } }, "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg=="],
 
     "globby/fast-glob/glob-parent": ["glob-parent@5.1.2", "", { "dependencies": { "is-glob": "^4.0.1" } }, "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow=="],

packages/freya-source-google-maps/package.json

@@ -0,0 +1,14 @@
+{
+	"name": "@freya/source-google-maps",
+	"version": "0.0.0",
+	"type": "module",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"scripts": {
+		"test": "bun test src/"
+	},
+	"dependencies": {
+		"@freya/source-mcp": "workspace:*",
+		"arktype": "^2.1.0"
+	}
+}

packages/freya-source-google-maps/src/google-maps-source.test.ts

@@ -0,0 +1,135 @@
+import type {
+	McpCallToolParams,
+	McpCallToolResult,
+	McpClient,
+	McpListToolsResult,
+	McpReadResourceParams,
+	McpReadResourceResult,
+} from "@freya/source-mcp"
+
+import { describe, expect, test } from "bun:test"
+
+import { GoogleMapsAction, GoogleMapsSource, GoogleMapsSourceId, GoogleMapsTool } from "./index"
+
+class MockMcpClient implements McpClient {
+	readonly calls: McpCallToolParams[] = []
+
+	async listTools(): Promise<McpListToolsResult> {
+		return {
+			tools: Object.values(GoogleMapsTool).map((name) => ({
+				name,
+				description: `${name} description`,
+			})),
+		}
+	}
+
+	async readResource(_params: McpReadResourceParams): Promise<McpReadResourceResult> {
+		throw new Error("unexpected resource read")
+	}
+
+	async callTool(params: McpCallToolParams): Promise<McpCallToolResult> {
+		this.calls.push(params)
+		return {
+			structuredContent: {
+				tool: params.name,
+				arguments: params.arguments ?? {},
+			},
+		}
+	}
+}
+
+describe("GoogleMapsSource", () => {
+	test("uses the Google Maps source id", () => {
+		const source = new GoogleMapsSource({ client: new MockMcpClient() })
+		expect(source.id).toBe(GoogleMapsSourceId)
+	})
+
+	test("exposes documented Google Maps MCP tools as actions", async () => {
+		const source = new GoogleMapsSource({ client: new MockMcpClient() })
+
+		const actions = await source.listActions()
+
+		expect(Object.keys(actions).sort()).toEqual(Object.values(GoogleMapsAction).sort())
+		expect(actions[GoogleMapsAction.SearchPlaces]!.id).toBe(GoogleMapsAction.SearchPlaces)
+	})
+
+	test("maps action execution to the underlying MCP tool", async () => {
+		const client = new MockMcpClient()
+		const source = new GoogleMapsSource({ client })
+
+		const result = await source.executeAction(GoogleMapsAction.SearchPlaces, {
+			textQuery: "coffee shops near Golden Gate Park",
+			regionCode: "US",
+		})
+
+		expect(client.calls).toEqual([
+			{
+				name: GoogleMapsTool.SearchPlaces,
+				arguments: {
+					textQuery: "coffee shops near Golden Gate Park",
+					regionCode: "US",
+				},
+			},
+		])
+		expect(result).toEqual({
+			tool: GoogleMapsTool.SearchPlaces,
+			arguments: {
+				textQuery: "coffee shops near Golden Gate Park",
+				regionCode: "US",
+			},
+		})
+	})
+
+	test("validates action input before calling the MCP tool", async () => {
+		const client = new MockMcpClient()
+		const source = new GoogleMapsSource({ client })
+
+		await expectRejectsWithMessage(
+			source.executeAction(GoogleMapsAction.SearchPlaces, {}),
+			"textQuery must be a string",
+		)
+		expect(client.calls).toEqual([])
+	})
+
+	test("validates resolve names query objects", async () => {
+		const client = new MockMcpClient()
+		const source = new GoogleMapsSource({ client })
+
+		await expectRejectsWithMessage(
+			source.executeAction(GoogleMapsAction.ResolveNames, { queries: [{}] }),
+			"queries[0].text must be a string",
+		)
+		expect(client.calls).toEqual([])
+	})
+
+	test("does not produce feed items or context by default", async () => {
+		const source = new GoogleMapsSource({ client: new MockMcpClient() })
+
+		const contextEntries = await source.fetchContext(undefined as never)
+		const items = await source.fetchItems(undefined as never)
+
+		expect(contextEntries).toBeNull()
+		expect(items).toEqual([])
+	})
+})
+
+async function expectRejectsWithMessage(
+	promise: Promise<unknown>,
+	expectedMessage: string,
+): Promise<void> {
+	try {
+		await promise
+	} catch (err) {
+		expect(errorMessage(err)).toContain(expectedMessage)
+		return
+	}
+
+	throw new Error(`Expected promise to reject with "${expectedMessage}"`)
+}
+
+function errorMessage(err: unknown): string {
+	if (err instanceof Error) {
+		return err.message
+	}
+	return String(err)
+}

packages/freya-source-google-maps/src/google-maps-source.ts

@@ -0,0 +1,151 @@
+import {
+	McpSource,
+	type McpActionMapping,
+	type McpClient,
+	type McpHttpHeaders,
+	type McpSourceOptions,
+} from "@freya/source-mcp"
+
+import {
+	ComputeRoutesInput,
+	LookupWeatherInput,
+	ResolveMapsUrlsInput,
+	ResolveNamesInput,
+	SearchPlacesInput,
+} from "./schemas"
+
+export type GoogleMapsApiKey = string | (() => Promise<string>)
+
+export interface GoogleMapsSourceOptions {
+	readonly endpoint?: string | URL
+	readonly apiKey?: GoogleMapsApiKey
+	readonly timeoutMs?: number
+	readonly headers?: McpHttpHeaders | (() => Promise<McpHttpHeaders>)
+	readonly requestInit?: RequestInit
+	readonly transportOptions?: McpSourceOptions["transportOptions"]
+	readonly client?: McpClient
+	readonly clientFactory?: McpSourceOptions["clientFactory"]
+}
+
+export const GoogleMapsSourceId = "freya.google-maps"
+
+export const GoogleMapsMcpEndpoint = "https://mapstools.googleapis.com/mcp"
+
+export const GoogleMapsAction = {
+	SearchPlaces: "search-places",
+	LookupWeather: "lookup-weather",
+	ComputeRoutes: "compute-routes",
+	ResolveNames: "resolve-names",
+	ResolveMapsUrls: "resolve-maps-urls",
+} as const
+
+export type GoogleMapsAction = (typeof GoogleMapsAction)[keyof typeof GoogleMapsAction]
+
+export const GoogleMapsTool = {
+	SearchPlaces: "search_places",
+	LookupWeather: "lookup_weather",
+	ComputeRoutes: "compute_routes",
+	ResolveNames: "resolve_names",
+	ResolveMapsUrls: "resolve_maps_urls",
+} as const
+
+export type GoogleMapsTool = (typeof GoogleMapsTool)[keyof typeof GoogleMapsTool]
+
+const GoogleMapsActions = {
+	[GoogleMapsAction.SearchPlaces]: {
+		tool: GoogleMapsTool.SearchPlaces,
+		description:
+			"Find places, businesses, addresses, locations, and points of interest with Google Maps.",
+		input: SearchPlacesInput,
+	},
+	[GoogleMapsAction.LookupWeather]: {
+		tool: GoogleMapsTool.LookupWeather,
+		description: "Retrieve current conditions and weather forecasts through Google Maps.",
+		input: LookupWeatherInput,
+	},
+	[GoogleMapsAction.ComputeRoutes]: {
+		tool: GoogleMapsTool.ComputeRoutes,
+		description: "Compute a Google Maps route between an origin and destination.",
+		input: ComputeRoutesInput,
+	},
+	[GoogleMapsAction.ResolveNames]: {
+		tool: GoogleMapsTool.ResolveNames,
+		description: "Resolve specific place names or addresses into Google Maps Place IDs.",
+		input: ResolveNamesInput,
+	},
+	[GoogleMapsAction.ResolveMapsUrls]: {
+		tool: GoogleMapsTool.ResolveMapsUrls,
+		description: "Resolve Google Maps URLs into canonical Google Maps Place IDs.",
+		input: ResolveMapsUrlsInput,
+	},
+} as const satisfies Record<GoogleMapsAction, McpActionMapping>
+
+export class GoogleMapsSource extends McpSource {
+	constructor(options: GoogleMapsSourceOptions = {}) {
+		super({
+			id: GoogleMapsSourceId,
+			url: options.endpoint ?? GoogleMapsMcpEndpoint,
+			clientName: "freya-source-google-maps",
+			clientVersion: "0.0.0",
+			timeoutMs: options.timeoutMs,
+			headers: createGoogleMapsHeaders({
+				headers: options.headers,
+				apiKey: options.apiKey,
+			}),
+			requestInit: options.requestInit,
+			transportOptions: options.transportOptions,
+			client: options.client,
+			clientFactory: options.clientFactory,
+			actions: GoogleMapsActions,
+		})
+	}
+}
+
+interface GoogleMapsHeaderOptions {
+	readonly headers: McpHttpHeaders | (() => Promise<McpHttpHeaders>) | undefined
+	readonly apiKey: GoogleMapsApiKey | undefined
+}
+
+function createGoogleMapsHeaders({
+	headers,
+	apiKey,
+}: GoogleMapsHeaderOptions): McpHttpHeaders | (() => Promise<McpHttpHeaders>) | undefined {
+	if (!apiKey) {
+		return headers
+	}
+
+	return async () => {
+		const merged = new Headers()
+		const resolvedHeaders = typeof headers === "function" ? await headers() : headers
+		if (resolvedHeaders) {
+			applyHeaders(merged, resolvedHeaders)
+		}
+
+		if (apiKey) {
+			const resolvedApiKey = typeof apiKey === "function" ? await apiKey() : apiKey
+			merged.set("x-goog-api-key", resolvedApiKey)
+		}
+
+		return merged
+	}
+}
+
+function applyHeaders(target: Headers, headers: McpHttpHeaders): void {
+	if (headers instanceof Headers) {
+		headers.forEach((value, key) => {
+			target.set(key, value)
+		})
+		return
+	}
+
+	if (Array.isArray(headers)) {
+		for (const [key, value] of headers) {
+			target.set(key, value)
+		}
+		return
+	}
+
+	for (const [key, value] of Object.entries(headers)) {
+		target.set(key, value)
+	}
+}

packages/freya-source-google-maps/src/index.ts

@@ -0,0 +1,17 @@
+export {
+	GoogleMapsAction,
+	GoogleMapsMcpEndpoint,
+	GoogleMapsSource,
+	GoogleMapsSourceId,
+	GoogleMapsTool,
+	type GoogleMapsApiKey,
+	type GoogleMapsSourceOptions,
+} from "./google-maps-source"
+
+export {
+	ComputeRoutesInput,
+	LookupWeatherInput,
+	ResolveMapsUrlsInput,
+	ResolveNamesInput,
+	SearchPlacesInput,
+} from "./schemas"

packages/freya-source-google-maps/src/schemas.ts

@@ -0,0 +1,41 @@
+import { type } from "arktype"
+
+const ResolveNameQuery = type({
+	"+": "reject",
+	text: "string",
+})
+
+export const SearchPlacesInput = type({
+	"+": "reject",
+	textQuery: "string",
+	"locationBias?": "unknown",
+	"languageCode?": "string",
+	"regionCode?": "string",
+})
+
+export const LookupWeatherInput = type({
+	"+": "reject",
+	location: "unknown",
+	"date?": "unknown",
+	"hour?": "number",
+	"unitsSystem?": "'UNITS_SYSTEM_UNSPECIFIED' | 'METRIC' | 'IMPERIAL'",
+})
+
+export const ComputeRoutesInput = type({
+	"+": "reject",
+	origin: "unknown",
+	destination: "unknown",
+	"travelMode?": "'ROUTE_TRAVEL_MODE_UNSPECIFIED' | 'DRIVE' | 'WALK'",
+})
+
+export const ResolveNamesInput = type({
+	"+": "reject",
+	queries: ResolveNameQuery.array(),
+	"locationBias?": "unknown",
+	"regionCode?": "string",
+})
+
+export const ResolveMapsUrlsInput = type({
+	"+": "reject",
+	urls: "string[]",
+})

packages/freya-source-google-maps/tsconfig.json

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

packages/freya-source-mcp/package.json

@@ -0,0 +1,14 @@
+{
+	"name": "@freya/source-mcp",
+	"version": "0.0.0",
+	"type": "module",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"scripts": {
+		"test": "bun test src/"
+	},
+	"dependencies": {
+		"@freya/core": "workspace:*",
+		"@modelcontextprotocol/sdk": "^1.27.1"
+	}
+}

packages/freya-source-mcp/src/index.ts

@@ -0,0 +1,26 @@
+export {
+	McpSource,
+	type McpActionMapping,
+	type McpContextResource,
+	type McpContextTool,
+	type McpFeedItem,
+	type McpFeedItemMapping,
+	type McpSourceOptions,
+} from "./mcp-source"
+
+export {
+	StreamableHttpMcpClient,
+	type McpCallToolParams,
+	type McpCallToolResult,
+	type McpClient,
+	type McpHttpHeaders,
+	type McpListToolsParams,
+	type McpListToolsResult,
+	type McpReadResourceParams,
+	type McpReadResourceResult,
+	type McpResourceContent,
+	type McpRequestOptions,
+	type McpTool,
+	type McpToolContent,
+	type StreamableHttpMcpClientOptions,
+} from "./mcp-client"

packages/freya-source-mcp/src/mcp-client.test.ts

@@ -0,0 +1,275 @@
+import { ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js"
+import { describe, expect, test } from "bun:test"
+
+import { StreamableHttpMcpClient, type StreamableHttpMcpClientOptions } from "./mcp-client"
+
+type JsonRpcId = string | number
+
+type FetchLike = NonNullable<
+	NonNullable<StreamableHttpMcpClientOptions["transportOptions"]>["fetch"]
+>
+
+describe("StreamableHttpMcpClient", () => {
+	test("retries connection after initial connection failure", async () => {
+		const methods: string[] = []
+		let initializeAttempts = 0
+		const fetch: FetchLike = async (_url, init) => {
+			const method = requestMethod(init)
+
+			if (init?.method === "GET") {
+				return new Response(null, { status: 405, statusText: "Method Not Allowed" })
+			}
+
+			methods.push(method)
+			switch (method) {
+				case "initialize":
+					initializeAttempts += 1
+					if (initializeAttempts === 1) {
+						throw new Error("Transient connection failure")
+					}
+					return jsonRpcResponse(requestId(init), {
+						protocolVersion: "2025-06-18",
+						capabilities: {
+							tools: {},
+						},
+						serverInfo: {
+							name: "test-mcp",
+							version: "1.0.0",
+						},
+					})
+				case "notifications/initialized":
+					return new Response(null, { status: 202, statusText: "Accepted" })
+				case "tools/list":
+					return jsonRpcResponse(requestId(init), {
+						tools: [],
+					})
+				default:
+					throw new Error(`Unexpected MCP method: ${method}`)
+			}
+		}
+
+		const client = new StreamableHttpMcpClient({
+			url: "https://example.test/mcp",
+			transportOptions: { fetch },
+		})
+
+		await expectRejectedMessage(client.listTools(), "Transient connection failure")
+
+		const result = await client.listTools()
+		await client.close()
+
+		expect(result.tools).toEqual([])
+		expect(initializeAttempts).toBe(2)
+		expect(methods).toEqual(["initialize", "initialize", "notifications/initialized", "tools/list"])
+	})
+
+	test("applies timeout to initial connection request", async () => {
+		const methods: string[] = []
+		let initializeAttempts = 0
+		const fetch: FetchLike = async (_url, init) => {
+			if (init?.method === "GET") {
+				return new Response(null, { status: 405, statusText: "Method Not Allowed" })
+			}
+
+			const method = requestMethod(init)
+			methods.push(method)
+
+			switch (method) {
+				case "initialize":
+					initializeAttempts += 1
+					if (initializeAttempts === 1) {
+						return new Promise<Response>(() => {})
+					}
+					return jsonRpcResponse(requestId(init), {
+						protocolVersion: "2025-06-18",
+						capabilities: {
+							tools: {},
+						},
+						serverInfo: {
+							name: "test-mcp",
+							version: "1.0.0",
+						},
+					})
+				case "notifications/cancelled":
+				case "notifications/initialized":
+					return new Response(null, { status: 202, statusText: "Accepted" })
+				case "tools/list":
+					return jsonRpcResponse(requestId(init), {
+						tools: [],
+					})
+				default:
+					throw new Error(`Unexpected MCP method: ${method}`)
+			}
+		}
+
+		const client = new StreamableHttpMcpClient({
+			url: "https://example.test/mcp",
+			timeoutMs: 1,
+			transportOptions: { fetch },
+		})
+
+		await expectMcpErrorCode(client.listTools(), ErrorCode.RequestTimeout)
+
+		const result = await client.listTools()
+		await client.close()
+
+		expect(result.tools).toEqual([])
+		expect(initializeAttempts).toBe(2)
+		expect(methods).toEqual([
+			"initialize",
+			"notifications/cancelled",
+			"initialize",
+			"notifications/initialized",
+			"tools/list",
+		])
+	})
+
+	test("applies caller signal to initial connection request", async () => {
+		const methods: string[] = []
+		const fetch = createSuccessfulFetch(methods)
+		const controller = new AbortController()
+		controller.abort(new Error("Caller aborted"))
+
+		const client = new StreamableHttpMcpClient({
+			url: "https://example.test/mcp",
+			transportOptions: { fetch },
+		})
+
+		await expectRejectedMessageContaining(
+			client.listTools(undefined, { signal: controller.signal }),
+			"Caller aborted",
+		)
+		expect(methods).toEqual([])
+
+		const result = await client.listTools()
+		await client.close()
+
+		expect(result.tools).toEqual([])
+		expect(methods).toEqual(["initialize", "notifications/initialized", "tools/list"])
+	})
+})
+
+function createSuccessfulFetch(methods: string[]): FetchLike {
+	return async (_url, init) => {
+		if (init?.method === "GET") {
+			return new Response(null, { status: 405, statusText: "Method Not Allowed" })
+		}
+
+		const method = requestMethod(init)
+		methods.push(method)
+
+		switch (method) {
+			case "initialize":
+				return jsonRpcResponse(requestId(init), {
+					protocolVersion: "2025-06-18",
+					capabilities: {
+						tools: {},
+					},
+					serverInfo: {
+						name: "test-mcp",
+						version: "1.0.0",
+					},
+				})
+			case "notifications/initialized":
+				return new Response(null, { status: 202, statusText: "Accepted" })
+			case "tools/list":
+				return jsonRpcResponse(requestId(init), {
+					tools: [],
+				})
+			default:
+				throw new Error(`Unexpected MCP method: ${method}`)
+		}
+	}
+}
+
+function jsonRpcResponse(id: JsonRpcId, result: Record<string, unknown>): Response {
+	return Response.json({
+		jsonrpc: "2.0",
+		id,
+		result,
+	})
+}
+
+function requestMethod(init: RequestInit | undefined): string {
+	const request = requestBody(init)
+	const method = request.method
+	if (typeof method !== "string") {
+		throw new Error("Expected JSON-RPC request method")
+	}
+	return method
+}
+
+function requestId(init: RequestInit | undefined): JsonRpcId {
+	const request = requestBody(init)
+	const id = request.id
+	if (typeof id !== "string" && typeof id !== "number") {
+		throw new Error("Expected JSON-RPC request id")
+	}
+	return id
+}
+
+function requestBody(init: RequestInit | undefined): Record<string, unknown> {
+	const body = init?.body
+	if (typeof body !== "string") {
+		throw new Error("Expected string request body")
+	}
+
+	const value: unknown = JSON.parse(body)
+	if (!isRecord(value)) {
+		throw new Error("Expected object request body")
+	}
+
+	return value
+}
+
+async function expectRejectedMessage(promise: Promise<unknown>, message: string): Promise<void> {
+	try {
+		await promise
+	} catch (error) {
+		expect(error).toBeInstanceOf(Error)
+		if (error instanceof Error) {
+			expect(error.message).toBe(message)
+			return
+		}
+		throw new Error("Expected promise to reject with an Error")
+	}
+
+	throw new Error(`Expected promise to reject with message: ${message}`)
+}
+
+async function expectMcpErrorCode(promise: Promise<unknown>, code: ErrorCode): Promise<void> {
+	try {
+		await promise
+	} catch (error) {
+		expect(error).toBeInstanceOf(McpError)
+		if (error instanceof McpError) {
+			expect(error.code).toBe(code)
+			return
+		}
+		throw new Error("Expected promise to reject with an McpError")
+	}
+
+	throw new Error(`Expected promise to reject with MCP error code: ${code}`)
+}
+
+async function expectRejectedMessageContaining(
+	promise: Promise<unknown>,
+	message: string,
+): Promise<void> {
+	try {
+		await promise
+	} catch (error) {
+		expect(error).toBeInstanceOf(Error)
+		if (error instanceof Error) {
+			expect(error.message).toContain(message)
+			return
+		}
+		throw new Error("Expected promise to reject with an Error")
+	}
+
+	throw new Error(`Expected promise to reject with message containing: ${message}`)
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value)
+}

packages/freya-source-mcp/src/mcp-client.ts

@@ -0,0 +1,276 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js"
+import {
+	StreamableHTTPClientTransport,
+	type StreamableHTTPClientTransportOptions,
+} from "@modelcontextprotocol/sdk/client/streamableHttp.js"
+
+export interface McpRequestOptions {
+	readonly signal?: AbortSignal
+	readonly timeout?: number
+}
+
+export interface McpListToolsParams {
+	readonly cursor?: string
+}
+
+export interface McpReadResourceParams {
+	readonly uri: string
+}
+
+export interface McpCallToolParams {
+	readonly name: string
+	readonly arguments?: Record<string, unknown>
+}
+
+export interface McpTool {
+	readonly name: string
+	readonly title?: string
+	readonly description?: string
+	readonly inputSchema?: {
+		readonly type: "object"
+		readonly properties?: Record<string, object>
+		readonly required?: string[]
+		readonly [key: string]: unknown
+	}
+	readonly outputSchema?: {
+		readonly type: "object"
+		readonly properties?: Record<string, object>
+		readonly required?: string[]
+		readonly [key: string]: unknown
+	}
+	readonly annotations?: {
+		readonly title?: string
+		readonly readOnlyHint?: boolean
+		readonly destructiveHint?: boolean
+		readonly idempotentHint?: boolean
+		readonly openWorldHint?: boolean
+	}
+	readonly _meta?: Record<string, unknown>
+}
+
+export interface McpListToolsResult {
+	readonly tools: readonly McpTool[]
+	readonly nextCursor?: string
+}
+
+export type McpResourceContent = McpTextResourceContent | McpBlobResourceContent
+
+export interface McpTextResourceContent {
+	readonly uri: string
+	readonly mimeType?: string
+	readonly text: string
+	readonly _meta?: Record<string, unknown>
+}
+
+export interface McpBlobResourceContent {
+	readonly uri: string
+	readonly mimeType?: string
+	readonly blob: string
+	readonly _meta?: Record<string, unknown>
+}
+
+export interface McpReadResourceResult {
+	readonly contents: readonly McpResourceContent[]
+	readonly _meta?: Record<string, unknown>
+}
+
+export type McpToolContent =
+	| McpToolTextContent
+	| McpToolImageContent
+	| McpToolAudioContent
+	| McpToolResourceContent
+	| McpToolResourceLinkContent
+
+export interface McpToolTextContent {
+	readonly type: "text"
+	readonly text: string
+	readonly _meta?: Record<string, unknown>
+}
+
+export interface McpToolImageContent {
+	readonly type: "image"
+	readonly data: string
+	readonly mimeType: string
+	readonly _meta?: Record<string, unknown>
+}
+
+export interface McpToolAudioContent {
+	readonly type: "audio"
+	readonly data: string
+	readonly mimeType: string
+	readonly _meta?: Record<string, unknown>
+}
+
+export interface McpToolResourceContent {
+	readonly type: "resource"
+	readonly resource: McpResourceContent
+	readonly _meta?: Record<string, unknown>
+}
+
+export interface McpToolResourceLinkContent {
+	readonly type: "resource_link"
+	readonly uri: string
+	readonly name: string
+	readonly title?: string
+	readonly description?: string
+	readonly mimeType?: string
+	readonly _meta?: Record<string, unknown>
+}
+
+export interface McpCallToolResult {
+	readonly content?: readonly McpToolContent[]
+	readonly structuredContent?: Record<string, unknown>
+	readonly toolResult?: unknown
+	readonly isError?: boolean
+	readonly _meta?: Record<string, unknown>
+	readonly [key: string]: unknown
+}
+
+export interface McpClient {
+	listTools(params?: McpListToolsParams, options?: McpRequestOptions): Promise<McpListToolsResult>
+	readResource(
+		params: McpReadResourceParams,
+		options?: McpRequestOptions,
+	): Promise<McpReadResourceResult>
+	callTool(params: McpCallToolParams, options?: McpRequestOptions): Promise<McpCallToolResult>
+	close?(): Promise<void>
+}
+
+export type McpHttpHeaders =
+	| Headers
+	| Record<string, string>
+	| readonly (readonly [string, string])[]
+
+export interface StreamableHttpMcpClientOptions {
+	readonly url: string | URL
+	readonly name?: string
+	readonly version?: string
+	readonly timeoutMs?: number
+	readonly headers?: McpHttpHeaders | (() => Promise<McpHttpHeaders>)
+	readonly requestInit?: RequestInit
+	readonly transportOptions?: Omit<StreamableHTTPClientTransportOptions, "requestInit">
+}
+
+export class StreamableHttpMcpClient implements McpClient {
+	private clientPromise: Promise<Client> | null = null
+
+	constructor(private readonly options: StreamableHttpMcpClientOptions) {}
+
+	async listTools(
+		params?: McpListToolsParams,
+		options?: McpRequestOptions,
+	): Promise<McpListToolsResult> {
+		const request = requestOptions(this.options.timeoutMs, options)
+		const client = await this.client(request)
+		return client.listTools(params, request)
+	}
+
+	async readResource(
+		params: McpReadResourceParams,
+		options?: McpRequestOptions,
+	): Promise<McpReadResourceResult> {
+		const request = requestOptions(this.options.timeoutMs, options)
+		const client = await this.client(request)
+		return client.readResource(params, request)
+	}
+
+	async callTool(
+		params: McpCallToolParams,
+		options?: McpRequestOptions,
+	): Promise<McpCallToolResult> {
+		const request = requestOptions(this.options.timeoutMs, options)
+		const client = await this.client(request)
+		return client.callTool(params, undefined, request)
+	}
+
+	async close(): Promise<void> {
+		if (!this.clientPromise) return
+		const client = await this.clientPromise
+		this.clientPromise = null
+		await client.close()
+	}
+
+	private client(options?: McpRequestOptions): Promise<Client> {
+		if (!this.clientPromise) {
+			const promise = this.connect(options)
+			this.clientPromise = promise
+			void promise.catch(() => {
+				if (this.clientPromise === promise) {
+					this.clientPromise = null
+				}
+			})
+		}
+		return this.clientPromise
+	}
+
+	private async connect(options?: McpRequestOptions): Promise<Client> {
+		const client = new Client({
+			name: this.options.name ?? "freya-source-mcp",
+			version: this.options.version ?? "0.0.0",
+		})
+
+		const transport = new StreamableHTTPClientTransport(toUrl(this.options.url), {
+			...this.options.transportOptions,
+			requestInit: await mergeRequestInit(this.options.requestInit, this.options.headers),
+		})
+
+		await client.connect(transport, options)
+		return client
+	}
+}
+
+function requestOptions(
+	defaultTimeoutMs: number | undefined,
+	options: McpRequestOptions | undefined,
+): McpRequestOptions | undefined {
+	if (defaultTimeoutMs === undefined && options === undefined) {
+		return undefined
+	}
+	return {
+		...(defaultTimeoutMs === undefined ? {} : { timeout: defaultTimeoutMs }),
+		...options,
+	}
+}
+
+function toUrl(value: string | URL): URL {
+	if (value instanceof URL) return value
+	return new URL(value)
+}
+
+async function mergeRequestInit(
+	requestInit: RequestInit | undefined,
+	headers: McpHttpHeaders | (() => Promise<McpHttpHeaders>) | undefined,
+): Promise<RequestInit | undefined> {
+	if (!requestInit && !headers) return undefined
+
+	const mergedHeaders = new Headers(requestInit?.headers)
+	const extraHeaders = typeof headers === "function" ? await headers() : headers
+	if (extraHeaders) {
+		applyHeaders(mergedHeaders, extraHeaders)
+	}
+
+	return {
+		...requestInit,
+		headers: mergedHeaders,
+	}
+}
+
+function applyHeaders(target: Headers, headers: McpHttpHeaders): void {
+	if (headers instanceof Headers) {
+		headers.forEach((value, key) => {
+			target.set(key, value)
+		})
+		return
+	}
+
+	if (Array.isArray(headers)) {
+		for (const [key, value] of headers) {
+			target.set(key, value)
+		}
+		return
+	}
+
+	for (const [key, value] of Object.entries(headers)) {
+		target.set(key, value)
+	}
+}

packages/freya-source-mcp/src/mcp-source.test.ts

@@ -0,0 +1,355 @@
+import { Context, UnknownActionError, contextKey, type ActionDefinition } from "@freya/core"
+import { describe, expect, test } from "bun:test"
+
+import type {
+	McpCallToolParams,
+	McpCallToolResult,
+	McpClient,
+	McpListToolsParams,
+	McpListToolsResult,
+	McpReadResourceParams,
+	McpReadResourceResult,
+	McpTool,
+} from "./mcp-client"
+
+import { McpSource } from "./mcp-source"
+
+class FakeMcpClient implements McpClient {
+	tools: readonly McpTool[] = []
+	readonly resources = new Map<string, McpReadResourceResult>()
+	readonly toolResults = new Map<string, McpCallToolResult>()
+	readonly listToolParams: Array<McpListToolsParams | undefined> = []
+	readonly readResourceParams: McpReadResourceParams[] = []
+	readonly callToolParams: McpCallToolParams[] = []
+
+	async listTools(params?: McpListToolsParams): Promise<McpListToolsResult> {
+		this.listToolParams.push(params)
+		return { tools: this.tools }
+	}
+
+	async readResource(params: McpReadResourceParams): Promise<McpReadResourceResult> {
+		this.readResourceParams.push(params)
+		const result = this.resources.get(params.uri)
+		if (!result) {
+			throw new Error(`Missing resource: ${params.uri}`)
+		}
+		return result
+	}
+
+	async callTool(params: McpCallToolParams): Promise<McpCallToolResult> {
+		this.callToolParams.push(params)
+		const result = this.toolResults.get(params.name)
+		if (!result) {
+			throw new Error(`Missing tool result: ${params.name}`)
+		}
+		return result
+	}
+}
+
+describe("McpSource", () => {
+	test("reads configured MCP resources into context", async () => {
+		const NotificationsKey = contextKey<{ unread: number }>("com.example.mcp", "notifications")
+		const client = new FakeMcpClient()
+		client.resources.set("mcp://notifications", {
+			contents: [
+				{
+					uri: "mcp://notifications",
+					mimeType: "application/json",
+					text: JSON.stringify({ unread: 3 }),
+				},
+			],
+		})
+
+		const source = new McpSource({
+			id: "com.example.mcp",
+			client,
+			resources: [
+				{
+					uri: "mcp://notifications",
+					contextKey: NotificationsKey,
+				},
+			],
+		})
+
+		const context = new Context()
+		const entries = await source.fetchContext(context)
+		context.set(entries ?? [])
+
+		expect(context.get(NotificationsKey)).toEqual({ unread: 3 })
+		expect(client.readResourceParams).toEqual([{ uri: "mcp://notifications" }])
+	})
+
+	test("calls configured MCP tools into context", async () => {
+		const ViewerKey = contextKey<{ name: string }>("com.example.mcp", "viewer")
+		const client = new FakeMcpClient()
+		client.toolResults.set("viewer", {
+			structuredContent: { name: "Kenneth" },
+		})
+
+		const source = new McpSource({
+			id: "com.example.mcp",
+			client,
+			contextTools: [
+				{
+					tool: "viewer",
+					contextKey: ViewerKey,
+				},
+			],
+		})
+
+		const context = new Context()
+		const entries = await source.fetchContext(context)
+		context.set(entries ?? [])
+
+		expect(context.get(ViewerKey)).toEqual({ name: "Kenneth" })
+		expect(client.callToolParams).toEqual([{ name: "viewer", arguments: {} }])
+	})
+
+	test("projects configured MCP resources into feed items", async () => {
+		const client = new FakeMcpClient()
+		client.resources.set("mcp://alerts", {
+			contents: [
+				{
+					uri: "mcp://alerts",
+					text: JSON.stringify([{ title: "Build failed" }]),
+				},
+			],
+		})
+
+		const source = new McpSource({
+			id: "com.example.mcp",
+			client,
+			feedItems: [
+				{
+					kind: "resource",
+					uri: "mcp://alerts",
+					type: "mcp-alerts",
+				},
+			],
+		})
+
+		const context = new Context(new Date("2026-01-01T00:00:00.000Z"))
+		const items = await source.fetchItems(context)
+
+		expect(items).toHaveLength(1)
+		expect(items[0]).toMatchObject({
+			sourceId: "com.example.mcp",
+			type: "mcp-alerts",
+			timestamp: context.time,
+			data: {
+				kind: "mcp-resource",
+				uri: "mcp://alerts",
+				value: [{ title: "Build failed" }],
+			},
+		})
+	})
+
+	test("lists allowlisted MCP tools as Freya actions", async () => {
+		const client = new FakeMcpClient()
+		client.tools = [
+			{
+				name: "github.create_issue",
+				description: "Create a GitHub issue",
+				inputSchema: { type: "object" },
+			},
+			{
+				name: "github.delete_repo",
+				description: "Delete a repository",
+				inputSchema: { type: "object" },
+			},
+		]
+
+		const source = new McpSource({
+			id: "com.example.github",
+			client,
+			actions: {
+				"create-issue": {
+					tool: "github.create_issue",
+				},
+			},
+		})
+
+		const actions = await source.listActions()
+
+		expect(Object.keys(actions)).toEqual(["create-issue"])
+		expect(actions["create-issue"]).toMatchObject({
+			id: "create-issue",
+			description: "Create a GitHub issue",
+		})
+	})
+
+	test("executes allowlisted MCP tools as Freya actions", async () => {
+		const client = new FakeMcpClient()
+		client.toolResults.set("github.create_issue", {
+			structuredContent: { issueNumber: 42 },
+		})
+
+		const source = new McpSource({
+			id: "com.example.github",
+			client,
+			actions: {
+				"create-issue": {
+					tool: "github.create_issue",
+				},
+			},
+		})
+
+		const result = await source.executeAction("create-issue", { title: "Bug" })
+
+		expect(result).toEqual({ issueNumber: 42 })
+		expect(client.callToolParams).toEqual([
+			{
+				name: "github.create_issue",
+				arguments: { title: "Bug" },
+			},
+		])
+	})
+
+	test("validates mapped action input before calling MCP tools", async () => {
+		const client = new FakeMcpClient()
+		client.toolResults.set("github.create_issue", {
+			structuredContent: { issueNumber: 42 },
+		})
+
+		const source = new McpSource({
+			id: "com.example.github",
+			client,
+			actions: {
+				"create-issue": {
+					tool: "github.create_issue",
+					input: createIssueInputSchema(),
+				},
+			},
+		})
+
+		await expectRejectedMessage(
+			source.executeAction("create-issue", { title: 42 }),
+			'Invalid MCP action "create-issue" params: title: Expected string',
+		)
+		expect(client.callToolParams).toEqual([])
+	})
+
+	test("rejects MCP tools that are not allowlisted as actions", async () => {
+		const client = new FakeMcpClient()
+		client.tools = [
+			{
+				name: "github.create_issue",
+				description: "Create a GitHub issue",
+				inputSchema: { type: "object" },
+			},
+			{
+				name: "github.delete_repo",
+				description: "Delete a repository",
+				inputSchema: { type: "object" },
+			},
+		]
+		client.toolResults.set("github.delete_repo", {
+			structuredContent: { deleted: true },
+		})
+
+		const source = new McpSource({
+			id: "com.example.github",
+			client,
+			actions: {
+				"create-issue": {
+					tool: "github.create_issue",
+				},
+			},
+		})
+
+		const actions = await source.listActions()
+
+		expect(Object.keys(actions)).toEqual(["create-issue"])
+		await expectUnknownActionError(source.executeAction("github.delete_repo", {}))
+		expect(client.callToolParams).toEqual([])
+	})
+
+	test("rejects unknown actions", async () => {
+		const source = new McpSource({
+			id: "com.example.mcp",
+			client: new FakeMcpClient(),
+			actions: {
+				"known-action": {
+					tool: "known_tool",
+				},
+			},
+		})
+
+		await expectUnknownActionError(source.executeAction("unknown-action", {}))
+	})
+
+	test("requires object params for default action argument mapping", async () => {
+		const source = new McpSource({
+			id: "com.example.mcp",
+			client: new FakeMcpClient(),
+			actions: {
+				"known-action": {
+					tool: "known_tool",
+				},
+			},
+		})
+
+		await expectRejectedMessage(
+			source.executeAction("known-action", "bad params"),
+			'MCP action "known-action" requires object params',
+		)
+	})
+})
+
+async function expectUnknownActionError(promise: Promise<unknown>): Promise<void> {
+	try {
+		await promise
+	} catch (error) {
+		expect(error).toBeInstanceOf(UnknownActionError)
+		return
+	}
+
+	throw new Error("Expected promise to reject with UnknownActionError")
+}
+
+async function expectRejectedMessage(promise: Promise<unknown>, message: string): Promise<void> {
+	try {
+		await promise
+	} catch (error) {
+		expect(error).toBeInstanceOf(Error)
+		if (error instanceof Error) {
+			expect(error.message).toBe(message)
+			return
+		}
+		throw new Error("Expected promise to reject with an Error")
+	}
+
+	throw new Error(`Expected promise to reject with message: ${message}`)
+}
+
+function createIssueInputSchema(): NonNullable<ActionDefinition["input"]> {
+	return {
+		"~standard": {
+			version: 1,
+			vendor: "freya-test",
+			validate(value: unknown) {
+				if (!isRecord(value)) {
+					return {
+						issues: [{ message: "Expected object" }],
+					}
+				}
+
+				if (typeof value.title !== "string") {
+					return {
+						issues: [{ message: "Expected string", path: ["title"] }],
+					}
+				}
+
+				return {
+					value: {
+						title: value.title.trim(),
+					},
+				}
+			},
+		},
+	}
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value)
+}

packages/freya-source-mcp/src/mcp-source.ts

@@ -0,0 +1,624 @@
+import type {
+	ActionDefinition,
+	ContextEntry,
+	ContextKey,
+	FeedItem,
+	FeedItemSignals,
+	FeedSource,
+	Slot,
+} from "@freya/core"
+
+import { Context, UnknownActionError } from "@freya/core"
+
+import {
+	StreamableHttpMcpClient,
+	type McpCallToolResult,
+	type McpClient,
+	type McpHttpHeaders,
+	type McpResourceContent,
+	type McpTool,
+	type McpToolContent,
+	type StreamableHttpMcpClientOptions,
+} from "./mcp-client"
+
+export type McpFeedItem = FeedItem<string, Record<string, unknown>>
+
+/**
+ * Configuration for an MCP-backed `FeedSource`.
+ *
+ * The source is intentionally projection-based: remote MCP resources/tools are
+ * only exposed to Freya when listed here as context entries, feed items, or
+ * allowlisted actions.
+ */
+export interface McpSourceOptions {
+	/** Stable Freya source identifier, for example `freya.github` or `freya.discord`. */
+	readonly id: string
+	/** Streamable HTTP MCP endpoint. Required unless `client` or `clientFactory` is provided. */
+	readonly url?: string | URL
+	/** Client name advertised during MCP initialization. */
+	readonly clientName?: string
+	/** Client version advertised during MCP initialization. */
+	readonly clientVersion?: string
+	/** Default timeout, in milliseconds, for MCP connection and request calls. */
+	readonly timeoutMs?: number
+	/** Static or lazily-resolved HTTP headers for the MCP transport. */
+	readonly headers?: McpHttpHeaders | (() => Promise<McpHttpHeaders>)
+	/** Additional `fetch` options merged into the MCP transport request init. */
+	readonly requestInit?: RequestInit
+	/** Additional transport options forwarded to the MCP SDK streamable HTTP transport. */
+	readonly transportOptions?: StreamableHttpMcpClientOptions["transportOptions"]
+	/** Preconfigured MCP client, primarily useful for tests or custom transports. */
+	readonly client?: McpClient
+	/** Lazy MCP client factory, useful when client construction depends on runtime state. */
+	readonly clientFactory?: () => McpClient | Promise<McpClient>
+	/** Freya source dependencies used by the context graph scheduler. */
+	readonly dependencies?: readonly string[]
+	/** MCP resources to read and write into Freya context keys. */
+	readonly resources?: readonly McpContextResource[]
+	/** MCP tools to call and write into Freya context keys. */
+	readonly contextTools?: readonly McpContextTool[]
+	/** MCP resources or tools to project into feed items. */
+	readonly feedItems?: readonly McpFeedItemMapping[]
+	/** Freya action IDs mapped to explicit, allowlisted MCP tools. */
+	readonly actions?: Record<string, McpActionMapping>
+}
+
+export interface McpContextResource<T = unknown> {
+	readonly uri: string
+	readonly contextKey: ContextKey<T>
+	readonly map?: (contents: readonly McpResourceContent[], context: Context) => T | null
+}
+
+export type McpToolArguments =
+	| Record<string, unknown>
+	| ((context: Context) => Record<string, unknown>)
+
+export interface McpContextTool<T = unknown> {
+	readonly tool: string
+	readonly arguments?: McpToolArguments
+	readonly contextKey: ContextKey<T>
+	readonly map?: (result: McpCallToolResult, context: Context) => T | null
+}
+
+/**
+ * Mapping from a Freya action ID to an MCP tool call.
+ *
+ * Only actions declared in `McpSourceOptions.actions` can be executed through
+ * the source. The map is keyed by Freya action ID, while `tool` names the
+ * remote MCP tool to call.
+ */
+export interface McpActionMapping {
+	/** Remote MCP tool name to call when the Freya action is executed. */
+	readonly tool: string
+	/** Optional action description; falls back to the MCP tool description/title when omitted. */
+	readonly description?: string
+	/** Optional Standard Schema input validator exposed on the Freya action and checked locally. */
+	readonly input?: ActionDefinition["input"]
+	/** Static MCP arguments or a mapper from validated Freya action params to MCP arguments. */
+	readonly arguments?: Record<string, unknown> | ((params: unknown) => Record<string, unknown>)
+	/** Optional mapper from raw MCP tool result to the Freya action return value. */
+	readonly mapResult?: (result: McpCallToolResult) => unknown
+}
+
+export type McpFeedItemMapping = McpResourceFeedItemMapping | McpToolFeedItemMapping
+
+export type McpFeedPayload = McpResourceFeedPayload | McpToolFeedPayload
+
+export interface McpFeedItemBaseMapping {
+	readonly type: string
+	readonly id?: string | ((payload: McpFeedPayload, context: Context) => string)
+	readonly mapData?: (payload: McpFeedPayload, context: Context) => Record<string, unknown> | null
+	readonly signals?:
+		| FeedItemSignals
+		| ((payload: McpFeedPayload, context: Context) => FeedItemSignals | undefined)
+	readonly slots?:
+		| Record<string, Slot>
+		| ((payload: McpFeedPayload, context: Context) => Record<string, Slot>)
+}
+
+export interface McpResourceFeedItemMapping extends McpFeedItemBaseMapping {
+	readonly kind: "resource"
+	readonly uri: string
+}
+
+export interface McpToolFeedItemMapping extends McpFeedItemBaseMapping {
+	readonly kind: "tool"
+	readonly tool: string
+	readonly arguments?: McpToolArguments
+}
+
+export interface McpResourceFeedPayload {
+	readonly kind: "resource"
+	readonly uri: string
+	readonly contents: readonly McpResourceContent[]
+	readonly value: unknown
+}
+
+export interface McpToolFeedPayload {
+	readonly kind: "tool"
+	readonly tool: string
+	readonly result: McpCallToolResult
+	readonly value: unknown
+}
+
+/**
+ * FeedSource backed by a remote MCP server.
+ *
+ * The source intentionally uses explicit projections. A remote MCP server can
+ * expose many resources and tools, but only configured resources/tools enter the
+ * Freya context graph or action surface.
+ */
+export class McpSource implements FeedSource<McpFeedItem> {
+	readonly id: string
+	readonly dependencies: readonly string[] | undefined
+
+	private clientPromise: Promise<McpClient> | null = null
+
+	constructor(private readonly options: McpSourceOptions) {
+		this.id = options.id
+		this.dependencies = options.dependencies
+
+		if (!options.client && !options.clientFactory && !options.url) {
+			throw new Error("McpSource requires either a client, clientFactory, or remote url")
+		}
+	}
+
+	async listActions(): Promise<Record<string, ActionDefinition>> {
+		const actionMappings = this.options.actions
+		if (!actionMappings) {
+			return {}
+		}
+
+		const tools = await this.toolsByName()
+		const actions: Record<string, ActionDefinition> = {}
+
+		for (const [actionId, mapping] of Object.entries(actionMappings)) {
+			const tool = tools.get(mapping.tool)
+			if (!tool) {
+				throw new Error(
+					`Configured MCP action "${actionId}" maps to missing tool "${mapping.tool}"`,
+				)
+			}
+
+			const description = mapping.description ?? tool.description ?? tool.title
+			actions[actionId] = {
+				id: actionId,
+				...(description ? { description } : {}),
+				...(mapping.input ? { input: mapping.input } : {}),
+			}
+		}
+
+		return actions
+	}
+
+	async executeAction(actionId: string, params: unknown): Promise<unknown> {
+		const mapping = this.options.actions?.[actionId]
+		if (!mapping) {
+			throw new UnknownActionError(actionId)
+		}
+		const validatedParams = await validateActionInput(actionId, params, mapping)
+
+		const client = await this.client()
+		const result = await client.callTool(
+			{
+				name: mapping.tool,
+				arguments: resolveActionArguments(actionId, validatedParams, mapping),
+			},
+			this.requestOptions(),
+		)
+
+		if (result.isError) {
+			throw new Error(`MCP tool "${mapping.tool}" returned an error: ${toolResultText(result)}`)
+		}
+
+		return mapping.mapResult ? mapping.mapResult(result) : toolResultValue(result)
+	}
+
+	async fetchContext(context: Context): Promise<readonly ContextEntry[] | null> {
+		const resources = this.options.resources ?? []
+		const contextTools = this.options.contextTools ?? []
+		if (resources.length === 0 && contextTools.length === 0) {
+			return null
+		}
+
+		const entries: ContextEntry[] = []
+		const client = await this.client()
+
+		for (const resource of resources) {
+			const result = await client.readResource({ uri: resource.uri }, this.requestOptions())
+			const value = resource.map
+				? resource.map(result.contents, context)
+				: resourceContentsValue(result.contents)
+
+			if (value !== null) {
+				entries.push([resource.contextKey, value])
+			}
+		}
+
+		for (const tool of contextTools) {
+			const result = await client.callTool(
+				{
+					name: tool.tool,
+					arguments: resolveToolArguments(tool.arguments, context),
+				},
+				this.requestOptions(),
+			)
+
+			if (result.isError) {
+				throw new Error(`MCP tool "${tool.tool}" returned an error: ${toolResultText(result)}`)
+			}
+
+			const value = tool.map ? tool.map(result, context) : toolResultValue(result)
+			if (value !== null) {
+				entries.push([tool.contextKey, value])
+			}
+		}
+
+		return entries.length > 0 ? entries : null
+	}
+
+	async fetchItems(context: Context): Promise<McpFeedItem[]> {
+		const mappings = this.options.feedItems ?? []
+		if (mappings.length === 0) {
+			return []
+		}
+
+		const client = await this.client()
+		const items: McpFeedItem[] = []
+
+		for (const mapping of mappings) {
+			const payload = await this.fetchFeedPayload(client, mapping, context)
+			const data = mapping.mapData
+				? mapping.mapData(payload, context)
+				: defaultFeedItemData(payload)
+
+			if (data === null) {
+				continue
+			}
+
+			items.push({
+				id: resolveFeedItemId(this.id, mapping, payload, context),
+				sourceId: this.id,
+				type: mapping.type,
+				timestamp: context.time,
+				data,
+				...resolveSignals(mapping, payload, context),
+				...resolveSlots(mapping, payload, context),
+			})
+		}
+
+		return items
+	}
+
+	async close(): Promise<void> {
+		if (!this.clientPromise) return
+		const client = await this.clientPromise
+		this.clientPromise = null
+		await client.close?.()
+	}
+
+	private async fetchFeedPayload(
+		client: McpClient,
+		mapping: McpFeedItemMapping,
+		context: Context,
+	): Promise<McpFeedPayload> {
+		switch (mapping.kind) {
+			case "resource": {
+				const result = await client.readResource({ uri: mapping.uri }, this.requestOptions())
+				return {
+					kind: "resource",
+					uri: mapping.uri,
+					contents: result.contents,
+					value: resourceContentsValue(result.contents),
+				}
+			}
+			case "tool": {
+				const result = await client.callTool(
+					{
+						name: mapping.tool,
+						arguments: resolveToolArguments(mapping.arguments, context),
+					},
+					this.requestOptions(),
+				)
+				if (result.isError) {
+					throw new Error(`MCP tool "${mapping.tool}" returned an error: ${toolResultText(result)}`)
+				}
+				return {
+					kind: "tool",
+					tool: mapping.tool,
+					result,
+					value: toolResultValue(result),
+				}
+			}
+		}
+	}
+
+	private async toolsByName(): Promise<Map<string, McpTool>> {
+		const client = await this.client()
+		const tools = new Map<string, McpTool>()
+		let cursor: string | undefined
+
+		do {
+			const result = await client.listTools(cursor ? { cursor } : undefined, this.requestOptions())
+			for (const tool of result.tools) {
+				tools.set(tool.name, tool)
+			}
+			cursor = result.nextCursor
+		} while (cursor)
+
+		return tools
+	}
+
+	private client(): Promise<McpClient> {
+		if (!this.clientPromise) {
+			this.clientPromise = this.createClient()
+		}
+		return this.clientPromise
+	}
+
+	private async createClient(): Promise<McpClient> {
+		if (this.options.client) {
+			return this.options.client
+		}
+
+		if (this.options.clientFactory) {
+			return this.options.clientFactory()
+		}
+
+		return new StreamableHttpMcpClient({
+			url: this.options.url!,
+			name: this.options.clientName,
+			version: this.options.clientVersion,
+			timeoutMs: this.options.timeoutMs,
+			headers: this.options.headers,
+			requestInit: this.options.requestInit,
+			transportOptions: this.options.transportOptions,
+		})
+	}
+
+	private requestOptions(): { timeout?: number } | undefined {
+		if (this.options.timeoutMs === undefined) {
+			return undefined
+		}
+		return { timeout: this.options.timeoutMs }
+	}
+}
+
+async function validateActionInput(
+	actionId: string,
+	params: unknown,
+	mapping: McpActionMapping,
+): Promise<unknown> {
+	if (!mapping.input) {
+		return params
+	}
+
+	const result = await mapping.input["~standard"].validate(params)
+	if (result.issues) {
+		throw new Error(
+			`Invalid MCP action "${actionId}" params: ${formatStandardSchemaIssues(result.issues)}`,
+		)
+	}
+
+	return result.value
+}
+
+function resolveToolArguments(
+	args: McpToolArguments | undefined,
+	context: Context,
+): Record<string, unknown> {
+	if (!args) return {}
+	if (typeof args === "function") {
+		return args(context)
+	}
+	return args
+}
+
+function resolveActionArguments(
+	actionId: string,
+	params: unknown,
+	mapping: McpActionMapping,
+): Record<string, unknown> {
+	if (mapping.arguments) {
+		if (typeof mapping.arguments === "function") {
+			return mapping.arguments(params)
+		}
+		return mapping.arguments
+	}
+
+	if (params === undefined || params === null) {
+		return {}
+	}
+
+	if (!isRecord(params)) {
+		throw new Error(`MCP action "${actionId}" requires object params`)
+	}
+
+	return params
+}
+
+function resolveFeedItemId(
+	sourceId: string,
+	mapping: McpFeedItemMapping,
+	payload: McpFeedPayload,
+	context: Context,
+): string {
+	if (typeof mapping.id === "function") {
+		return mapping.id(payload, context)
+	}
+	if (mapping.id) {
+		return mapping.id
+	}
+
+	const identifier = payload.kind === "resource" ? payload.uri : payload.tool
+	return `${sourceId}-${mapping.type}-${slug(identifier)}`
+}
+
+function resolveSignals(
+	mapping: McpFeedItemMapping,
+	payload: McpFeedPayload,
+	context: Context,
+): { signals?: FeedItemSignals } {
+	if (!mapping.signals) return {}
+	const signals =
+		typeof mapping.signals === "function" ? mapping.signals(payload, context) : mapping.signals
+	return signals ? { signals } : {}
+}
+
+function resolveSlots(
+	mapping: McpFeedItemMapping,
+	payload: McpFeedPayload,
+	context: Context,
+): { slots?: Record<string, Slot> } {
+	if (!mapping.slots) return {}
+	const slots =
+		typeof mapping.slots === "function" ? mapping.slots(payload, context) : mapping.slots
+	return { slots }
+}
+
+function defaultFeedItemData(payload: McpFeedPayload): Record<string, unknown> {
+	switch (payload.kind) {
+		case "resource":
+			return {
+				kind: "mcp-resource",
+				uri: payload.uri,
+				value: payload.value,
+			}
+		case "tool":
+			return {
+				kind: "mcp-tool",
+				tool: payload.tool,
+				value: payload.value,
+			}
+	}
+}
+
+function resourceContentsValue(contents: readonly McpResourceContent[]): unknown {
+	const values = contents.map(resourceContentValue)
+	if (values.length === 1) {
+		return values[0]
+	}
+	return values
+}
+
+function resourceContentValue(content: McpResourceContent): unknown {
+	if ("text" in content) {
+		return parseTextValue(content.text, content.mimeType)
+	}
+
+	return {
+		uri: content.uri,
+		...(content.mimeType ? { mimeType: content.mimeType } : {}),
+		blob: content.blob,
+	}
+}
+
+function toolResultValue(result: McpCallToolResult): unknown {
+	if (result.structuredContent) {
+		return result.structuredContent
+	}
+
+	if ("toolResult" in result) {
+		return result.toolResult
+	}
+
+	if (result.content) {
+		const values = result.content.map(toolContentValue)
+		if (values.length === 1) {
+			return values[0]
+		}
+		return values
+	}
+
+	return result
+}
+
+function toolContentValue(content: McpToolContent): unknown {
+	switch (content.type) {
+		case "text":
+			return parseTextValue(content.text)
+		case "resource":
+			return resourceContentValue(content.resource)
+		case "resource_link":
+			return {
+				type: content.type,
+				uri: content.uri,
+				name: content.name,
+				...(content.title ? { title: content.title } : {}),
+				...(content.description ? { description: content.description } : {}),
+				...(content.mimeType ? { mimeType: content.mimeType } : {}),
+			}
+		case "image":
+		case "audio":
+			return {
+				type: content.type,
+				data: content.data,
+				mimeType: content.mimeType,
+			}
+	}
+}
+
+function toolResultText(result: McpCallToolResult): string {
+	const value = toolResultValue(result)
+	if (typeof value === "string") {
+		return value
+	}
+	return JSON.stringify(value)
+}
+
+function parseTextValue(text: string, mimeType?: string): unknown {
+	if (shouldParseJson(text, mimeType)) {
+		try {
+			return JSON.parse(text)
+		} catch {
+			return text
+		}
+	}
+	return text
+}
+
+function shouldParseJson(text: string, mimeType?: string): boolean {
+	if (mimeType?.includes("json")) {
+		return true
+	}
+
+	const trimmed = text.trim()
+	return trimmed.startsWith("{") || trimmed.startsWith("[")
+}
+
+function slug(value: string): string {
+	return value
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-|-$/g, "")
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value)
+}
+
+function formatStandardSchemaIssues(
+	issues: readonly {
+		readonly message: string
+		readonly path?: readonly (PropertyKey | { readonly key: PropertyKey })[]
+	}[],
+): string {
+	return issues.map(formatStandardSchemaIssue).join("; ")
+}
+
+function formatStandardSchemaIssue(issue: {
+	readonly message: string
+	readonly path?: readonly (PropertyKey | { readonly key: PropertyKey })[]
+}): string {
+	const path = issue.path?.map(formatStandardSchemaPathSegment).join(".")
+	return path ? `${path}: ${issue.message}` : issue.message
+}
+
+function formatStandardSchemaPathSegment(
+	segment: PropertyKey | { readonly key: PropertyKey },
+): string {
+	if (typeof segment === "object" && segment !== null && "key" in segment) {
+		return String(segment.key)
+	}
+	return String(segment)
+}

packages/freya-source-mcp/tsconfig.json

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

packages/freya-source-reminders/package.json

@@ -0,0 +1,19 @@
+{
+	"name": "@freya/source-reminders",
+	"version": "0.0.0",
+	"type": "module",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"scripts": {
+		"test": "bun test src/"
+	},
+	"dependencies": {
+		"@freya/components": "workspace:*",
+		"@freya/core": "workspace:*",
+		"arktype": "^2.1.0"
+	},
+	"peerDependencies": {
+		"@json-render/core": "*",
+		"@nym.sh/jrx": "*"
+	}
+}

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

@@ -0,0 +1,11 @@
+export { ReminderSource, type ReminderSourceOptions } from "./reminder-source.ts"
+export {
+	createReminderOccurrenceId,
+	expandReminderOccurrences,
+	expandReminderOriginalDueAts,
+	findReminderOccurrenceIndex,
+	recurrenceAfterSplit,
+	stopRecurrenceAfterOccurrenceCount,
+} from "./recurrence.ts"
+export { renderReminderFeedItem } from "./renderer.tsx"
+export * from "./types.ts"

packages/freya-source-reminders/src/recurrence.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, test } from "bun:test"
+
+import type { Reminder } from "./types.ts"
+
+import { expandReminderOriginalDueAts, findReminderOccurrenceIndex } from "./recurrence.ts"
+import { ReminderPriority, ReminderRecurrenceFrequency, ReminderWeekday } from "./types.ts"
+
+describe("recurrence", () => {
+	test("deduplicates weekly weekdays before applying recurrence count", () => {
+		const reminder = weeklyReminder({
+			recurrence: {
+				frequency: ReminderRecurrenceFrequency.Weekly,
+				interval: 1,
+				weekdays: [ReminderWeekday.Monday, ReminderWeekday.Monday, ReminderWeekday.Wednesday],
+				count: 3,
+			},
+		})
+
+		const originalDueAts = expandReminderOriginalDueAts(
+			reminder,
+			new Date("2026-06-08T00:00:00Z"),
+			new Date("2026-06-22T00:00:00Z"),
+		)
+
+		expect(originalDueAts.map(toIsoString)).toEqual([
+			"2026-06-08T09:00:00.000Z",
+			"2026-06-10T09:00:00.000Z",
+			"2026-06-15T09:00:00.000Z",
+		])
+	})
+
+	test("deduplicates weekly weekdays before calculating occurrence indexes", () => {
+		const reminder = weeklyReminder({
+			recurrence: {
+				frequency: ReminderRecurrenceFrequency.Weekly,
+				interval: 1,
+				weekdays: [ReminderWeekday.Monday, ReminderWeekday.Monday, ReminderWeekday.Wednesday],
+			},
+		})
+
+		expect(findReminderOccurrenceIndex(reminder, new Date("2026-06-10T09:00:00Z"))).toBe(1)
+		expect(findReminderOccurrenceIndex(reminder, new Date("2026-06-15T09:00:00Z"))).toBe(2)
+	})
+})
+
+function weeklyReminder(overrides: Partial<Reminder> = {}): Reminder {
+	const now = new Date("2026-06-01T00:00:00Z")
+	return {
+		id: "r1",
+		title: "Take vitamins",
+		notes: null,
+		dueAt: new Date("2026-06-08T09:00:00Z"),
+		timeZone: "UTC",
+		recurrence: {
+			frequency: ReminderRecurrenceFrequency.Weekly,
+			interval: 1,
+			weekdays: [ReminderWeekday.Monday],
+		},
+		priority: ReminderPriority.Normal,
+		createdAt: now,
+		updatedAt: now,
+		...overrides,
+	}
+}
+
+function toIsoString(date: Date): string {
+	return date.toISOString()
+}

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

@@ -0,0 +1,392 @@
+import type {
+	Reminder,
+	ReminderOccurrence,
+	ReminderOccurrenceOverride,
+	ReminderOccurrencePatch,
+	ReminderRecurrence,
+	ReminderWeekday,
+} from "./types.ts"
+
+import { ReminderRecurrenceFrequency } from "./types.ts"
+
+interface ZonedDateTimeParts {
+	year: number
+	month: number
+	day: number
+	hour: number
+	minute: number
+	second: number
+	millisecond: number
+}
+
+interface ExpandReminderOccurrencesOptions {
+	from: Date
+	to: Date
+	includeCompleted: boolean
+	overrides?: readonly ReminderOccurrenceOverride[]
+}
+
+export function createReminderOccurrenceId(originalDueAt: Date): string {
+	return originalDueAt.toISOString()
+}
+
+export function expandReminderOccurrences(
+	reminder: Reminder,
+	options: ExpandReminderOccurrencesOptions,
+): ReminderOccurrence[] {
+	const originalDueAts = new Map<string, Date>()
+	for (const dueAt of expandReminderOriginalDueAts(reminder, options.from, options.to)) {
+		originalDueAts.set(createReminderOccurrenceId(dueAt), dueAt)
+	}
+
+	const overrideById = new Map<string, ReminderOccurrenceOverride>()
+	for (const override of options.overrides ?? []) {
+		if (override.reminderId !== reminder.id) continue
+		if (!isCurrentOriginalDueAt(reminder, override.originalDueAt)) continue
+		overrideById.set(override.occurrenceId, override)
+		originalDueAts.set(override.occurrenceId, override.originalDueAt)
+	}
+
+	const occurrences: ReminderOccurrence[] = []
+	const originals = Array.from(originalDueAts.values()).sort(compareDates)
+
+	for (const originalDueAt of originals) {
+		const occurrenceId = createReminderOccurrenceId(originalDueAt)
+		const override = overrideById.get(occurrenceId)
+		if (override?.deletedAt) continue
+
+		const occurrence = createOccurrence(reminder, originalDueAt, override)
+		if (occurrence.dueAt < options.from || occurrence.dueAt > options.to) continue
+		if (!options.includeCompleted && occurrence.completedAt) continue
+
+		occurrences.push(occurrence)
+	}
+
+	return occurrences.sort(compareOccurrences)
+}
+
+export function expandReminderOriginalDueAts(reminder: Reminder, from: Date, to: Date): Date[] {
+	if (to < reminder.dueAt) return []
+
+	if (!reminder.recurrence) {
+		return reminder.dueAt >= from && reminder.dueAt <= to ? [reminder.dueAt] : []
+	}
+
+	switch (reminder.recurrence.frequency) {
+		case ReminderRecurrenceFrequency.Daily:
+			return expandDaily(reminder, from, to)
+		case ReminderRecurrenceFrequency.Weekly:
+			return expandWeekly(reminder, from, to)
+		case ReminderRecurrenceFrequency.Monthly:
+			return expandMonthly(reminder, from, to)
+		case ReminderRecurrenceFrequency.Yearly:
+			return expandYearly(reminder, from, to)
+	}
+}
+
+export function findReminderOccurrenceIndex(
+	reminder: Reminder,
+	occurrenceDueAt: Date,
+): number | null {
+	if (!reminder.recurrence) {
+		return reminder.dueAt.getTime() === occurrenceDueAt.getTime() ? 0 : null
+	}
+
+	const originals = expandReminderOriginalDueAts(reminder, reminder.dueAt, occurrenceDueAt)
+	for (let index = 0; index < originals.length; index++) {
+		if (originals[index]!.getTime() === occurrenceDueAt.getTime()) {
+			return index
+		}
+	}
+
+	return null
+}
+
+function isCurrentOriginalDueAt(reminder: Reminder, originalDueAt: Date): boolean {
+	return findReminderOccurrenceIndex(reminder, originalDueAt) !== null
+}
+
+export function stopRecurrenceAfterOccurrenceCount(
+	recurrence: ReminderRecurrence,
+	count: number,
+): ReminderRecurrence | null {
+	if (count <= 0) return null
+	return { ...recurrence, count }
+}
+
+export function recurrenceAfterSplit(
+	recurrence: ReminderRecurrence,
+	occurrenceIndex: number,
+): ReminderRecurrence | null {
+	if (recurrence.count === undefined) {
+		return { ...recurrence }
+	}
+
+	const remainingCount = recurrence.count - occurrenceIndex
+	if (remainingCount <= 1) return null
+
+	return { ...recurrence, count: remainingCount }
+}
+
+function expandDaily(reminder: Reminder, from: Date, to: Date): Date[] {
+	return expandStepped(reminder, from, to, function addDaily(parts, step) {
+		return addDays(parts, step)
+	})
+}
+
+function expandMonthly(reminder: Reminder, from: Date, to: Date): Date[] {
+	const anchor = getZonedParts(reminder.dueAt, reminder.timeZone).day
+	return expandStepped(reminder, from, to, function addMonthly(parts, step) {
+		return addMonths(parts, step, anchor)
+	})
+}
+
+function expandYearly(reminder: Reminder, from: Date, to: Date): Date[] {
+	const anchor = getZonedParts(reminder.dueAt, reminder.timeZone).day
+	return expandStepped(reminder, from, to, function addYearly(parts, step) {
+		return addMonths(parts, step * 12, anchor)
+	})
+}
+
+function expandStepped(
+	reminder: Reminder,
+	from: Date,
+	to: Date,
+	addStep: (parts: ZonedDateTimeParts, step: number) => ZonedDateTimeParts,
+): Date[] {
+	const recurrence = reminder.recurrence
+	if (!recurrence) return []
+
+	const dates: Date[] = []
+	const start = getZonedParts(reminder.dueAt, reminder.timeZone)
+	let emitted = 0
+	let index = 0
+
+	while (true) {
+		const parts = addStep(start, index * recurrence.interval)
+		const dueAt = zonedPartsToDate(parts, reminder.timeZone)
+		if (isAfterRecurrenceEnd(dueAt, recurrence, emitted)) break
+		if (dueAt > to) break
+
+		if (dueAt >= from) {
+			dates.push(dueAt)
+		}
+
+		emitted++
+		index++
+	}
+
+	return dates
+}
+
+function expandWeekly(reminder: Reminder, from: Date, to: Date): Date[] {
+	const recurrence = reminder.recurrence
+	if (!recurrence) return []
+
+	const start = getZonedParts(reminder.dueAt, reminder.timeZone)
+	const startWeekday = weekdayForParts(start)
+	const weekStart = addDays(start, -startWeekday)
+	const weekdays = recurrence.weekdays?.length
+		? Array.from(new Set(recurrence.weekdays)).sort(compareNumbers)
+		: [startWeekday as ReminderWeekday]
+
+	const dates: Date[] = []
+	let emitted = 0
+	let weekIndex = 0
+
+	while (true) {
+		let weekHadFutureDate = false
+
+		for (const weekday of weekdays) {
+			const parts = addDays(weekStart, weekIndex * recurrence.interval * 7 + weekday)
+			const dueAt = zonedPartsToDate(parts, reminder.timeZone)
+			if (dueAt < reminder.dueAt) continue
+			if (isAfterRecurrenceEnd(dueAt, recurrence, emitted)) return dates
+			if (dueAt > to) {
+				weekHadFutureDate = true
+				continue
+			}
+
+			if (dueAt >= from) {
+				dates.push(dueAt)
+			}
+
+			emitted++
+		}
+
+		if (weekHadFutureDate) break
+		weekIndex++
+	}
+
+	return dates.sort(compareDates)
+}
+
+function createOccurrence(
+	reminder: Reminder,
+	originalDueAt: Date,
+	override: ReminderOccurrenceOverride | undefined,
+): ReminderOccurrence {
+	const patch = override?.patch
+
+	return {
+		reminderId: reminder.id,
+		occurrenceId: createReminderOccurrenceId(originalDueAt),
+		title: patch?.title ?? reminder.title,
+		notes: valueWithNullableOverride(reminder.notes, patch, "notes"),
+		originalDueAt,
+		dueAt: patch?.dueAt ?? originalDueAt,
+		timeZone: patch?.timeZone ?? reminder.timeZone,
+		recurrence: reminder.recurrence,
+		priority: patch?.priority ?? reminder.priority,
+		completedAt: override?.completedAt ?? null,
+	}
+}
+
+function valueWithNullableOverride(
+	fallback: string | null,
+	patch: ReminderOccurrencePatch | undefined,
+	key: "notes",
+): string | null {
+	if (!patch) return fallback
+	if (Object.prototype.hasOwnProperty.call(patch, key)) {
+		return patch[key] ?? null
+	}
+	return fallback
+}
+
+function isAfterRecurrenceEnd(
+	dueAt: Date,
+	recurrence: ReminderRecurrence,
+	emittedCount: number,
+): boolean {
+	if (recurrence.count !== undefined && emittedCount >= recurrence.count) {
+		return true
+	}
+	if (recurrence.until !== undefined && dueAt > recurrence.until) {
+		return true
+	}
+	return false
+}
+
+function getZonedParts(date: Date, timeZone: string): ZonedDateTimeParts {
+	const formatter = new Intl.DateTimeFormat("en-US", {
+		timeZone,
+		year: "numeric",
+		month: "2-digit",
+		day: "2-digit",
+		hour: "2-digit",
+		minute: "2-digit",
+		second: "2-digit",
+		hourCycle: "h23",
+	})
+
+	const parts = formatter.formatToParts(date)
+	return {
+		year: numberPart(parts, "year"),
+		month: numberPart(parts, "month"),
+		day: numberPart(parts, "day"),
+		hour: numberPart(parts, "hour"),
+		minute: numberPart(parts, "minute"),
+		second: numberPart(parts, "second"),
+		millisecond: date.getUTCMilliseconds(),
+	}
+}
+
+function zonedPartsToDate(parts: ZonedDateTimeParts, timeZone: string): Date {
+	const localAsUtc = Date.UTC(
+		parts.year,
+		parts.month - 1,
+		parts.day,
+		parts.hour,
+		parts.minute,
+		parts.second,
+		parts.millisecond,
+	)
+	let timestamp = localAsUtc
+
+	for (let i = 0; i < 3; i++) {
+		const offset = getTimeZoneOffsetMs(new Date(timestamp), timeZone)
+		const next = localAsUtc - offset
+		if (next === timestamp) break
+		timestamp = next
+	}
+
+	return new Date(timestamp)
+}
+
+function getTimeZoneOffsetMs(date: Date, timeZone: string): number {
+	const parts = getZonedParts(date, timeZone)
+	const zonedAsUtc = Date.UTC(
+		parts.year,
+		parts.month - 1,
+		parts.day,
+		parts.hour,
+		parts.minute,
+		parts.second,
+		parts.millisecond,
+	)
+
+	return zonedAsUtc - date.getTime()
+}
+
+function numberPart(parts: Intl.DateTimeFormatPart[], type: Intl.DateTimeFormatPartTypes): number {
+	const part = parts.find(function matchesType(value) {
+		return value.type === type
+	})
+	if (!part) {
+		throw new Error(`Missing ${type} part while formatting zoned date`)
+	}
+	return Number(part.value)
+}
+
+function addDays(parts: ZonedDateTimeParts, days: number): ZonedDateTimeParts {
+	const date = new Date(Date.UTC(parts.year, parts.month - 1, parts.day + days))
+	return {
+		...parts,
+		year: date.getUTCFullYear(),
+		month: date.getUTCMonth() + 1,
+		day: date.getUTCDate(),
+	}
+}
+
+function addMonths(
+	parts: ZonedDateTimeParts,
+	months: number,
+	anchorDay: number,
+): ZonedDateTimeParts {
+	const monthIndex = parts.year * 12 + parts.month - 1 + months
+	const year = Math.floor(monthIndex / 12)
+	const month = positiveModulo(monthIndex, 12) + 1
+	const day = Math.min(anchorDay, daysInMonth(year, month))
+
+	return {
+		...parts,
+		year,
+		month,
+		day,
+	}
+}
+
+function daysInMonth(year: number, month: number): number {
+	return new Date(Date.UTC(year, month, 0)).getUTCDate()
+}
+
+function weekdayForParts(parts: ZonedDateTimeParts): number {
+	return new Date(Date.UTC(parts.year, parts.month - 1, parts.day)).getUTCDay()
+}
+
+function positiveModulo(value: number, divisor: number): number {
+	return ((value % divisor) + divisor) % divisor
+}
+
+function compareDates(a: Date, b: Date): number {
+	return a.getTime() - b.getTime()
+}
+
+function compareNumbers(a: number, b: number): number {
+	return a - b
+}
+
+function compareOccurrences(a: ReminderOccurrence, b: ReminderOccurrence): number {
+	return a.dueAt.getTime() - b.dueAt.getTime()
+}

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

@@ -0,0 +1,706 @@
+import { Context, TimeRelevance } from "@freya/core"
+import { describe, expect, mock, test } from "bun:test"
+
+import type {
+	CreateReminderInput,
+	Reminder,
+	ReminderListParams,
+	ReminderOccurrenceOverride,
+	ReminderOccurrenceOverrideInput,
+	ReminderOccurrenceOverrideListParams,
+	ReminderPatch,
+	ReminderStorage,
+} from "./types.ts"
+
+import { ReminderSource } from "./reminder-source.ts"
+import {
+	ReminderAction,
+	ReminderEditScope,
+	ReminderPriority,
+	ReminderRecurrenceFrequency,
+	ReminderUpdateResultType,
+	ReminderWeekday,
+} from "./types.ts"
+
+class InMemoryReminderStorage implements ReminderStorage {
+	readonly reminders = new Map<string, Reminder>()
+	readonly overrides = new Map<string, ReminderOccurrenceOverride>()
+	private nextId = 1
+	private readonly listeners = new Set<() => void>()
+
+	constructor(reminders: Reminder[] = []) {
+		for (const reminder of reminders) {
+			this.reminders.set(reminder.id, reminder)
+		}
+	}
+
+	async listReminders(_params: ReminderListParams): Promise<Reminder[]> {
+		return Array.from(this.reminders.values())
+	}
+
+	async getReminder(id: string): Promise<Reminder | null> {
+		return this.reminders.get(id) ?? null
+	}
+
+	async createReminder(input: CreateReminderInput): Promise<Reminder> {
+		const now = new Date("2026-06-01T00:00:00Z")
+		const reminder: Reminder = {
+			id: `reminder-${this.nextId++}`,
+			title: input.title,
+			notes: input.notes ?? null,
+			dueAt: input.dueAt,
+			timeZone: input.timeZone ?? "UTC",
+			recurrence: input.recurrence ?? null,
+			priority: input.priority ?? ReminderPriority.Normal,
+			createdAt: now,
+			updatedAt: now,
+		}
+
+		this.reminders.set(reminder.id, reminder)
+		this.notify()
+		return reminder
+	}
+
+	async updateReminder(id: string, patch: ReminderPatch): Promise<Reminder> {
+		const existing = this.reminders.get(id)
+		if (!existing) {
+			throw new Error(`Reminder not found: ${id}`)
+		}
+
+		const updated: Reminder = {
+			...existing,
+			updatedAt: new Date("2026-06-01T00:01:00Z"),
+		}
+		if (hasOwn(patch, "title")) updated.title = patch.title
+		if (hasOwn(patch, "notes")) updated.notes = patch.notes ?? null
+		if (hasOwn(patch, "dueAt")) updated.dueAt = patch.dueAt
+		if (hasOwn(patch, "timeZone")) updated.timeZone = patch.timeZone
+		if (hasOwn(patch, "recurrence")) updated.recurrence = patch.recurrence ?? null
+		if (hasOwn(patch, "priority")) updated.priority = patch.priority
+
+		this.reminders.set(id, updated)
+		this.notify()
+		return updated
+	}
+
+	async deleteReminder(id: string): Promise<void> {
+		this.reminders.delete(id)
+		this.notify()
+	}
+
+	async listOccurrenceOverrides(
+		params: ReminderOccurrenceOverrideListParams,
+	): Promise<ReminderOccurrenceOverride[]> {
+		const reminderIds = new Set(params.reminderIds)
+		return Array.from(this.overrides.values()).filter(function matches(override) {
+			if (!reminderIds.has(override.reminderId)) return false
+			const dueAt = override.patch?.dueAt ?? override.originalDueAt
+			return (
+				isWithin(override.originalDueAt, params.from, params.to) ||
+				isWithin(dueAt, params.from, params.to)
+			)
+		})
+	}
+
+	async getOccurrenceOverride(
+		reminderId: string,
+		occurrenceId: string,
+	): Promise<ReminderOccurrenceOverride | null> {
+		return this.overrides.get(overrideKey(reminderId, occurrenceId)) ?? null
+	}
+
+	async upsertOccurrenceOverride(
+		input: ReminderOccurrenceOverrideInput,
+	): Promise<ReminderOccurrenceOverride> {
+		const existing = this.overrides.get(overrideKey(input.reminderId, input.occurrenceId))
+		const now = new Date("2026-06-01T00:02:00Z")
+		const override: ReminderOccurrenceOverride = {
+			...existing,
+			...input,
+			createdAt: existing?.createdAt ?? now,
+			updatedAt: now,
+		}
+
+		this.overrides.set(overrideKey(input.reminderId, input.occurrenceId), override)
+		this.notify()
+		return override
+	}
+
+	async deleteOccurrenceOverride(reminderId: string, occurrenceId: string): Promise<void> {
+		this.overrides.delete(overrideKey(reminderId, occurrenceId))
+		this.notify()
+	}
+
+	subscribe(callback: () => void): () => void {
+		this.listeners.add(callback)
+		return () => {
+			this.listeners.delete(callback)
+		}
+	}
+
+	private notify(): void {
+		for (const listener of this.listeners) {
+			listener()
+		}
+	}
+}
+
+function reminder(overrides: Partial<Reminder> = {}): Reminder {
+	const now = new Date("2026-06-01T00:00:00Z")
+	return {
+		id: "r1",
+		title: "Take vitamins",
+		notes: null,
+		dueAt: new Date("2026-06-12T09:00:00Z"),
+		timeZone: "UTC",
+		recurrence: null,
+		priority: ReminderPriority.Normal,
+		createdAt: now,
+		updatedAt: now,
+		...overrides,
+	}
+}
+
+function context(time: string): Context {
+	return new Context(new Date(time))
+}
+
+function overrideKey(reminderId: string, occurrenceId: string): string {
+	return `${reminderId}:${occurrenceId}`
+}
+
+function isWithin(date: Date, from: Date, to: Date): boolean {
+	return date >= from && date <= to
+}
+
+function hasOwn<TObject extends object, TKey extends keyof TObject>(
+	object: TObject,
+	key: TKey,
+): object is TObject & Required<Pick<TObject, TKey>> {
+	return Object.prototype.hasOwnProperty.call(object, key)
+}
+
+describe("ReminderSource", () => {
+	describe("FeedSource interface", () => {
+		test("has correct id and actions", async () => {
+			const source = new ReminderSource({ storage: new InMemoryReminderStorage() })
+
+			expect(source.id).toBe("freya.reminders")
+			const actions = await source.listActions()
+
+			expect(actions[ReminderAction.CreateReminder]?.id).toBe(ReminderAction.CreateReminder)
+			expect(actions[ReminderAction.UpdateReminder]?.id).toBe(ReminderAction.UpdateReminder)
+			expect(actions[ReminderAction.DeleteReminder]?.id).toBe(ReminderAction.DeleteReminder)
+			expect(actions[ReminderAction.CompleteReminder]?.id).toBe(ReminderAction.CompleteReminder)
+			expect(actions[ReminderAction.UncompleteReminder]?.id).toBe(ReminderAction.UncompleteReminder)
+		})
+
+		test("fetchContext returns null", async () => {
+			const source = new ReminderSource({ storage: new InMemoryReminderStorage() })
+
+			await expect(source.fetchContext(context("2026-06-12T09:00:00Z"))).resolves.toBeNull()
+		})
+
+		test("notifies item listeners after source actions", async () => {
+			const storage = new InMemoryReminderStorage()
+			const source = new ReminderSource({ storage })
+			const listener = mock()
+			source.onItemsUpdate(listener)
+
+			await source.createReminder({
+				title: "Buy milk",
+				dueAt: new Date("2026-06-12T18:00:00Z"),
+			})
+
+			expect(listener).toHaveBeenCalled()
+		})
+	})
+
+	describe("fetchItems", () => {
+		test("returns a one-off reminder occurrence", async () => {
+			const storage = new InMemoryReminderStorage([
+				reminder({
+					id: "buy-milk",
+					title: "Buy milk",
+					dueAt: new Date("2026-06-12T18:00:00Z"),
+				}),
+			])
+			const source = new ReminderSource({ storage, lookBackMs: 0 })
+
+			const items = await source.fetchItems(context("2026-06-12T12:00:00Z"))
+
+			expect(items).toHaveLength(1)
+			expect(items[0]!.data.title).toBe("Buy milk")
+			expect(items[0]!.data.reminderId).toBe("buy-milk")
+			expect(items[0]!.signals?.timeRelevance).toBe(TimeRelevance.Upcoming)
+		})
+
+		test("expands daily recurrence inside the feed window", async () => {
+			const storage = new InMemoryReminderStorage([
+				reminder({
+					dueAt: new Date("2026-06-10T09:00:00Z"),
+					recurrence: {
+						frequency: ReminderRecurrenceFrequency.Daily,
+						interval: 1,
+					},
+				}),
+			])
+			const source = new ReminderSource({
+				storage,
+				lookBackMs: 0,
+				lookAheadMs: 48 * 60 * 60 * 1000,
+			})
+
+			const items = await source.fetchItems(context("2026-06-12T00:00:00Z"))
+
+			expect(
+				items.map(function dueAt(item) {
+					return item.data.dueAt.toISOString()
+				}),
+			).toEqual(["2026-06-12T09:00:00.000Z", "2026-06-13T09:00:00.000Z"])
+		})
+
+		test("expands weekly recurrence on selected weekdays", async () => {
+			const storage = new InMemoryReminderStorage([
+				reminder({
+					dueAt: new Date("2026-06-08T09:00:00Z"),
+					recurrence: {
+						frequency: ReminderRecurrenceFrequency.Weekly,
+						interval: 1,
+						weekdays: [ReminderWeekday.Monday, ReminderWeekday.Wednesday, ReminderWeekday.Friday],
+					},
+				}),
+			])
+			const source = new ReminderSource({
+				storage,
+				lookBackMs: 0,
+				lookAheadMs: 6 * 24 * 60 * 60 * 1000,
+			})
+
+			const items = await source.fetchItems(context("2026-06-08T00:00:00Z"))
+
+			expect(
+				items.map(function dueAt(item) {
+					return item.data.dueAt.toISOString()
+				}),
+			).toEqual([
+				"2026-06-08T09:00:00.000Z",
+				"2026-06-10T09:00:00.000Z",
+				"2026-06-12T09:00:00.000Z",
+			])
+		})
+
+		test("deduplicates weekly weekdays before applying recurrence count", async () => {
+			const storage = new InMemoryReminderStorage([
+				reminder({
+					dueAt: new Date("2026-06-08T09:00:00Z"),
+					recurrence: {
+						frequency: ReminderRecurrenceFrequency.Weekly,
+						interval: 1,
+						weekdays: [ReminderWeekday.Monday, ReminderWeekday.Monday, ReminderWeekday.Wednesday],
+						count: 3,
+					},
+				}),
+			])
+			const source = new ReminderSource({
+				storage,
+				lookBackMs: 0,
+				lookAheadMs: 14 * 24 * 60 * 60 * 1000,
+			})
+
+			const items = await source.fetchItems(context("2026-06-08T00:00:00Z"))
+
+			expect(
+				items.map(function dueAt(item) {
+					return item.data.dueAt.toISOString()
+				}),
+			).toEqual([
+				"2026-06-08T09:00:00.000Z",
+				"2026-06-10T09:00:00.000Z",
+				"2026-06-15T09:00:00.000Z",
+			])
+		})
+
+		test("omits completed occurrences by default", async () => {
+			const storage = new InMemoryReminderStorage([
+				reminder({
+					dueAt: new Date("2026-06-12T09:00:00Z"),
+					recurrence: {
+						frequency: ReminderRecurrenceFrequency.Daily,
+						interval: 1,
+					},
+				}),
+			])
+			const source = new ReminderSource({
+				storage,
+				lookBackMs: 0,
+				lookAheadMs: 48 * 60 * 60 * 1000,
+			})
+
+			await source.completeReminder({
+				reminderId: "r1",
+				occurrenceDueAt: new Date("2026-06-12T09:00:00Z"),
+				completedAt: new Date("2026-06-12T09:05:00Z"),
+			})
+
+			const items = await source.fetchItems(context("2026-06-12T00:00:00Z"))
+
+			expect(
+				items.map(function dueAt(item) {
+					return item.data.dueAt.toISOString()
+				}),
+			).toEqual(["2026-06-13T09:00:00.000Z"])
+		})
+	})
+
+	describe("updates", () => {
+		test("updates one recurring occurrence through an override", async () => {
+			const storage = new InMemoryReminderStorage([
+				reminder({
+					dueAt: new Date("2026-06-12T09:00:00Z"),
+					recurrence: {
+						frequency: ReminderRecurrenceFrequency.Daily,
+						interval: 1,
+					},
+				}),
+			])
+			const source = new ReminderSource({
+				storage,
+				lookBackMs: 0,
+				lookAheadMs: 48 * 60 * 60 * 1000,
+			})
+
+			const result = await source.updateReminder({
+				reminderId: "r1",
+				scope: ReminderEditScope.ThisOccurrence,
+				occurrenceDueAt: new Date("2026-06-12T09:00:00Z"),
+				patch: {
+					title: "Take vitamins with breakfast",
+					dueAt: new Date("2026-06-12T10:00:00Z"),
+				},
+			})
+
+			expect(result.type).toBe(ReminderUpdateResultType.UpdatedOccurrence)
+			expect(storage.reminders.get("r1")?.title).toBe("Take vitamins")
+
+			const items = await source.fetchItems(context("2026-06-12T00:00:00Z"))
+			expect(items[0]!.data.title).toBe("Take vitamins with breakfast")
+			expect(items[0]!.data.dueAt.toISOString()).toBe("2026-06-12T10:00:00.000Z")
+			expect(items[1]!.data.title).toBe("Take vitamins")
+		})
+
+		test("updates an entire recurring reminder", async () => {
+			const storage = new InMemoryReminderStorage([
+				reminder({
+					dueAt: new Date("2026-06-12T09:00:00Z"),
+					recurrence: {
+						frequency: ReminderRecurrenceFrequency.Daily,
+						interval: 1,
+					},
+				}),
+			])
+			const source = new ReminderSource({
+				storage,
+				lookBackMs: 0,
+				lookAheadMs: 48 * 60 * 60 * 1000,
+			})
+
+			await source.updateReminder({
+				reminderId: "r1",
+				scope: ReminderEditScope.EntireSeries,
+				patch: { title: "Take medication" },
+			})
+
+			const items = await source.fetchItems(context("2026-06-12T00:00:00Z"))
+			expect(
+				items.map(function title(item) {
+					return item.data.title
+				}),
+			).toEqual(["Take medication", "Take medication"])
+		})
+
+		test("splits a recurring reminder for this-and-future updates", async () => {
+			const storage = new InMemoryReminderStorage([
+				reminder({
+					dueAt: new Date("2026-06-10T09:00:00Z"),
+					recurrence: {
+						frequency: ReminderRecurrenceFrequency.Daily,
+						interval: 1,
+					},
+				}),
+			])
+			const source = new ReminderSource({
+				storage,
+				lookBackMs: 0,
+				lookAheadMs: 48 * 60 * 60 * 1000,
+			})
+
+			const result = await source.updateReminder({
+				reminderId: "r1",
+				scope: ReminderEditScope.ThisAndFuture,
+				occurrenceDueAt: new Date("2026-06-12T09:00:00Z"),
+				patch: {
+					title: "Take vitamins later",
+					dueAt: new Date("2026-06-12T10:00:00Z"),
+				},
+			})
+
+			expect(result.type).toBe(ReminderUpdateResultType.SplitReminder)
+			expect(storage.reminders.size).toBe(2)
+			expect(storage.reminders.get("r1")?.recurrence?.count).toBe(2)
+
+			const items = await source.fetchItems(context("2026-06-12T00:00:00Z"))
+			expect(
+				items.map(function itemLabel(item) {
+					return `${item.data.title}:${item.data.dueAt.toISOString()}`
+				}),
+			).toEqual([
+				"Take vitamins later:2026-06-12T10:00:00.000Z",
+				"Take vitamins later:2026-06-13T10:00:00.000Z",
+			])
+		})
+
+		test("updates weekly weekdays when a this-and-future split moves weekday", async () => {
+			const storage = new InMemoryReminderStorage([
+				reminder({
+					dueAt: new Date("2026-06-08T09:00:00Z"),
+					recurrence: {
+						frequency: ReminderRecurrenceFrequency.Weekly,
+						interval: 1,
+						weekdays: [ReminderWeekday.Monday],
+					},
+				}),
+			])
+			const source = new ReminderSource({
+				storage,
+				lookBackMs: 0,
+				lookAheadMs: 14 * 24 * 60 * 60 * 1000,
+			})
+
+			const result = await source.updateReminder({
+				reminderId: "r1",
+				scope: ReminderEditScope.ThisAndFuture,
+				occurrenceDueAt: new Date("2026-06-15T09:00:00Z"),
+				patch: {
+					dueAt: new Date("2026-06-16T09:00:00Z"),
+				},
+			})
+
+			expect(result.type).toBe(ReminderUpdateResultType.SplitReminder)
+			expect(
+				result.type === ReminderUpdateResultType.SplitReminder
+					? result.newReminder.recurrence?.weekdays
+					: null,
+			).toEqual([ReminderWeekday.Tuesday])
+
+			const items = await source.fetchItems(context("2026-06-15T00:00:00Z"))
+			expect(
+				items.map(function dueAt(item) {
+					return item.data.dueAt.toISOString()
+				}),
+			).toEqual(["2026-06-16T09:00:00.000Z", "2026-06-23T09:00:00.000Z"])
+		})
+
+		test("collapses single-occurrence updates on one-off reminders to the reminder", async () => {
+			const storage = new InMemoryReminderStorage([reminder()])
+			const source = new ReminderSource({ storage, lookBackMs: 0 })
+
+			await source.updateReminder({
+				reminderId: "r1",
+				scope: ReminderEditScope.ThisOccurrence,
+				occurrenceDueAt: new Date("2026-06-12T09:00:00Z"),
+				patch: { title: "Take supplements" },
+			})
+
+			expect(storage.reminders.get("r1")?.title).toBe("Take supplements")
+			expect(storage.overrides.size).toBe(0)
+		})
+
+		test("rejects one-off scoped updates with a mismatched occurrence", async () => {
+			const storage = new InMemoryReminderStorage([reminder()])
+			const source = new ReminderSource({ storage, lookBackMs: 0 })
+			const staleDueAt = new Date("2026-06-13T09:00:00Z")
+
+			for (const scope of [ReminderEditScope.ThisOccurrence, ReminderEditScope.ThisAndFuture]) {
+				await expect(
+					source.updateReminder({
+						reminderId: "r1",
+						scope,
+						occurrenceDueAt: staleDueAt,
+						patch: { title: "Should not apply" },
+					}),
+				).rejects.toThrow("occurrenceDueAt does not match this reminder")
+			}
+
+			expect(storage.reminders.get("r1")?.title).toBe("Take vitamins")
+			expect(storage.overrides.size).toBe(0)
+		})
+	})
+
+	describe("deletes", () => {
+		test("collapses single-occurrence deletes on one-off reminders to the reminder", async () => {
+			const storage = new InMemoryReminderStorage([reminder()])
+			const source = new ReminderSource({ storage, lookBackMs: 0 })
+
+			await source.deleteReminder({
+				reminderId: "r1",
+				scope: ReminderEditScope.ThisOccurrence,
+				occurrenceDueAt: new Date("2026-06-12T09:00:00Z"),
+			})
+
+			expect(storage.reminders.has("r1")).toBe(false)
+			expect(storage.overrides.size).toBe(0)
+		})
+
+		test("rejects one-off scoped deletes with a mismatched occurrence", async () => {
+			const storage = new InMemoryReminderStorage([reminder()])
+			const source = new ReminderSource({ storage, lookBackMs: 0 })
+			const staleDueAt = new Date("2026-06-13T09:00:00Z")
+
+			for (const scope of [ReminderEditScope.ThisOccurrence, ReminderEditScope.ThisAndFuture]) {
+				await expect(
+					source.deleteReminder({
+						reminderId: "r1",
+						scope,
+						occurrenceDueAt: staleDueAt,
+					}),
+				).rejects.toThrow("occurrenceDueAt does not match this reminder")
+			}
+
+			expect(storage.reminders.has("r1")).toBe(true)
+			expect(storage.overrides.size).toBe(0)
+		})
+
+		test("deletes one recurring occurrence through an override", async () => {
+			const storage = new InMemoryReminderStorage([
+				reminder({
+					dueAt: new Date("2026-06-12T09:00:00Z"),
+					recurrence: {
+						frequency: ReminderRecurrenceFrequency.Daily,
+						interval: 1,
+					},
+				}),
+			])
+			const source = new ReminderSource({
+				storage,
+				lookBackMs: 0,
+				lookAheadMs: 48 * 60 * 60 * 1000,
+			})
+
+			await source.deleteReminder({
+				reminderId: "r1",
+				scope: ReminderEditScope.ThisOccurrence,
+				occurrenceDueAt: new Date("2026-06-12T09:00:00Z"),
+			})
+
+			const items = await source.fetchItems(context("2026-06-12T00:00:00Z"))
+			expect(
+				items.map(function dueAt(item) {
+					return item.data.dueAt.toISOString()
+				}),
+			).toEqual(["2026-06-13T09:00:00.000Z"])
+		})
+
+		test("deduplicates weekly weekdays before ending this and future", async () => {
+			const storage = new InMemoryReminderStorage([
+				reminder({
+					dueAt: new Date("2026-06-08T09:00:00Z"),
+					recurrence: {
+						frequency: ReminderRecurrenceFrequency.Weekly,
+						interval: 1,
+						weekdays: [ReminderWeekday.Monday, ReminderWeekday.Monday, ReminderWeekday.Wednesday],
+					},
+				}),
+			])
+			const source = new ReminderSource({
+				storage,
+				lookBackMs: 0,
+				lookAheadMs: 14 * 24 * 60 * 60 * 1000,
+			})
+
+			await source.deleteReminder({
+				reminderId: "r1",
+				scope: ReminderEditScope.ThisAndFuture,
+				occurrenceDueAt: new Date("2026-06-10T09:00:00Z"),
+			})
+
+			expect(storage.reminders.get("r1")?.recurrence?.count).toBe(1)
+
+			const items = await source.fetchItems(context("2026-06-08T00:00:00Z"))
+			expect(
+				items.map(function dueAt(item) {
+					return item.data.dueAt.toISOString()
+				}),
+			).toEqual(["2026-06-08T09:00:00.000Z"])
+		})
+
+		test("ignores stale future overrides after deleting this and future", async () => {
+			const storage = new InMemoryReminderStorage([
+				reminder({
+					dueAt: new Date("2026-06-10T09:00:00Z"),
+					recurrence: {
+						frequency: ReminderRecurrenceFrequency.Daily,
+						interval: 1,
+					},
+				}),
+			])
+			const source = new ReminderSource({
+				storage,
+				lookBackMs: 0,
+				lookAheadMs: 48 * 60 * 60 * 1000,
+			})
+
+			await source.updateReminder({
+				reminderId: "r1",
+				scope: ReminderEditScope.ThisOccurrence,
+				occurrenceDueAt: new Date("2026-06-12T09:00:00Z"),
+				patch: {
+					title: "Take vitamins later",
+					dueAt: new Date("2026-06-12T10:00:00Z"),
+				},
+			})
+			expect(storage.overrides.size).toBe(1)
+
+			await source.deleteReminder({
+				reminderId: "r1",
+				scope: ReminderEditScope.ThisAndFuture,
+				occurrenceDueAt: new Date("2026-06-12T09:00:00Z"),
+			})
+
+			const items = await source.fetchItems(context("2026-06-12T00:00:00Z"))
+
+			expect(items).toEqual([])
+		})
+	})
+
+	describe("actions", () => {
+		test("executeAction creates reminders from ISO date input", async () => {
+			const storage = new InMemoryReminderStorage()
+			const source = new ReminderSource({
+				storage,
+				lookBackMs: 0,
+				lookAheadMs: 48 * 60 * 60 * 1000,
+			})
+
+			const created = await source.executeAction(ReminderAction.CreateReminder, {
+				title: "Review notes",
+				dueAt: "2026-06-12T15:00:00Z",
+				recurrence: {
+					frequency: "daily",
+					interval: 1,
+					count: 2,
+				},
+			})
+
+			expect((created as Reminder).id).toBe("reminder-1")
+			const items = await source.fetchItems(context("2026-06-12T12:00:00Z"))
+			expect(items).toHaveLength(2)
+		})
+
+		test("executeAction rejects unknown actions", async () => {
+			const source = new ReminderSource({ storage: new InMemoryReminderStorage() })
+
+			await expect(source.executeAction("missing", {})).rejects.toThrow("Unknown action")
+		})
+	})
+})

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

@@ -0,0 +1,633 @@
+import type {
+	ActionDefinition,
+	Context,
+	ContextEntry,
+	FeedItemSignals,
+	FeedSource,
+} from "@freya/core"
+
+import { TimeRelevance, UnknownActionError } from "@freya/core"
+import { type } from "arktype"
+
+import type {
+	CompleteReminderInput,
+	CreateReminderInput,
+	DeleteReminderInput,
+	Reminder,
+	ReminderDeleteResult,
+	ReminderEditScope,
+	ReminderFeedItem,
+	ReminderOccurrence,
+	ReminderOccurrenceOverride,
+	ReminderOccurrenceOverrideInput,
+	ReminderOccurrencePatch,
+	ReminderPatch,
+	ReminderPriority,
+	ReminderStorage,
+	ReminderUpdateResult,
+	UncompleteReminderInput,
+	UpdateReminderInput,
+} from "./types.ts"
+
+import {
+	createReminderOccurrenceId,
+	expandReminderOccurrences,
+	findReminderOccurrenceIndex,
+	recurrenceAfterSplit,
+	stopRecurrenceAfterOccurrenceCount,
+} from "./recurrence.ts"
+import {
+	CompleteReminderInput as CompleteReminderInputSchema,
+	DeleteReminderInput as DeleteReminderInputSchema,
+	ReminderAction,
+	ReminderDeleteResultType,
+	ReminderEditScope as ReminderEditScopeValue,
+	ReminderFeedItemType,
+	ReminderPriority as ReminderPriorityValue,
+	ReminderRecurrenceFrequency,
+	ReminderTimeZoneInput,
+	ReminderUpdateResultType,
+	ReminderWeekday,
+	UncompleteReminderInput as UncompleteReminderInputSchema,
+	UpdateReminderInput as UpdateReminderInputSchema,
+	createReminderInputSchema,
+} from "./types.ts"
+
+interface ArkSchema<T> {
+	(value: unknown): T | InstanceType<typeof type.errors>
+}
+
+export interface ReminderSourceOptions {
+	storage: ReminderStorage
+	/** Default: 24 hours. */
+	lookAheadMs?: number
+	/** Default: 24 hours, so earlier reminders from today remain visible. */
+	lookBackMs?: number
+	/** Default: false. */
+	includeCompleted?: boolean
+	/** Default: UTC. Used when create input omits timeZone. */
+	defaultTimeZone?: string
+}
+
+const DEFAULT_LOOK_AHEAD_MS = 24 * 60 * 60 * 1000
+const DEFAULT_LOOK_BACK_MS = 24 * 60 * 60 * 1000
+const DEFAULT_TIME_ZONE = "UTC"
+
+const FIFTEEN_MINUTES_MS = 15 * 60 * 1000
+const ONE_HOUR_MS = 60 * 60 * 1000
+const ONE_DAY_MS = 24 * 60 * 60 * 1000
+
+/**
+ * FeedSource for one-off and recurring reminders.
+ *
+ * ReminderSource stores only canonical reminders plus occurrence overrides.
+ * It owns recurrence expansion, edit-scope semantics, and feed item signals.
+ */
+export class ReminderSource implements FeedSource<ReminderFeedItem> {
+	readonly id = "freya.reminders"
+
+	private readonly storage: ReminderStorage
+	private readonly lookAheadMs: number
+	private readonly lookBackMs: number
+	private readonly includeCompleted: boolean
+	private readonly defaultTimeZone: string
+	private readonly createReminderInput: ReturnType<typeof createReminderInputSchema>
+	private readonly itemListeners = new Set<(items: ReminderFeedItem[]) => void>()
+
+	constructor(options: ReminderSourceOptions) {
+		this.storage = options.storage
+		this.lookAheadMs = options.lookAheadMs ?? DEFAULT_LOOK_AHEAD_MS
+		this.lookBackMs = options.lookBackMs ?? DEFAULT_LOOK_BACK_MS
+		this.includeCompleted = options.includeCompleted ?? false
+		this.defaultTimeZone = options.defaultTimeZone ?? DEFAULT_TIME_ZONE
+		assertSchema(ReminderTimeZoneInput, this.defaultTimeZone)
+		this.createReminderInput = createReminderInputSchema(this.defaultTimeZone)
+	}
+
+	async listActions(): Promise<Record<string, ActionDefinition>> {
+		return {
+			[ReminderAction.CreateReminder]: {
+				id: ReminderAction.CreateReminder,
+				description: "Create a reminder",
+			},
+			[ReminderAction.UpdateReminder]: {
+				id: ReminderAction.UpdateReminder,
+				description: "Update a reminder or scoped recurrence occurrence",
+			},
+			[ReminderAction.DeleteReminder]: {
+				id: ReminderAction.DeleteReminder,
+				description: "Delete a reminder or scoped recurrence occurrence",
+			},
+			[ReminderAction.CompleteReminder]: {
+				id: ReminderAction.CompleteReminder,
+				description: "Complete a reminder occurrence",
+			},
+			[ReminderAction.UncompleteReminder]: {
+				id: ReminderAction.UncompleteReminder,
+				description: "Clear completion for a reminder occurrence",
+			},
+		}
+	}
+
+	async executeAction(actionId: string, params: unknown): Promise<unknown> {
+		switch (actionId) {
+			case ReminderAction.CreateReminder:
+				return this.createReminder(assertSchema(this.createReminderInput, params))
+			case ReminderAction.UpdateReminder:
+				return this.updateReminder(assertSchema(UpdateReminderInputSchema, params))
+			case ReminderAction.DeleteReminder:
+				return this.deleteReminder(assertSchema(DeleteReminderInputSchema, params))
+			case ReminderAction.CompleteReminder:
+				return this.completeReminder(assertSchema(CompleteReminderInputSchema, params))
+			case ReminderAction.UncompleteReminder:
+				return this.uncompleteReminder(assertSchema(UncompleteReminderInputSchema, params))
+			default:
+				throw new UnknownActionError(actionId)
+		}
+	}
+
+	async fetchContext(_context: Context): Promise<readonly ContextEntry[] | null> {
+		return null
+	}
+
+	onItemsUpdate(callback: (items: ReminderFeedItem[]) => void): () => void {
+		this.itemListeners.add(callback)
+		const cleanupStorage = this.storage.subscribe?.(() => {
+			this.notifyItemsChanged()
+		})
+
+		return () => {
+			this.itemListeners.delete(callback)
+			cleanupStorage?.()
+		}
+	}
+
+	async fetchItems(context: Context): Promise<ReminderFeedItem[]> {
+		const from = new Date(context.time.getTime() - this.lookBackMs)
+		const to = new Date(context.time.getTime() + this.lookAheadMs)
+		const reminders = await this.storage.listReminders({
+			from,
+			to,
+			includeCompleted: this.includeCompleted,
+		})
+
+		if (reminders.length === 0) return []
+
+		const reminderIds = reminders.map(function reminderId(reminder) {
+			return reminder.id
+		})
+		const overrides = await this.storage.listOccurrenceOverrides({ reminderIds, from, to })
+		const overridesByReminderId = groupOverridesByReminderId(overrides)
+
+		const items: ReminderFeedItem[] = []
+		for (const reminder of reminders) {
+			const occurrences = expandReminderOccurrences(reminder, {
+				from,
+				to,
+				includeCompleted: this.includeCompleted,
+				overrides: overridesByReminderId.get(reminder.id),
+			})
+
+			for (const occurrence of occurrences) {
+				items.push(createFeedItem(occurrence, context.time, this.id))
+			}
+		}
+
+		return items.sort(compareFeedItems)
+	}
+
+	async createReminder(input: CreateReminderInput): Promise<Reminder> {
+		const reminder = await this.storage.createReminder(
+			assertSchema(this.createReminderInput, input),
+		)
+		this.notifyItemsChanged()
+		return reminder
+	}
+
+	async updateReminder(input: UpdateReminderInput): Promise<ReminderUpdateResult> {
+		const parsed = assertSchema(UpdateReminderInputSchema, input)
+		const reminder = await this.requireReminder(parsed.reminderId)
+		const result = await this.updateExistingReminder(reminder, parsed)
+		this.notifyItemsChanged()
+		return result
+	}
+
+	async deleteReminder(input: DeleteReminderInput): Promise<ReminderDeleteResult> {
+		const parsed = assertSchema(DeleteReminderInputSchema, input)
+		const reminder = await this.requireReminder(parsed.reminderId)
+		const result = await this.deleteExistingReminder(reminder, parsed)
+		this.notifyItemsChanged()
+		return result
+	}
+
+	async completeReminder(input: CompleteReminderInput): Promise<ReminderOccurrenceOverride> {
+		const parsed = assertSchema(CompleteReminderInputSchema, input)
+		const reminder = await this.requireReminder(parsed.reminderId)
+		const occurrenceDueAt = parsed.occurrenceDueAt
+		this.requireKnownOccurrence(reminder, occurrenceDueAt)
+
+		const override = await this.mergeOccurrenceOverride(reminder.id, occurrenceDueAt, {
+			completedAt: parsed.completedAt ?? new Date(),
+			deletedAt: null,
+		})
+
+		this.notifyItemsChanged()
+		return override
+	}
+
+	async uncompleteReminder(input: UncompleteReminderInput): Promise<ReminderOccurrenceOverride> {
+		const parsed = assertSchema(UncompleteReminderInputSchema, input)
+		const reminder = await this.requireReminder(parsed.reminderId)
+		const occurrenceDueAt = parsed.occurrenceDueAt
+		this.requireKnownOccurrence(reminder, occurrenceDueAt)
+
+		const override = await this.mergeOccurrenceOverride(reminder.id, occurrenceDueAt, {
+			completedAt: null,
+		})
+
+		this.notifyItemsChanged()
+		return override
+	}
+
+	private async updateExistingReminder(
+		reminder: Reminder,
+		input: UpdateReminderInput,
+	): Promise<ReminderUpdateResult> {
+		if (input.scope === ReminderEditScopeValue.EntireSeries) {
+			const updated = await this.storage.updateReminder(reminder.id, input.patch)
+			return {
+				type: ReminderUpdateResultType.UpdatedReminder,
+				reminder: updated,
+			}
+		}
+
+		const occurrenceDueAt = requireOccurrenceDueAt(input)
+		this.requireKnownOccurrence(reminder, occurrenceDueAt)
+
+		if (!reminder.recurrence) {
+			const updated = await this.storage.updateReminder(reminder.id, input.patch)
+			return {
+				type: ReminderUpdateResultType.UpdatedReminder,
+				reminder: updated,
+			}
+		}
+
+		if (input.scope === ReminderEditScopeValue.ThisOccurrence) {
+			if (hasOwn(input.patch, "recurrence")) {
+				throw new Error("recurrence cannot be changed for a single occurrence")
+			}
+
+			const { recurrence: _recurrence, ...occurrencePatch } = input.patch
+			const override = await this.mergeOccurrenceOverride(reminder.id, occurrenceDueAt, {
+				patch: occurrencePatch,
+			})
+			return {
+				type: ReminderUpdateResultType.UpdatedOccurrence,
+				override,
+			}
+		}
+
+		return this.splitReminder(reminder, occurrenceDueAt, input.patch)
+	}
+
+	private async deleteExistingReminder(
+		reminder: Reminder,
+		input: DeleteReminderInput,
+	): Promise<ReminderDeleteResult> {
+		if (input.scope === ReminderEditScopeValue.EntireSeries) {
+			await this.storage.deleteReminder(reminder.id)
+			return { type: ReminderDeleteResultType.DeletedReminder }
+		}
+
+		const occurrenceDueAt = requireOccurrenceDueAt(input)
+		this.requireKnownOccurrence(reminder, occurrenceDueAt)
+
+		if (!reminder.recurrence) {
+			await this.storage.deleteReminder(reminder.id)
+			return { type: ReminderDeleteResultType.DeletedReminder }
+		}
+
+		if (input.scope === ReminderEditScopeValue.ThisOccurrence) {
+			const override = await this.mergeOccurrenceOverride(reminder.id, occurrenceDueAt, {
+				deletedAt: new Date(),
+			})
+			return {
+				type: ReminderDeleteResultType.DeletedOccurrence,
+				override,
+			}
+		}
+
+		const occurrenceIndex = findReminderOccurrenceIndex(reminder, occurrenceDueAt)
+		if (occurrenceIndex === null) {
+			throw new Error("occurrenceDueAt does not match this reminder")
+		}
+		if (occurrenceIndex === 0) {
+			await this.storage.deleteReminder(reminder.id)
+			return { type: ReminderDeleteResultType.DeletedReminder }
+		}
+
+		const recurrence = stopRecurrenceAfterOccurrenceCount(reminder.recurrence, occurrenceIndex)
+		const updated = await this.storage.updateReminder(reminder.id, { recurrence })
+		return {
+			type: ReminderDeleteResultType.EndedReminder,
+			reminder: updated,
+		}
+	}
+
+	private async splitReminder(
+		reminder: Reminder,
+		occurrenceDueAt: Date,
+		patch: ReminderPatch,
+	): Promise<ReminderUpdateResult> {
+		if (!reminder.recurrence) {
+			const updated = await this.storage.updateReminder(reminder.id, patch)
+			return {
+				type: ReminderUpdateResultType.UpdatedReminder,
+				reminder: updated,
+			}
+		}
+
+		const occurrenceIndex = findReminderOccurrenceIndex(reminder, occurrenceDueAt)
+		if (occurrenceIndex === null) {
+			throw new Error("occurrenceDueAt does not match this reminder")
+		}
+
+		if (occurrenceIndex === 0) {
+			const updated = await this.storage.updateReminder(reminder.id, patch)
+			return {
+				type: ReminderUpdateResultType.UpdatedReminder,
+				reminder: updated,
+			}
+		}
+
+		const previousRecurrence = stopRecurrenceAfterOccurrenceCount(
+			reminder.recurrence,
+			occurrenceIndex,
+		)
+		const previousReminder = await this.storage.updateReminder(reminder.id, {
+			recurrence: previousRecurrence,
+		})
+		const newReminder = await this.storage.createReminder(
+			createSplitReminderInput(reminder, occurrenceDueAt, occurrenceIndex, patch),
+		)
+
+		return {
+			type: ReminderUpdateResultType.SplitReminder,
+			previousReminder,
+			newReminder,
+		}
+	}
+
+	private requireKnownOccurrence(reminder: Reminder, occurrenceDueAt: Date): void {
+		const occurrenceIndex = findReminderOccurrenceIndex(reminder, occurrenceDueAt)
+		if (occurrenceIndex === null) {
+			throw new Error("occurrenceDueAt does not match this reminder")
+		}
+	}
+
+	private async requireReminder(id: string): Promise<Reminder> {
+		const reminder = await this.storage.getReminder(id)
+		if (!reminder) {
+			throw new Error(`Reminder not found: ${id}`)
+		}
+		return reminder
+	}
+
+	private async mergeOccurrenceOverride(
+		reminderId: string,
+		originalDueAt: Date,
+		patch: Partial<ReminderOccurrenceOverrideInput>,
+	): Promise<ReminderOccurrenceOverride> {
+		const occurrenceId = createReminderOccurrenceId(originalDueAt)
+		const existing = await this.storage.getOccurrenceOverride(reminderId, occurrenceId)
+
+		const input: ReminderOccurrenceOverrideInput = {
+			reminderId,
+			occurrenceId,
+			originalDueAt,
+			patch: mergeOccurrencePatch(existing?.patch, patch.patch),
+			completedAt: hasOwn(patch, "completedAt")
+				? (patch.completedAt ?? null)
+				: existing?.completedAt,
+			deletedAt: hasOwn(patch, "deletedAt") ? (patch.deletedAt ?? null) : existing?.deletedAt,
+		}
+
+		return this.storage.upsertOccurrenceOverride(input)
+	}
+
+	private notifyItemsChanged(): void {
+		for (const listener of this.itemListeners) {
+			listener([])
+		}
+	}
+}
+
+function createFeedItem(
+	occurrence: ReminderOccurrence,
+	now: Date,
+	sourceId: string,
+): ReminderFeedItem {
+	return {
+		id: `reminder-${occurrence.reminderId}-${occurrence.occurrenceId}`,
+		sourceId,
+		type: ReminderFeedItemType.Reminder,
+		timestamp: now,
+		data: {
+			reminderId: occurrence.reminderId,
+			occurrenceId: occurrence.occurrenceId,
+			title: occurrence.title,
+			notes: occurrence.notes,
+			originalDueAt: occurrence.originalDueAt,
+			dueAt: occurrence.dueAt,
+			timeZone: occurrence.timeZone,
+			recurrence: occurrence.recurrence,
+			priority: occurrence.priority,
+			completedAt: occurrence.completedAt,
+		},
+		signals: computeSignals(occurrence, now),
+	}
+}
+
+function computeSignals(occurrence: ReminderOccurrence, now: Date): FeedItemSignals {
+	if (occurrence.completedAt) {
+		return { urgency: 0, timeRelevance: TimeRelevance.Ambient }
+	}
+
+	const msUntilDue = occurrence.dueAt.getTime() - now.getTime()
+	let urgency: number
+	let timeRelevance: TimeRelevance
+
+	if (msUntilDue < 0) {
+		urgency = 1
+		timeRelevance = TimeRelevance.Imminent
+	} else if (msUntilDue <= FIFTEEN_MINUTES_MS) {
+		urgency = 0.95
+		timeRelevance = TimeRelevance.Imminent
+	} else if (msUntilDue <= ONE_HOUR_MS) {
+		urgency = 0.8
+		timeRelevance = TimeRelevance.Imminent
+	} else if (msUntilDue <= ONE_DAY_MS) {
+		urgency = 0.5
+		timeRelevance = TimeRelevance.Upcoming
+	} else {
+		urgency = 0.2
+		timeRelevance = TimeRelevance.Ambient
+	}
+
+	return {
+		urgency: clamp01(urgency + priorityUrgencyAdjustment(occurrence.priority)),
+		timeRelevance,
+	}
+}
+
+function createSplitReminderInput(
+	reminder: Reminder,
+	occurrenceDueAt: Date,
+	occurrenceIndex: number,
+	patch: ReminderPatch,
+): CreateReminderInput {
+	const dueAt = patch.dueAt ?? occurrenceDueAt
+	const timeZone = patch.timeZone ?? reminder.timeZone
+	const recurrence = hasOwn(patch, "recurrence")
+		? (patch.recurrence ?? null)
+		: alignSplitRecurrence(
+				recurrenceAfterSplit(reminder.recurrence!, occurrenceIndex),
+				occurrenceDueAt,
+				reminder.timeZone,
+				dueAt,
+				timeZone,
+			)
+
+	return {
+		title: patch.title ?? reminder.title,
+		notes: hasOwn(patch, "notes") ? (patch.notes ?? null) : reminder.notes,
+		dueAt,
+		timeZone,
+		recurrence,
+		priority: patch.priority ?? reminder.priority,
+	}
+}
+
+function alignSplitRecurrence(
+	recurrence: Reminder["recurrence"],
+	occurrenceDueAt: Date,
+	occurrenceTimeZone: string,
+	dueAt: Date,
+	timeZone: string,
+): Reminder["recurrence"] {
+	if (
+		!recurrence ||
+		recurrence.frequency !== ReminderRecurrenceFrequency.Weekly ||
+		!recurrence.weekdays?.length
+	) {
+		return recurrence
+	}
+
+	const previousWeekday = weekdayForDate(occurrenceDueAt, occurrenceTimeZone)
+	const nextWeekday = weekdayForDate(dueAt, timeZone)
+	if (previousWeekday === nextWeekday || recurrence.weekdays.includes(nextWeekday)) {
+		return recurrence
+	}
+
+	const weekdays = recurrence.weekdays
+		.filter(function keepOtherWeekdays(weekday) {
+			return weekday !== previousWeekday
+		})
+		.concat(nextWeekday)
+		.sort(compareWeekdays)
+
+	return { ...recurrence, weekdays }
+}
+
+function weekdayForDate(date: Date, timeZone: string): ReminderWeekday {
+	const parts = new Intl.DateTimeFormat("en-US", {
+		timeZone,
+		year: "numeric",
+		month: "2-digit",
+		day: "2-digit",
+	}).formatToParts(date)
+
+	const year = numberDatePart(parts, "year")
+	const month = numberDatePart(parts, "month")
+	const day = numberDatePart(parts, "day")
+	return new Date(Date.UTC(year, month - 1, day)).getUTCDay() as ReminderWeekday
+}
+
+function numberDatePart(
+	parts: Intl.DateTimeFormatPart[],
+	type: Intl.DateTimeFormatPartTypes,
+): number {
+	const part = parts.find(function matchesType(value) {
+		return value.type === type
+	})
+	if (!part) {
+		throw new Error(`Missing ${type} part while formatting reminder date`)
+	}
+	return Number(part.value)
+}
+
+function compareWeekdays(a: ReminderWeekday, b: ReminderWeekday): number {
+	return a - b
+}
+
+function mergeOccurrencePatch(
+	existing: ReminderOccurrencePatch | undefined,
+	next: ReminderOccurrencePatch | undefined,
+): ReminderOccurrencePatch | undefined {
+	if (!existing) return next
+	if (!next) return existing
+	return { ...existing, ...next }
+}
+
+function groupOverridesByReminderId(
+	overrides: readonly ReminderOccurrenceOverride[],
+): Map<string, ReminderOccurrenceOverride[]> {
+	const grouped = new Map<string, ReminderOccurrenceOverride[]>()
+	for (const override of overrides) {
+		const list = grouped.get(override.reminderId) ?? []
+		list.push(override)
+		grouped.set(override.reminderId, list)
+	}
+	return grouped
+}
+
+function priorityUrgencyAdjustment(priority: ReminderPriority): number {
+	switch (priority) {
+		case ReminderPriorityValue.High:
+			return 0.1
+		case ReminderPriorityValue.Low:
+			return -0.1
+		case ReminderPriorityValue.Normal:
+			return 0
+	}
+}
+
+function requireOccurrenceDueAt(input: { scope: ReminderEditScope; occurrenceDueAt?: Date }): Date {
+	if (!input.occurrenceDueAt) {
+		throw new Error(`${input.scope} requires occurrenceDueAt`)
+	}
+	return input.occurrenceDueAt
+}
+
+function assertSchema<T>(schema: ArkSchema<T>, value: unknown): T {
+	const result = schema(value)
+	if (result instanceof type.errors) {
+		throw new Error(result.summary)
+	}
+	return result
+}
+
+function hasOwn<TObject extends object, TKey extends PropertyKey>(
+	object: TObject,
+	key: TKey,
+): object is TObject & Record<TKey, unknown> {
+	return Object.prototype.hasOwnProperty.call(object, key)
+}
+
+function clamp01(value: number): number {
+	return Math.max(0, Math.min(1, value))
+}
+
+function compareFeedItems(a: ReminderFeedItem, b: ReminderFeedItem): number {
+	return a.data.dueAt.getTime() - b.data.dueAt.getTime()
+}

packages/freya-source-reminders/src/renderer.tsx

@@ -0,0 +1,62 @@
+/** @jsxImportSource @nym.sh/jrx */
+
+import type { FeedItemRenderer } from "@freya/core"
+
+import { FeedCard, SansSerifText, SerifText } from "@freya/components"
+
+import type { ReminderOccurrenceData } from "./types.ts"
+
+import { ReminderPriority, ReminderRecurrenceFrequency } from "./types.ts"
+
+export const renderReminderFeedItem: FeedItemRenderer<"reminder", ReminderOccurrenceData> = (
+	item,
+) => {
+	const { data } = item
+	const status = data.completedAt ? "Completed" : formatDueStatus(data.dueAt)
+	const recurrence = formatRecurrence(data.recurrence)
+
+	return (
+		<FeedCard>
+			<SansSerifText content={status} style="text-xs uppercase" />
+			<SerifText content={data.title} style="text-lg" />
+			<SansSerifText content={formatDueAt(data.dueAt, data.timeZone)} style="text-sm" />
+			{data.notes ? <SansSerifText content={data.notes} style="text-sm text-secondary" /> : null}
+			{recurrence ? (
+				<SansSerifText content={recurrence} style="text-xs text-secondary uppercase" />
+			) : null}
+			{data.priority !== ReminderPriority.Normal ? (
+				<SansSerifText content={data.priority} style="text-xs text-secondary uppercase" />
+			) : null}
+		</FeedCard>
+	)
+}
+
+function formatDueAt(date: Date, timeZone: string): string {
+	return new Intl.DateTimeFormat("en-US", {
+		timeZone,
+		dateStyle: "medium",
+		timeStyle: "short",
+	}).format(date)
+}
+
+function formatDueStatus(date: Date): string {
+	const now = new Date()
+	if (date.getTime() < now.getTime()) return "Due"
+	return "Upcoming"
+}
+
+function formatRecurrence(recurrence: ReminderOccurrenceData["recurrence"]): string | null {
+	if (!recurrence) return null
+
+	const interval = recurrence.interval === 1 ? "" : `${recurrence.interval} `
+	switch (recurrence.frequency) {
+		case ReminderRecurrenceFrequency.Daily:
+			return recurrence.interval === 1 ? "Daily" : `Every ${interval}days`
+		case ReminderRecurrenceFrequency.Weekly:
+			return recurrence.interval === 1 ? "Weekly" : `Every ${interval}weeks`
+		case ReminderRecurrenceFrequency.Monthly:
+			return recurrence.interval === 1 ? "Monthly" : `Every ${interval}months`
+		case ReminderRecurrenceFrequency.Yearly:
+			return recurrence.interval === 1 ? "Yearly" : `Every ${interval}years`
+	}
+}

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

@@ -0,0 +1,373 @@
+import type { FeedItem } from "@freya/core"
+
+import { type } from "arktype"
+
+export const ReminderPriority = {
+	Low: "low",
+	Normal: "normal",
+	High: "high",
+} as const
+
+export type ReminderPriority = (typeof ReminderPriority)[keyof typeof ReminderPriority]
+
+export const ReminderRecurrenceFrequency = {
+	Daily: "daily",
+	Weekly: "weekly",
+	Monthly: "monthly",
+	Yearly: "yearly",
+} as const
+
+export type ReminderRecurrenceFrequency =
+	(typeof ReminderRecurrenceFrequency)[keyof typeof ReminderRecurrenceFrequency]
+
+export const ReminderWeekday = {
+	Sunday: 0,
+	Monday: 1,
+	Tuesday: 2,
+	Wednesday: 3,
+	Thursday: 4,
+	Friday: 5,
+	Saturday: 6,
+} as const
+
+export type ReminderWeekday = (typeof ReminderWeekday)[keyof typeof ReminderWeekday]
+
+export const ReminderEditScope = {
+	ThisOccurrence: "this-occurrence",
+	ThisAndFuture: "this-and-future",
+	EntireSeries: "entire-series",
+} as const
+
+export type ReminderEditScope = (typeof ReminderEditScope)[keyof typeof ReminderEditScope]
+
+export const ReminderAction = {
+	CreateReminder: "create-reminder",
+	UpdateReminder: "update-reminder",
+	DeleteReminder: "delete-reminder",
+	CompleteReminder: "complete-reminder",
+	UncompleteReminder: "uncomplete-reminder",
+} as const
+
+export type ReminderAction = (typeof ReminderAction)[keyof typeof ReminderAction]
+
+export const ReminderUpdateResultType = {
+	UpdatedReminder: "updated-reminder",
+	UpdatedOccurrence: "updated-occurrence",
+	SplitReminder: "split-reminder",
+} as const
+
+export type ReminderUpdateResultType =
+	(typeof ReminderUpdateResultType)[keyof typeof ReminderUpdateResultType]
+
+export const ReminderDeleteResultType = {
+	DeletedReminder: "deleted-reminder",
+	DeletedOccurrence: "deleted-occurrence",
+	EndedReminder: "ended-reminder",
+} as const
+
+export type ReminderDeleteResultType =
+	(typeof ReminderDeleteResultType)[keyof typeof ReminderDeleteResultType]
+
+export const ReminderDateInput = type.or("Date", "string.date.iso.parse")
+export const ReminderTitleInput = type.pipe(
+	type.string,
+	function trimTitle(value) {
+		return value.trim()
+	},
+	type.string.atLeastLength(1),
+)
+export const ReminderTimeZoneInput = type("string", ":", function isTimeZone(value, ctx) {
+	try {
+		new Intl.DateTimeFormat("en-US", { timeZone: value }).format(new Date())
+		return true
+	} catch {
+		return ctx.reject("a valid IANA time zone")
+	}
+})
+
+export const ReminderPriorityInput = type.enumerated(
+	ReminderPriority.Low,
+	ReminderPriority.Normal,
+	ReminderPriority.High,
+)
+
+export const ReminderEditScopeInput = type.enumerated(
+	ReminderEditScope.ThisOccurrence,
+	ReminderEditScope.ThisAndFuture,
+	ReminderEditScope.EntireSeries,
+)
+
+export const ReminderRecurrenceFrequencyInput = type.enumerated(
+	ReminderRecurrenceFrequency.Daily,
+	ReminderRecurrenceFrequency.Weekly,
+	ReminderRecurrenceFrequency.Monthly,
+	ReminderRecurrenceFrequency.Yearly,
+)
+
+export const ReminderWeekdayInput = type.enumerated(0, 1, 2, 3, 4, 5, 6)
+
+export const ReminderRecurrenceInput = type({
+	"+": "reject",
+	frequency: ReminderRecurrenceFrequencyInput,
+	interval: ["number.integer >= 1", "=", 1],
+	"weekdays?": ReminderWeekdayInput.array().atLeastLength(1),
+	"count?": "number.integer >= 1",
+	"until?": ReminderDateInput,
+})
+
+const ReminderRecurrenceNullableInput = type.or(ReminderRecurrenceInput, "null")
+const ReminderNotesInput = type.or("string", "null")
+
+export const ReminderPatchInput = type({
+	"+": "reject",
+	"title?": ReminderTitleInput,
+	"notes?": ReminderNotesInput,
+	"dueAt?": ReminderDateInput,
+	"timeZone?": ReminderTimeZoneInput,
+	"recurrence?": ReminderRecurrenceNullableInput,
+	"priority?": ReminderPriorityInput,
+})
+
+export const ReminderOccurrencePatchInput = type({
+	"+": "reject",
+	"title?": ReminderTitleInput,
+	"notes?": ReminderNotesInput,
+	"dueAt?": ReminderDateInput,
+	"timeZone?": ReminderTimeZoneInput,
+	"priority?": ReminderPriorityInput,
+})
+
+export function createReminderInputSchema(defaultTimeZone: string) {
+	return type({
+		"+": "reject",
+		title: ReminderTitleInput,
+		notes: [ReminderNotesInput, "=", null],
+		dueAt: ReminderDateInput,
+		timeZone: [ReminderTimeZoneInput, "=", defaultTimeZone],
+		recurrence: [ReminderRecurrenceNullableInput, "=", null],
+		priority: [ReminderPriorityInput, "=", ReminderPriority.Normal],
+	})
+}
+
+export const UpdateReminderInput = type({
+	"+": "reject",
+	reminderId: ReminderTitleInput,
+	scope: ReminderEditScopeInput,
+	"occurrenceDueAt?": ReminderDateInput,
+	patch: ReminderPatchInput,
+})
+
+export const DeleteReminderInput = type({
+	"+": "reject",
+	reminderId: ReminderTitleInput,
+	scope: ReminderEditScopeInput,
+	"occurrenceDueAt?": ReminderDateInput,
+})
+
+export const CompleteReminderInput = type({
+	"+": "reject",
+	reminderId: ReminderTitleInput,
+	occurrenceDueAt: ReminderDateInput,
+	"completedAt?": ReminderDateInput,
+})
+
+export const UncompleteReminderInput = type({
+	"+": "reject",
+	reminderId: ReminderTitleInput,
+	occurrenceDueAt: ReminderDateInput,
+})
+
+export interface ReminderRecurrence {
+	frequency: ReminderRecurrenceFrequency
+	/** Repeat every N frequency units. Defaults to 1 when parsed from actions. */
+	interval: number
+	/** Weekly recurrences only. Defaults to the weekday of dueAt. */
+	weekdays?: ReminderWeekday[]
+	/** Maximum number of generated occurrences, including the first one. */
+	count?: number
+	/** Last allowed occurrence instant, inclusive. */
+	until?: Date
+}
+
+export interface Reminder {
+	id: string
+	title: string
+	notes: string | null
+	dueAt: Date
+	timeZone: string
+	recurrence: ReminderRecurrence | null
+	priority: ReminderPriority
+	createdAt: Date
+	updatedAt: Date
+}
+
+export interface CreateReminderInput {
+	title: string
+	notes?: string | null
+	dueAt: Date
+	timeZone?: string
+	recurrence?: ReminderRecurrence | null
+	priority?: ReminderPriority
+}
+
+export interface ReminderPatch {
+	title?: string
+	notes?: string | null
+	dueAt?: Date
+	timeZone?: string
+	recurrence?: ReminderRecurrence | null
+	priority?: ReminderPriority
+}
+
+export interface ReminderOccurrencePatch {
+	title?: string
+	notes?: string | null
+	dueAt?: Date
+	timeZone?: string
+	priority?: ReminderPriority
+}
+
+export interface ReminderOccurrenceOverrideInput {
+	reminderId: string
+	occurrenceId: string
+	originalDueAt: Date
+	patch?: ReminderOccurrencePatch
+	completedAt?: Date | null
+	deletedAt?: Date | null
+}
+
+export interface ReminderOccurrenceOverride extends ReminderOccurrenceOverrideInput {
+	createdAt?: Date
+	updatedAt?: Date
+}
+
+export interface ReminderOccurrence {
+	reminderId: string
+	occurrenceId: string
+	title: string
+	notes: string | null
+	originalDueAt: Date
+	dueAt: Date
+	timeZone: string
+	recurrence: ReminderRecurrence | null
+	priority: ReminderPriority
+	completedAt: Date | null
+}
+
+export interface ReminderListParams {
+	from: Date
+	to: Date
+	includeCompleted: boolean
+}
+
+export interface ReminderOccurrenceOverrideListParams {
+	reminderIds: readonly string[]
+	from: Date
+	to: Date
+}
+
+/**
+ * Storage adapters should return reminders that may produce occurrences in the
+ * requested window. For recurring reminders this can include records whose
+ * first dueAt is before `from`. Returning a superset is valid; ReminderSource
+ * performs final recurrence expansion, override application, and filtering.
+ */
+export interface ReminderStorage {
+	listReminders(params: ReminderListParams): Promise<Reminder[]>
+	getReminder(id: string): Promise<Reminder | null>
+	createReminder(input: CreateReminderInput): Promise<Reminder>
+	updateReminder(id: string, patch: ReminderPatch): Promise<Reminder>
+	deleteReminder(id: string): Promise<void>
+	/**
+	 * Return overrides whose originalDueAt or patched dueAt may affect the
+	 * requested window. Returning a superset is valid.
+	 */
+	listOccurrenceOverrides(
+		params: ReminderOccurrenceOverrideListParams,
+	): Promise<ReminderOccurrenceOverride[]>
+	getOccurrenceOverride(
+		reminderId: string,
+		occurrenceId: string,
+	): Promise<ReminderOccurrenceOverride | null>
+	upsertOccurrenceOverride(
+		input: ReminderOccurrenceOverrideInput,
+	): Promise<ReminderOccurrenceOverride>
+	deleteOccurrenceOverride(reminderId: string, occurrenceId: string): Promise<void>
+	subscribe?(callback: () => void): () => void
+}
+
+export interface UpdateReminderInput {
+	reminderId: string
+	scope: ReminderEditScope
+	occurrenceDueAt?: Date
+	patch: ReminderPatch
+}
+
+export interface DeleteReminderInput {
+	reminderId: string
+	scope: ReminderEditScope
+	occurrenceDueAt?: Date
+}
+
+export interface CompleteReminderInput {
+	reminderId: string
+	occurrenceDueAt: Date
+	completedAt?: Date
+}
+
+export interface UncompleteReminderInput {
+	reminderId: string
+	occurrenceDueAt: Date
+}
+
+export type ReminderUpdateResult =
+	| {
+			type: typeof ReminderUpdateResultType.UpdatedReminder
+			reminder: Reminder
+	  }
+	| {
+			type: typeof ReminderUpdateResultType.UpdatedOccurrence
+			override: ReminderOccurrenceOverride
+	  }
+	| {
+			type: typeof ReminderUpdateResultType.SplitReminder
+			previousReminder: Reminder
+			newReminder: Reminder
+	  }
+
+export type ReminderDeleteResult =
+	| {
+			type: typeof ReminderDeleteResultType.DeletedReminder
+	  }
+	| {
+			type: typeof ReminderDeleteResultType.DeletedOccurrence
+			override: ReminderOccurrenceOverride
+	  }
+	| {
+			type: typeof ReminderDeleteResultType.EndedReminder
+			reminder: Reminder
+	  }
+
+export const ReminderFeedItemType = {
+	Reminder: "reminder",
+} as const
+
+export type ReminderFeedItemType = (typeof ReminderFeedItemType)[keyof typeof ReminderFeedItemType]
+
+export interface ReminderOccurrenceData extends Record<string, unknown> {
+	reminderId: string
+	occurrenceId: string
+	title: string
+	notes: string | null
+	originalDueAt: Date
+	dueAt: Date
+	timeZone: string
+	recurrence: ReminderRecurrence | null
+	priority: ReminderPriority
+	completedAt: Date | null
+}
+
+export type ReminderFeedItem = FeedItem<
+	typeof ReminderFeedItemType.Reminder,
+	ReminderOccurrenceData
+>

packages/freya-source-web-search/package.json

@@ -0,0 +1,14 @@
+{
+	"name": "@freya/source-web-search",
+	"version": "0.0.0",
+	"type": "module",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"scripts": {
+		"test": "bun test ."
+	},
+	"dependencies": {
+		"@freya/core": "workspace:*",
+		"arktype": "^2.1.0"
+	}
+}

packages/freya-source-web-search/src/exa-client.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, test } from "bun:test"
+
+import { ExaSearchClient } from "./exa-client.ts"
+
+describe("ExaSearchClient", () => {
+	test("maps request and response", async () => {
+		const originalFetch = globalThis.fetch
+		let requestUrl = ""
+		let requestHeaders: Headers
+		let requestBody: unknown
+
+		globalThis.fetch = (async (
+			input: Parameters<typeof fetch>[0],
+			init?: Parameters<typeof fetch>[1],
+		) => {
+			requestUrl = String(input)
+			requestHeaders = new Headers(init?.headers)
+			requestBody = JSON.parse(String(init?.body))
+
+			return new Response(
+				JSON.stringify({
+					requestId: "exa-request-1",
+					results: [
+						{
+							id: "result-1",
+							url: "https://example.com",
+							title: "Example",
+							publishedDate: "2026-01-01T00:00:00.000Z",
+							author: "Author",
+							image: "https://example.com/image.png",
+							favicon: "https://example.com/favicon.ico",
+							highlights: ["A useful passage"],
+							highlightScores: [0.7],
+							summary: "Summary",
+						},
+					],
+				}),
+				{ status: 200 },
+			)
+		}) as unknown as typeof fetch
+
+		try {
+			const client = new ExaSearchClient("api-key", "https://api.example.test")
+			const result = await client.search({
+				query: "test query",
+				numResults: 3,
+				includeDomains: ["example.com"],
+				highlights: false,
+			})
+
+			expect(requestUrl).toBe("https://api.example.test/search")
+			expect(requestHeaders!.get("x-api-key")).toBe("api-key")
+			expect(requestBody).toEqual({
+				query: "test query",
+				numResults: 3,
+				includeDomains: ["example.com"],
+				contents: { highlights: false },
+			})
+			expect(result).toEqual({
+				query: "test query",
+				requestId: "exa-request-1",
+				results: [
+					{
+						id: "result-1",
+						url: "https://example.com",
+						title: "Example",
+						publishedDate: "2026-01-01T00:00:00.000Z",
+						author: "Author",
+						image: "https://example.com/image.png",
+						favicon: "https://example.com/favicon.ico",
+						text: null,
+						highlights: ["A useful passage"],
+						highlightScores: [0.7],
+						summary: "Summary",
+					},
+				],
+			})
+		} finally {
+			globalThis.fetch = originalFetch
+		}
+	})
+
+	test("throws on non-ok response", async () => {
+		const originalFetch = globalThis.fetch
+		globalThis.fetch = (async () =>
+			new Response("nope", { status: 401, statusText: "Unauthorized" })) as unknown as typeof fetch
+
+		try {
+			const client = new ExaSearchClient("bad-key")
+			await expect(client.search({ query: "test" })).rejects.toThrow(
+				"Exa API error: 401 Unauthorized",
+			)
+		} finally {
+			globalThis.fetch = originalFetch
+		}
+	})
+})

packages/freya-source-web-search/src/exa-client.ts

@@ -0,0 +1,124 @@
+import { type } from "arktype"
+
+import type {
+	WebSearchClient,
+	WebSearchRequest,
+	WebSearchResponse,
+	WebSearchResult,
+} from "./types.ts"
+
+const EXA_API_BASE = "https://api.exa.ai"
+const DEFAULT_NUM_RESULTS = 10
+
+const ExaSearchResult = type({
+	id: "string",
+	url: "string",
+	"title?": "string | null",
+	"publishedDate?": "string | null",
+	"author?": "string | null",
+	"image?": "string | null",
+	"favicon?": "string | null",
+	"text?": "string | null",
+	"highlights?": "string[]",
+	"highlightScores?": "number[]",
+	"summary?": "string | null",
+})
+
+const ExaSearchResponse = type({
+	results: ExaSearchResult.array(),
+	"requestId?": "string",
+})
+
+interface ExaSearchBody {
+	query: string
+	numResults?: number
+	includeDomains?: string[]
+	excludeDomains?: string[]
+	startCrawlDate?: string
+	endCrawlDate?: string
+	startPublishedDate?: string
+	endPublishedDate?: string
+	type?: WebSearchRequest["type"]
+	category?: string
+	userLocation?: string
+	moderation?: boolean
+	contents: {
+		highlights: boolean
+	}
+}
+
+export class ExaSearchClient implements WebSearchClient {
+	private readonly apiKey: string
+	private readonly baseUrl: string
+
+	constructor(apiKey: string, baseUrl = EXA_API_BASE) {
+		this.apiKey = apiKey
+		this.baseUrl = baseUrl
+	}
+
+	async search(request: WebSearchRequest): Promise<WebSearchResponse> {
+		const response = await fetch(new URL("/search", this.baseUrl), {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				"x-api-key": this.apiKey,
+			},
+			body: JSON.stringify(toExaSearchBody(request)),
+		})
+
+		if (!response.ok) {
+			throw new Error(`Exa API error: ${response.status} ${response.statusText}`)
+		}
+
+		const data = await response.json()
+		const parsed = ExaSearchResponse(data)
+		if (parsed instanceof type.errors) {
+			throw new Error(`Invalid Exa API response: ${parsed.summary}`)
+		}
+
+		return {
+			query: request.query,
+			requestId: parsed.requestId ?? null,
+			results: parsed.results.map(toWebSearchResult),
+		}
+	}
+}
+
+function toExaSearchBody(request: WebSearchRequest): ExaSearchBody {
+	const body: ExaSearchBody = {
+		query: request.query,
+		numResults: request.numResults ?? DEFAULT_NUM_RESULTS,
+		contents: {
+			highlights: request.highlights ?? true,
+		},
+	}
+
+	if (request.includeDomains) body.includeDomains = request.includeDomains
+	if (request.excludeDomains) body.excludeDomains = request.excludeDomains
+	if (request.startCrawlDate) body.startCrawlDate = request.startCrawlDate
+	if (request.endCrawlDate) body.endCrawlDate = request.endCrawlDate
+	if (request.startPublishedDate) body.startPublishedDate = request.startPublishedDate
+	if (request.endPublishedDate) body.endPublishedDate = request.endPublishedDate
+	if (request.type) body.type = request.type
+	if (request.category) body.category = request.category
+	if (request.userLocation) body.userLocation = request.userLocation
+	if (request.moderation !== undefined) body.moderation = request.moderation
+
+	return body
+}
+
+function toWebSearchResult(result: typeof ExaSearchResult.infer): WebSearchResult {
+	return {
+		id: result.id,
+		url: result.url,
+		title: result.title ?? null,
+		publishedDate: result.publishedDate ?? null,
+		author: result.author ?? null,
+		image: result.image ?? null,
+		favicon: result.favicon ?? null,
+		text: result.text ?? null,
+		highlights: result.highlights ?? [],
+		highlightScores: result.highlightScores ?? [],
+		summary: result.summary ?? null,
+	}
+}

packages/freya-source-web-search/src/index.ts

@@ -0,0 +1,11 @@
+export { ExaSearchClient } from "./exa-client.ts"
+export { WebSearchSource } from "./web-search-source.ts"
+export {
+	WebSearchAction,
+	WebSearchType,
+	type WebSearchClient,
+	type WebSearchRequest,
+	type WebSearchResponse,
+	type WebSearchResult,
+	type WebSearchSourceOptions,
+} from "./types.ts"

packages/freya-source-web-search/src/types.ts

@@ -0,0 +1,61 @@
+export const WebSearchAction = {
+	Search: "search",
+} as const
+
+export type WebSearchAction = (typeof WebSearchAction)[keyof typeof WebSearchAction]
+
+export const WebSearchType = {
+	Instant: "instant",
+	Fast: "fast",
+	Auto: "auto",
+	DeepLite: "deep-lite",
+	Deep: "deep",
+	DeepReasoning: "deep-reasoning",
+} as const
+
+export type WebSearchType = (typeof WebSearchType)[keyof typeof WebSearchType]
+
+export interface WebSearchRequest {
+	query: string
+	numResults?: number
+	includeDomains?: string[]
+	excludeDomains?: string[]
+	startCrawlDate?: string
+	endCrawlDate?: string
+	startPublishedDate?: string
+	endPublishedDate?: string
+	type?: WebSearchType
+	category?: string
+	userLocation?: string
+	moderation?: boolean
+	highlights?: boolean
+}
+
+export interface WebSearchResult extends Record<string, unknown> {
+	id: string
+	url: string
+	title: string | null
+	publishedDate: string | null
+	author: string | null
+	image: string | null
+	favicon: string | null
+	text: string | null
+	highlights: string[]
+	highlightScores: number[]
+	summary: string | null
+}
+
+export interface WebSearchResponse extends Record<string, unknown> {
+	query: string
+	requestId: string | null
+	results: WebSearchResult[]
+}
+
+export interface WebSearchClient {
+	search(request: WebSearchRequest): Promise<WebSearchResponse>
+}
+
+export interface WebSearchSourceOptions {
+	apiKey?: string
+	client?: WebSearchClient
+}

packages/freya-source-web-search/src/web-search-source.test.ts

@@ -0,0 +1,123 @@
+import { Context } from "@freya/core"
+import { describe, expect, test } from "bun:test"
+
+import type { WebSearchClient, WebSearchRequest, WebSearchResponse } from "./types.ts"
+
+import { WebSearchAction } from "./types.ts"
+import { WebSearchSource } from "./web-search-source.ts"
+
+class RecordingSearchClient implements WebSearchClient {
+	requests: WebSearchRequest[] = []
+
+	async search(request: WebSearchRequest): Promise<WebSearchResponse> {
+		this.requests.push(request)
+		return {
+			query: request.query,
+			requestId: "request-1",
+			results: [
+				{
+					id: "https://example.com/a",
+					url: "https://example.com/a",
+					title: "Example result",
+					publishedDate: "2026-01-01T00:00:00.000Z",
+					author: "Example Author",
+					image: null,
+					favicon: "https://example.com/favicon.ico",
+					text: null,
+					highlights: ["Relevant excerpt"],
+					highlightScores: [0.8],
+					summary: null,
+				},
+			],
+		}
+	}
+}
+
+describe("WebSearchSource", () => {
+	test("has correct id", () => {
+		const source = new WebSearchSource({ client: new RecordingSearchClient() })
+
+		expect(source.id).toBe("freya.web-search")
+	})
+
+	test("does not provide context or feed items", async () => {
+		const source = new WebSearchSource({ client: new RecordingSearchClient() })
+
+		expect("fetchItems" in source).toBe(false)
+		expect(await source.fetchContext(new Context())).toBeNull()
+	})
+
+	test("lists search action", async () => {
+		const source = new WebSearchSource({ client: new RecordingSearchClient() })
+		const actions = await source.listActions()
+
+		expect(actions[WebSearchAction.Search]).toBeDefined()
+		expect(actions[WebSearchAction.Search]!.id).toBe(WebSearchAction.Search)
+		expect(actions[WebSearchAction.Search]!.input).toBeDefined()
+	})
+
+	test("executes search action with normalized params", async () => {
+		const client = new RecordingSearchClient()
+		const source = new WebSearchSource({ client })
+
+		const result = await source.executeAction(WebSearchAction.Search, {
+			query: "  latest personal assistant research  ",
+			includeDomains: ["exa.ai"],
+			type: "fast",
+			userLocation: "gb",
+			moderation: true,
+		})
+
+		expect(result.requestId).toBe("request-1")
+		expect(result.results).toHaveLength(1)
+		expect(client.requests).toEqual([
+			{
+				query: "latest personal assistant research",
+				numResults: 10,
+				includeDomains: ["exa.ai"],
+				type: "fast",
+				userLocation: "GB",
+				moderation: true,
+			},
+		])
+	})
+
+	test("allows per-call numResults override", async () => {
+		const client = new RecordingSearchClient()
+		const source = new WebSearchSource({ client })
+
+		await source.executeAction(WebSearchAction.Search, {
+			query: "freya",
+			numResults: 2,
+		})
+
+		expect(client.requests[0]!.numResults).toBe(2)
+	})
+
+	test("throws for invalid action", async () => {
+		const source = new WebSearchSource({ client: new RecordingSearchClient() })
+
+		await expect(source.executeAction("missing", {})).rejects.toThrow("Unknown action")
+	})
+
+	test("throws for invalid search params", async () => {
+		const source = new WebSearchSource({ client: new RecordingSearchClient() })
+
+		await expect(
+			source.executeAction(WebSearchAction.Search, {
+				query: "",
+			}),
+		).rejects.toThrow("query must not be empty")
+
+		await expect(
+			source.executeAction(WebSearchAction.Search, {
+				query: "x",
+				numResults: 101,
+			}),
+		).rejects.toThrow("numResults must be an integer")
+	})
+
+	test("throws if neither client nor apiKey is provided", () => {
+		expect(() => new WebSearchSource({})).toThrow("Either client or apiKey must be provided")
+	})
+})

packages/freya-source-web-search/src/web-search-source.ts

@@ -0,0 +1,121 @@
+import type { ActionDefinition, Context, ContextEntry, FeedSource } from "@freya/core"
+
+import { UnknownActionError } from "@freya/core"
+import { type } from "arktype"
+
+import type {
+	WebSearchClient,
+	WebSearchRequest,
+	WebSearchResponse,
+	WebSearchSourceOptions,
+} from "./types.ts"
+
+import { ExaSearchClient } from "./exa-client.ts"
+import { WebSearchAction, WebSearchType } from "./types.ts"
+
+const DEFAULT_NUM_RESULTS = 10
+const MIN_NUM_RESULTS = 1
+const MAX_NUM_RESULTS = 100
+
+const SearchInput = type({
+	"+": "reject",
+	query: "string",
+	"numResults?": "number",
+	"includeDomains?": "string[]",
+	"excludeDomains?": "string[]",
+	"startCrawlDate?": "string.date.iso",
+	"endCrawlDate?": "string.date.iso",
+	"startPublishedDate?": "string.date.iso",
+	"endPublishedDate?": "string.date.iso",
+	"type?": "'instant' | 'fast' | 'auto' | 'deep-lite' | 'deep' | 'deep-reasoning'",
+	"category?": "string",
+	"userLocation?": "string",
+	"moderation?": "boolean",
+	"highlights?": "boolean",
+})
+
+/**
+ * Action-only FeedSource for web search through Exa.
+ *
+ * It intentionally does not produce feed items. Consumers call the `search`
+ * action and receive structured web results.
+ */
+export class WebSearchSource implements FeedSource {
+	readonly id = "freya.web-search"
+
+	private readonly client: WebSearchClient
+
+	constructor(options: WebSearchSourceOptions) {
+		if (!options.client && !options.apiKey) {
+			throw new Error("Either client or apiKey must be provided")
+		}
+		this.client = options.client ?? new ExaSearchClient(options.apiKey!)
+	}
+
+	async listActions(): Promise<Record<string, ActionDefinition>> {
+		return {
+			[WebSearchAction.Search]: {
+				id: WebSearchAction.Search,
+				description: "Search the web and return structured results",
+				input: SearchInput,
+			},
+		}
+	}
+
+	async executeAction(actionId: string, params: unknown): Promise<WebSearchResponse> {
+		switch (actionId) {
+			case WebSearchAction.Search:
+				return this.client.search(this.parseSearchInput(params))
+			default:
+				throw new UnknownActionError(actionId)
+		}
+	}
+
+	async fetchContext(_context: Context): Promise<readonly ContextEntry[] | null> {
+		return null
+	}
+
+	private parseSearchInput(params: unknown): WebSearchRequest {
+		const parsed = SearchInput(params)
+		if (parsed instanceof type.errors) {
+			throw new Error(parsed.summary)
+		}
+
+		const query = parsed.query.trim()
+		if (!query) {
+			throw new Error("query must not be empty")
+		}
+
+		const numResults = parsed.numResults ?? DEFAULT_NUM_RESULTS
+		if (
+			!Number.isInteger(numResults) ||
+			numResults < MIN_NUM_RESULTS ||
+			numResults > MAX_NUM_RESULTS
+		) {
+			throw new Error(`numResults must be an integer from ${MIN_NUM_RESULTS} to ${MAX_NUM_RESULTS}`)
+		}
+
+		if (parsed.userLocation && !/^[A-Za-z]{2}$/.test(parsed.userLocation)) {
+			throw new Error("userLocation must be a two-letter ISO country code")
+		}
+
+		const request: WebSearchRequest = {
+			query,
+			numResults,
+		}
+
+		if (parsed.includeDomains) request.includeDomains = parsed.includeDomains
+		if (parsed.excludeDomains) request.excludeDomains = parsed.excludeDomains
+		if (parsed.startCrawlDate) request.startCrawlDate = parsed.startCrawlDate
+		if (parsed.endCrawlDate) request.endCrawlDate = parsed.endCrawlDate
+		if (parsed.startPublishedDate) request.startPublishedDate = parsed.startPublishedDate
+		if (parsed.endPublishedDate) request.endPublishedDate = parsed.endPublishedDate
+		if (parsed.type) request.type = parsed.type as WebSearchType
+		if (parsed.category) request.category = parsed.category
+		if (parsed.userLocation) request.userLocation = parsed.userLocation.toUpperCase()
+		if (parsed.moderation !== undefined) request.moderation = parsed.moderation
+		if (parsed.highlights !== undefined) request.highlights = parsed.highlights
+
+		return request
+	}
+}