forge-openclaw-plugin 0.2.47 → 0.2.49

package/dist/server/server/src/health.js

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { z } from "zod";
 import { getDatabase, runInTransaction } from "./db.js";
 import { HttpError } from "./errors.js";
+import { buildWorkoutSessionPersistenceSeed, buildWorkoutSessionPresentation, workoutActivityDescriptorSchema, workoutDetailsSchema } from "./health-workout-adapters.js";
 import { getMovementMobileBootstrap, ingestMovementSync, movementSyncPayloadSchema } from "./movement.js";
 import { ingestScreenTimeSync, screenTimeSyncPayloadSchema } from "./screen-time.js";
 import { recordActivityEvent } from "./repositories/activity-events.js";
@@ -235,6 +236,11 @@ export const mobileHealthSyncSchema = z.object({
         averageHeartRate: z.number().nonnegative().nullable().optional(),
         maxHeartRate: z.number().nonnegative().nullable().optional(),
         sourceDevice: z.string().trim().default("Apple Health"),
+        sourceSystem: z.string().trim().min(1).default("apple_health"),
+        sourceBundleIdentifier: z.string().trim().optional(),
+        sourceProductType: z.string().trim().optional(),
+        activity: workoutActivityDescriptorSchema.optional(),
+        details: workoutDetailsSchema.optional(),
         links: z.array(healthLinkSchema).default([]),
         annotations: workoutAnnotationSchema.partial().default({})
     }))
