om-memory-system 4.19.1 → 4.20.0

package/dist/services/ai-cleanup-handlers.d.ts

@@ -0,0 +1,31 @@
+import type { UserProfileManager } from "./user-profile/user-profile-manager.js";
+import type { AiCleanupJobDeps, AiCleanupJobView } from "./user-profile/ai-cleanup-job.js";
+interface ApiResponse<T = any> {
+    success: boolean;
+    data?: T;
+    error?: string;
+}
+export interface AiCleanupHandlerDeps extends AiCleanupJobDeps {
+    manager?: UserProfileManager;
+}
+/**
+ * Starts a background cleanup of the selected items, or returns the job already running.
+ * A stale `profileVersion` fails at once, because the dialog's item ids are positions in
+ * the profile it read.
+ */
+export declare function handleAiCleanupStart(userId?: string, body?: any, deps?: AiCleanupHandlerDeps): Promise<ApiResponse<AiCleanupJobView | null>>;
+/** The state of the user's job, or null when there is none. */
+export declare function handleAiCleanupStatus(userId?: string): Promise<ApiResponse<AiCleanupJobView | null>>;
+/** Stops a running job, or discards a finished one. */
+export declare function handleAiCleanupStop(userId?: string): Promise<ApiResponse<null>>;
+/**
+ * Puts the ticked changes of the finished job into the newest profile and saves it with
+ * the version check. When another save lands first, it loads the profile and tries
+ * again, at most MAX_PROFILE_SAVE_ATTEMPTS times. The request's `profile` field is
+ * ignored; the job holds the result.
+ */
+export declare function handleAiCleanupApply(userId?: string, body?: any, deps?: AiCleanupHandlerDeps): Promise<ApiResponse<{
+    applied: number;
+    skipped: number;
+}>>;
+export {};

package/dist/services/ai-cleanup-handlers.js

