forge-openclaw-plugin 0.2.47 → 0.2.48

package/dist/index.html

@@ -13,7 +13,7 @@
     />
     <link rel="icon" type="image/png" href="/forge/assets/favicon-BCHm9dUV.ico" />
     <link rel="alternate icon" href="/forge/assets/favicon-BCHm9dUV.ico" />
-    <script type="module" crossorigin src="/forge/assets/index-BejDHw1R.js"></script>
+    <script type="module" crossorigin src="/forge/assets/index-Bv9FWWsZ.js"></script>
     <link rel="modulepreload" crossorigin href="/forge/assets/vendor-D_NZFJze.js">
     <link rel="modulepreload" crossorigin href="/forge/assets/board-CAszQU7Y.js">
     <link rel="modulepreload" crossorigin href="/forge/assets/ui-B5MjRjKe.js">

package/dist/openclaw/api-client.js

@@ -46,6 +46,20 @@ export function canBootstrapOperatorSession(baseUrl) {
 function isRecord(value) {
     return typeof value === "object" && value !== null;
 }
+function extractUpstreamErrorCode(body) {
+    return isRecord(body) &&
+        isRecord(body.error) &&
+        typeof body.error.code === "string"
+        ? body.error.code
+        : null;
+}
+function buildGuidedUpstreamMessage(result, fallback) {
+    const upstreamCode = extractUpstreamErrorCode(result.body);
+    if (result.status === 401 && upstreamCode === "auth_required") {
+        return `${fallback} In OpenClaw, do not fall back to raw Forge routes. Call forge_get_agent_onboarding, then use the shared plugin tools. For official habit outcomes, use forge_update_entities on entityType "habit" with patch.checkIn instead of a direct check-in route call.`;
+    }
+    return fallback;
+}
 function buildErrorBody(code, message) {
     return {
         ok: false,
@@ -342,7 +356,7 @@ export function expectForgeSuccess(result) {
             typeof result.body.error.message === "string"
             ? result.body.error.message
             : `Forge API returned ${result.status}`;
-        throw new ForgePluginError(result.status, "forge_plugin_upstream_error", message);
+        throw new ForgePluginError(result.status, "forge_plugin_upstream_error", buildGuidedUpstreamMessage(result, message));
     }
     return result.body;
 }

package/dist/openclaw/tools.js

@@ -848,7 +848,7 @@ export function registerForgePluginTools(api, config) {
     registerWriteTool(api, config, {
         name: "forge_update_entities",
         label: "Update Forge Entities",
-        description: "Update one or more Forge entities through the ordered batch workflow. Pass `operations` as an array. Each operation must include `entityType`, `id`, and `patch`. This is the preferred update path for calendar_event, work_block_template, task_timebox, preferences basic CRUD entities, and questionnaire_instrument too.",
+        description: "Update one or more Forge entities through the ordered batch workflow. Pass `operations` as an array. Each operation must include `entityType`, `id`, and `patch`. This is the preferred update path for calendar_event, work_block_template, task_timebox, preferences basic CRUD entities, questionnaire_instrument, and official habit outcome logging through `habit.patch.checkIn`.",
         parameters: Type.Object({
             atomic: Type.Optional(Type.Boolean()),
             operations: Type.Array(Type.Object({

package/dist/server/server/src/app.js

@@ -830,7 +830,8 @@ const AGENT_ONBOARDING_ENTITY_CATALOG_BASE = [
         ],
         searchHints: [
             "Search by title before creating a duplicate habit.",
-            "Use linkedTo when the habit should already be attached to a goal, project, task, or Psyche entity."
+            "Use linkedTo when the habit should already be attached to a goal, project, task, or Psyche entity.",
+            "To log an official habit outcome from the shared agent tool surface, patch the habit through forge_update_entities with checkIn: { status, dateKey?, note?, description? }."
         ],
         examples: [
             '{"title":"Morning training","frequency":"daily","polarity":"positive","linkedGoalIds":["goal_train_body"],"linkedValueIds":["value_steadiness"],"linkedBehaviorIds":["behavior_regulating_walk"]}'
@@ -3096,6 +3097,7 @@ const AGENT_ONBOARDING_ENTITY_CONVERSATION_PLAYBOOKS = [
             "Ask for the time window, place, or movement item that makes the question concrete.",
             "Ask what they are trying to notice, preserve, or answer through that movement context.",
             "Choose the dedicated day, month, all-time, timeline, places, trip-detail, or selection route once the question shape is clear.",
+            "If the truth of one uncertain span is still unclear, read the timeline or saved-box detail before you mutate it.",
             "Skip the meta lane question when the user already named the exact correction or review target and only one ambiguity remains.",
             "If the request is filling a missing-data gap, use a user-defined movement box rather than a raw stay or trip patch.",
             "If the request is repairing already-saved movement data, use the repair route that matches the saved object instead of treating it like a missing span.",
@@ -3113,6 +3115,7 @@ const AGENT_ONBOARDING_ENTITY_CONVERSATION_PLAYBOOKS = [
             "Ask what part of the current energy picture feels most important or inaccurate.",
             "Ask what should stay true if they are changing profile or template assumptions.",
             "Ask whether the user is describing a stable weekly shape or just how today feels when the lane is still blurred.",
+            "If the user describes a repeatable day-shape such as 'Mondays crash after lunch', treat that as a weekday-template question before you reach for profile or fatigue-signal routes.",
             "If the user already named the life-force lane clearly, skip the meta lane question and ask only for the specific weekday, profile field, or signal that still matters.",
             "If the request is about a durable baseline, use profile or weekday-template mutation rather than a fatigue signal; if it is about right now, prefer the fatigue-signal route.",
             "If the user wants to see what changed after a write, read the overview back instead of leaving the result implicit.",
@@ -3126,11 +3129,12 @@ const AGENT_ONBOARDING_ENTITY_CONVERSATION_PLAYBOOKS = [
         askSequence: [
             "Ask whether the job is flow discovery, one flow edit, execution, run history, published output, node-level inspection, or latest-node-output lookup.",
             "Ask which flow, slug, run, or node the request is about.",
-            "Ask whether they need the flow contract, a run result, a published output, or a node result.",
+            "Ask whether they need the stable flow contract, one run result, one published output, one node result, or the latest node output.",
             "Ask what the user is trying to learn, repair, or publish through that flow.",
             "If the user already named the flow and action clearly, skip the meta lane question and ask only for the missing run, node, or output scope.",
             "If the user wants a stable public input contract or published output, prefer those dedicated reads instead of detouring through run history first.",
             "If the user is still shaping a payload or edit, prefer flow detail or box catalog reads before asking for structured inputs.",
+            "If the user is debugging one failed run, ask whether the useful artifact is the run summary, one node result, the latest node output, or the published output before you start asking for edits.",
             "Prefer flow detail or published-output reads for stable contracts, and use run or node-result routes only when the user is asking about execution history or debugging.",
             "Route to the dedicated workbench route family once the execution lane is clear."
         ]
@@ -3985,8 +3989,8 @@ function buildAgentOnboardingPayload(request) {
         tokenRecovery: {
             rawTokenStoredByForge: false,
             recoveryAction: "rotate_or_issue_new_token",
-            rotationSummary: "Forge reveals raw tokens once. If you lose one, rotate it or issue a new token from Settings and update the plugin config.",
-            settingsSummary: "Token creation, rotation, and revocation all live under Forge Settings so recovery is explicit and operator-controlled."
+            rotationSummary: "Forge reveals raw tokens once. If you lose one, rotate it or issue a new token through /api/v1/settings/tokens, then update the plugin config.",
+            settingsSummary: "Token creation, rotation, and revocation all live on explicit settings routes so recovery stays operator-controlled without requiring a browser click."
         },
         requiredHeaders: {
             authorization: "Authorization: Bearer <forge-api-token>",
@@ -4281,19 +4285,24 @@ function buildAgentOnboardingPayload(request) {
                 installSteps: [
                     "Install the Forge plugin from the repo or published package.",
                     "Restart the OpenClaw gateway so the tool surface and UI proxy routes refresh.",
-                    "Open Forge Settings -> Agents to issue or rotate a managed token when remote scoped auth is needed."
+                    "For localhost or Tailscale, finish onboarding through operator-session bootstrap and CLI verification without opening the Forge UI.",
+                    "If remote scoped auth is needed, issue or rotate a managed token through /api/v1/settings/tokens and update the plugin config without a Settings click."
                 ],
                 verifyCommands: [
                     `curl -s ${origin}/api/v1/health`,
                     "openclaw plugins install ./projects/forge/openclaw-plugin",
                     "openclaw plugins info forge-openclaw-plugin",
-                    "openclaw gateway restart"
+                    "openclaw gateway restart",
+                    "openclaw forge onboarding",
+                    "openclaw forge health"
                 ],
                 configNotes: [
                     "Localhost and Tailscale targets can usually use the operator-session path without a long-lived token.",
+                    "The operator-session route is /api/v1/auth/operator-session, so trusted local OpenClaw onboarding does not need a browser confirmation step.",
                     "If your current OpenClaw build blocks the repo-local install because of the package scanner, keep the repo folder on plugins.load.paths and verify that plugins info still points at the local Forge source path before continuing.",
                     "Use a distinct actor label such as Albert (claw) so OpenClaw-originated work stays obvious in Forge provenance.",
-                    "Create each agent as a Forge bot user, then use userId or userIds in tool inputs whenever the agent should focus on one human, one bot, or a specific collaboration slice."
+                    "Create each agent as a Forge bot user, then use userId or userIds in tool inputs whenever the agent should focus on one human, one bot, or a specific collaboration slice.",
+                    "If you genuinely need a durable managed token, create it through /api/v1/settings/tokens instead of sending the operator into the Settings UI."
                 ]
             },
             hermes: {
@@ -4301,7 +4310,7 @@ function buildAgentOnboardingPayload(request) {
                 installSteps: [
                     "Install forge-hermes-plugin into the Python environment Hermes actually runs.",
                     "Let Hermes load the Forge plugin and bundled skill pack on startup.",
-                    "Use Forge Settings -> Agents if Hermes needs a managed token for remote or durable access."
+                    "If Hermes needs remote or durable scoped auth, issue a managed token through /api/v1/settings/tokens and update the Hermes config without a Settings click."
                 ],
                 verifyCommands: [
                     "python -m pip show forge-hermes-plugin",
@@ -4436,7 +4445,7 @@ function buildAgentOnboardingPayload(request) {
             saveSuggestionTone: "gentle_optional",
             maxQuestionsPerTurn: 1,
             psycheExplorationRule: "When a Psyche entity needs understanding first, begin with one exploratory question before any working formulation, replacement belief, suggested title, or save pitch. Keep the opening reflection to one or two short sentences, stay in plain prose instead of bullets or numbered lists, keep that first reply short, do not mention Forge search or save structure yet, avoid colons or list-shaped phrasing, prefer what/when/how over why until the experience is grounded, wait for the user's answer before offering a fuller formulation, ask permission before moving from charged exploration into naming or challenge when needed, do not widen into adjacent entities until the current one has a working sentence the user recognizes, and once the lived experience is coherent stop deepening and help the user name it cleanly. When the user is updating a Psyche record because of one fresh episode, anchor in that episode before renaming the durable formulation. If the user accepts the wording, move toward the save instead of reopening deeper exploration.",
-            specializedSurfaceRule: "For Movement, Life Force, and Workbench, clarify the lane first, then name the dedicated route family in plain language and do not guess at a generic CRUD path. When the user already named a precise correction or review target, confirm only the route-selecting detail that is still missing. After a concrete specialized-surface correction, read the relevant specialized view back when the user is trying to understand the result rather than just store it. The canonical runtime routes stay under /api/v1/*, and the OpenClaw HTTP mirror exposes the same families under /forge/v1/movement, /forge/v1/life-force, and /forge/v1/workbench.",
+            specializedSurfaceRule: "For Movement, Life Force, and Workbench, clarify the lane first, then name the dedicated route family in plain language and do not guess at a generic CRUD path. If the truth of the current state is still uncertain, read the relevant specialized view before you mutate it. When the user already named a precise correction or review target, confirm only the route-selecting detail that is still missing. After a concrete specialized-surface correction, read the relevant specialized view back when the user is trying to understand the result rather than just store it. The canonical runtime routes stay under /api/v1/*, and the OpenClaw HTTP mirror exposes the same families under /forge/v1/movement, /forge/v1/life-force, and /forge/v1/workbench.",
             reviewShortcutRule: "When the user is reviewing or correcting an existing record, narrow the saved object, timeframe, or route family first. Do not reopen the whole intake unless the user is actually redefining the record.",
             readModelWriteRule: "Self-observation is note-backed and should be written through observed notes with frontmatter.observedAt. Sleep and workout sessions stay on batch CRUD by default; use the reflective review helpers only when enriching one already-known record after review.",
             psycheOpeningQuestionRule: "Prefer a concrete opening question tied to the entity: ask when the value mattered, what happened the last time the pattern appeared, what cue or body signal came first before the behavior, what the belief starts saying about self or outcome, what feels most at risk inside the mode, what the part is trying to get the user to do or stop doing, or where the shift began in the incident. Reflect briefly before the question, choose one follow-up lane at a time, say what is becoming clearer before the next deeper question, and if several Psyche entities are visible hold the adjacent ones lightly until the main container is clear.",
@@ -4460,9 +4469,9 @@ function buildAgentOnboardingPayload(request) {
             batchingRule: "forge_create_entities, forge_update_entities, forge_delete_entities, and forge_restore_entities all accept operations as arrays. Batch CRUD is the default for simple entities, so batch multiple related mutations together instead of reaching for a long list of entity-specific routes.",
             searchRule: "forge_search_entities accepts searches as an array. Search before create or update when duplicate risk exists.",
             createRule: "Each create operation must include entityType and full data. entityType alone is not enough. This includes calendar_event, work_block_template, task_timebox, sleep_session, workout_session, preference CRUD entities, and questionnaire_instrument alongside the usual planning and Psyche entities.",
-            updateRule: "Each update operation must include entityType, id, and patch. For projects, lifecycle changes are status patches: active to restart, paused to suspend, completed to finish. Keep task and project scheduling rules on those same patch payloads. Calendar-event updates still run downstream provider projection sync, and manual health-session field edits belong on the batch route by default rather than on the reflective review helpers.",
+            updateRule: "Each update operation must include entityType, id, and patch. For projects, lifecycle changes are status patches: active to restart, paused to suspend, completed to finish. Keep task and project scheduling rules on those same patch payloads. Official habit outcomes can also be logged through forge_update_entities by patching the habit with checkIn: { status, dateKey?, note?, description? } instead of route-hunting. Calendar-event updates still run downstream provider projection sync, and manual health-session field edits belong on the batch route by default rather than on the reflective review helpers.",
             createExample: '{"operations":[{"entityType":"goal","data":{"title":"Create meaningfully"},"clientRef":"goal-create-1"},{"entityType":"goal","data":{"title":"Build a beautiful family"},"clientRef":"goal-create-2"}]}',
-            updateExample: '{"operations":[{"entityType":"project","id":"project_123","patch":{"status":"paused","schedulingRules":{"blockWorkBlockKinds":["main_activity"],"allowWorkBlockKinds":["secondary_activity"]}},"clientRef":"project-suspend-1"},{"entityType":"task","id":"task_456","patch":{"plannedDurationSeconds":5400,"schedulingRules":{"allowEventKeywords":["creative"],"blockEventKeywords":["clinic"]}},"clientRef":"task-scheduling-1"}]}'
+            updateExample: '{"operations":[{"entityType":"project","id":"project_123","patch":{"status":"paused","schedulingRules":{"blockWorkBlockKinds":["main_activity"],"allowWorkBlockKinds":["secondary_activity"]}},"clientRef":"project-suspend-1"},{"entityType":"habit","id":"habit_456","patch":{"checkIn":{"status":"missed","note":"Resisted the urge after dinner.","description":"85 sec reset"}},"clientRef":"habit-check-in-1"}]}'
         }
     };
 }

package/dist/server/server/src/health-workout-adapters.js

@@ -0,0 +1,465 @@
+import { z } from "zod";
+const scalarSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+export const workoutActivityDescriptorSchema = z.object({
+    sourceSystem: z.string().trim().min(1),
+    providerActivityType: z.string().trim().min(1),
+    providerRawValue: z.number().int().nullable().optional(),
+    canonicalKey: z.string().trim().min(1),
+    canonicalLabel: z.string().trim().min(1),
+    familyKey: z.string().trim().min(1),
+    familyLabel: z.string().trim().min(1),
+    isFallback: z.boolean().default(false)
+});
+export const workoutMetricSchema = z.object({
+    key: z.string().trim().min(1),
+    label: z.string().trim().min(1),
+    category: z.string().trim().min(1),
+    unit: z.string().trim().min(1).default("count"),
+    statistic: z.string().trim().min(1).default("value"),
+    value: scalarSchema,
+    startedAt: z.string().datetime().nullable().optional(),
+    endedAt: z.string().datetime().nullable().optional()
+});
+export const workoutEventSchema = z.object({
+    type: z.string().trim().min(1),
+    label: z.string().trim().min(1),
+    startedAt: z.string().datetime(),
+    endedAt: z.string().datetime().nullable().optional(),
+    durationSeconds: z.number().int().nonnegative().default(0),
+    metadata: z.record(z.string(), scalarSchema).default({})
+});
+export const workoutComponentSchema = z.object({
+    externalUid: z.string().trim().min(1),
+    startedAt: z.string().datetime(),
+    endedAt: z.string().datetime().nullable().optional(),
+    durationSeconds: z.number().int().nonnegative().default(0),
+    activity: workoutActivityDescriptorSchema,
+    metrics: z.array(workoutMetricSchema).default([]),
+    metadata: z.record(z.string(), scalarSchema).default({})
+});
+export const workoutDetailsSchema = z.object({
+    sourceSystem: z.string().trim().min(1),
+    metrics: z.array(workoutMetricSchema).default([]),
+    events: z.array(workoutEventSchema).default([]),
+    components: z.array(workoutComponentSchema).default([]),
+    metadata: z.record(z.string(), scalarSchema).default({})
+});
+const APPLE_HEALTH_ACTIVITY_TYPES = new Map([
+    [1, { key: "american_football", label: "American football" }],
+    [2, { key: "archery", label: "Archery" }],
+    [3, { key: "australian_football", label: "Australian football" }],
+    [4, { key: "badminton", label: "Badminton" }],
+    [5, { key: "baseball", label: "Baseball" }],
+    [6, { key: "basketball", label: "Basketball" }],
+    [7, { key: "bowling", label: "Bowling" }],
+    [8, { key: "boxing", label: "Boxing" }],
+    [9, { key: "climbing", label: "Climbing" }],
+    [10, { key: "cricket", label: "Cricket" }],
+    [11, { key: "cross_training", label: "Cross training" }],
+    [12, { key: "curling", label: "Curling" }],
+    [13, { key: "cycling", label: "Cycling" }],
+    [14, { key: "dance", label: "Dance" }],
+    [15, { key: "dance_inspired_training", label: "Dance-inspired training" }],
+    [16, { key: "elliptical", label: "Elliptical" }],
+    [17, { key: "equestrian_sports", label: "Equestrian sports" }],
+    [18, { key: "fencing", label: "Fencing" }],
+    [19, { key: "fishing", label: "Fishing" }],
+    [20, { key: "functional_strength_training", label: "Functional strength training" }],
+    [21, { key: "golf", label: "Golf" }],
+    [22, { key: "gymnastics", label: "Gymnastics" }],
+    [23, { key: "handball", label: "Handball" }],
+    [24, { key: "hiking", label: "Hiking" }],
+    [25, { key: "hockey", label: "Hockey" }],
+    [26, { key: "hunting", label: "Hunting" }],
+    [27, { key: "lacrosse", label: "Lacrosse" }],
+    [28, { key: "martial_arts", label: "Martial arts" }],
+    [29, { key: "mind_and_body", label: "Mind and body" }],
+    [30, { key: "mixed_metabolic_cardio_training", label: "Mixed metabolic cardio training" }],
+    [31, { key: "paddle_sports", label: "Paddle sports" }],
+    [32, { key: "play", label: "Play" }],
+    [33, { key: "preparation_and_recovery", label: "Preparation and recovery" }],
+    [34, { key: "racquetball", label: "Racquetball" }],
+    [35, { key: "rowing", label: "Rowing" }],
+    [36, { key: "rugby", label: "Rugby" }],
+    [37, { key: "running", label: "Running" }],
+    [38, { key: "sailing", label: "Sailing" }],
+    [39, { key: "skating_sports", label: "Skating sports" }],
+    [40, { key: "snow_sports", label: "Snow sports" }],
+    [41, { key: "soccer", label: "Soccer" }],
+    [42, { key: "softball", label: "Softball" }],
+    [43, { key: "squash", label: "Squash" }],
+    [44, { key: "stair_climbing", label: "Stair climbing" }],
+    [45, { key: "surfing_sports", label: "Surfing sports" }],
+    [46, { key: "swimming", label: "Swimming" }],
+    [47, { key: "table_tennis", label: "Table tennis" }],
+    [48, { key: "tennis", label: "Tennis" }],
+    [49, { key: "track_and_field", label: "Track and field" }],
+    [50, { key: "traditional_strength_training", label: "Traditional strength training" }],
+    [51, { key: "volleyball", label: "Volleyball" }],
+    [52, { key: "walking", label: "Walking" }],
+    [53, { key: "water_fitness", label: "Water fitness" }],
+    [54, { key: "water_polo", label: "Water polo" }],
+    [55, { key: "water_sports", label: "Water sports" }],
+    [56, { key: "wrestling", label: "Wrestling" }],
+    [57, { key: "yoga", label: "Yoga" }],
+    [58, { key: "barre", label: "Barre" }],
+    [59, { key: "core_training", label: "Core training" }],
+    [60, { key: "cross_country_skiing", label: "Cross-country skiing" }],
+    [61, { key: "downhill_skiing", label: "Downhill skiing" }],
+    [62, { key: "flexibility", label: "Flexibility" }],
+    [63, { key: "high_intensity_interval_training", label: "High-intensity interval training" }],
+    [64, { key: "jump_rope", label: "Jump rope" }],
+    [65, { key: "kickboxing", label: "Kickboxing" }],
+    [66, { key: "pilates", label: "Pilates" }],
+    [67, { key: "snowboarding", label: "Snowboarding" }],
+    [68, { key: "stairs", label: "Stairs" }],
+    [69, { key: "step_training", label: "Step training" }],
+    [70, { key: "wheelchair_walk_pace", label: "Wheelchair walk pace" }],
+    [71, { key: "wheelchair_run_pace", label: "Wheelchair run pace" }],
+    [72, { key: "tai_chi", label: "Tai chi" }],
+    [73, { key: "mixed_cardio", label: "Mixed cardio" }],
+    [74, { key: "hand_cycling", label: "Hand cycling" }],
+    [75, { key: "disc_sports", label: "Disc sports" }],
+    [76, { key: "fitness_gaming", label: "Fitness gaming" }],
+    [77, { key: "cardio_dance", label: "Cardio dance" }],
+    [78, { key: "social_dance", label: "Social dance" }],
+    [79, { key: "pickleball", label: "Pickleball" }],
+    [80, { key: "cooldown", label: "Cooldown" }],
+    [82, { key: "swim_bike_run", label: "Swim-bike-run" }],
+    [83, { key: "transition", label: "Transition" }],
+    [84, { key: "underwater_diving", label: "Underwater diving" }],
+    [3000, { key: "other", label: "Other" }]
+]);
+const CARDIO_KEYS = new Set([
+    "walking",
+    "running",
+    "cycling",
+    "rowing",
+    "elliptical",
+    "hiking",
+    "mixed_cardio",
+    "mixed_metabolic_cardio_training",
+    "high_intensity_interval_training",
+    "jump_rope",
+    "stair_climbing",
+    "stairs",
+    "step_training",
+    "cross_country_skiing",
+    "downhill_skiing",
+    "snowboarding",
+    "hand_cycling",
+    "wheelchair_walk_pace",
+    "wheelchair_run_pace",
+    "track_and_field",
+    "cross_training",
+    "cardio_dance",
+    "fitness_gaming",
+    "swim_bike_run",
+    "transition"
+]);
+const STRENGTH_KEYS = new Set([
+    "traditional_strength_training",
+    "functional_strength_training",
+    "core_training",
+    "cross_training",
+    "climbing"
+]);
+const MOBILITY_KEYS = new Set([
+    "barre",
+    "pilates",
+    "flexibility",
+    "preparation_and_recovery",
+    "cooldown"
+]);
+const MINDFUL_KEYS = new Set([
+    "mind_and_body",
+    "yoga",
+    "tai_chi"
+]);
+const WATER_KEYS = new Set([
+    "swimming",
+    "water_fitness",
+    "water_polo",
+    "water_sports",
+    "paddle_sports",
+    "surfing_sports",
+    "sailing",
+    "underwater_diving"
+]);
+const TEAM_SPORT_KEYS = new Set([
+    "american_football",
+    "australian_football",
+    "baseball",
+    "basketball",
+    "cricket",
+    "handball",
+    "hockey",
+    "lacrosse",
+    "rugby",
+    "soccer",
+    "softball",
+    "volleyball",
+    "water_polo"
+]);
+const RACKET_KEYS = new Set([
+    "badminton",
+    "pickleball",
+    "racquetball",
+    "squash",
+    "table_tennis",
+    "tennis"
+]);
+const COMBAT_KEYS = new Set([
+    "boxing",
+    "kickboxing",
+    "martial_arts",
+    "wrestling",
+    "fencing"
+]);
+const WINTER_KEYS = new Set([
+    "cross_country_skiing",
+    "downhill_skiing",
+    "snow_sports",
+    "snowboarding",
+    "curling"
+]);
+function cleanString(value) {
+    return typeof value === "string" && value.trim().length > 0
+        ? value.trim()
+        : null;
+}
+function humanizeKey(value) {
+    return value
+        .trim()
+        .replace(/^activity_/i, "")
+        .replaceAll("_", " ")
+        .replace(/\s+/g, " ")
+        .replace(/\b\w/g, (letter) => letter.toUpperCase());
+}
+function normalizeCanonicalKey(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replaceAll("-", "_")
+        .replace(/\s+/g, "_");
+}
+function resolveActivityFamily(key) {
+    const normalized = normalizeCanonicalKey(key);
+    if (CARDIO_KEYS.has(normalized)) {
+        return { familyKey: "cardio", familyLabel: "Cardio" };
+    }
+    if (STRENGTH_KEYS.has(normalized)) {
+        return { familyKey: "strength", familyLabel: "Strength" };
+    }
+    if (MOBILITY_KEYS.has(normalized)) {
+        return { familyKey: "mobility", familyLabel: "Mobility" };
+    }
+    if (MINDFUL_KEYS.has(normalized)) {
+        return { familyKey: "mindful", familyLabel: "Mindful" };
+    }
+    if (WATER_KEYS.has(normalized)) {
+        return { familyKey: "water", familyLabel: "Water" };
+    }
+    if (TEAM_SPORT_KEYS.has(normalized)) {
+        return { familyKey: "team_sport", familyLabel: "Team sport" };
+    }
+    if (RACKET_KEYS.has(normalized)) {
+        return { familyKey: "racket", familyLabel: "Racket" };
+    }
+    if (COMBAT_KEYS.has(normalized)) {
+        return { familyKey: "combat", familyLabel: "Combat" };
+    }
+    if (WINTER_KEYS.has(normalized)) {
+        return { familyKey: "winter", familyLabel: "Winter" };
+    }
+    if (normalized.includes("dance") ||
+        normalized === "play" ||
+        normalized === "disc_sports" ||
+        normalized === "golf" ||
+        normalized === "gymnastics" ||
+        normalized === "bowling") {
+        return { familyKey: "recreation", familyLabel: "Recreation" };
+    }
+    return { familyKey: "other", familyLabel: "Other" };
+}
+function inferSourceSystem(source, sourceType, provenance) {
+    const fromProvenance = cleanString(provenance?.sourceSystem);
+    if (fromProvenance) {
+        return fromProvenance;
+    }
+    if (source === "apple_health" || sourceType.includes("healthkit")) {
+        return "apple_health";
+    }
+    if (source === "forge_habit" || source === "manual" || sourceType === "manual") {
+        return "forge";
+    }
+    return cleanString(sourceType) ?? cleanString(source) ?? "unknown";
+}
+function buildFallbackActivity(sourceSystem, workoutType, providerActivityType = "generic_workout_type", providerRawValue = null, isFallback = false) {
+    const canonicalKey = normalizeCanonicalKey(workoutType.length > 0 ? workoutType : "workout");
+    const canonicalLabel = humanizeKey(canonicalKey);
+    const family = resolveActivityFamily(canonicalKey);
+    return {
+        sourceSystem,
+        providerActivityType,
+        providerRawValue,
+        canonicalKey,
+        canonicalLabel,
+        familyKey: family.familyKey,
+        familyLabel: family.familyLabel,
+        isFallback
+    };
+}
+function normalizeAppleHealthActivity(workoutType, existingActivity) {
+    if (existingActivity?.sourceSystem === "apple_health") {
+        const family = resolveActivityFamily(existingActivity.canonicalKey);
+        return {
+            ...existingActivity,
+            familyKey: family.familyKey,
+            familyLabel: family.familyLabel
+        };
+    }
+    const rawMatch = /^activity_(\d+)$/i.exec(workoutType.trim());
+    const rawValue = rawMatch ? Number(rawMatch[1]) : null;
+    if (rawValue != null) {
+        const catalog = APPLE_HEALTH_ACTIVITY_TYPES.get(rawValue);
+        if (catalog) {
+            const family = resolveActivityFamily(catalog.key);
+            return {
+                sourceSystem: "apple_health",
+                providerActivityType: "hk_workout_activity_type",
+                providerRawValue: rawValue,
+                canonicalKey: catalog.key,
+                canonicalLabel: catalog.label,
+                familyKey: family.familyKey,
+                familyLabel: family.familyLabel,
+                isFallback: false
+            };
+        }
+    }
+    const normalizedKey = normalizeCanonicalKey(workoutType);
+    for (const [providerRawValue, catalog] of APPLE_HEALTH_ACTIVITY_TYPES.entries()) {
+        if (catalog.key === normalizedKey) {
+            const family = resolveActivityFamily(catalog.key);
+            return {
+                sourceSystem: "apple_health",
+                providerActivityType: "hk_workout_activity_type",
+                providerRawValue,
+                canonicalKey: catalog.key,
+                canonicalLabel: catalog.label,
+                familyKey: family.familyKey,
+                familyLabel: family.familyLabel,
+                isFallback: false
+            };
+        }
+    }
+    return buildFallbackActivity("apple_health", normalizedKey, "hk_workout_activity_type", rawValue, true);
+}
+const workoutSourceAdapters = new Map([
+    [
+        "apple_health",
+        {
+            sourceSystem: "apple_health",
+            normalizeActivity: ({ workoutType, existingActivity }) => normalizeAppleHealthActivity(workoutType, existingActivity)
+        }
+    ],
+    [
+        "forge",
+        {
+            sourceSystem: "forge",
+            normalizeActivity: ({ workoutType, existingActivity }) => {
+                if (existingActivity) {
+                    return {
+                        ...existingActivity,
+                        ...resolveActivityFamily(existingActivity.canonicalKey)
+                    };
+                }
+                return buildFallbackActivity("forge", workoutType, "forge_workout_type");
+            }
+        }
+    ]
+]);
+function getWorkoutSourceAdapter(sourceSystem) {
+    return (workoutSourceAdapters.get(sourceSystem) ??
+        {
+            sourceSystem,
+            normalizeActivity: ({ workoutType, existingActivity }) => {
+                if (existingActivity) {
+                    return {
+                        ...existingActivity,
+                        ...resolveActivityFamily(existingActivity.canonicalKey)
+                    };
+                }
+                return buildFallbackActivity(sourceSystem, workoutType, "generic_workout_type");
+            }
+        });
+}
+function normalizeWorkoutDetails(sourceSystem, value) {
+    const parsed = workoutDetailsSchema.safeParse(value);
+    if (!parsed.success) {
+        return {
+            sourceSystem,
+            metrics: [],
+            events: [],
+            components: [],
+            metadata: {}
+        };
+    }
+    return {
+        ...parsed.data,
+        sourceSystem,
+        metrics: [...parsed.data.metrics].sort((left, right) => {
+            if (left.category === right.category) {
+                return left.label.localeCompare(right.label);
+            }
+            return left.category.localeCompare(right.category);
+        }),
+        events: [...parsed.data.events].sort((left, right) => left.startedAt.localeCompare(right.startedAt)),
+        components: [...parsed.data.components].sort((left, right) => left.startedAt.localeCompare(right.startedAt))
+    };
+}
+export function buildWorkoutSessionPresentation(input) {
+    const provenance = input.provenance ?? {};
+    const derived = input.derived ?? {};
+    const sourceSystem = inferSourceSystem(input.source, input.sourceType, provenance);
+    const storedActivity = workoutActivityDescriptorSchema.safeParse(derived.activity).success
+        ? workoutActivityDescriptorSchema.parse(derived.activity)
+        : workoutActivityDescriptorSchema.safeParse(provenance.activity).success
+            ? workoutActivityDescriptorSchema.parse(provenance.activity)
+            : null;
+    const adapter = getWorkoutSourceAdapter(sourceSystem);
+    const activity = adapter.normalizeActivity({
+        workoutType: input.workoutType,
+        existingActivity: storedActivity
+    });
+    const details = normalizeWorkoutDetails(sourceSystem, derived.details ?? provenance.details);
+    return {
+        sourceSystem,
+        sourceBundleIdentifier: cleanString(provenance.sourceBundleIdentifier),
+        sourceProductType: cleanString(provenance.sourceProductType),
+        workoutType: activity.canonicalKey,
+        workoutTypeLabel: activity.canonicalLabel,
+        activityFamily: activity.familyKey,
+        activityFamilyLabel: activity.familyLabel,
+        activity,
+        details
+    };
+}
+export function buildWorkoutSessionPersistenceSeed(input) {
+    const sourceSystem = cleanString(input.sourceSystem) ??
+        inferSourceSystem(input.source, input.sourceType, undefined);
+    const parsedActivity = workoutActivityDescriptorSchema.safeParse(input.activity);
+    const adapter = getWorkoutSourceAdapter(sourceSystem);
+    const activity = adapter.normalizeActivity({
+        workoutType: input.workoutType,
+        existingActivity: parsedActivity.success ? parsedActivity.data : null
+    });
+    const details = normalizeWorkoutDetails(sourceSystem, input.details);
+    return {
+        sourceSystem,
+        sourceBundleIdentifier: cleanString(input.sourceBundleIdentifier),
+        sourceProductType: cleanString(input.sourceProductType),
+        activity,
+        details
+    };
+}