forge-openclaw-plugin 0.2.109 → 0.2.111

package/dist/server/server/src/health-weight-loss.js

@@ -4,6 +4,7 @@ import { getDatabase, runInTransaction } from "./db.js";
 import { getSettings } from "./repositories/settings.js";
 import { getDefaultUser, resolveUserForMutation } from "./repositories/users.js";
 import { readEncryptedSecret } from "./repositories/calendar.js";
+import { hallNiddkWeeklyRateKgToDailyEnergyAdjustment } from "../../src/lib/weight-loss-energy-model.js";
 const optionalNumberSchema = z
     .union([z.coerce.number().finite(), z.null()])
     .optional();
@@ -269,12 +270,31 @@ function average(values) {
     }
     return real.reduce((sum, value) => sum + value, 0) / real.length;
 }
-function metricTotal(metrics, key) {
+function median(values) {
+    const sorted = values
+        .filter((value) => Number.isFinite(value))
+        .sort((left, right) => left - right);
+    if (sorted.length === 0) {
+        return null;
+    }
+    const middle = Math.floor(sorted.length / 2);
+    if (sorted.length % 2 === 1) {
+        return sorted[middle] ?? null;
+    }
+    return ((sorted[middle - 1] ?? 0) + (sorted[middle] ?? 0)) / 2;
+}
+function metricRecord(metrics, key) {
     const metric = metrics[key];
     if (!metric || typeof metric !== "object") {
         return null;
     }
-    const record = metric;
+    return metric;
+}
+function metricTotal(metrics, key) {
+    const record = metricRecord(metrics, key);
+    if (!record) {
+        return null;
+    }
     for (const field of ["total", "average", "latest"]) {
         const value = record[field];
         if (typeof value === "number" && Number.isFinite(value)) {
@@ -283,6 +303,31 @@ function metricTotal(metrics, key) {
     }
     return null;
 }
+function metricSampleCount(metrics, key) {
+    const value = metricRecord(metrics, key)?.sampleCount;
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function metricLatestSampleAt(metrics, key) {
+    const value = metricRecord(metrics, key)?.latestSampleAt;
+    return typeof value === "string" && value.trim().length > 0
+        ? value.trim()
+        : null;
+}
+function sampleHourOfDay(value) {
+    if (!value) {
+        return null;
+    }
+    const match = value.match(/T(\d{2}):/);
+    if (match?.[1]) {
+        const parsed = Number(match[1]);
+        return Number.isFinite(parsed) ? parsed : null;
+    }
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime())) {
+        return null;
+    }
+    return date.getHours();
+}
 function parsePlanNoteNumber(notes, key) {
     if (!notes) {
         return null;
@@ -292,6 +337,30 @@ function parsePlanNoteNumber(notes, key) {
     const parsed = Number(match?.[1]?.trim());
     return Number.isFinite(parsed) ? parsed : null;
 }
+function parsePlanNoteText(notes, key) {
+    if (!notes) {
+        return null;
+    }
+    const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const match = notes.match(new RegExp(`${escapedKey}=([^;]+)`));
+    return match?.[1]?.trim() ?? null;
+}
+function mifflinStJeorRestingKcal(input) {
+    if ((input.sex !== "male" && input.sex !== "female") ||
+        input.ageYears == null ||
+        input.ageYears <= 0 ||
+        input.heightCm == null ||
+        input.heightCm <= 0 ||
+        input.weightKg == null ||
+        input.weightKg <= 0) {
+        return null;
+    }
+    const sexAdjustment = input.sex === "male" ? 5 : -161;
+    return (10 * input.weightKg +
+        6.25 * input.heightCm -
+        5 * input.ageYears +
+        sexAdjustment);
+}
 function estimateStepActiveCaloriesKcal(input) {
     if (input.stepCount == null ||
         input.stepCount <= 0 ||
@@ -344,6 +413,8 @@ function buildStoredEnergyModel(input) {
             dateKey: row.date_key,
             activeEnergyKcal: metricTotal(metrics, "activeEnergyBurned"),
             restingEnergyKcal: metricTotal(metrics, "basalEnergyBurned"),
+            restingSampleCount: metricSampleCount(metrics, "basalEnergyBurned"),
+            restingLatestSampleAt: metricLatestSampleAt(metrics, "basalEnergyBurned"),
             exerciseMinutes: metricTotal(metrics, "appleExerciseTime"),
             stepCount: metricTotal(metrics, "stepCount")
         };
@@ -396,7 +467,59 @@ function buildStoredEnergyModel(input) {
             .get(input.userId, input.dayStartAt, input.dayEndAt)
         : null;
     const activeEnergyAverage = average(dailyHealthKit.map((day) => day.activeEnergyKcal));
-    const restingEnergyAverage = average(dailyHealthKit.map((day) => day.restingEnergyKcal));
+    const restingEvidenceDays = dailyHealthKit.filter((day) => day.restingEnergyKcal != null);
+    const restingExclusionReasons = [];
+    const qualifiedRestingDays = restingEvidenceDays.filter((day) => {
+        const reasons = [];
+        if (day.dateKey >= todayKey) {
+            reasons.push("current_day_or_future_day");
+        }
+        if ((day.restingSampleCount ?? 0) < 24) {
+            reasons.push(`sample_count_${day.restingSampleCount ?? 0}_below_24`);
+        }
+        const latestSampleHour = sampleHourOfDay(day.restingLatestSampleAt);
+        if (latestSampleHour == null) {
+            reasons.push("missing_latest_basal_sample");
+        }
+        else if (latestSampleHour < 20) {
+            reasons.push(`latest_basal_sample_hour_${latestSampleHour}_before_20`);
+        }
+        if (input.formulaRestingKcal != null && day.restingEnergyKcal != null) {
+            const lowThreshold = Math.max(input.formulaRestingKcal * 0.75, 1000);
+            if (day.restingEnergyKcal < lowThreshold) {
+                reasons.push(`basal_${round(day.restingEnergyKcal, 0)}_below_${round(lowThreshold, 0)}`);
+            }
+        }
+        if (reasons.length > 0) {
+            restingExclusionReasons.push(`${day.dateKey}: ${reasons.join(",")}`);
+            return false;
+        }
+        return true;
+    });
+    const wearableRestingKcal = median(qualifiedRestingDays
+        .map((day) => day.restingEnergyKcal)
+        .filter((value) => value != null));
+    const chosenRestingKcal = input.formulaRestingKcal ?? input.savedRestingKcal ?? null;
+    const chosenRestingSource = input.formulaRestingKcal != null
+        ? "mifflin_profile_baseline"
+        : input.savedRestingKcal != null
+            ? "saved_plan_legacy"
+            : null;
+    const restingConfidence = (() => {
+        if (input.formulaRestingKcal == null && input.savedRestingKcal != null) {
+            return "low";
+        }
+        if (input.formulaRestingKcal == null) {
+            return "low";
+        }
+        if (wearableRestingKcal != null &&
+            Math.abs(wearableRestingKcal - input.formulaRestingKcal) /
+                input.formulaRestingKcal >
+                0.15) {
+            return "review";
+        }
+        return qualifiedRestingDays.length > 0 ? "high" : "medium";
+    })();
     const workoutEnergyAverage = average([...workoutByDay.values()]);
     const movementCaloriesAverage = average([...movementByDay.values()]);
     const fallbackActiveBurn = workoutEnergyAverage != null || movementCaloriesAverage != null
@@ -477,13 +600,15 @@ function buildStoredEnergyModel(input) {
     const todayActiveCalories = input.dailyActiveOverride?.activeCaloriesKcal ??
         todayObservedActiveCalories ??
         baselineActiveCalories;
-    const todayTargetAdjustmentKcal = todayActiveCalories - baselineActiveCalories;
-    const estimatedTdeeKcal = activeBurnKcal != null && restingEnergyAverage != null
-        ? round(activeBurnKcal + restingEnergyAverage, 0)
+    const todayActiveSurplusKcal = Math.max(0, todayActiveCalories - baselineActiveCalories);
+    const todayActivityBufferKcal = todayActiveSurplusKcal * input.activityEatBackFraction;
+    const todayTargetAdjustmentKcal = todayActivityBufferKcal;
+    const estimatedTdeeKcal = activeBurnKcal != null && chosenRestingKcal != null
+        ? round(activeBurnKcal + chosenRestingKcal, 0)
         : input.inferredTdee;
     const hasHealthKitDailyActiveEnergy = activeEnergyAverage != null;
     const hasHealthKitEnergy = hasHealthKitDailyActiveEnergy ||
-        restingEnergyAverage != null ||
+        wearableRestingKcal != null ||
         workoutEnergyAverage != null;
     const hasMovementEnergy = movementCaloriesAverage != null;
     const sourceConfidence = activeEnergyAverage != null
@@ -493,7 +618,18 @@ function buildStoredEnergyModel(input) {
             : "target_inference_only";
     return {
         activeEnergyCalories: activeEnergyAverage != null ? round(activeEnergyAverage, 0) : null,
-        restingEnergyCalories: restingEnergyAverage != null ? round(restingEnergyAverage, 0) : null,
+        restingEnergyCalories: chosenRestingKcal != null ? round(chosenRestingKcal, 0) : null,
+        formulaRestingKcal: input.formulaRestingKcal != null
+            ? round(input.formulaRestingKcal, 0)
+            : null,
+        wearableRestingKcal: wearableRestingKcal != null ? round(wearableRestingKcal, 0) : null,
+        wearableRestingSource: wearableRestingKcal != null ? "healthkit_basal_energy" : null,
+        wearableRestingDayCount: restingEvidenceDays.length,
+        wearableRestingCoverageQualifiedDayCount: qualifiedRestingDays.length,
+        chosenRestingKcal: chosenRestingKcal != null ? round(chosenRestingKcal, 0) : null,
+        chosenRestingSource,
+        restingConfidence,
+        restingExclusionReasons,
         wearableConfidence: hasHealthKitEnergy
             ? "measured_directional"
             : "directional",
@@ -507,6 +643,9 @@ function buildStoredEnergyModel(input) {
             : null,
         todayActiveCaloriesSource: todayActiveSource,
         todayTargetAdjustmentKcal: round(todayTargetAdjustmentKcal, 0),
+        todayActiveSurplusKcal: round(todayActiveSurplusKcal, 0),
+        todayActivityBufferKcal: round(todayActivityBufferKcal, 0),
+        activityEatBackFraction: round(input.activityEatBackFraction, 2),
         todayWorkoutEnergyKcal: todayWorkoutEnergy != null ? round(todayWorkoutEnergy, 0) : null,
         todayMovementCaloriesKcal: todayMovementCalories != null ? round(todayMovementCalories, 0) : null,
         todayHealthKitActiveCaloriesKcal: todayHealthKitActive != null ? round(todayHealthKitActive, 0) : null,
@@ -1539,9 +1678,17 @@ export function getWeightLossViewData(userIds, options = {}) {
         ? round(recentTotals.calories / recentTrackedDays, 0)
         : 0;
     const inferredTdee = target.calorieTarget != null
-        ? round(target.calorieTarget + Math.abs(n(target.weeklyRateGoalKg)) * 1100, 0)
+        ? round(target.calorieTarget +
+            Math.abs(hallNiddkWeeklyRateKgToDailyEnergyAdjustment(target.weeklyRateGoalKg) ?? 0), 0)
         : null;
     const defaultActiveCalories = parsePlanNoteNumber(target.notes, "activity_kcal");
+    const formulaRestingKcal = mifflinStJeorRestingKcal({
+        sex: parsePlanNoteText(target.notes, "sex"),
+        ageYears: parsePlanNoteNumber(target.notes, "age_years"),
+        heightCm: parsePlanNoteNumber(target.notes, "height_cm"),
+        weightKg: weightTrend.latestWeightKg
+    });
+    const activityEatBackFraction = Math.min(1, Math.max(0, parsePlanNoteNumber(target.notes, "eat_back_fraction") ?? 0.5));
     const dailyActiveOverride = getDailyEnergyOverride(userId, todayKey);
     const energyModel = buildStoredEnergyModel({
         userId,
@@ -1554,7 +1701,10 @@ export function getWeightLossViewData(userIds, options = {}) {
         recentFoodLogDayCount: recentTrackedDays,
         defaultActiveCalories,
         latestWeightKg: weightTrend.latestWeightKg,
-        dailyActiveOverride
+        dailyActiveOverride,
+        formulaRestingKcal,
+        savedRestingKcal: parsePlanNoteNumber(target.notes, "resting_kcal"),
+        activityEatBackFraction
     });
     const todayTargetCalories = Math.max(0, round(target.calorieTarget + energyModel.todayTargetAdjustmentKcal, 0));
     const todayLedger = buildTodayLedger(logs, target, todayKey, todayTargetCalories, energyModel.todayTargetAdjustmentKcal, energyModel.todayActiveCaloriesSource);

package/dist/server/src/lib/weight-loss-energy-model.js

@@ -0,0 +1,64 @@
+export const HALL_NIDDK_LINEAR_WEIGHT_MODEL = {
+    id: "hall_niddk_linearized_adult_12w",
+    label: "Hall/NIDDK linearized adult model",
+    defaultPlanningHorizonDays: 84,
+    steadyStateKcalPerKgPerDay: 10 / 0.45359237,
+    timeConstantDays: 365,
+    staticEnergyDensityKcalPerKg: 7700
+};
+function positiveFinite(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0
+        ? value
+        : null;
+}
+export function hallNiddkWeightModelParameters(options = {}) {
+    const planningHorizonDays = positiveFinite(options.planningHorizonDays) ??
+        HALL_NIDDK_LINEAR_WEIGHT_MODEL.defaultPlanningHorizonDays;
+    const timeConstantDays = positiveFinite(options.timeConstantDays) ??
+        HALL_NIDDK_LINEAR_WEIGHT_MODEL.timeConstantDays;
+    const steadyStateKcalPerKgPerDay = positiveFinite(options.steadyStateKcalPerKgPerDay) ??
+        HALL_NIDDK_LINEAR_WEIGHT_MODEL.steadyStateKcalPerKgPerDay;
+    const responseFraction = 1 - Math.exp(-planningHorizonDays / timeConstantDays);
+    return {
+        planningHorizonDays,
+        timeConstantDays,
+        steadyStateKcalPerKgPerDay,
+        responseFraction
+    };
+}
+export function hallNiddkWeeklyRateKgToDailyEnergyAdjustment(weeklyRateKg, options = {}) {
+    if (typeof weeklyRateKg !== "number" || !Number.isFinite(weeklyRateKg)) {
+        return null;
+    }
+    if (weeklyRateKg === 0) {
+        return 0;
+    }
+    const parameters = hallNiddkWeightModelParameters(options);
+    if (parameters.responseFraction <= 0) {
+        return null;
+    }
+    const targetChangeKg = weeklyRateKg * (parameters.planningHorizonDays / 7);
+    return ((targetChangeKg * parameters.steadyStateKcalPerKgPerDay) /
+        parameters.responseFraction);
+}
+export function hallNiddkDailyEnergyAdjustmentToAverageWeeklyRateKg(dailyEnergyAdjustmentKcal, options = {}) {
+    if (typeof dailyEnergyAdjustmentKcal !== "number" ||
+        !Number.isFinite(dailyEnergyAdjustmentKcal)) {
+        return null;
+    }
+    if (dailyEnergyAdjustmentKcal === 0) {
+        return 0;
+    }
+    const parameters = hallNiddkWeightModelParameters(options);
+    const totalChangeKg = (dailyEnergyAdjustmentKcal / parameters.steadyStateKcalPerKgPerDay) *
+        parameters.responseFraction;
+    return totalChangeKg / (parameters.planningHorizonDays / 7);
+}
+export function staticKgRateToDailyEnergyAdjustment(weeklyRateKg) {
+    if (typeof weeklyRateKg !== "number" || !Number.isFinite(weeklyRateKg)) {
+        return null;
+    }
+    return ((weeklyRateKg *
+        HALL_NIDDK_LINEAR_WEIGHT_MODEL.staticEnergyDensityKcalPerKg) /
+        7);
+}

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "forge-openclaw-plugin",
   "name": "Forge",
   "description": "Curated OpenClaw adapter for the Forge collaboration API, UI entrypoint, and localhost auto-start runtime.",
-  "version": "0.2.109",
+  "version": "0.2.111",
   "activation": {
     "onStartup": true,
     "onCapabilities": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-openclaw-plugin",
-  "version": "0.2.109",
+  "version": "0.2.111",
   "description": "Curated OpenClaw adapter for the Forge collaboration API, UI entrypoint, and localhost auto-start runtime.",
   "type": "module",
   "license": "Apache-2.0",

package/skills/forge-openclaw/SKILL.md

@@ -238,6 +238,11 @@ Entity conversation rule:
 
 - For all entity creation or update flows, first use [`entity_conversation_playbooks.md`](./entity_conversation_playbooks.md) to decide the next best question.
 - Ask only for what is missing or unclear. Do not walk through every schema field.
+- Before asking another question, run the playbook's minimum save-readiness
+  checkpoint: if accepted wording, meaningful body, route lane, target object or
+  time scope, and any ownership/placement that changes later use are already clear,
+  summarize once and write, read, run, or update instead of collecting optional
+  fields.
 - Let each question have one job. Know what you are trying to clarify before you ask it.
 - Before you ask, decide the exact missing thing you need and how that answer will help you name, place, or save the record.
 - Prefer a progression of:
@@ -299,6 +304,11 @@ Psyche interview rule:
 - In that first exploratory turn, ask only one question, do not search Forge or mention whether a matching entity exists, and avoid openings like "This sounds like" or "What you're describing is".
 - In that first exploratory turn, prefer exactly two sentences: one brief empathic reflection and one concrete question. Avoid colons because they tend to trigger list-like answers.
 - Follow the preferred opening-question patterns in [`psyche_entity_playbooks.md`](./psyche_entity_playbooks.md) when they fit the entity the user is exploring.
+- After a Psyche formulation lands, use the Psyche save-readiness checkpoint from
+  the playbook. If the belief sentence, functional loop, behavior move, part-state,
+  trigger episode, value, event type, emotion definition, or flashcard cue/message is
+  true enough to save, ask at most one accuracy question and then use shared batch
+  CRUD.
 - If the user already offers a usable belief sentence, value phrase, or mode name,
   refine from their wording first instead of replacing it with a cleaner label too
   early.

package/skills/forge-openclaw/entity_conversation_playbooks.md

@@ -258,6 +258,39 @@ Most good Forge intake flows follow this sequence:
 
 That sequence is not a script. Skip steps the user already answered.
 
+## Minimum save-readiness checkpoint
+
+Use this before asking another polished follow-up. The question quality is worse, not
+better, when the agent keeps exploring after the record or route is already clear
+enough to act.
+
+- For normal batch entities, save or update when you have the accepted working name
+  or distinctive wording, the meaningful body of the record, and owner scope only if
+  ownership changes accountability. Do not ask for tags, links, dates, priority,
+  assignees, or status just because those fields exist.
+- For strategic and planning records, the minimum is the intended outcome plus the
+  hierarchy placement that would change later retrieval or execution. If placement is
+  not known but the user asked to capture the idea now, save the provisional record
+  with clear wording and leave placement for a later link/update.
+- For operational records, the minimum is the target action plus the time, object, or
+  state that makes the action truthful: event time for a calendar event, recurrence
+  for a work block, task and slot for a timebox, task id for a task run, or target
+  record and signed minutes for a work adjustment. Generate a plain title yourself
+  when the title is obvious.
+- For read-model and review surfaces, the minimum is the practical question plus any
+  scope that would change the answer. Once you have that, read the overview instead
+  of asking for a preferred report shape.
+- For specialized Movement, Life Force, and Workbench writes, the minimum is the
+  selected lane plus the target span/object/weekday/flow/run/node and the intended
+  correction or effect. Do not ask a reflective question after the dedicated route
+  and write shape are already selected.
+- For reflective non-Psyche records, the minimum is what future review should
+  remember and the container that preserves it. If a stronger Psyche container clearly
+  emerges, route there; otherwise do not keep deepening just to make the note more
+  therapeutic.
+- Close the loop in one sentence before acting: "What seems clear now is..." followed
+  by the save, update, read, run, or handoff.
+
 ## Project-management hierarchy playbook
 
 When the conversation is about Forge planning or delivery, preserve this

package/skills/forge-openclaw/psyche_entity_playbooks.md

@@ -236,6 +236,37 @@ of leaving it as warm reflective prose.
 - Save through shared batch entity routes only after the user accepts the working
   wording or explicitly asks to save.
 
+## Psyche save-readiness checkpoint
+
+Use this before asking another deepening question. Psyche work should feel careful,
+but not endless. Once the user recognizes the working formulation, protect momentum and
+save the record instead of reopening the whole story.
+
+- For `belief_entry`, the minimum is the accepted sentence or prediction plus whether
+  it is mainly about self, others, world/safety, or outcome when that distinction is
+  visible.
+- For `behavior_pattern`, the minimum is a concrete cue or situation, the felt
+  meaning/body shift, the behavior or urge, and at least one payoff or cost. A
+  preferred response is useful, but do not force it before saving a provisional
+  functional analysis.
+- For `behavior`, the minimum is the repeated move, the cue or urge that brings it
+  online, and whether the move functions as avoidance, committed action, repair, or
+  recovery when that is clear.
+- For `mode_profile`, the minimum is the part's voice or posture, what it is trying
+  to protect, and what danger or burden it expects.
+- For `mode_guide_session`, the minimum is the present trigger, a brief summary of
+  what the active part seems to want, and the answers gathered so far.
+- For `trigger_report`, the minimum is the situation, felt stake, meaning or thought,
+  action/urge, and consequence that make it one emotionally meaningful episode.
+- For `psyche_value`, `event_type`, and `emotion_definition`, the minimum is the
+  future use: what this value, recurring moment, or lived feeling label will help
+  future reports notice consistently.
+- For `flashcard`, the minimum is the cue or urge sentence and one brief message the
+  user can recognize while triggered. Link to beliefs, modes, values, or patterns only
+  when the link is already clear or will materially improve retrieval.
+- After the minimum is present, ask one accuracy question at most: "Is this true
+  enough to save as a first version?" If yes, save through shared batch CRUD.
+
 ## Psyche Hypothesis Map
 
 Use these shapes after at least one concrete example is clear. The hypothesis should