@@ -0,0 +1,126 @@
+import { log } from "./logger.js";
+import { sortProfileItems, stripProfileVectors } from "../utils/profile.js";
+async function cleanupUser(userId) {
+    if (userId)
+        return userId;
+    const { CONFIG } = await import("../config.js");
+    const { resolveWebProfileUserId } = await import("./profile-identity.js");
+    return (await resolveWebProfileUserId(CONFIG)) || "unknown";
+}
+async function managerOf(deps) {
+    return (deps.manager ?? (await import("./user-profile/user-profile-manager.js")).userProfileManager);
+}
+function handlerError(step, error) {
+    // The log never holds profile text, so only the error's kind is kept.
+    log(`AI cleanup ${step}: error`, { code: error instanceof Error ? error.name : "unknown" });
+    return { success: false, error: String(error) };
+}
+/** The profile in the order the dialog lists it, so item ids match its positions. */
+function sortedProfile(profileData) {
+    const data = JSON.parse(profileData);
+    data.preferences = sortProfileItems(data.preferences, "confidence");
+    data.patterns = sortProfileItems(data.patterns, "frequency");
+    data.workflows = sortProfileItems(data.workflows, "frequency");
+    return data;
+}
+/** The job as the dialog sees it: no vectors, and no API key in an error. */
+async function clientView(job) {
+    if (job?.status.state === "done") {
+        const result = { ...job.status.result, old: stripProfileVectors(job.status.result.old) };
+        return { ...job, status: { ...job.status, result } };
+    }
+    if (job?.status.state === "failed") {
+        const { CONFIG } = await import("../config.js");
+        const { redactTraceText } = await import("./capture-diagnostics.js");
+        return { ...job, status: { ...job.status, error: redactTraceText(job.status.error, CONFIG) } };
+    }
+    return job;
+}
+/**
+ * Starts a background cleanup of the selected items, or returns the job already running.
+ * A stale `profileVersion` fails at once, because the dialog's item ids are positions in
+ * the profile it read.
+ */
+export async function handleAiCleanupStart(userId, body, deps = {}) {
+    try {
+        const { getAiCleanupJob, startAiCleanupJob } = await import("./user-profile/ai-cleanup-job.js");
+        const user = await cleanupUser(userId);
+        const current = getAiCleanupJob(user);
+        if (current?.status.state === "running")
+            return { success: true, data: current };
+        const profile = await (await managerOf(deps)).getActiveProfile(user);
+        if (!profile)
+            return { success: false, error: "No profile found to clean up" };
+        if (typeof body?.profileVersion === "number" && profile.version !== body.profileVersion) {
+            return { success: false, error: "Profile changed. Reload it before running AI cleanup." };
+        }
+        const includeIds = Array.isArray(body?.includeIds)
+            ? body.includeIds.filter((id) => typeof id === "string")
+            : undefined;
+        const job = startAiCleanupJob(user, { profileData: sortedProfile(profile.profileData), includeIds }, deps);
+        return { success: true, data: await clientView(job) };
+    }
+    catch (error) {
+        return handlerError("start", error);
+    }
+}
+/** The state of the user's job, or null when there is none. */
+export async function handleAiCleanupStatus(userId) {
+    try {
+        const { getAiCleanupJob } = await import("./user-profile/ai-cleanup-job.js");
+        return { success: true, data: await clientView(getAiCleanupJob(await cleanupUser(userId))) };
+    }
+    catch (error) {
+        return handlerError("status", error);
+    }
+}
+/** Stops a running job, or discards a finished one. */
+export async function handleAiCleanupStop(userId) {
+    try {
+        const { stopAiCleanupJob } = await import("./user-profile/ai-cleanup-job.js");
+        stopAiCleanupJob(await cleanupUser(userId));
+        return { success: true, data: null };
+    }
+    catch (error) {
+        return handlerError("stop", error);
+    }
+}
+/**
+ * Puts the ticked changes of the finished job into the newest profile and saves it with
+ * the version check. When another save lands first, it loads the profile and tries
+ * again, at most MAX_PROFILE_SAVE_ATTEMPTS times. The request's `profile` field is
+ * ignored; the job holds the result.
+ */
+export async function handleAiCleanupApply(userId, body, deps = {}) {
+    try {
+        const { getAiCleanupResult, stopAiCleanupJob } = await import("./user-profile/ai-cleanup-job.js");
+        const { applyCleanupEdits } = await import("./user-profile/ai-cleanup-apply.js");
+        const { MAX_PROFILE_SAVE_ATTEMPTS, saveProfile } = await import("./user-profile/merge-and-save.js");
+        const user = await cleanupUser(userId);
+        const job = getAiCleanupResult(user);
+        if (!job)
+            return { success: false, error: "No finished cleanup found. Run AI cleanup again." };
+        const accepted = {
+            merged: Array.isArray(body?.acceptedMerged) ? body.acceptedMerged : [],
+            removed: Array.isArray(body?.acceptedRemoved) ? body.acceptedRemoved : [],
+        };
+        const manager = await managerOf(deps);
+        for (let attempt = 1; attempt <= MAX_PROFILE_SAVE_ATTEMPTS; attempt++) {
+            const profile = await manager.getActiveProfile(user);
+            if (!profile)
+                return { success: false, error: "Profile not found" };
+            const result = applyCleanupEdits(JSON.parse(profile.profileData), job, accepted);
+            const saved = result.applied === 0 ||
+                (await saveProfile(profile, result.profile, "AI cleanup applied", 0, manager));
+            if (saved) {
+                stopAiCleanupJob(user);
+                return { success: true, data: { applied: result.applied, skipped: result.skipped } };
+            }
+            log("AI cleanup apply: save conflict", { attempt, of: MAX_PROFILE_SAVE_ATTEMPTS });
+        }
+        return { success: false, error: "Profile saved at the same moment. Try Apply again." };
+    }
+    catch (error) {
+        return handlerError("apply", error);
+    }
+}

package/dist/services/api-handlers.d.ts

@@ -1,6 +1,5 @@
 import { type KeywordCount } from "./keyword-counts.js";
 import type { MemoryType } from "../types/index.js";
