@zooique/memora 2.0.3 → 3.0.0

package/dist/agent/managers/chatLockManager.js

@@ -1,91 +1,51 @@
 /**
- * ChatLockManager — chat() 并发锁管理器
+ * ChatLockManager — chat() 并发锁管理器：并发锁 + token 校验 + 超时保护 + 外部 signal 合并。
  *
- * 职责：
- *   - chat() 并发锁（防止多轮 chat 同时执行）
- *   - token 校验（防止 race condition：超时释放后新调用获取锁，旧 finally 误清新调用者资源）
- *   - 超时保护（LLM 卡死时中断 generator + 释放锁）
- *   - 外部 signal 合并（外部 abort 时触发内部 abort）
- *
- * 从 agent.ts 提取（AUDIT-1-1，ADR-017 架构层先行原则首次实践）
- *
- * race condition 防护设计：
- *   原锁是简单布尔值 `_chatBusy`，无 owner 校验。超时回调与 finally 块无差别清理，
- *   导致 race condition：T=0 A 获取锁 → T=180s 超时释放 → T=181s B 获取锁
- *   → T=182s A 的 finally 误清 B 的锁/计时器/controller。
- *
- *   防护方案：
- *   - 获取锁时 token 递增：`const myToken = ++this._chatLockToken`
- *   - 超时回调校验 `this._chatLockToken === myToken` 后才释放
- *   - finally 块校验 `this._chatLockToken === myToken` 后才清理
- *   - 不匹配时跳过清理，避免误清新调用者的资源
- *
- *   选择 number 而非 Symbol：递增计数器可序列化、零依赖、足够唯一（同一 Agent 实例内）
+ * race condition 防护（token 机制）：原锁仅布尔 _chatBusy，超时回调与 finally 块无差别清理，
+ * 可能误清新调用者的资源（T=0 A 获取→超时释放→B 获取→A finally 误清 B）。
+ * 故获取锁时递增 token，超时回调/finally 均校验 token 是否仍是当前持有者，不匹配则跳过清理。
  */
 import { clearSafeTimeout, safeSetTimeout } from '../../utils/safeTimer.js';
 import { logger } from '../../logging/logger.js';
 /**
- * chat() 并发锁管理器
- *
- * 使用方式：
- *   const mgr = new ChatLockManager();
- *   const { token, internalAbort } = mgr.acquire(180_000);
- *   const cleanup = mgr.attachExternalSignal(externalSignal, internalAbort);
- *   try {
- *     // ... 使用 internalAbort.signal 传递给 generator ...
- *   } finally {
- *     mgr.release(token);
- *     cleanup();
- *   }
- *
- * 强制释放（宿主兜底）：
- *   mgr.forceRelease();
- *
- * 销毁（Agent.close 时）：
- *   mgr.dispose();
+ * chat() 并发锁管理器。acquire 返回 token+internalAbort，finally 中 release(token)。
+ * forceRelease 供宿主无进展超时兜底；dispose 供 Agent.close。
  */
 export class ChatLockManager {
-    /** chat() 是否正在执行（并发锁） */
+    /** 并发锁标志 */
     _chatBusy = false;
-    /**
-     * chat() 锁持有者 token（race condition 防护）
-     *
-     * 获取锁时递增，超时回调和 finally 块据此判断是否仍是当前持有者。
-     * 不匹配时跳过清理，避免误清新调用者的资源。
-     */
+    /** 锁持有者 token（race condition 防护，校验当前持有者避免误清新调用者资源） */
     _chatLockToken = 0;
-    /** 聊天锁超时计时器（防止 LLM 卡死时锁永久持有） */
+    /** 锁超时计时器（防 LLM 卡死时锁永久持有） */
     chatLockTimer = null;
-    /** chat() 内部 AbortController（超时时中断 generator，防止并发） */
+    /** 内部 AbortController（超时时中断 generator） */
     chatAbortController = null;
     /** 当前是否持有锁 */
     get isBusy() {
         return this._chatBusy;
     }
     /**
-     * 获取锁，返回 token + 内部 AbortController
-     *
-     * @param timeoutMs 锁超时时间（LLM 卡死保护）
-     * @param onTimeout 超时回调（用于日志记录等）
-     * @returns token（用于 finally 校验）+ internalAbort（用于传递给 loop.processUserInput）
+     * 获取锁，返回 token（finally 校验）+ internalAbort（传给 loop.processUserInput）。
+     * 超时保护：锁超时后自动释放锁（允许新对话进入），但不中断生成流——
+     * LLM 无进展由 provider 层请求级/事件停滞超时兜底，锁不对整次对话时长设硬上限。
      */
     acquire(timeoutMs, onTimeout) {
         this._chatBusy = true;
-        // 分配本调用的 token，超时回调和 finally 块据此判断是否仍是当前持有者
-        // 避免 race condition：超时释放后新调用获取锁，旧 finally 误清新调用者的资源
+        // 分配本调用 token，超时/finally 据此判断是否仍是持有者，避免误清新调用资源
         const token = ++this._chatLockToken;
-        // 内部 AbortController，超时时中断 generator 而非仅释放锁
+        // 中断信号（用户 stop / 插话 / 宿主 forceRelease 会 abort 它；锁自身超时不 abort）
         const internalAbort = new AbortController();
         this.chatAbortController = internalAbort;
-        // 超时保护：LLM 卡死时中断 generator + 释放锁，防止并发
-        // 超时回调校验 token 后才清理，避免误清新调用者的资源
         this.chatLockTimer = safeSetTimeout(() => {
-            // 令牌不匹配：锁已被新调用者获取（或本调用已正常退出），跳过清理
+            // token 不匹配：锁已被新调用者获取（或本调用已正常退出），跳过清理
             if (this._chatLockToken !== token) {
                 return;
             }
-            logger.warn({ timeoutMs }, 'chat() 锁超时，中断 generator 并释放锁');
-            internalAbort.abort();
+            logger.warn({ timeoutMs }, 'chat() 锁超时，自动释放锁（不中断生成流）');
+            // 仅释放锁（自增 token 令旧 generator 的 finally release 跳过清理，避免误清新调用），
+            // 不 abort 生成流——LLM 无进展/停滞由 provider 层超时兜底（请求级 120s + SSE 事件停滞 120s），
+            // 锁不再对「整次对话时长」设硬上限，慢但正常的长时间对话不被误杀。
+            this._chatLockToken++;
             this._chatBusy = false;
             this.chatLockTimer = null;
             this.chatAbortController = null;
@@ -93,32 +53,19 @@ export class ChatLockManager {
         }, timeoutMs);
         return { token, internalAbort };
     }
-    /**
-     * 合并外部 signal：外部 abort 时触发内部 abort
-     *
-     * addEventListener 对已 aborted 的 signal 不触发回调，
-     * 需手动检查并触发 internalAbort，否则外部已取消的请求仍会进入主流程。
-     *
-     * @returns 清理函数（finally 块中调用 removeEventListener）
-     */
+    /** 合并外部 signal：外部 abort 时触发内部 abort；返回 cleanup。addEventListener 对已 aborted 的 signal 不触发，需手动检查。 */
     attachExternalSignal(externalSignal, internalAbort) {
         if (!externalSignal)
             return () => { };
         const onExternalAbort = () => internalAbort.abort();
         externalSignal.addEventListener('abort', onExternalAbort, { once: true });
-        // addEventListener 对已 aborted 的 signal 不触发回调
-        // 需手动检查并触发 internalAbort，否则外部已取消的请求仍会进入主流程
+        // 外部 signal 已 aborted 时不触发回调，手动触发一次，避免外部已取消请求仍进入主流程
         if (externalSignal.aborted) {
             internalAbort.abort();
         }
         return () => externalSignal.removeEventListener('abort', onExternalAbort);
     }
-    /**
-     * finally 块清理（token 校验后）
-     *
-     * 仅当本调用仍是当前锁持有者时才清理资源。
-     * 若 token 已变（超时释放后被新调用者获取），跳过清理避免误清新调用者的状态。
-     */
+    /** finally 清理（token 校验）：仅当前持有者清理，token 已变则跳过避免误清新调用者状态 */
     release(token) {
         if (this._chatLockToken !== token) {
             return;
@@ -131,34 +78,19 @@ export class ChatLockManager {
         }
     }
     /**
-     * 强制释放对话锁（宿主无进展超时兜底）
-     *
-     * 场景：宿主主进程"无进展超时"兜底后，generator 可能仍卡在不可中断的 await 点
-     *   （executeToolCalls 和 generateContextSummary 已覆盖 signal 响应，但其他
-     *   第三方库或未来新增的 await 点仍可能不响应 signal）。
-     *   此时 _chatBusy 锁未释放，用户再发消息会被 chat() 的竞态保护拒绝，
-     *   表现为"UI 能操作但发不出消息"，需等到 3 分钟锁超时才能恢复。
-     *
-     * 安全机制：
-     *   - 递增 _chatLockToken，让原 chat() 的 finally 块检测到 token 不匹配后
-     *     跳过资源清理（避免误清新调用者的 _chatBusy/chatAbortController）
-     *   - abort chatAbortController，让响应 signal 的 await 点（如 fetch）退出
-     *   - 原 generator 仍可能在后台运行（无法真正中断不响应 signal 的 await），
-     *     但其 finally 块的 token 校验会阻止它影响新调用
-     *
-     * 幂等性：_chatBusy 已 false 时 no-op（多次调用安全）
+     * 强制释放对话锁（宿主无进展超时兜底）。幂等：_chatBusy 已 false 时 no-op。
+     * generator 可能卡在不可响应的 await 点，递增 token 让原 finally 跳过清理；
+     * abort controller 让响应 signal 的 await 点退出。原 generator 后台残留也无法影响新调用。
      */
     forceRelease() {
         if (!this._chatBusy)
             return;
-        // 递增 token 让原 chat() 的 finally 块跳过清理（避免误清新调用者的资源）
+        // 递增 token 让原 chat() finally 跳过清理（避免误清新调用者资源）
         this._chatLockToken++;
-        // abort 当前 generator（响应 signal 的 await 点会 throw AbortError 退出）
         if (this.chatAbortController) {
             this.chatAbortController.abort();
             this.chatAbortController = null;
         }
-        // 清理锁超时定时器（避免后续触发重复清理）
         if (this.chatLockTimer) {
             clearSafeTimeout(this.chatLockTimer);
             this.chatLockTimer = null;
@@ -167,15 +99,11 @@ export class ChatLockManager {
         logger.warn('对话锁被强制释放（宿主无进展超时兜底）');
     }
     /**
-     * 销毁管理器（Agent.close 时调用）
-     *
-     * 与 forceRelease() 的区别：不记录 warn 日志（close 是正常生命周期，非异常场景）。
-     * 递增 token 使任何进行中的 chat() generator 的 finally 块检测到 token 变化后
-     * 跳过资源清理（close 已接管清理职责）。
+     * 销毁管理器（Agent.close 时调用）。与 forceRelease 同行为但不记 warn 日志
+     * （close 为正常生命周期）。递增 token 使进行中 generator 的 finally 跳过清理。
      */
     dispose() {
-        // 递增 token，使任何进行中的 chat() generator 的 finally 块
-        // 检测到 token 变化后跳过资源清理（close 已接管清理职责）
+        // 递增 token，让进行中 chat() finally 跳过资源清理（close 已接管清理职责）
         this._chatLockToken++;
         if (this.chatAbortController) {
             this.chatAbortController.abort();

package/dist/agent/managers/chatLockManager.js.map

@@ -1 +1 @@
-{"version":3,"file":"chatLockManager.js","sourceRoot":"","sources":["../../../src/agent/managers/chatLockManager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"chatLockManager.js","sourceRoot":"","sources":["../../../src/agent/managers/chatLockManager.ts"],"names":[],"mappings":"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"}

package/dist/agent/managers/dedupManager.d.ts

@@ -1,52 +1,36 @@
 /**
- * 语义去重管理器 — L1 记忆治理子系统
- *
- * 从 MemoryInspector 拆分出来，专责异步 LLM 语义去重。
- * 与 MemoryInspector 的分工：
- *   - MemoryInspector：同步读写入口（snapshot/search/stats/writeXxx/relations）
- *   - DedupManager：异步 LLM 治理（deduplicateMemories）
- *
- * 拆分理由（SPLIT-3，2026-07-21）：
- *   - 职责分离——同步读写 vs 异步 LLM 治理是两个独立关注点
- *   - 依赖清晰——MemoryInspector 不再依赖 LLM Provider，纯存储读写
- *   - 可测试性——去重逻辑独立测试，无需 mock loop/history/advisor
- *   - 自包含——去重逻辑（配对 + LLM 判断 + 降级 + prompt）形成自闭合子系统
- *
- * 设计原则：
- *   - 静默降级——backgroundProvider 未注入时返回 skippedReason 报告，不抛错
- *   - 不物理删除——仅降级 score（→ 0.1），保留可恢复性
- *   - 异步执行——不阻塞主对话热路径（由宿主定时任务或用户手动触发）
- *
- * @module agent/managers/dedupManager
+ * 记忆治理管理者（从 MemoryInspector 拆分，专责异步 LLM 语义去重）。
+ * 职责分离：MemoryInspector 纯存储读写，DedupManager 异步 LLM 治理。
+ * 设计原则：未注入 provider 时静默降级返回报告不抛错；不物理删除仅软删重复方保留可恢复性；不阻塞主对话热路径。
  */
 import type { Memory } from '../../memory/types.js';
 import type { IMemoryStorage } from '../../memory/storageInterface.js';
 import type { LlmProvider } from '../../llm/provider.js';
 /** 名称高度相似的候选记忆对（待 LLM 判断语义等价性） */
 export interface DedupPair {
-    /** 记忆 A（score 较高，作为保留候选） */
+    /** 记忆 A（保留候选） */
     a: Memory;
-    /** 记忆 B（score 较低，作为降级候选） */
+    /** 记忆 B（重复方，软删候选） */
     b: Memory;
     /** 名称归一化相似度（0-1，越小越相似） */
     nameSimilarity: number;
 }
 /** LLM 对单对记忆的语义等价判断结果 */
 export interface DedupVerdict {
-    /** 是否语义等价（true → 降级低分记忆） */
+    /** 是否语义等价（true → 软删重复方） */
     isDuplicate: boolean;
-    /** 合并后的内容（isDuplicate=true 时提供，保留更完整的信息） */
+    /** 合并后的内容（isDuplicate=true 时提供，保留更完整信息） */
     mergedContent?: string;
-    /** LLM 判断理由（便于审计和调试） */
+    /** LLM 判断理由（便于审计调试） */
     reason: string;
 }
-/** 降级记忆的审计详情（DedupReport.verdicts 元素，供 UI 展示"为什么降级"） */
+/** 降级记忆审计详情（供 UI 展示"为什么降级" + 合并后内容） */
 export interface DedupVerdictSummary {
-    /** 被降级的记忆 ID（与 demotedIds 元素一一对应） */
+    /** 被降级记忆 ID（与 demotedIds 一一对应） */
     demotedId: string;
-    /** LLM 判断理由（便于用户审计降级是否合理） */
+    /** LLM 判断理由（便于审计降级是否合理） */
     reason: string;
-    /** 合并后的完整内容（便于用户验证合并质量；未提供 mergedContent 时省略，渲染器负责截断展示） */
+    /** 合并后完整内容（便于验证合并质量；缺失时渲染器负责截断展示） */
     mergedContent?: string;
 }
 /** 语义去重报告（deduplicateMemories 返回值） */
@@ -57,113 +41,45 @@ export interface DedupReport {
     pairCount: number;
     /** LLM 判定为语义等价并执行降级的对数 */
     deduplicatedCount: number;
-    /** 被降级的记忆 ID 列表（score 降至 DEDUP_LOW_SCORE，未物理删除） */
+    /** 被降级记忆 ID 列表（未物理删除） */
     demotedIds: string[];
-    /** 降级审计详情（与 demotedIds 一一对应，供 UI 展示 reason + mergedContentPreview） */
+    /** 降级审计详情（与 demotedIds 一一对应） */
     verdicts?: DedupVerdictSummary[];
-    /** 跳过原因（LLM 不可用 / 无候选对 / LLM 失败降级） */
+    /** 跳过原因（LLM 不可用 / 无候选对） */
     skippedReason?: string;
 }
-/**
- * 语义去重管理器
- *
- * 扫描名称高度相似的记忆对，调用 LLM 判断语义等价性，降级低分记忆。
- *
- * 装配：由 assembler.ts 在组合根创建，backgroundProvider 可选注入。
- * 调用：Agent.deduplicateMemories() 透传至本类。
- */
+/** 语义去重管理器：扫描名称高度相似的记忆对，LLM 判断语义等价性，降级低分记忆。assembler 组合根创建，由 Agent 透传调用。 */
 export declare class DedupManager {
     private readonly index;
-    /** 去重完成回调（宿主可据此发射事件通知用户） */
+    /** 去重完成回调（宿主据此发射事件通知用户） */
     private readonly onCompleted?;
-    /** 后台 LLM Provider（可选，用于语义去重等异步治理任务，未注入时降级跳过） */
+    /** 后台 LLM Provider（可选，未注入时降级跳过） */
     private readonly backgroundProvider;
-    /**
-     * @param index - 记忆存储（用于读写候选记忆）
-     * @param backgroundProvider - 后台 LLM Provider（可选，用于语义去重，未注入时降级跳过）
-     */
+    /** 治理源列表（默认 GOVERNANCE_SOURCES；空治理源时去重空转，测试可显式注入） */
+    private readonly sources;
     constructor(index: IMemoryStorage, backgroundProvider?: LlmProvider | null, 
-    /** 去重完成回调（宿主可据此发射事件通知用户） */
-    onCompleted?: ((report: DedupReport) => void) | undefined);
+    /** 去重完成回调（宿主据此发射事件通知用户） */
+    onCompleted?: ((report: DedupReport) => void) | undefined, sources?: readonly string[]);
     /**
-     * 语义去重：扫描名称高度相似的记忆对，调用 LLM 判断语义等价性
-     *
-     * 流程：
-     *   1. 从 insight/profile/work-projection 加载候选记忆（上限 50 条）
-     *   2. 按名称归一化 Levenshtein 距离筛选相似对（上限 10 对）
-     *   3. 对每对调用 LLM 判断语义等价性（结构化 JSON 输出）
-     *   4. 等价则降级低分记忆（score → 0.1，不物理删除，保留可恢复性）
-     *   5. 返回去重报告
-     *
-     * 安全设计：
-     *   - 不物理删除——仅降级 score，用户可通过宿主 UI 手动恢复
-     *   - LLM 失败降级——返回已处理的报告，不阻塞调用方
-     *   - 异步执行——不阻塞主对话热路径（由宿主定时任务或用户手动触发）
-     *   - backgroundProvider 未注入时静默跳过（返回 skippedReason）
-     *
-     * @param signal 可选的 AbortSignal（取消正在进行的 LLM 判断）
-     * @returns 去重报告
+     * 语义去重：加载候选（上限 50）→ 名称相似度筛选对（上限 10）→ LLM 判断语义等价 → 等价则软删重复方。
+     * 安全设计：不物理删除仅软删（可恢复）；LLM 失败降级不阻塞；provider 未注入静默返回 skippedReason。
      */
     deduplicateMemories(signal?: AbortSignal): Promise<DedupReport>;
     /**
-     * 筛选名称高度相似的候选记忆对
-     *
-     * 判定规则（满足任一即视为名称相似）：
-     *   1. 归一化 Levenshtein 距离 ≤ 0.3（如 "用户偏好" vs "用户偏爱"）
-     *   2. 一个名称包含另一个（如 "用户偏好" vs "用户偏好设置"）
-     *
-     * 去重设计：
-     *   - 已配对的记忆不再参与后续配对（避免 A-B-C 三元组产生 A-B + A-C + B-C 三对）
-     *   - 候选对按相似度升序排列（越相似越优先），取前 10 对
-     *
-     * @param candidates 候选记忆列表（已按 score 降序）
-     * @returns 名称相似的记忆对列表（a.score ≥ b.score）
+     * 筛选名称高度相似的候选记忆对。判定：归一化 Levenshtein ≤0.3 或一方包含另一方。
+     * 已配对的记忆不再参与后续配对（避免三元组产生多对）；按相似度升序（越相似越优先）取前 10 对。
      */
     private findNameOverlapPairs;
-    /**
-     * 计算两个名称的归一化相似度（0-1，越小越相似）
-     *
-     * 综合两种规则取较小值：
-     *   1. 归一化 Levenshtein 距离 = distance / max(len_a, len_b)
-     *   2. 包含关系：若一个名称包含另一个，相似度 = 0（完全相似）
-     *
-     * @param nameA 名称 A
-     * @param nameB 名称 B
-     * @returns 相似度（0=完全相似，1=完全不同）
-     */
+    /** 名称归一化相似度（0-1，越小越相似）。规则：包含关系=0；否则 Levenshtein 距离 / max(len)。 */
     private static computeNameSimilarity;
     /**
-     * 调用 LLM 判断单对记忆的语义等价性
-     *
-     * 使用结构化 JSON 输出（isDuplicate + mergedContent + reason），
-     * 流式累积 + parseLlmJson + 异常封装委托给 llmJudgeHelper.judgeWithLlm。
-     *
-     * LLM 失败时抛出 MemoraError（由 deduplicateMemories 捕获并降级跳过此对）。
-     *
-     * @param pair 候选记忆对
-     * @param signal 可选的 AbortSignal
-     * @returns LLM 判断结果
+     * 调用 LLM 判断单对记忆语义等价：结构化 JSON 输出（isDuplicate+mergedContent+reason）。
+     * 流式累积/解析/异常封装委托 llmJudgeHelper.judgeWithLlm；失败抛 MemoraError 由调用方捕获跳过。
      */
     private judgeDuplicate;
-    /**
-     * 降级重复记忆（score → DEDUP_LOW_SCORE）
-     *
-     * 安全设计：
-     *   - 不物理删除，仅降低 score，保留可恢复性
-     *   - 合并内容由 keepMerged() 单独写回保留方 a（职责清晰：本方法只降级低分方）
-     *
-     * @param memory 待降级的记忆（低分方）
-     */
+    /** 软删重复记忆（不物理删除保留可恢复；合并内容由 keepMerged 单独写回 a）。重复方以 delete 进入回收站。 */
     private demoteMemory;
-    /**
-     * 将合并内容写回保留方（高分记忆 a）
-     *
-     * 保持 a 的 id/source/name/score/createdAt 不变，仅更新 content 为合并后内容并刷新
-     * accessedAt，使"两条重复记忆合并为一条更完整记忆"的语义真正落库（M6 修复）。
-     *
-     * @param memory 保留方记忆（高分方）
-     * @param mergedContent LLM 生成的合并后完整内容
-     */
+    /** 将合并内容写回保留方 a：保持 id/source/name/createdAt 不变，仅刷新 content + accessedAt */
     private keepMerged;
 }
 //# sourceMappingURL=dedupManager.d.ts.map

package/dist/agent/managers/dedupManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dedupManager.d.ts","sourceRoot":"","sources":["../../../src/agent/managers/dedupManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAEnE,OAAO,KAAK,EAAE,WAAW,EAAW,MAAM,mBAAmB,CAAC;AAgC9D,kCAAkC;AAClC,MAAM,WAAW,SAAS;IACxB,4BAA4B;IAC5B,CAAC,EAAE,MAAM,CAAC;IACV,4BAA4B;IAC5B,CAAC,EAAE,MAAM,CAAC;IACV,0BAA0B;IAC1B,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,yBAAyB;AACzB,MAAM,WAAW,YAAY;IAC3B,4BAA4B;IAC5B,WAAW,EAAE,OAAO,CAAC;IACrB,4CAA4C;IAC5C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wBAAwB;IACxB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wDAAwD;AACxD,MAAM,WAAW,mBAAmB;IAClC,qCAAqC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,sCAAsC;AACtC,MAAM,WAAW,WAAW;IAC1B,gBAAgB;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,0BAA0B;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mDAAmD;IACnD,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACjC,sCAAsC;IACtC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAID;;;;;;;GAOG;AACH,qBAAa,YAAY;IASrB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAEtB,4BAA4B;IAC5B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IAX/B,iDAAiD;IACjD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAqB;IAExD;;;OAGG;gBAEgB,KAAK,EAAE,cAAc,EACtC,kBAAkB,GAAE,WAAW,GAAG,IAAW;IAC7C,4BAA4B;IACX,WAAW,CAAC,GAAE,CAAC,MAAM,EAAE,WAAW,KAAK,IAAI,aAAA;IAK9D;;;;;;;;;;;;;;;;;;OAkBG;IACG,mBAAmB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAiFrE;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,oBAAoB;IAgC5B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,MAAM,CAAC,qBAAqB;IAqBpC;;;;;;;;;;;OAWG;YACW,cAAc;IAoB5B;;;;;;;;OAQG;IACH,OAAO,CAAC,YAAY;IAMpB;;;;;;;;OAQG;IACH,OAAO,CAAC,UAAU;CASnB"}
+{"version":3,"file":"dedupManager.d.ts","sourceRoot":"","sources":["../../../src/agent/managers/dedupManager.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,KAAK,EAAE,WAAW,EAAW,MAAM,mBAAmB,CAAC;AAyB9D,kCAAkC;AAClC,MAAM,WAAW,SAAS;IACxB,iBAAiB;IACjB,CAAC,EAAE,MAAM,CAAC;IACV,qBAAqB;IACrB,CAAC,EAAE,MAAM,CAAC;IACV,0BAA0B;IAC1B,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,yBAAyB;AACzB,MAAM,WAAW,YAAY;IAC3B,2BAA2B;IAC3B,WAAW,EAAE,OAAO,CAAC;IACrB,2CAA2C;IAC3C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,uCAAuC;AACvC,MAAM,WAAW,mBAAmB;IAClC,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,sCAAsC;AACtC,MAAM,WAAW,WAAW;IAC1B,gBAAgB;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,0BAA0B;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,yBAAyB;IACzB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,gCAAgC;IAChC,QAAQ,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACjC,2BAA2B;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAID,4EAA4E;AAC5E,qBAAa,YAAY;IAOrB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAEtB,2BAA2B;IAC3B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IAT/B,mCAAmC;IACnC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAqB;IACxD,qDAAqD;IACrD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;gBAGzB,KAAK,EAAE,cAAc,EACtC,kBAAkB,GAAE,WAAW,GAAG,IAAW;IAC7C,2BAA2B;IACV,WAAW,CAAC,GAAE,CAAC,MAAM,EAAE,WAAW,KAAK,IAAI,aAAA,EAC5D,OAAO,GAAE,SAAS,MAAM,EAAuB;IAMjD;;;OAGG;IACG,mBAAmB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAmFrE;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAgC5B,kEAAkE;IAClE,OAAO,CAAC,MAAM,CAAC,qBAAqB;IAkBpC;;;OAGG;YACW,cAAc;IAoB5B,oEAAoE;IACpE,OAAO,CAAC,YAAY;IAIpB,2EAA2E;IAC3E,OAAO,CAAC,UAAU;CASnB"}