@@ -766,6 +772,15 @@ function mapSleepRawLog(row) {
     };
 }
 function mapWorkoutSession(row) {
+    const provenance = safeJsonParse(row.provenance_json, {});
+    const derived = safeJsonParse(row.derived_json, {});
+    const presentation = buildWorkoutSessionPresentation({
+        source: row.source,
+        sourceType: row.source_type,
+        workoutType: row.workout_type,
+        provenance,
+        derived
+    });
     return {
         id: row.id,
         externalUid: row.external_uid,
@@ -773,7 +788,15 @@ function mapWorkoutSession(row) {
         userId: row.user_id,
         source: row.source,
         sourceType: row.source_type,
-        workoutType: row.workout_type,
+        sourceSystem: presentation.sourceSystem,
+        sourceBundleIdentifier: presentation.sourceBundleIdentifier,
+        sourceProductType: presentation.sourceProductType,
+        workoutType: presentation.workoutType,
+        workoutTypeLabel: presentation.workoutTypeLabel,
+        activityFamily: presentation.activityFamily,
+        activityFamilyLabel: presentation.activityFamilyLabel,
+        activity: presentation.activity,
+        details: presentation.details,
         sourceDevice: row.source_device,
         startedAt: row.started_at,
         endedAt: row.ended_at,
@@ -794,8 +817,8 @@ function mapWorkoutSession(row) {
         links: safeJsonParse(row.links_json, []),
         tags: safeJsonParse(row.tags_json, []),
         annotations: safeJsonParse(row.annotations_json, {}),
-        provenance: safeJsonParse(row.provenance_json, {}),
-        derived: safeJsonParse(row.derived_json, {}),
+        provenance,
+        derived,
         generatedFromHabitId: row.generated_from_habit_id,
         generatedFromCheckInId: row.generated_from_check_in_id,
         reconciliationStatus: row.reconciliation_status,
@@ -1904,10 +1927,20 @@ function insertOrUpdateWorkoutSession(pairing, input) {
         .get(pairing.user_id, input.externalUid);
     const annotations = workoutAnnotationSchema.parse(input.annotations ?? {});
     const now = nowIso();
+    const basePersistenceSeed = buildWorkoutSessionPersistenceSeed({
+        source: "apple_health",
+        sourceType: "healthkit",
+        workoutType: input.workoutType,
+        sourceSystem: input.sourceSystem,
+        sourceBundleIdentifier: input.sourceBundleIdentifier,
+        sourceProductType: input.sourceProductType,
+        activity: input.activity,
+        details: input.details
+    });
     const matchedGenerated = existing ??
         findMatchingGeneratedWorkout({
             userId: pairing.user_id,
-            workoutType: input.workoutType,
+            workoutType: basePersistenceSeed.activity.canonicalKey,
             startedAt: input.startedAt,
             endedAt: input.endedAt
         });
@@ -1915,6 +1948,26 @@ function insertOrUpdateWorkoutSession(pairing, input) {
         const existingLinks = safeJsonParse(matchedGenerated.links_json, []);
         const existingTags = safeJsonParse(matchedGenerated.tags_json, []);
         const existingAnnotations = safeJsonParse(matchedGenerated.annotations_json, {});
+        const existingProvenance = safeJsonParse(matchedGenerated.provenance_json, {});
+        const existingDerived = safeJsonParse(matchedGenerated.derived_json, {});
+        const persistenceSeed = buildWorkoutSessionPersistenceSeed({
+            source: "apple_health",
+            sourceType: matchedGenerated.generated_from_habit_id
+                ? "reconciled"
+                : "healthkit",
+            workoutType: input.workoutType,
+            sourceSystem: input.sourceSystem,
+            sourceBundleIdentifier: input.sourceBundleIdentifier ??
+                (typeof existingProvenance.sourceBundleIdentifier === "string"
+                    ? existingProvenance.sourceBundleIdentifier
+                    : null),
+            sourceProductType: input.sourceProductType ??
+                (typeof existingProvenance.sourceProductType === "string"
+                    ? existingProvenance.sourceProductType
+                    : null),
+            activity: input.activity ?? existingDerived.activity ?? existingProvenance.activity,
+            details: input.details ?? existingDerived.details ?? existingProvenance.details
+        });
         const mergedLinks = mergeHealthLinks(existingLinks, input.links, annotations.links);
         const mergedTags = mergeStringLists(existingTags, annotations.tags);
         const nextSubjectiveEffort = matchedGenerated.subjective_effort ?? annotations.subjectiveEffort ?? null;
@@ -1945,12 +1998,21 @@ function insertOrUpdateWorkoutSession(pairing, input) {
              reconciliation_status = ?, updated_at = ?
          WHERE id = ?`)
             .run(input.externalUid, pairing.id, matchedGenerated.generated_from_habit_id ? "reconciled" : "healthkit", input.sourceDevice, input.startedAt, input.endedAt, Math.max(0, Math.round((Date.parse(input.endedAt) - Date.parse(input.startedAt)) / 1000)), input.activeEnergyKcal ?? null, input.totalEnergyKcal ?? null, input.distanceMeters ?? null, input.stepCount ?? null, input.exerciseMinutes ?? null, input.averageHeartRate ?? null, input.maxHeartRate ?? null, nextSubjectiveEffort, nextMoodBefore, nextMoodAfter, nextMeaningText, nextPlannedContext, nextSocialContext, JSON.stringify(mergedLinks), JSON.stringify(mergedTags), JSON.stringify(nextAnnotations), JSON.stringify({
+            ...existingProvenance,
             importedVia: "ios_companion",
             pairingSessionId: pairing.id,
+            sourceSystem: persistenceSeed.sourceSystem,
+            sourceBundleIdentifier: persistenceSeed.sourceBundleIdentifier,
+            sourceProductType: persistenceSeed.sourceProductType,
+            activity: persistenceSeed.activity,
+            details: persistenceSeed.details,
             mergedWithGenerated: matchedGenerated.generated_from_habit_id !== null,
             priorSource: matchedGenerated.source,
             updatedAt: now
         }), JSON.stringify({
+            ...existingDerived,
+            activity: persistenceSeed.activity,
+            details: persistenceSeed.details,
             paceMetersPerMinute: input.distanceMeters && input.exerciseMinutes
                 ? Number((input.distanceMeters / input.exerciseMinutes).toFixed(2))
                 : null
@@ -1972,11 +2034,18 @@ function insertOrUpdateWorkoutSession(pairing, input) {
          provenance_json, derived_json, reconciliation_status, created_at, updated_at
        )
        VALUES (?, ?, ?, ?, 'apple_health', 'healthkit', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'standalone', ?, ?)`)
-        .run(id, input.externalUid, pairing.id, pairing.user_id, input.workoutType, input.sourceDevice, input.startedAt, input.endedAt, Math.max(0, Math.round((Date.parse(input.endedAt) - Date.parse(input.startedAt)) / 1000)), input.activeEnergyKcal ?? null, input.totalEnergyKcal ?? null, input.distanceMeters ?? null, input.stepCount ?? null, input.exerciseMinutes ?? null, input.averageHeartRate ?? null, input.maxHeartRate ?? null, annotations.subjectiveEffort, annotations.moodBefore, annotations.moodAfter, annotations.meaningText, annotations.plannedContext, annotations.socialContext, JSON.stringify(input.links), JSON.stringify(annotations.tags), JSON.stringify(annotations), JSON.stringify({
+        .run(id, input.externalUid, pairing.id, pairing.user_id, basePersistenceSeed.activity.canonicalKey, input.sourceDevice, input.startedAt, input.endedAt, Math.max(0, Math.round((Date.parse(input.endedAt) - Date.parse(input.startedAt)) / 1000)), input.activeEnergyKcal ?? null, input.totalEnergyKcal ?? null, input.distanceMeters ?? null, input.stepCount ?? null, input.exerciseMinutes ?? null, input.averageHeartRate ?? null, input.maxHeartRate ?? null, annotations.subjectiveEffort, annotations.moodBefore, annotations.moodAfter, annotations.meaningText, annotations.plannedContext, annotations.socialContext, JSON.stringify(input.links), JSON.stringify(annotations.tags), JSON.stringify(annotations), JSON.stringify({
         importedVia: "ios_companion",
         pairingSessionId: pairing.id,
+        sourceSystem: basePersistenceSeed.sourceSystem,
+        sourceBundleIdentifier: basePersistenceSeed.sourceBundleIdentifier,
+        sourceProductType: basePersistenceSeed.sourceProductType,
+        activity: basePersistenceSeed.activity,
+        details: basePersistenceSeed.details,
         createdAt: now
     }), JSON.stringify({
+        activity: basePersistenceSeed.activity,
+        details: basePersistenceSeed.details,
         paceMetersPerMinute: input.distanceMeters && input.exerciseMinutes
             ? Number((input.distanceMeters / input.exerciseMinutes).toFixed(2))
             : null
@@ -2814,6 +2883,8 @@ export function getFitnessViewData(userIds) {
             habitGeneratedSessionCount: recent.filter((session) => session.sourceType === "habit_generated").length,
             reconciledSessionCount: recent.filter((session) => session.reconciliationStatus === "merged").length,
             topWorkoutType: orderedWorkoutTypes[0]?.[0] ?? null,
+            topWorkoutTypeLabel: recent.find((session) => session.workoutType === orderedWorkoutTypes[0]?.[0])
+                ?.workoutTypeLabel ?? null,
             streakDays: Array.from(new Set(weekly.map((session) => dayKey(session.startedAt)))).length
         },
         weeklyTrend: weekly
@@ -2821,12 +2892,21 @@ export function getFitnessViewData(userIds) {
             id: session.id,
             dateKey: dayKey(session.startedAt),
             workoutType: session.workoutType,
+            workoutTypeLabel: session.workoutTypeLabel,
+            activityFamily: session.activityFamily,
+            activityFamilyLabel: session.activityFamilyLabel,
             durationMinutes: Math.round(session.durationSeconds / 60),
             energyKcal: Math.round(session.totalEnergyKcal ?? session.activeEnergyKcal ?? 0)
         }))
             .reverse(),
         typeBreakdown: orderedWorkoutTypes.map(([workoutType, metrics]) => ({
             workoutType,
+            workoutTypeLabel: recent.find((session) => session.workoutType === workoutType)?.workoutTypeLabel ??
+                workoutType,
+            activityFamily: recent.find((session) => session.workoutType === workoutType)?.activityFamily ??
+                "other",
+            activityFamilyLabel: recent.find((session) => session.workoutType === workoutType)
+                ?.activityFamilyLabel ?? "Other",
             sessionCount: metrics.sessionCount,
             totalMinutes: metrics.totalMinutes,
             energyKcal: metrics.energyKcal
@@ -3180,6 +3260,11 @@ export function createWorkoutSession(input, activity) {
         tags: parsed.tags,
         links: parsed.links
     };
+    const persistenceSeed = buildWorkoutSessionPersistenceSeed({
+        source: parsed.source,
+        sourceType: parsed.sourceType,
+        workoutType: parsed.workoutType
+    });
     getDatabase()
         .prepare(`INSERT INTO health_workout_sessions (
          id, external_uid, pairing_session_id, user_id, source, source_type, workout_type, source_device,
@@ -3189,16 +3274,21 @@ export function createWorkoutSession(input, activity) {
          provenance_json, derived_json, reconciliation_status, created_at, updated_at
        )
        VALUES (?, ?, NULL, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'standalone', ?, ?)`)
-        .run(id, externalUid, userId, parsed.source, parsed.sourceType, parsed.workoutType, parsed.sourceDevice, parsed.startedAt, parsed.endedAt, durationSeconds, parsed.activeEnergyKcal ?? null, parsed.totalEnergyKcal ?? null, parsed.distanceMeters ?? null, parsed.stepCount ?? null, parsed.exerciseMinutes ?? null, parsed.averageHeartRate ?? null, parsed.maxHeartRate ?? null, parsed.subjectiveEffort ?? null, parsed.moodBefore, parsed.moodAfter, parsed.meaningText, parsed.plannedContext, parsed.socialContext, JSON.stringify(parsed.links), JSON.stringify(parsed.tags), JSON.stringify(annotations), JSON.stringify({
+        .run(id, externalUid, userId, parsed.source, parsed.sourceType, persistenceSeed.activity.canonicalKey, parsed.sourceDevice, parsed.startedAt, parsed.endedAt, durationSeconds, parsed.activeEnergyKcal ?? null, parsed.totalEnergyKcal ?? null, parsed.distanceMeters ?? null, parsed.stepCount ?? null, parsed.exerciseMinutes ?? null, parsed.averageHeartRate ?? null, parsed.maxHeartRate ?? null, parsed.subjectiveEffort ?? null, parsed.moodBefore, parsed.moodAfter, parsed.meaningText, parsed.plannedContext, parsed.socialContext, JSON.stringify(parsed.links), JSON.stringify(parsed.tags), JSON.stringify(annotations), JSON.stringify({
         manualEntry: true,
         entryMode: "local",
         source: parsed.source,
         sourceType: parsed.sourceType,
+        sourceSystem: persistenceSeed.sourceSystem,
+        activity: persistenceSeed.activity,
+        details: persistenceSeed.details,
         sourceDevice: parsed.sourceDevice,
         actor: activity?.actor ?? null,
         createdAt: now,
         ...parsed.provenance
     }), JSON.stringify({
+        activity: persistenceSeed.activity,
+        details: persistenceSeed.details,
         paceMetersPerMinute: parsed.distanceMeters && parsed.exerciseMinutes
             ? Number((parsed.distanceMeters / parsed.exerciseMinutes).toFixed(2))
             : null
@@ -3268,8 +3358,25 @@ export function updateWorkoutSession(workoutId, patch, activity) {
         links
     };
     const currentProvenance = safeJsonParse(current.provenance_json, {});
+    const currentDerived = safeJsonParse(current.derived_json, {});
     const nextExerciseMinutes = parsed.exerciseMinutes ?? current.exercise_minutes;
     const nextDistanceMeters = parsed.distanceMeters ?? current.distance_meters;
+    const persistenceSeed = buildWorkoutSessionPersistenceSeed({
+        source: parsed.source ?? current.source,
+        sourceType: parsed.sourceType ?? current.source_type,
+        workoutType: parsed.workoutType ?? current.workout_type,
+        sourceSystem: typeof currentProvenance.sourceSystem === "string"
+            ? currentProvenance.sourceSystem
+            : null,
+        sourceBundleIdentifier: typeof currentProvenance.sourceBundleIdentifier === "string"
+            ? currentProvenance.sourceBundleIdentifier
+            : null,
+        sourceProductType: typeof currentProvenance.sourceProductType === "string"
+            ? currentProvenance.sourceProductType
+            : null,
+        activity: currentDerived.activity ?? currentProvenance.activity,
+        details: currentDerived.details ?? currentProvenance.details
+    });
     getDatabase()
         .prepare(`UPDATE health_workout_sessions
        SET external_uid = ?, source = ?, source_type = ?, workout_type = ?, source_device = ?,
@@ -3279,12 +3386,20 @@ export function updateWorkoutSession(workoutId, patch, activity) {
            social_context = ?, links_json = ?, tags_json = ?, annotations_json = ?, provenance_json = ?,
            derived_json = ?, updated_at = ?
        WHERE id = ?`)
-        .run(parsed.externalUid ?? current.external_uid, parsed.source ?? current.source, parsed.sourceType ?? current.source_type, parsed.workoutType ?? current.workout_type, parsed.sourceDevice ?? current.source_device, startedAt, endedAt, durationSeconds, parsed.activeEnergyKcal ?? current.active_energy_kcal, parsed.totalEnergyKcal ?? current.total_energy_kcal, nextDistanceMeters, parsed.stepCount ?? current.step_count, nextExerciseMinutes, parsed.averageHeartRate ?? current.average_heart_rate, parsed.maxHeartRate ?? current.max_heart_rate, annotations.subjectiveEffort, annotations.moodBefore, annotations.moodAfter, annotations.meaningText, annotations.plannedContext, annotations.socialContext, JSON.stringify(links), JSON.stringify(tags), JSON.stringify(annotations), JSON.stringify({
+        .run(parsed.externalUid ?? current.external_uid, parsed.source ?? current.source, parsed.sourceType ?? current.source_type, persistenceSeed.activity.canonicalKey, parsed.sourceDevice ?? current.source_device, startedAt, endedAt, durationSeconds, parsed.activeEnergyKcal ?? current.active_energy_kcal, parsed.totalEnergyKcal ?? current.total_energy_kcal, nextDistanceMeters, parsed.stepCount ?? current.step_count, nextExerciseMinutes, parsed.averageHeartRate ?? current.average_heart_rate, parsed.maxHeartRate ?? current.max_heart_rate, annotations.subjectiveEffort, annotations.moodBefore, annotations.moodAfter, annotations.meaningText, annotations.plannedContext, annotations.socialContext, JSON.stringify(links), JSON.stringify(tags), JSON.stringify(annotations), JSON.stringify({
         ...currentProvenance,
         ...(parsed.provenance ?? {}),
+        sourceSystem: persistenceSeed.sourceSystem,
+        sourceBundleIdentifier: persistenceSeed.sourceBundleIdentifier,
+        sourceProductType: persistenceSeed.sourceProductType,
+        activity: persistenceSeed.activity,
+        details: persistenceSeed.details,
         updatedAt: now,
         updatedByActor: activity?.actor ?? null
     }), JSON.stringify({
+        ...currentDerived,
+        activity: persistenceSeed.activity,
+        details: persistenceSeed.details,
         paceMetersPerMinute: nextDistanceMeters && nextExerciseMinutes
             ? Number((nextDistanceMeters / nextExerciseMinutes).toFixed(2))
             : null
@@ -3441,6 +3556,11 @@ export function createGeneratedWorkoutFromHabit(args) {
     }
     const now = nowIso();
     const id = `workout_${randomUUID().replaceAll("-", "").slice(0, 10)}`;
+    const persistenceSeed = buildWorkoutSessionPersistenceSeed({
+        source: "forge_habit",
+        sourceType: "habit_generated",
+        workoutType: template.workoutType
+    });
     getDatabase()
         .prepare(`INSERT INTO health_workout_sessions (
          id, external_uid, pairing_session_id, user_id, source, source_type, workout_type, source_device,
@@ -3448,7 +3568,7 @@ export function createGeneratedWorkoutFromHabit(args) {
          derived_json, generated_from_habit_id, generated_from_check_in_id, reconciliation_status, created_at, updated_at
        )
        VALUES (?, ?, NULL, ?, 'forge_habit', 'habit_generated', ?, 'Habit automation', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'awaiting_import_match', ?, ?)`)
-        .run(id, `habit_${args.checkInId}`, args.userId, template.workoutType, startedAt, endedAt, template.durationMinutes * 60, JSON.stringify([
+        .run(id, `habit_${args.checkInId}`, args.userId, persistenceSeed.activity.canonicalKey, startedAt, endedAt, template.durationMinutes * 60, JSON.stringify([
         ...(template.links ?? []),
         ...(args.linkedEntities ?? [])
     ]), JSON.stringify(template.tags), JSON.stringify({
@@ -3457,8 +3577,13 @@ export function createGeneratedWorkoutFromHabit(args) {
     }), JSON.stringify({
         generatedFrom: "habit_completion",
         habitId: args.habitId,
-        checkInId: args.checkInId
+        checkInId: args.checkInId,
+        sourceSystem: persistenceSeed.sourceSystem,
+        activity: persistenceSeed.activity,
+        details: persistenceSeed.details
     }), JSON.stringify({
+        activity: persistenceSeed.activity,
+        details: persistenceSeed.details,
         xpReward: template.xpReward
     }), args.habitId, args.checkInId, now, now);
     recordActivityEvent({

package/dist/server/server/src/openapi.js

@@ -2137,6 +2137,11 @@ export function buildOpenApiDocument() {
             "id",
             "label",
             "agentType",
+            "identityKey",
+            "provider",
+            "machineKey",
+            "personaKey",
+            "linkedUsers",
             "trustLevel",
             "autonomyMode",
             "approvalMode",
@@ -2150,6 +2155,20 @@ export function buildOpenApiDocument() {
             id: { type: "string" },
             label: { type: "string" },
             agentType: { type: "string" },
+            identityKey: nullable({ type: "string" }),
+            provider: nullable({ type: "string", enum: ["openclaw", "hermes", "codex"] }),
+            machineKey: nullable({ type: "string" }),
+            personaKey: nullable({ type: "string" }),
+            linkedUsers: arrayOf({
+                type: "object",
+                additionalProperties: false,
+                required: ["userId", "role", "user"],
+                properties: {
+                    userId: { type: "string" },
+                    role: { type: "string" },
+                    user: nullable({ $ref: "#/components/schemas/UserSummary" })
+                }
+            }),
             trustLevel: {
                 type: "string",
                 enum: ["standard", "trusted", "autonomous"]
@@ -4055,6 +4074,12 @@ export function buildOpenApiDocument() {
             "userId",
             "source",
             "sourceType",
+            "sourceSystem",
+            "workoutTypeLabel",
+            "activityFamily",
+            "activityFamilyLabel",
+            "activity",
+            "details",
             "workoutType",
             "sourceDevice",
             "startedAt",
@@ -4091,7 +4116,15 @@ export function buildOpenApiDocument() {
             userId: { type: "string" },
             source: { type: "string" },
             sourceType: { type: "string" },
+            sourceSystem: { type: "string" },
+            sourceBundleIdentifier: nullable({ type: "string" }),
+            sourceProductType: nullable({ type: "string" }),
             workoutType: { type: "string" },
+            workoutTypeLabel: { type: "string" },
+            activityFamily: { type: "string" },
+            activityFamilyLabel: { type: "string" },
+            activity: { type: "object", additionalProperties: true },
+            details: { type: "object", additionalProperties: true },
             sourceDevice: { type: "string" },
             startedAt: { type: "string", format: "date-time" },
             endedAt: { type: "string", format: "date-time" },

package/dist/server/server/src/repositories/agent-runtime-sessions.js

@@ -1,7 +1,8 @@
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { getDatabase, runInTransaction } from "../db.js";
 import { recordActivityEvent } from "./activity-events.js";
 import { listAgentActions } from "./collaboration.js";
+import { ensureBotUser, getUserById } from "./users.js";
 import { agentActionSchema, agentRuntimeEventLevelSchema, agentRuntimeReconnectPlanSchema, agentRuntimeSessionEventSchema, agentRuntimeSessionSchema, createAgentRuntimeSessionEventSchema, createAgentRuntimeSessionSchema, disconnectAgentRuntimeSessionSchema, heartbeatAgentRuntimeSessionSchema, reconnectAgentRuntimeSessionSchema } from "../types.js";
 function parseMetadata(raw) {
     try {
@@ -211,7 +212,95 @@ function ensureCurrentSessionInstance(row, externalSessionId) {
     }
     return true;
 }
-function disconnectSupersededSingletonSessions(parsed, sessionId, now) {
+function normalizeIdentityPart(value) {
+    return (value
+        ?.trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9._:]+/g, "_")
+        .replace(/^_+|_+$/g, "") ?? "");
+}
+function shortHash(value) {
+    return createHash("sha1").update(value).digest("hex").slice(0, 12);
+}
+function canonicalRuntimeAgentLabel(provider) {
+    if (provider === "openclaw") {
+        return "Forge OpenClaw";
+    }
+    if (provider === "hermes") {
+        return "Forge Hermes";
+    }
+    return "Forge Codex";
+}
+function canonicalRuntimeDescription(provider) {
+    return `${canonicalRuntimeAgentLabel(provider)} runtime agent with stable Forge identity and linked Kanban user.`;
+}
+function canonicalAgentUserSpec(provider) {
+    if (provider === "openclaw") {
+        return {
+            id: "user_agent_openclaw",
+            handle: "openclaw",
+            displayName: "OpenClaw",
+            description: "OpenClaw runtime actor linked to Forge agent identity and Kanban ownership.",
+            accentColor: "#38bdf8"
+        };
+    }
+    if (provider === "hermes") {
+        return {
+            id: "user_agent_hermes",
+            handle: "hermes",
+            displayName: "Hermes",
+            description: "Hermes runtime actor linked to Forge agent identity and Kanban ownership.",
+            accentColor: "#a78bfa"
+        };
+    }
+    return {
+        id: "user_agent_codex",
+        handle: "codex",
+        displayName: "Codex",
+        description: "Codex runtime actor linked to Forge agent identity and Kanban ownership.",
+        accentColor: "#22c55e"
+    };
+}
+function deriveMachineKey(input) {
+    const explicit = normalizeIdentityPart(input.machineKey);
+    if (explicit) {
+        return explicit;
+    }
+    const source = [
+        normalizeText(input.dataRoot) ?? "",
+        normalizeText(input.baseUrl) ?? "local"
+    ].join("|");
+    return `machine_${shortHash(source)}`;
+}
+function derivePersonaKey(input) {
+    return (normalizeIdentityPart(input.personaKey) ||
+        normalizeIdentityPart(input.agentType) ||
+        "default");
+}
+function deriveAgentIdentityKey(input) {
+    const explicit = normalizeIdentityPart(input.agentIdentityKey);
+    if (explicit) {
+        return explicit;
+    }
+    return `runtime:${input.provider}:${deriveMachineKey(input)}:${derivePersonaKey(input)}`;
+}
+function linkAgentIdentityUsers(agentId, provider, linkedUserIds, now) {
+    const primaryUser = ensureBotUser(canonicalAgentUserSpec(provider));
+    const normalizedUserIds = Array.from(new Set([primaryUser.id, ...linkedUserIds.map((id) => id.trim()).filter(Boolean)]));
+    for (const userId of normalizedUserIds) {
+        if (!getUserById(userId)) {
+            continue;
+        }
+        getDatabase()
+            .prepare(`INSERT INTO agent_identity_users (agent_id, user_id, role, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?)
+         ON CONFLICT(agent_id, user_id) DO UPDATE SET
+           role = excluded.role,
+           updated_at = excluded.updated_at`)
+            .run(agentId, userId, userId === primaryUser.id ? "primary" : "linked", now, now);
+    }
+}
+function disconnectSupersededSingletonSessions(parsed, sessionId, agentId, now) {
     if (!parsed.metadata?.singleton) {
         return;
     }
@@ -224,11 +313,11 @@ function disconnectSupersededSingletonSessions(parsed, sessionId, now) {
          created_at, updated_at
        FROM agent_runtime_sessions
        WHERE provider = ?
-         AND agent_label = ?
+         AND agent_id = ?
          AND coalesce(base_url, '') = coalesce(?, '')
          AND coalesce(data_root, '') = coalesce(?, '')
          AND id <> ?`)
-        .all(parsed.provider, parsed.agentLabel, normalizeText(parsed.baseUrl), normalizeText(parsed.dataRoot), sessionId);
+        .all(parsed.provider, agentId, normalizeText(parsed.baseUrl), normalizeText(parsed.dataRoot), sessionId);
     for (const row of rows) {
         if (row.status === "disconnected" && row.ended_at) {
             continue;
@@ -251,29 +340,45 @@ function disconnectSupersededSingletonSessions(parsed, sessionId, now) {
     }
 }
 function upsertRuntimeAgentIdentity(input) {
+    const identityKey = deriveAgentIdentityKey(input);
+    const machineKey = deriveMachineKey(input);
+    const personaKey = derivePersonaKey(input);
+    const label = canonicalRuntimeAgentLabel(input.provider);
     const existing = getDatabase()
         .prepare(`SELECT id
        FROM agent_identities
-       WHERE lower(label) = lower(?)
+       WHERE identity_key = ?
+          OR (
+            (identity_key IS NULL OR machine_key IS NULL OR machine_key = 'legacy' OR identity_key LIKE 'runtime:%:legacy:%')
+            AND (
+              provider = ?
+              OR lower(agent_type) = lower(?)
+              OR lower(label) = lower(?)
+            )
+          )
        LIMIT 1`)
-        .get(input.agentLabel);
+        .get(identityKey, input.provider, input.provider, label);
     const now = new Date().toISOString();
-    const description = `${input.provider[0].toUpperCase()}${input.provider.slice(1)} runtime session participant registered through Forge.`;
+    const description = canonicalRuntimeDescription(input.provider);
     if (existing) {
         getDatabase()
             .prepare(`UPDATE agent_identities
-         SET agent_type = ?, updated_at = ?
+         SET label = ?, agent_type = ?, identity_key = ?, provider = ?,
+             machine_key = ?, persona_key = ?, description = ?, updated_at = ?
          WHERE id = ?`)
-            .run(input.agentType || input.provider, now, existing.id);
+            .run(label, input.agentType || input.provider, identityKey, input.provider, machineKey, personaKey, description, now, existing.id);
+        linkAgentIdentityUsers(existing.id, input.provider, input.linkedUserIds, now);
         return existing.id;
     }
     const agentId = `agt_${randomUUID().replaceAll("-", "").slice(0, 10)}`;
     getDatabase()
         .prepare(`INSERT INTO agent_identities (
-        id, label, agent_type, trust_level, autonomy_mode, approval_mode,
+        id, label, agent_type, identity_key, provider, machine_key, persona_key,
+        trust_level, autonomy_mode, approval_mode,
         description, created_at, updated_at
-      ) VALUES (?, ?, ?, 'trusted', 'approval_required', 'approval_by_default', ?, ?, ?)`)
-        .run(agentId, input.agentLabel, input.agentType || input.provider, description, now, now);
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, 'trusted', 'approval_required', 'approval_by_default', ?, ?, ?)`)
+        .run(agentId, label, input.agentType || input.provider, identityKey, input.provider, machineKey, personaKey, description, now, now);
+    linkAgentIdentityUsers(agentId, input.provider, input.linkedUserIds, now);
     return agentId;
 }
 function insertSessionEvent(sessionId, input, now = new Date().toISOString()) {
@@ -321,6 +426,7 @@ export function registerAgentRuntimeSession(input) {
     return runInTransaction(() => {
         const now = new Date().toISOString();
         const agentId = upsertRuntimeAgentIdentity(parsed);
+        const agentLabel = canonicalRuntimeAgentLabel(parsed.provider);
         const existing = getSessionRowByCompositeKey(parsed.provider, parsed.sessionKey);
         const sessionId = existing?.id ?? `ags_${randomUUID().replaceAll("-", "").slice(0, 10)}`;
         if (existing) {
@@ -332,7 +438,7 @@ export function registerAgentRuntimeSession(input) {
                last_error = ?, last_seen_at = ?, last_heartbeat_at = ?, started_at = ?,
                ended_at = NULL, metadata_json = ?, updated_at = ?
            WHERE id = ?`)
-                .run(agentId, parsed.agentLabel, parsed.agentType || parsed.provider, parsed.sessionLabel || parsed.sessionKey, parsed.actorLabel, parsed.connectionMode, parsed.status === "error" ? "error" : "connected", normalizeText(parsed.baseUrl), normalizeText(parsed.webUrl), normalizeText(parsed.dataRoot), normalizeText(parsed.externalSessionId), parsed.staleAfterSeconds, normalizeText(parsed.lastError), now, now, now, JSON.stringify(parsed.metadata), now, sessionId);
+                .run(agentId, agentLabel, parsed.agentType || parsed.provider, parsed.sessionLabel || parsed.sessionKey, parsed.actorLabel, parsed.connectionMode, parsed.status === "error" ? "error" : "connected", normalizeText(parsed.baseUrl), normalizeText(parsed.webUrl), normalizeText(parsed.dataRoot), normalizeText(parsed.externalSessionId), parsed.staleAfterSeconds, normalizeText(parsed.lastError), now, now, now, JSON.stringify(parsed.metadata), now, sessionId);
             insertSessionEvent(sessionId, {
                 eventType: "session_registered",
                 title: "Session re-registered",
@@ -349,7 +455,7 @@ export function registerAgentRuntimeSession(input) {
              last_seen_at, last_heartbeat_at, started_at, ended_at, metadata_json,
              created_at, updated_at
            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 0, NULL, ?, ?, ?, ?, NULL, ?, ?, ?)`)
-                .run(sessionId, agentId, parsed.agentLabel, parsed.agentType || parsed.provider, parsed.provider, parsed.sessionKey, parsed.sessionLabel || parsed.sessionKey, parsed.actorLabel, parsed.connectionMode, parsed.status === "error" ? "error" : "connected", normalizeText(parsed.baseUrl), normalizeText(parsed.webUrl), normalizeText(parsed.dataRoot), normalizeText(parsed.externalSessionId), parsed.staleAfterSeconds, normalizeText(parsed.lastError), now, now, now, JSON.stringify(parsed.metadata), now, now);
+                .run(sessionId, agentId, agentLabel, parsed.agentType || parsed.provider, parsed.provider, parsed.sessionKey, parsed.sessionLabel || parsed.sessionKey, parsed.actorLabel, parsed.connectionMode, parsed.status === "error" ? "error" : "connected", normalizeText(parsed.baseUrl), normalizeText(parsed.webUrl), normalizeText(parsed.dataRoot), normalizeText(parsed.externalSessionId), parsed.staleAfterSeconds, normalizeText(parsed.lastError), now, now, now, JSON.stringify(parsed.metadata), now, now);
             insertSessionEvent(sessionId, {
                 eventType: "session_registered",
                 title: "Session registered",
@@ -357,12 +463,12 @@ export function registerAgentRuntimeSession(input) {
                 metadata: parsed.metadata
             }, now);
         }
-        disconnectSupersededSingletonSessions(parsed, sessionId, now);
+        disconnectSupersededSingletonSessions(parsed, sessionId, agentId, now);
         recordActivityEvent({
             entityType: "session",
             entityId: sessionId,
             eventType: "agent_session_registered",
-            title: `Agent session registered: ${parsed.agentLabel}`,
+            title: `Agent session registered: ${agentLabel}`,
             description: `${parsed.provider} registered a live agent session.`,
             actor: parsed.actorLabel,
             source: "agent",