-import type { UserProfileData } from "./user-profile/types.js";
 interface ApiResponse<T = any> {
     success: boolean;
     data?: T;
@@ -148,27 +147,6 @@ export declare function handleGetUserProfile(userId?: string): Promise<ApiRespon
 export declare function handleGetProfileChangelog(profileId: string, limit?: number): Promise<ApiResponse<any[]>>;
 export declare function handleGetProfileSnapshot(changelogId: string): Promise<ApiResponse<any>>;
 export declare function handleRefreshProfile(userId?: string): Promise<ApiResponse<any>>;
-export declare function handleAICleanup(userId?: string, includeIds?: string[], profileVersion?: number): Promise<ApiResponse<any>>;
-/**
- * Merge an AI-cleanup result into a full profile.
- * When includeIds is set, only scoped items are mutated; everything else is preserved.
- */
-export declare function mergeCleanupIntoProfile(args: {
-    currentProfile: UserProfileData;
-    oldProfileData: UserProfileData;
-    cleanedData: UserProfileData;
-    includeIds?: string[];
-    acceptedMerged?: string[][];
-    acceptedRemoved?: string[];
-    allMerged?: Array<{
-        ids: string[];
-        result: string;
-    }>;
-    allRemovedIds?: string[];
-    /** True when the client sent acceptance arrays (even if empty = reject all). */
-    explicitAcceptance?: boolean;
-}): UserProfileData;
-export declare function handleApplyCleanup(userId?: string, body?: any): Promise<ApiResponse<any>>;
 type CategoryCleanupDeps = import("./user-profile/category-cleanup.js").CleanupDeps;
 /** Starts a background preview job, or returns the one already running. Changes nothing in the profile. */
 export declare function handleCategoryCleanupStart(userId?: string, deps?: CategoryCleanupDeps): Promise<ApiResponse<any>>;

package/dist/services/api-handlers.js

@@ -884,194 +884,6 @@ export async function handleRefreshProfile(userId) {
         return { success: false, error: String(error) };
     }
 }
