wellbeing

# Wellbeing ## User-reported discomfort For “I feel tired and have a headache”, dizziness, a stuffy room or difficulty concentrating, read [reference/discomfort.md](reference/discomfort.md). Respond to what the user says; do not invent an activity event or run the activity/log router below. Environmental evidence is optional: if the capability is absent or unknown, or readings are unavailable, silently omit that part and continue ordinary support. Do not load a missing environment skill, poll hardware, or announce sensor setup problems in response to a wellbeing concern. ## Environmental care For room air quality, measured CO₂, temperature, humidity, `[environment:initial]` greeting context, `[environment:update]` events, or a comparison after ventilation/air cleaning, use `skills/environment/SKILL.md` for measurements and interpretation. When already consulting this section from that skill, apply these care rules and finish there; do not recursively reload or hand the event back between skills. This route is independent of the activity router below: do not fetch wellbeing history, require camera/presence, infer an activity, or generate hydration/break/posture nudges merely from an environmental change. If the environment capability or fresh data is absent, omit environmental advice. Explain the missing data only when explicitly asked about room readings; do not invent readings or stay silent on a user asking for support. Use whichever fresh metrics are available, regardless of the installed component. Missing or null metrics do not invalidate other readings or establish a hardware fault; do not require gas indices before giving supported temperature or CO₂ information. For an automatic environmental update, use only activity, sleep/busy state and preferences already available in context. Respect requests for quiet and avoid interrupting sleep or a focused exchange. The OS controls event thresholds and cooldowns; an emitted event still permits `NO_REPLY` when there is no useful new advice. Do not bypass these gates with your own timers or repeated tool calls. A direct user question should receive an answer even when a proactive reminder would be inappropriate. An initial report (`reason: "initial"`) can offer one brief factual observation without a change or advice. During a startup greeting, add at most one sentence with one or two supplied readings; preserve the greeting when readings are absent. For the separate post-greeting update, do not greet again. Never wait for sensors, fetch data for the greeting, or arrange duplicate follow-ups. Quiet/sleep preferences still take precedence. A first snapshot says nothing about improvement, health, or whether the room is safe. Offer at most one practical suggestion, with room for user choice. A meaningful improvement can merit a short acknowledgment when it follows an actual user concern/action; do not congratulate every decrease or say the air is now safe. Keep observations separate from health claims and never infer concentration, fatigue, dehydration, disease, CO₂ or oxygen shortage from the available indices. A fresh measured `co2_ppm` may support a conditional ventilation suggestion, but does not establish the cause of tiredness or impaired concentration. Particle filtration alone does not lower CO₂. Missing CO₂ does not invalidate other fresh environmental measurements. No environment-specific wellbeing log action exists: do not POST these events as activities or misuse hydration/break/posture nudge actions. ## Gotchas (concrete facts, NOT suggestions) **Endpoints — use verbatim, never substitute a port or path:** | Purpose | URL | |---|---| | Read wellbeing history | `http://127.0.0.1:5000/api/openclaw/wellbeing-history` | | Log wellbeing nudge | `http://127.0.0.1:5000/api/wellbeing/log` | | Log posture nudge | `http://127.0.0.1:5000/api/posture/log` | - Port **5000** = the backend (data APIs: wellbeing / posture / mood / music / openclaw history). - Port **5001** = HAL (audio, camera, face, presence, speaker). Has **NO** `/api/wellbeing/*` or `/api/posture/*` routes — calling 5001 returns 404 silently and your nudge is lost. - Posture nudges live on a **separate JSONL** (`/root/local/users/<user>/posture/`) for clean timeline separation; the wellbeing log keeps hydration/break/meal/sleep/morning rows. - Do not pattern-match from other skills: `5001/audio/play`, `5001/face/enroll`, `5001/camera/snapshot` are unrelated. **User attribution:** every `user` field MUST come from the `[context: current_user=X]` tag the backend injects into the triggering event. Strangers collapse to `"unknown"`. If no context tag is present, default to `"unknown"`. **Thresholds (production values):** ``` HYDRATION_THRESHOLD_MIN = 45 BREAK_THRESHOLD_MIN = 30 BREAK_THRESHOLD_TIRED = 20 # replaces the above when `yawning` is in the labels YAWN_ACK_COOLDOWN_MIN = 60 # acknowledge a yawn at most once an hour TOILET_DRINK_THRESHOLD = 2 # count-based — fires once per N drinks since last nudge ``` **The backend writes activities; you only write nudges.** Rows for `drink` / `break` / `celebrate` / `yawning` / sedentary labels are posted by the backend directly when `motion.activity` fires — before the event reaches you. Do NOT re-log them. You still POST `nudge_hydration` / `nudge_break` because only you know when you actually spoke. **Presence rows** (`enter` / `leave`) are written by the backend on `presence.*` events. You never POST those either. ## Rules (Never / Only) 1. **Only** call `http://127.0.0.1:5000/api/openclaw/wellbeing-history` to read history. **Never** read `/root/local/users/*/wellbeing/*.jsonl` or `/root/local/users/*/posture/*.jsonl` with `cat`, `ls`, `head`, `tail`, `grep`, or any filesystem tool. Posture history is digested into `last_posture_nudge_age_min` upstream — no agent-side read is needed. 2. **Only** POST to `http://127.0.0.1:5000/api/wellbeing/log` (hydration / break / toilet / morning / sleep / meal) or `http://127.0.0.1:5000/api/posture/log` (nudge_posture / praise_posture). **Never** substitute `5001`, `8080`, or any other port. **Never** omit `http://` or hardcode `localhost`. 3. **Only** write these action values: `nudge_hydration`, `nudge_break`, `nudge_toilet`, `morning_greeting`, `sleep_winddown`, `meal_reminder`, `noted_yawn` (wellbeing log), `nudge_posture`, `praise_posture` (posture log). Never invent new actions. (Activity rows — `drink`, `break`, `yawning`, raw sedentary labels, raw eat labels like `eating burger` / `dining` / `tasting food` — are written by the backend, never by you. There are no agent-written `posture_alert` rows; HAL's per-frame samples live in a separate debug JSONL on the device and never reach the posture history API.) 4. On a non-2xx response from a POST → you used the wrong port or path. Fix the URL and retry **once**. Do not give up silently — the nudge row must land, or the skill will spam reminders forever. 5. **Never** infer `user` from memory, `KNOWLEDGE.md`, chat history, or `senderLabel`. Only the `[context: current_user=X]` tag counts. 6. **Trust the log, not memory.** If the history response contains no `nudge_hydration` entry, no nudge has happened — ignore any self-memory claim otherwise. ## Read pre-fetched context (do not re-fetch) The backend injects a `[wellbeing_context: {...JSON...}]` block into every motion.activity turn. Sedentary turns may also carry `[posture_summary: {...}]` + `[computer_streak_min: N]` blocks (see `reference/posture.md`). **Do NOT fire any tool calls to re-fetch this data.** Saves the entire read tool turn. Schema (every field is pre-computed in the backend — agent only applies thresholds and picks phrasing): ```json { "hydration_delta_min": 8, // minutes since last drink/enter/nudge_hydration; -1 if no reset today "break_delta_min": 23, // minutes since last break/enter/nudge_break; -1 if no reset today "latest_activity": "using computer", // most recent action label (sedentary or reset); "" if no events "count_today": {"drink": 3, "break": 1}, // tally of reset actions today; missing key = 0; whole field omitted if all zero "time_of_day": "afternoon", // morning|noon|afternoon|evening|night — coarse bucket for reaction flavor "current_hour": 14, // exact hour 0-23 — used by activity router for hour-based routes "first_activity_today": false, // true when no prior REAL user activity events today (presence enter/leave and agent-written nudges/reminders are NOT counted) "meal_window": "", // "lunch" (11:30-13:30) | "dinner" (18:30-20:30) | "" — set by current_hour "meal_signal_in_window": false, // true when a meal signal (meal_reminder you already fired OR a raw eat label like "eating burger" / "dining" the backend logged) already exists in the current window today "morning_greeting_done_today": false, // true when a morning_greeting action exists today "sleep_winddown_done_today": false, // true when a sleep_winddown action exists today "yawn_ack_age_min": -1, // minutes since you last posted `noted_yawn`; -1 = not yet today. Gates route #1b (>= YAWN_ACK_COOLDOWN_MIN or -1 to speak) "drinks_since_toilet_nudge": 2, // count of `drink` rows logged after the most recent `nudge_toilet` today (or all today's drinks if none yet); counter resets the moment you POST `nudge_toilet` "patterns": { // wellbeing patterns from patterns.json (mtime < 6h, strength >= moderate); omitted if none "drink": {"typical_hour": 9, "typical_minute": 15, "strength": "moderate"} }, "bootstrap_needed": false, // true → patterns missing/stale AND days >= 3; only invoke habit Flow A when also nudging "last_posture_nudge_age_min": 12 // minutes since the most recent nudge_posture today; -1 if none. Used by posture-nudge / praise routes — see reference/posture.md } ``` Notes: - Delta = `-1` means no reset action has happened today yet → treat as "no nudge" (delta undefined). - `count_today` is for **reaction phrasing only** ("N-th drink today", streak callouts). It does NOT decide whether to speak — that's the trigger labels in the activity message. - `patterns` only surfaces moderate/strong matches. Weak patterns are filtered out by the backend. - `bootstrap_needed=true` does NOT mean run Flow A unconditionally — only if THIS turn fires a nudge. ### Posture summary (only on long sedentary streaks) When the user has been sitting + bad-postured long enough, the activity message carries `[posture_summary: {...}]` + `[computer_streak_min: N]` blocks. See `reference/posture.md` for the schema, when HAL attaches it, and the decision logic. The wellbeing context's `last_posture_nudge_age_min` corroborates whether a nudge already fired recently (defends against double-nudge if the agent restarted). ### Fallback (only if context block is missing) If the message has no `[wellbeing_context: ...]` block (pre-fetch failed), fall back to the bash batch: ```bash { echo '---history---' curl -s "http://127.0.0.1:5000/api/openclaw/wellbeing-history?user=<current_user>&last=50" | jq '.data.events' & echo '---patterns---' PATTERNS=/root/local/users/<current_user>/habit/patterns.json if [ -f "$PATTERNS" ] && [ $(( $(date +%s) - $(stat -c %Y "$PATTERNS") )) -lt 21600 ]; then cat "$PATTERNS" fi & echo '---days---' ls /root/local/users/<current_user>/wellbeing/*.jsonl 2>/dev/null | wc -l & wait } ``` In the fallback path, compute deltas yourself by scanning `history` for the latest reset action. ## Decision rules (activity router) Read the `[activity] Activity detected: <labels>.` message + the `[wellbeing_context: ...]` block, then pick **exactly one** route. Apply top-to-bottom, first match wins. Reaction outranks everything — the user just acted; routing past it would feel tone-deaf. | # | Condition | Route | Output | |---|---|---|---| | 1 | labels list contains `drink`, `break`, or `celebrate` OR any raw eat label (`eating burger`, `dining`, `tasting food`, … — i.e. any `eating *` / `dining` / `tasting food`) | **reaction** | 1–3 sentence acknowledgment per the **Reaction** section. **No HW marker** (the backend already logged the row upstream). | | 1b | labels contain `yawning` AND (`yawn_ack_age_min == -1` OR `yawn_ack_age_min >= YAWN_ACK_COOLDOWN_MIN`) AND `current_hour < 21` | **yawn reaction** | Same shape as #1 — name the yawn, see **Reaction**. **Unlike #1 this one DOES take a marker**: POST `noted_yawn`, which is what starts the hour cooldown. Without the POST you will re-acknowledge every yawn all afternoon. | | 2 | `first_activity_today == true` AND `current_hour ∈ [5, 11)` AND `morning_greeting_done_today == false` | **morning-greeting** | See `reference/morning-greeting.md`. Logs `morning_greeting` action to gate next firings today. | | 3 | `current_hour >= 21` AND labels are sedentary and/or `yawning` (no `drink`/`break`) AND `sleep_winddown_done_today == false` | **sleep-winddown** | See `reference/sleep-winddown.md`. Logs `sleep_winddown` action. Replaces break nudge in late evening. A `yawning` label riding alongside a sedentary one does **not** disqualify this route — it is the strongest possible confirmation for it. | | 4 | `meal_window` is non-empty AND `meal_signal_in_window == false` | **meal-reminder** | See `reference/meal-reminder.md`. Logs `meal_reminder` action with trigger `lunch` / `dinner`. Gate covers BOTH a prior reminder you already fired AND a real eat label the backend logged — so we don't ask "have you eaten?" after a real meal. | | 5 | `[posture_summary]` block present in the message | **posture-nudge** | Speak a posture nudge per the **Posture phrasing** section + post `nudge_posture` to the **posture log** (NOT wellbeing log). Anchor the line on `dominant_region` and `streak_min`. Outranks plain break/hydration nudges so we don't double-up on "stand up". | | 6 | `hydration_delta_min >= HYDRATION_THRESHOLD_MIN` | **hydration-nudge** | Speak a hydration nudge per the **Phrasing** section + post `nudge_hydration` HW marker. | | 7 | `break_delta_min >= BREAK_THRESHOLD_MIN`, **or** `break_delta_min >= BREAK_THRESHOLD_TIRED` when the labels contain `yawning` | **break-nudge** | Speak a break nudge + post `nudge_break` HW marker. When the yawn is what brought the threshold down, use the **Tired break tone** table — the standard lines claim the user has been at it "a while", which is false at 20 minutes. | | 8 | `drinks_since_toilet_nudge >= TOILET_DRINK_THRESHOLD` | **toilet-nudge** | Speak a toilet nudge per the **Phrasing** section + post `nudge_toilet` HW marker. The POST resets the counter to 0 → next nudge only after another full N drinks. | | 9 | anything else (sedentary under threshold, or any delta == `-1` → no reset today yet) | **silent** | `NO_REPLY`. | **Rules:** - **One route per turn.** Pick the first matching row, then stop. - **Reference files own the phrasing** for routes #2–#5 (morning-greeting / sleep-winddown / meal-reminder / posture-nudge). The corresponding HW marker logs `action=<route name>` so the next event in the same window/day sees `*_done_today` / `*_done_this_window` true and skips re-firing. - The `nudge_*` row you POST in routes #6 (hydration) / #7 (break) acts as the next reset point for `hydration_delta_min` / `break_delta_min`, so once you nudge the delta drops to 0 and the next reminder of that kind only fires after another full threshold window. Route #8 (toilet) similarly resets `drinks_since_toilet_nudge` to 0 on POST. - Route #5 (posture) does NOT follow that pattern — re-firing is gated by HAL's tumbling pose window: a `[posture_summary]` block only appears at the end of each completed window where bad_ratio crossed the threshold AND the user is still sedentary. Your POST does not by itself reset a timer; if the block is absent, you cannot nudge. - **Never narrate the routing decision in the spoken reply.** The reply is read aloud verbatim — the row you picked and why is scratch, not speech. Device-observed leak, 2026-08-24: *"Route: sedentary `using computer` at 70 min since last break →