fairies: pixie edition (tldraw#7102)

### Change type

- [ ] `bugfix`
- [ ] `improvement`
- [ ] `feature`
- [ ] `api`
- [x] `other`

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Replaces shared todos with a per-page Fairy Tasks/Projects system and
refactors agents to new mode/actions architecture, alongside significant
UI, persistence, worker, and editor API updates.
> 
> - **Architecture/Agent**:
> - Introduce mode-based agent framework
(`idling/soloing/working/orchestrating`) via `FairyModeDefinition`;
remove wands.
> - Consolidate and expand action schemas (tasks, projects, pages,
sleep, etc.); update prompt part system with definitions and
logging/debug flags.
> - Track cumulative token usage; ensure fairies act on correct page;
add follow/summon behavior.
> - **Data/Persistence**:
> - Replace shared todos with `FairyTask` and `FairyProject`; persist
tasks/projects and update `PersistedFairyState`.
>   - Filter fairies/tasks by current page.
> - **UI**:
> - New task list (inline, dropdown, context menu), in-canvas task
rendering, revamped HUD/sidebar, group chat updates, i18n labels, and a
comprehensive Fairy Debug dialog.
> - Context/dropdown z-index fixes; select tool namespaced
(`select.fairy-throw`, `select.task-drag`).
> - **Worker/Backend**:
> - Add admin detection/header; optional logging of system
prompt/messages; stream usage metadata.
> - **Editor API**:
> - `setTool`/`removeTool` accept optional parent `StateNode`; add
tests.
> - **Fixes**:
>   - Safe label updates only for shapes supporting `richText`.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
4637dad. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Lu[ke] Wilson <l2wilson94@gmail.com>
Co-authored-by: Max Drake <maxdrake46@gmail.com>
Co-authored-by: David Sheldrick <d.j.sheldrick@gmail.com>

Author: 4 people

apps/dotcom/client/src/fairy/Fairies.tsx

@@ -1,11 +1,22 @@
-import { useMemo } from 'react'
+import { useEditor, useValue } from 'tldraw'
 import Fairy from './Fairy'
 import { FairyAgent } from './fairy-agent/agent/FairyAgent'
 
 export function Fairies({ agents }: { agents: FairyAgent[] }) {
-	const activeAgents = useMemo(
-		() => agents.filter((agent) => agent.$fairyEntity.get() !== undefined),
-		[agents]
+	const editor = useEditor()
+	const currentPageId = useValue('current page id', () => editor.getCurrentPageId(), [editor])
+
+	// Reactively filter fairies based on current page and each fairy's currentPageId
+	const activeAgents = useValue(
+		'active fairies on page',
+		() => {
+			return agents.filter((agent) => {
+				const entity = agent.$fairyEntity.get()
+				// Only show fairies that exist and are on the current page
+				return entity !== undefined && entity.currentPageId === currentPageId
+			})
+		},
+		[agents, currentPageId]
 	)
 
 	return (

apps/dotcom/client/src/fairy/Fairy.tsx

@@ -36,8 +36,11 @@ export default function Fairy({ agent }: { agent: FairyAgent }) {
 	const flipX = useValue('fairy flipX', () => fairy.get()?.flipX ?? false, [fairy])
 	const isSelected = useValue('fairy isSelected', () => fairy.get()?.isSelected ?? false, [fairy])
 	const isInSelectTool = useValue('is in select tool', () => editor.isIn('select.idle'), [editor])
+	const isInThrowTool = useValue('is in throw tool', () => editor.isIn('select.fairy-throw'), [
+		editor,
+	])
 	const isGenerating = useValue('is generating', () => agent.isGenerating(), [agent])
-	const isFairyGrabbable = !isGenerating && isInSelectTool
+	const isFairyGrabbable = isInSelectTool
 
 	// Listen to brush selection events and update fairy selection
 	const brush = useValue('editor brush', () => editor.getInstanceState().brush, [editor])
@@ -124,12 +127,7 @@ export default function Fairy({ agent }: { agent: FairyAgent }) {
 		// Skip dragging behavior on right-click (context menu will handle it)
 		if (e.button === 2) return
 		if (!editor.isIn('select.idle')) return
-		if (editor.getCurrentTool().id === 'fairy-throw') return
-
-		// right now we don't have a way for the fairy to break out of a user's grasp,
-		// but currently the UI is structured such that you cant be dragging the fairy
-		// when you press generate, so this is enough for now
-		if (agent.isGenerating()) return
+		if (editor.isIn('select.fairy-throw')) return
 
 		// Determine which fairies to drag before updating selection
 		const fairyAgents = $fairyAgentsAtom.get(editor)
@@ -199,11 +197,11 @@ export default function Fairy({ agent }: { agent: FairyAgent }) {
 				document.removeEventListener('pointerup', handlePointerUp)
 
 				// Activate the tool with all fairies that were selected at pointer down
-				const tool = editor.getStateDescendant('fairy-throw')
+				const tool = editor.getStateDescendant('select.fairy-throw')
 				if (tool && 'setFairies' in tool) {
 					;(tool as FairyThrowTool).setFairies(fairiesToDrag)
 				}
-				editor.setCurrentTool('fairy-throw')
+				editor.setCurrentTool('select.fairy-throw')
 			}
 		}
 
@@ -236,7 +234,10 @@ export default function Fairy({ agent }: { agent: FairyAgent }) {
 						height: `${FAIRY_SIZE}px`,
 						transform: `translate(-75%, -25%) scale(var(--tl-scale)) ${flipX ? ' scaleX(-1)' : ''}`,
 						transformOrigin: '75% 25%',
-						transition: isGenerating ? 'left 0.1s ease-in-out, top 0.1s ease-in-out' : 'none',
+						transition:
+							isGenerating && !isInThrowTool
+								? 'left 0.1s ease-in-out, top 0.1s ease-in-out'
+								: 'none',
 					}}
 					className={isSelected ? 'fairy-selected' : ''}
 				>

apps/dotcom/client/src/fairy/FairyApp.tsx

@@ -4,13 +4,14 @@ import {
 	PersistedFairyState,
 } from '@tldraw/fairy-shared'
 import { useCallback, useEffect, useRef } from 'react'
-import { react, throttle, useEditor, useValue } from 'tldraw'
+import { react, throttle, useEditor, useToasts, useValue } from 'tldraw'
 import { useApp } from '../tla/hooks/useAppState'
 import { useTldrawUser } from '../tla/hooks/useUser'
 import { FairyAgent } from './fairy-agent/agent/FairyAgent'
+import { $fairyProjects } from './FairyProjects'
+import { FairyTaskDragTool } from './FairyTaskDragTool'
+import { $fairyTasks, $showCanvasFairyTasks } from './FairyTaskList'
 import { FairyThrowTool } from './FairyThrowTool'
-import { $sharedTodoList, $showCanvasTodos } from './SharedTodoList'
-import { TodoDragTool } from './TodoDragTool'
 
 export function FairyApp({
 	setAgents,
@@ -22,6 +23,7 @@ export function FairyApp({
 	const editor = useEditor()
 	const user = useTldrawUser()
 	const app = useApp()
+	const toasts = useToasts()
 	const fairyConfigs = useValue(
 		'fairyConfigs',
 		() => JSON.parse(app?.getUser().fairies || '{}') as PersistedFairyConfigs,
@@ -33,9 +35,18 @@ export function FairyApp({
 		return await user.getToken()
 	}, [user])
 
-	const handleError = useCallback((e: any) => {
-		console.error('Error:', e)
-	}, [])
+	const handleError = useCallback(
+		(e: any) => {
+			const message = typeof e === 'string' ? e : e instanceof Error && e.message
+			toasts.addToast({
+				title: 'Error',
+				description: message || 'An error occurred',
+				severity: 'error',
+			})
+			console.error(e)
+		},
+		[toasts]
+	)
 
 	// Track whether we're currently loading state to prevent premature saves
 	const isLoadingStateRef = useRef(false)
@@ -45,18 +56,20 @@ export function FairyApp({
 	const loadedAgentIdsRef = useRef<Set<string>>(new Set())
 	const sharedTodoListLoadedRef = useRef(false)
 	const showCanvasTodosLoadedRef = useRef(false)
+	const projectsLoadedRef = useRef(false)
 
 	// Create agents dynamically from configs
 	useEffect(() => {
 		if (!editor) return
 
 		// Register the FairyThrowTool
-		editor.removeTool(FairyThrowTool)
-		editor.setTool(FairyThrowTool)
+		const selectTool = editor.root.children!.select
+		editor.removeTool(FairyThrowTool, selectTool)
+		editor.setTool(FairyThrowTool, selectTool)
 
 		// Register the TodoDragTool
-		editor.removeTool(TodoDragTool)
-		editor.setTool(TodoDragTool)
+		editor.removeTool(FairyTaskDragTool, selectTool)
+		editor.setTool(FairyTaskDragTool, selectTool)
 
 		const configIds = Object.keys(fairyConfigs)
 		const existingAgents = agentsRef.current
@@ -105,7 +118,7 @@ export function FairyApp({
 
 	// Load fairy state from backend when agents are created
 	useEffect(() => {
-		if (!app || agentsRef.current.length === 0 || !$sharedTodoList || !$showCanvasTodos || !fileId)
+		if (!app || agentsRef.current.length === 0 || !$fairyTasks || !$showCanvasFairyTasks || !fileId)
 			return
 
 		const fileState = app.getFileState(fileId)
@@ -130,16 +143,22 @@ export function FairyApp({
 
 				// Load shared todo list only once
 				if (fairyState.sharedTodoList && !sharedTodoListLoadedRef.current) {
-					$sharedTodoList.set(fairyState.sharedTodoList)
+					$fairyTasks.set(fairyState.sharedTodoList)
 					sharedTodoListLoadedRef.current = true
 				}
 
 				// Load show canvas todos only once
 				if (fairyState.showCanvasTodos && !showCanvasTodosLoadedRef.current) {
-					$showCanvasTodos.set(fairyState.showCanvasTodos)
+					$showCanvasFairyTasks.set(fairyState.showCanvasTodos)
 					showCanvasTodosLoadedRef.current = true
 				}
 
+				// Load projects only once
+				if (fairyState.projects && !projectsLoadedRef.current) {
+					$fairyProjects.set(fairyState.projects)
+					projectsLoadedRef.current = true
+				}
+
 				// Allow a tick for state to settle before allowing saves
 				setTimeout(() => {
 					isLoadingStateRef.current = false
@@ -154,8 +173,7 @@ export function FairyApp({
 	// Todo: Use FileStateUpdater for this
 	// Save fairy state to backend periodically
 	useEffect(() => {
-		if (!app || agentsRef.current.length === 0 || !$sharedTodoList || !$showCanvasTodos || !fileId)
-			return
+		if (!app || agentsRef.current.length === 0 || !fileId) return
 
 		const updateFairyState = throttle(() => {
 			// Don't save if we're currently loading state
@@ -169,8 +187,9 @@ export function FairyApp({
 					},
 					{} as Record<string, PersistedFairyAgentState>
 				),
-				sharedTodoList: $sharedTodoList.get(),
-				showCanvasTodos: $showCanvasTodos.get(),
+				sharedTodoList: $fairyTasks.get(),
+				showCanvasTodos: $showCanvasFairyTasks.get(),
+				projects: $fairyProjects.get(),
 			}
 			app.onFairyStateUpdate(fileId, fairyState)
 		}, 2000) // Save maximum every 2 seconds
@@ -182,26 +201,21 @@ export function FairyApp({
 				agent.$fairyEntity.get()
 				agent.$chatHistory.get()
 				agent.$todoList.get()
-				agent.$contextItems.get()
 				updateFairyState()
 			})
 			fairyCleanupFns.push(cleanup)
 		})
 
-		const cleanupSharedTodoList = react('shared todo list', () => {
-			$sharedTodoList.get()
-			updateFairyState()
-		})
-
-		const cleanupShowCanvasTodos = react('show canvas todos', () => {
-			$showCanvasTodos.get()
+		const cleanupSharedFairyState = react('shared fairy atom state', () => {
+			$fairyTasks.get()
+			$showCanvasFairyTasks.get()
+			$fairyProjects.get()
 			updateFairyState()
 		})
 
 		return () => {
 			updateFairyState.flush()
-			cleanupSharedTodoList()
-			cleanupShowCanvasTodos()
+			cleanupSharedFairyState()
 			fairyCleanupFns.forEach((cleanup) => cleanup())
 		}
 	}, [app, fairyConfigs, fileId])

apps/dotcom/client/src/fairy/FairyConfigDialog.tsx

@@ -10,62 +10,50 @@ import {
 	TldrawUiInput,
 	useValue,
 } from 'tldraw'
+import { F, useMsg } from '../tla/utils/i18n'
 import { FairyAgent } from './fairy-agent/agent/FairyAgent'
+import { fairyMessages } from './fairy-messages'
 
 export function FairyConfigDialog({ agent, onClose }: { agent: FairyAgent; onClose(): void }) {
 	const config = useValue(agent.$fairyConfig)
-	// const currentMode = getFairyMode(config.mode)
-	// const availableWands = currentMode.availableWands
+
+	const fairyNamePlaceholder = useMsg(fairyMessages.fairyNamePlaceholder)
+	const fairyPersonalityPlaceholder = useMsg(fairyMessages.fairyPersonalityPlaceholder)
 
 	return (
 		<>
 			<TldrawUiDialogHeader>
-				<TldrawUiDialogTitle>Fairy customization</TldrawUiDialogTitle>
+				<TldrawUiDialogTitle>
+					<F defaultMessage="Fairy customization" />
+				</TldrawUiDialogTitle>
 				<TldrawUiDialogCloseButton />
 			</TldrawUiDialogHeader>
 			<TldrawUiDialogBody style={{ maxWidth: 400 }}>
 				<div
 					className="fairy-config-dialog"
 					style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}
 				>
-					<label htmlFor="name">Name</label>
+					<label htmlFor="name">
+						<F defaultMessage="Name" />
+					</label>
 					<TldrawUiInput
 						className="fairy-config-input"
 						value={config.name}
 						onValueChange={(value) => agent.updateFairyConfig({ name: value })}
-						placeholder="Fairy's name"
+						placeholder={fairyNamePlaceholder}
 					/>
-					<label htmlFor="name">Personality</label>
+					<label htmlFor="name">
+						<F defaultMessage="Personality" />
+					</label>
 					<TldrawUiInput
 						className="fairy-config-input"
 						value={config.personality}
 						onValueChange={(value) => agent.updateFairyConfig({ personality: value })}
-						placeholder="Fairy's personality"
+						placeholder={fairyPersonalityPlaceholder}
 					/>
-					{/* <label htmlFor="mode">Mode</label>
-					<select
-						id="mode"
-						value={config.mode}
-						onChange={(e) => {
-							const newMode = getFairyMode(e.target.value as typeof config.mode)
-							const newConfig = {
-								...config,
-								mode: newMode.id,
-								// If current wand isn't available in new mode, use the mode's default wand
-								wand: (newMode.availableWands as readonly Wand['type'][]).includes(config.wand)
-									? config.wand
-									: newMode.defaultWand,
-							}
-							agent.$fairyConfig.set(newConfig)
-						}}
-					>
-						{FAIRY_MODE_DEFINITIONS.map((mode) => (
-							<option key={mode.id} value={mode.id}>
-								{mode.id.charAt(0).toUpperCase() + mode.id.slice(1)}
-							</option>
-						))}
-					</select> */}
-					<label htmlFor="hat">Hat</label>
+					<label htmlFor="hat">
+						<F defaultMessage="Hat" />
+					</label>
 					<select
 						id="hat"
 						value={config.outfit.hat}
@@ -81,28 +69,13 @@ export function FairyConfigDialog({ agent, onClose }: { agent: FairyAgent; onClo
 							</option>
 						))}
 					</select>
-					{/* <label htmlFor="wand">Wand</label>
-					<select
-						id="wand"
-						value={config.wand}
-						onChange={(e) => {
-							agent.$fairyConfig.set({ ...config, wand: e.target.value as Wand['type'] })
-						}}
-					>
-						{WAND_DEFINITIONS.map((wand) => {
-							const isAvailable = (availableWands as readonly Wand['type'][]).includes(wand.type)
-							return (
-								<option key={wand.type} value={wand.type} disabled={!isAvailable}>
-									{wand.name} — {wand.description}
-								</option>
-							)
-						})}
-					</select> */}
 				</div>
 			</TldrawUiDialogBody>
 			<TldrawUiDialogFooter className="tlui-dialog__footer__actions">
 				<TldrawUiButton type="normal" onClick={onClose}>
-					<TldrawUiButtonLabel>Close</TldrawUiButtonLabel>
+					<TldrawUiButtonLabel>
+						<F defaultMessage="Close" />
+					</TldrawUiButtonLabel>
 				</TldrawUiButton>
 			</TldrawUiDialogFooter>
 		</>

apps/dotcom/client/src/fairy/FairyContextMenuContent.tsx

@@ -11,8 +11,8 @@ export function FairyContextMenuContent({ agent }: { agent: FairyAgent }) {
 			<_ContextMenu.Content
 				className="tlui-menu fairy-sidebar-dropdown"
 				collisionPadding={4}
-				onClick={(e) => e.stopPropagation()}
-				style={{ zIndex: 10000000 }}
+				onPointerDown={(e) => e.stopPropagation()}
+				style={{ zIndex: 'var(--tl-layer-canvas-in-front)' }}
 			>
 				<FairyMenuContent agent={agent} menuType="context-menu" />
 			</_ContextMenu.Content>