-// Temporary storage for pending AI cleanup results (userId → result)
-const pendingCleanups = new Map();
-export async function handleAICleanup(userId, includeIds, profileVersion) {
-    try {
-        const { userProfileManager } = await import("./user-profile/user-profile-manager.js");
-        const { aiCleanupProfile, aiCleanupProfileFromIndexed, filterProfileForCleanup } = await import("./user-profile/ai-cleanup.js");
-        let targetUserId = userId;
-        if (!targetUserId) {
-            targetUserId = (await resolveWebProfileUserId(CONFIG)) || "unknown";
-        }
-        const profile = await userProfileManager.getActiveProfile(targetUserId);
-        if (!profile) {
-            return { success: false, error: "No profile found to clean up" };
-        }
-        if (profileVersion !== undefined && profile.version !== profileVersion) {
-            return { success: false, error: "Profile changed. Reload it before running AI cleanup." };
-        }
-        const profileData = JSON.parse(profile.profileData);
-        profileData.preferences = sortProfileItems(profileData.preferences, "confidence");
-        profileData.patterns = sortProfileItems(profileData.patterns, "frequency");
-        profileData.workflows = sortProfileItems(profileData.workflows, "frequency");
-        let indexed;
-        let result;
-        const scopedIds = includeIds && includeIds.length > 0 ? includeIds : undefined;
-        if (scopedIds) {
-            indexed = filterProfileForCleanup(profileData, scopedIds);
-            result = await aiCleanupProfileFromIndexed(indexed);
-        }
-        else {
-            result = await aiCleanupProfile(profileData);
-        }
-        pendingCleanups.set(targetUserId, {
-            cleaned: result.cleaned,
-            oldProfileData: profileData,
-            diff: result.diff,
-            allMerged: result.diff?.merged || [],
-            allRemovedIds: (result.diff?.removed || []).map((r) => r.id),
-            includeIds: scopedIds,
-            profileVersion: profile.version,
-            expiresAt: Date.now() + 30 * 60 * 1000,
-        });
-        return {
-            success: true,
-            data: {
-                old: profileData,
-                new: result.cleaned,
-                changes: result.diff,
-            },
-        };
-    }
-    catch (error) {
-        log("handleAICleanup: error", { error: String(error) });
-        return { success: false, error: String(error) };
-    }
-}
-/**
- * Merge an AI-cleanup result into a full profile.
- * When includeIds is set, only scoped items are mutated; everything else is preserved.
- */
-export function mergeCleanupIntoProfile(args) {
-    const { currentProfile, oldProfileData, cleanedData, includeIds, acceptedMerged = [], acceptedRemoved = [], allMerged = [], allRemovedIds = [], explicitAcceptance = false, } = args;
-    // Start from cleaned data, then restore any rejected removals/merges.
-    const scopedResult = {
-        preferences: [...cleanedData.preferences],
-        patterns: [...cleanedData.patterns],
-        workflows: [...cleanedData.workflows],
-    };
-    if (explicitAcceptance) {
-        for (const id of acceptedRemoved) {
-            removeItemFromProfile(scopedResult, oldProfileData, id);
-        }
-        for (const ids of acceptedMerged) {
-            for (let i = 1; i < ids.length; i++) {
-                removeItemFromProfile(scopedResult, oldProfileData, ids[i] ?? "");
-            }
-        }
-        const acceptedTargetIds = new Set(acceptedMerged.map((g) => g[0]));
-        for (const merge of allMerged) {
-            const groupIds = merge.ids;
-            if (groupIds.length <= 1)
-                continue;
-            if (acceptedTargetIds.has(groupIds[0]))
-                continue;
-            removeOneByDescription(scopedResult, merge.result, itemTypeFromId(groupIds[0] ?? ""));
-            for (const id of groupIds) {
-                if (id)
-                    pushItemFromProfile(scopedResult, oldProfileData, id);
-            }
-        }
-        const acceptedRemovedSet = new Set(acceptedRemoved);
-        for (const removedId of allRemovedIds) {
-            if (acceptedRemovedSet.has(removedId))
-                continue;
-            pushItemFromProfile(scopedResult, oldProfileData, removedId);
-        }
-    }
-    // Full-profile cleanup: cleaned (+ acceptance) replaces the whole profile.
-    if (!includeIds || includeIds.length === 0) {
-        return scopedResult;
-    }
-    // Partial selection: mutate only the analyzed scope inside the current full profile.
-    const result = {
-        preferences: [...currentProfile.preferences],
-        patterns: [...currentProfile.patterns],
-        workflows: [...currentProfile.workflows],
-    };
-    for (const id of includeIds) {
-        removeItemFromProfile(result, oldProfileData, id);
-    }
-    result.preferences.push(...scopedResult.preferences);
-    result.patterns.push(...scopedResult.patterns);
-    result.workflows.push(...scopedResult.workflows);
-    return result;
-}
-function pushItemFromProfile(target, source, id) {
-    const srcItem = findItemById(source, id);
-    if (!srcItem)
-        return;
-    const { id: _id, ...rest } = srcItem;
-    if (id.startsWith("pref_"))
-        target.preferences.push(rest);
-    else if (id.startsWith("pat_"))
-        target.patterns.push(rest);
-    else if (id.startsWith("wf_"))
-        target.workflows.push(rest);
-}
-export async function handleApplyCleanup(userId, body) {
-    try {
-        const { userProfileManager } = await import("./user-profile/user-profile-manager.js");
-        let targetUserId = userId;
-        if (!targetUserId) {
-            targetUserId = (await resolveWebProfileUserId(CONFIG)) || "unknown";
-        }
-        const pending = pendingCleanups.get(targetUserId);
-        if (!pending) {
-            return { success: false, error: "No pending cleanup found. Run AI cleanup first." };
-        }
-        if (Date.now() > pending.expiresAt) {
-            pendingCleanups.delete(targetUserId);
-            return { success: false, error: "Cleanup session expired. Run AI cleanup again." };
-        }
-        const profile = await userProfileManager.getActiveProfile(targetUserId);
-        if (!profile) {
-            return { success: false, error: "Profile not found" };
-        }
-        if (profile.version !== pending.profileVersion) {
-            pendingCleanups.delete(targetUserId);
-            return { success: false, error: "Profile changed. Run AI cleanup again." };
-        }
-        const cleanedData = body?.profile || pending.cleaned;
-        const acceptedMerged = Array.isArray(body?.acceptedMerged)
-            ? body.acceptedMerged
-            : [];
-        const acceptedRemoved = Array.isArray(body?.acceptedRemoved)
-            ? body.acceptedRemoved
-            : [];
-        const explicitAcceptance = Array.isArray(body?.acceptedMerged) || Array.isArray(body?.acceptedRemoved);
-        const existingData = JSON.parse(profile.profileData);
-        const result = mergeCleanupIntoProfile({
-            currentProfile: existingData,
-            oldProfileData: pending.oldProfileData,
-            cleanedData,
-            includeIds: pending.includeIds,
-            acceptedMerged,
-            acceptedRemoved,
-            allMerged: pending.allMerged,
-            allRemovedIds: pending.allRemovedIds,
-            explicitAcceptance,
-        });
-        const partial = (pending.includeIds && pending.includeIds.length > 0) || explicitAcceptance;
-        const success = await saveProfile(profile, result, partial ? "AI cleanup applied (partial)" : "AI cleanup applied");
-        if (!success) {
-            return { success: false, error: "Profile was modified by another session. Please retry." };
-        }
-        pendingCleanups.delete(targetUserId);
-        return {
-            success: true,
-            data: {
-                message: partial ? "Partial cleanup applied" : "Cleanup applied successfully",
-                version: profile.version + 1,
-            },
-        };
-    }
-    catch (error) {
-        log("handleApplyCleanup: error", { error: String(error) });
-        return { success: false, error: String(error) };
-    }
-}
 async function categoryCleanupUser(userId) {
     return userId || (await resolveWebProfileUserId(CONFIG)) || "unknown";
 }
