Under the Hood: How Wellness Runtime, Scoring, and Chat Home Work on Mac

This post is for readers who want the architecture story behind Meet Wellness in Aide: Your Mac Work Rhythm, Without the Noise — without opening the implementation plan.

It explains how local observation becomes chat-home status, how notifications are scheduled, and why Wellness consolidated into a single agent surface.

Design Principle: One Surface, Local-First

Early prototypes explored a separate Wellness window and tabbed dashboard. Shipping UX consolidated to WellnessChatHomeView inside the Wellness agent thread:

status → observable factors → one recommendation
week preview below, tentative until enough days exist
Accept on notifications routes here — no second entry point

That reduces cognitive load: users learn one place, not a menu item plus a window plus chat.

User-facing tour: How to Find Wellness in AideAI and What the Chat Home Shows.

Runtime Loop (60-Second Tick)

When Enable wellness runtime is on, WellnessEngine runs on a ~60 second tick coordinated by WellnessRuntimeAdapter under the app’s runtime supervisor.

Each tick roughly:

Aggregate signals — sessions, idle, meetings, context-switch rate (WellnessSignalAggregator)
Score load — map observation to load level (LoadScorer)
Recommend — pick category + copy for interventions (WellnessRecommender + InterventionTimingEngine)
Persist — daily snapshots and intervention events locally (WellnessEventStore)
Notify — schedule pushes when thresholds and user settings allow (NotificationScheduler)

Continuous work timers pause when you lock the screen or go away — so “continuous work” reflects plausible desk time, not overnight idle.

Meeting load refreshes on its own cadence from calendar-backed analysis (MeetingLoadAnalyzer).

From Raw Signals To “Balanced Pace”

Chat home deliberately hides raw 0–100 load as the headline KPI. Internally a score exists, but UI prioritizes:

semantic load level (low → high)
interpretable factors (active work, focused work, meetings, last break)
one recommendation tied to a category

Metrics pass through consistency rules — for example, focused work is capped by active work so Today blocks never imply impossible math.

Partial weeks (fewer than four days tracked) show explicit learning state instead of fake confidence.

Chat Context: Sanitized, Capped, Stale-Aware

When Wellness chat or Discuss needs Mac context, WellnessContextProvider builds a WellnessChatContextSnapshot:

aggregates only — no window titles, keystrokes, or message bodies
WellnessPromptBlockBuilder caps injected text around 1200 characters
snapshots go stale after ~5 minutes — stale context is not treated as fresh

This is stricter than generic activity recall. Privacy guide: What Aide Sees on Your Mac for Wellness.

Agent policy (WellnessAgentPolicy) controls which chat agents receive wellness blocks — the Wellness agent is primary; cross-agent behavior follows product rules without dumping full timelines.

Notifications And State Machines

Interventions record lifecycle events locally:

shown → accepted / dismissed / snoozed

Snooze reschedules (~15 minutes). Dismiss applies category cooldown to prevent spam. Accept deep-links to chat home. Discuss opens chat with snapshot context when online.

End-of-day flows support Still working? deferral instead of punishing late sessions.

Engine stop cancels pending interventions — settings changes re-evaluate runtime via startIfNeeded() so toggles take effect without relaunching the app.

User-facing actions: Smart Breaks: Wellness Notifications, Accept, and Discuss.

Feature Flag And Rollout

Mac Wellness ships behind Remote Config key mac_wellness_agent_enabled, default off until dogfood metrics look healthy (accept/dismiss rates, crash-free sessions).

That flag gates:

runtime start
personalized chat home
intervention scheduling

General Wellness chat prompts still work when the flag is off — only the Mac rhythm layer stays dark.

Analytics Without Surveillance

Product analytics (WellnessAnalyticsService) emits funnel events — intervention shown, accepted, dismissed, chat opened from notification — without PII. The goal is learning whether nudges help, not building a manager dashboard.

How Pieces Map To User Trust

Layer	User sees	Engineering job
Observation	Today / Week blocks	Local signal aggregation
Interpretation	Plain-language status	Load scoring + recommender
Action	One next step + notifications	Timing engine + scheduler
Conversation	Discuss with context	Sanitized snapshot injection
Control	Settings tab	Persisted `WellnessSettings`

Why This Matters Beyond Wellness

The pattern — local sense-making → minimal cloud context → one actionable surface — mirrors other AideAI bets: Activity Log for recall, Personal Memory for long-term facts, Study overview for semester clarity.

Wellness applies that pattern to intraday rhythm instead of assignments or files.