@@ -1144,57 +956,6 @@ export async function handleCategoryCleanupUndo(userId, deps) {
         return categoryCleanupError("undo", error);
     }
 }
-function itemTypeFromId(id) {
-    if (id.startsWith("pref_"))
-        return "preferences";
-    if (id.startsWith("pat_"))
-        return "patterns";
-    return "workflows";
-}
-function findItemById(profile, id) {
-    if (typeof id !== "string" || !id.includes("_"))
-        return null;
-    const parts = id.split("_");
-    const prefix = parts[0];
-    const idx = parseInt(parts[1] || "", 10);
-    if (isNaN(idx))
-        return null;
-    if (prefix === "pref")
-        return profile.preferences[idx] || null;
-    if (prefix === "pat")
-        return profile.patterns[idx] || null;
-    if (prefix === "wf")
-        return profile.workflows[idx] || null;
-    return null;
-}
-function removeItemFromProfile(target, source, id) {
-    const sourceItem = findItemById(source, id);
-    if (!sourceItem)
-        return false;
-    const itemType = itemTypeFromId(id);
-    const items = target[itemType];
-    const sourceKey = profileItemIdentityKey(sourceItem);
-    const index = items.findIndex((item) => profileItemIdentityKey(item) === sourceKey);
-    if (index < 0)
-        return false;
-    items.splice(index, 1);
-    return true;
-}
-function profileItemIdentityKey(item) {
-    return JSON.stringify({
-        category: item.category ?? null,
-        description: item.description ?? null,
-        steps: Array.isArray(item.steps) ? item.steps : null,
-    });
-}
-function removeOneByDescription(profile, desc, itemType) {
-    const items = profile[itemType];
-    const index = items.findIndex((item) => item.description === desc);
-    if (index < 0)
-        return false;
-    items.splice(index, 1);
-    return true;
-}
 export async function handleUpdateProfileItem(body) {
     try {
         const { userProfileManager } = await import("./user-profile/user-profile-manager.js");

package/dist/services/request-timeouts.d.ts

@@ -1,5 +1,7 @@
 export declare const EXTERNAL_PROFILE_CLEANUP_TIMEOUT_MS = 60000;
 export declare const OPENCODE_PROFILE_CLEANUP_TIMEOUT_MS = 300000;
+/** The most items one web AI cleanup request sends, so each request ends inside its time limit. */
+export declare const AI_CLEANUP_BATCH_SIZE = 100;
 export declare const NODE_HTTP_IDLE_TIMEOUT_MS: number;
 /**
  * Upper bound an OpenCode v2 model request waits for the per-prompt memory

package/dist/services/request-timeouts.js

@@ -1,5 +1,7 @@
 export const EXTERNAL_PROFILE_CLEANUP_TIMEOUT_MS = 60_000;
 export const OPENCODE_PROFILE_CLEANUP_TIMEOUT_MS = 300_000;
+/** The most items one web AI cleanup request sends, so each request ends inside its time limit. */
+export const AI_CLEANUP_BATCH_SIZE = 100;
 const HTTP_TIMEOUT_GRACE_MS = 30_000;
 export const NODE_HTTP_IDLE_TIMEOUT_MS = Math.max(EXTERNAL_PROFILE_CLEANUP_TIMEOUT_MS, OPENCODE_PROFILE_CLEANUP_TIMEOUT_MS) +
     HTTP_TIMEOUT_GRACE_MS;

package/dist/services/user-profile/ai-cleanup-apply.d.ts

@@ -0,0 +1,27 @@
+import type { CleanupDiff } from "./ai-cleanup.js";
+import type { UserProfileData } from "./types.js";
+/** What a finished cleanup job keeps for Apply. Ids are positions in `old`. */
+export interface CleanupJobResult {
+    old: UserProfileData;
+    changes: CleanupDiff;
+    mergedItems: Record<string, unknown>;
+}
+export interface AcceptedCleanup {
+    merged?: string[][];
+    removed?: string[];
+}
+export interface AppliedCleanup {
+    profile: UserProfileData;
+    applied: number;
+    skipped: number;
+}
+/**
+ * Puts the ticked changes of a job into `current`, which may be newer than the profile
+ * the job read. Each item is found by section, category, description and steps, so
+ * learning's counters do not break a match. A change is skipped when one of its items is
+ * gone. Every other item stays exactly as stored. Ticked ids that are not changes of
+ * the job are ignored.
+ */
+export declare function applyCleanupEdits(current: UserProfileData, job: CleanupJobResult, accepted: AcceptedCleanup): AppliedCleanup;
+/** The fields that identify a profile item. Counters and vectors are left out. */
+export declare function profileItemIdentityKey(item: any): string;

package/dist/services/user-profile/ai-cleanup-apply.js

@@ -0,0 +1,94 @@
+const SECTION_BY_PREFIX = {
+    pref: "preferences",
+    pat: "patterns",
+    wf: "workflows",
+};
+/**
+ * Puts the ticked changes of a job into `current`, which may be newer than the profile
+ * the job read. Each item is found by section, category, description and steps, so
+ * learning's counters do not break a match. A change is skipped when one of its items is
+ * gone. Every other item stays exactly as stored. Ticked ids that are not changes of
+ * the job are ignored.
+ */
+export function applyCleanupEdits(current, job, accepted) {
+    const profile = {
+        ...current,
+        preferences: [...current.preferences],
+        patterns: [...current.patterns],
+        workflows: [...current.workflows],
+    };
+    const merges = new Map(job.changes.merged.map((m) => [m.ids.join(","), m.ids]));
+    const removals = new Set(job.changes.removed.map((r) => r.id));
+    const used = new Set();
+    let applied = 0;
+    let skipped = 0;
+    for (const ticked of accepted.merged ?? []) {
+        const ids = Array.isArray(ticked) ? merges.get(ticked.join(",")) : undefined;
+        if (!ids || ids.length < 2)
+            continue;
+        const mergedItem = job.mergedItems[ids[0]];
+        const found = mergedItem ? locate(profile, job.old, ids, used) : null;
+        if (!found) {
+            skipped++;
+            continue;
+        }
+        const items = profile[found.section];
+        items[found.indices[0]] = { ...mergedItem };
+        for (const index of found.indices.slice(1).sort((a, b) => b - a))
+            items.splice(index, 1);
+        for (const id of ids)
+            used.add(id);
+        applied++;
+    }
+    for (const id of accepted.removed ?? []) {
+        if (typeof id !== "string" || !removals.has(id))
+            continue;
+        const found = locate(profile, job.old, [id], used);
+        if (!found) {
+            skipped++;
+            continue;
+        }
+        profile[found.section].splice(found.indices[0], 1);
+        used.add(id);
+        applied++;
+    }
+    return { profile, applied, skipped };
+}
+/**
+ * Finds each id's item from `old` in `profile`, at a distinct position, all in one
+ * section. Returns null when an item is gone or an earlier change already used it.
+ */
+function locate(profile, old, ids, used) {
+    const section = sectionOf(ids[0]);
+    if (!section)
+        return null;
+    const items = profile[section];
+    const indices = [];
+    for (const id of ids) {
+        if (used.has(id) || sectionOf(id) !== section)
+            return null;
+        const source = old[section][positionOf(id)];
+        if (!source)
+            return null;
+        const key = profileItemIdentityKey(source);
+        const index = items.findIndex((item, i) => !indices.includes(i) && profileItemIdentityKey(item) === key);
+        if (index < 0)
+            return null;
+        indices.push(index);
+    }
+    return { section, indices };
+}
+function sectionOf(id) {
+    return SECTION_BY_PREFIX[id.split("_")[0] ?? ""];
+}
+function positionOf(id) {
+    return Number.parseInt(id.split("_")[1] ?? "", 10);
+}
+/** The fields that identify a profile item. Counters and vectors are left out. */
+export function profileItemIdentityKey(item) {
+    return JSON.stringify({
+        category: item.category ?? null,
+        description: item.description ?? null,
+        steps: Array.isArray(item.steps) ? item.steps : null,
+    });
+}

package/dist/services/user-profile/ai-cleanup-batches.d.ts

@@ -0,0 +1,34 @@
+import type { UserProfileData } from "./types.js";
+import { type CleanupDiff, type IndexedProfile } from "./ai-cleanup.js";
+/** What one batch adds to the review: its changes, and the merged item of each merge. */
+export interface BatchCleanupResult {
+    diff: CleanupDiff;
+    mergedItems: Record<string, unknown>;
+}
+export interface BatchRunResult extends BatchCleanupResult {
+    failedBatches: number;
+    failedItems: number;
+}
+export interface RunInBatchesOptions {
+    callBatch?: (batch: IndexedProfile) => Promise<BatchCleanupResult>;
+    onProgress?: (done: number, total: number, failed: number) => void;
+    isStopped?: () => boolean;
+}
+/** Indexes the full profile once, so ids are profile positions, and keeps the selected items. */
+export declare function selectForCleanup(profileData: UserProfileData, includeIds: string[]): IndexedProfile;
+/**
+ * Packs each section on its own, sorted by category, so a category of up to `size` items
+ * stays in one batch. Likely duplicates share a category, and the model merges only
+ * inside a section.
+ */
+export declare function splitIntoBatches(indexed: IndexedProfile, size: number): IndexedProfile[];
+/** One model request for one batch. */
+export declare function cleanupBatch(indexed: IndexedProfile): Promise<BatchCleanupResult>;
+/**
+ * Runs the batches one after another and joins their results. A failed batch adds
+ * nothing, so its items stay as they are. Throws the first error when every batch
+ * fails. Returns null when stopped; the stop flag is read before and after each call.
+ */
+export declare function runInBatches(batches: IndexedProfile[], { callBatch, onProgress, isStopped }?: RunInBatchesOptions): Promise<BatchRunResult | null>;
+/** A fixed reason code for the log. Never the error text, which may quote the reply. */
+export declare function failureReason(error: unknown): string;