@zooique/memora 1.0.1 → 2.0.0

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

@@ -0,0 +1,116 @@
+/**
+ * ChatLockManager — chat() 并发锁管理器
+ *
+ * 职责：
+ *   - 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 实例内）
+ */
+/**
+ * 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();
+ */
+export declare class ChatLockManager {
+    /** chat() 是否正在执行（并发锁） */
+    private _chatBusy;
+    /**
+     * chat() 锁持有者 token（race condition 防护）
+     *
+     * 获取锁时递增，超时回调和 finally 块据此判断是否仍是当前持有者。
+     * 不匹配时跳过清理，避免误清新调用者的资源。
+     */
+    private _chatLockToken;
+    /** 聊天锁超时计时器（防止 LLM 卡死时锁永久持有） */
+    private chatLockTimer;
+    /** chat() 内部 AbortController（超时时中断 generator，防止并发） */
+    private chatAbortController;
+    /** 当前是否持有锁 */
+    get isBusy(): boolean;
+    /**
+     * 获取锁，返回 token + 内部 AbortController
+     *
+     * @param timeoutMs 锁超时时间（LLM 卡死保护）
+     * @param onTimeout 超时回调（用于日志记录等）
+     * @returns token（用于 finally 校验）+ internalAbort（用于传递给 loop.processUserInput）
+     */
+    acquire(timeoutMs: number, onTimeout?: () => void): {
+        token: number;
+        internalAbort: AbortController;
+    };
+    /**
+     * 合并外部 signal：外部 abort 时触发内部 abort
+     *
+     * addEventListener 对已 aborted 的 signal 不触发回调，
+     * 需手动检查并触发 internalAbort，否则外部已取消的请求仍会进入主流程。
+     *
+     * @returns 清理函数（finally 块中调用 removeEventListener）
+     */
+    attachExternalSignal(externalSignal: AbortSignal | undefined, internalAbort: AbortController): () => void;
+    /**
+     * finally 块清理（token 校验后）
+     *
+     * 仅当本调用仍是当前锁持有者时才清理资源。
+     * 若 token 已变（超时释放后被新调用者获取），跳过清理避免误清新调用者的状态。
+     */
+    release(token: number): void;
+    /**
+     * 强制释放对话锁（宿主无进展超时兜底）
+     *
+     * 场景：宿主主进程"无进展超时"兜底后，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（多次调用安全）
+     */
+    forceRelease(): void;
+    /**
+     * 销毁管理器（Agent.close 时调用）
+     *
+     * 与 forceRelease() 的区别：不记录 warn 日志（close 是正常生命周期，非异常场景）。
+     * 递增 token 使任何进行中的 chat() generator 的 finally 块检测到 token 变化后
+     * 跳过资源清理（close 已接管清理职责）。
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=chatLockManager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chatLockManager.d.ts","sourceRoot":"","sources":["../../../src/agent/managers/chatLockManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,eAAe;IAC1B,yBAAyB;IACzB,OAAO,CAAC,SAAS,CAAS;IAC1B;;;;;OAKG;IACH,OAAO,CAAC,cAAc,CAAa;IACnC,gCAAgC;IAChC,OAAO,CAAC,aAAa,CAA8C;IACnE,sDAAsD;IACtD,OAAO,CAAC,mBAAmB,CAAgC;IAE3D,cAAc;IACd,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED;;;;;;OAMG;IACH,OAAO,CACL,SAAS,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,MAAM,IAAI,GACrB;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,eAAe,CAAA;KAAE;IA8BpD;;;;;;;OAOG;IACH,oBAAoB,CAClB,cAAc,EAAE,WAAW,GAAG,SAAS,EACvC,aAAa,EAAE,eAAe,GAC7B,MAAM,IAAI;IAYb;;;;;OAKG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAY5B;;;;;;;;;;;;;;;;;OAiBG;IACH,YAAY,IAAI,IAAI;IAkBpB;;;;;;OAMG;IACH,OAAO,IAAI,IAAI;CAchB"}

package/dist/agent/managers/chatLockManager.js

@@ -0,0 +1,191 @@
+/**
+ * ChatLockManager — chat() 并发锁管理器
+ *
+ * 职责：
+ *   - 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 实例内）
+ */
+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();
+ */
+export class ChatLockManager {
+    /** chat() 是否正在执行（并发锁） */
+    _chatBusy = false;
+    /**
+     * chat() 锁持有者 token（race condition 防护）
+     *
+     * 获取锁时递增，超时回调和 finally 块据此判断是否仍是当前持有者。
+     * 不匹配时跳过清理，避免误清新调用者的资源。
+     */
+    _chatLockToken = 0;
+    /** 聊天锁超时计时器（防止 LLM 卡死时锁永久持有） */
+    chatLockTimer = null;
+    /** chat() 内部 AbortController（超时时中断 generator，防止并发） */
+    chatAbortController = null;
+    /** 当前是否持有锁 */
+    get isBusy() {
+        return this._chatBusy;
+    }
+    /**
+     * 获取锁，返回 token + 内部 AbortController
+     *
+     * @param timeoutMs 锁超时时间（LLM 卡死保护）
+     * @param onTimeout 超时回调（用于日志记录等）
+     * @returns token（用于 finally 校验）+ internalAbort（用于传递给 loop.processUserInput）
+     */
+    acquire(timeoutMs, onTimeout) {
+        this._chatBusy = true;
+        // 分配本调用的 token，超时回调和 finally 块据此判断是否仍是当前持有者
+        // 避免 race condition：超时释放后新调用获取锁，旧 finally 误清新调用者的资源
+        const token = ++this._chatLockToken;
+        // 内部 AbortController，超时时中断 generator 而非仅释放锁
+        const internalAbort = new AbortController();
+        this.chatAbortController = internalAbort;
+        // 超时保护：LLM 卡死时中断 generator + 释放锁，防止并发
+        // 超时回调校验 token 后才清理，避免误清新调用者的资源
+        this.chatLockTimer = safeSetTimeout(() => {
+            // 令牌不匹配：锁已被新调用者获取（或本调用已正常退出），跳过清理
+            if (this._chatLockToken !== token) {
+                return;
+            }
+            logger.warn({ timeoutMs }, 'chat() 锁超时，中断 generator 并释放锁');
+            internalAbort.abort();
+            this._chatBusy = false;
+            this.chatLockTimer = null;
+            this.chatAbortController = null;
+            onTimeout?.();
+        }, timeoutMs);
+        return { token, internalAbort };
+    }
+    /**
+     * 合并外部 signal：外部 abort 时触发内部 abort
+     *
+     * addEventListener 对已 aborted 的 signal 不触发回调，
+     * 需手动检查并触发 internalAbort，否则外部已取消的请求仍会进入主流程。
+     *
+     * @returns 清理函数（finally 块中调用 removeEventListener）
+     */
+    attachExternalSignal(externalSignal, internalAbort) {
+        if (!externalSignal)
+            return () => { };
+        const onExternalAbort = () => internalAbort.abort();
+        externalSignal.addEventListener('abort', onExternalAbort, { once: true });
+        // addEventListener 对已 aborted 的 signal 不触发回调
+        // 需手动检查并触发 internalAbort，否则外部已取消的请求仍会进入主流程
+        if (externalSignal.aborted) {
+            internalAbort.abort();
+        }
+        return () => externalSignal.removeEventListener('abort', onExternalAbort);
+    }
+    /**
+     * finally 块清理（token 校验后）
+     *
+     * 仅当本调用仍是当前锁持有者时才清理资源。
+     * 若 token 已变（超时释放后被新调用者获取），跳过清理避免误清新调用者的状态。
+     */
+    release(token) {
+        if (this._chatLockToken !== token) {
+            return;
+        }
+        this._chatBusy = false;
+        this.chatAbortController = null;
+        if (this.chatLockTimer) {
+            clearSafeTimeout(this.chatLockTimer);
+            this.chatLockTimer = null;
+        }
+    }
+    /**
+     * 强制释放对话锁（宿主无进展超时兜底）
+     *
+     * 场景：宿主主进程"无进展超时"兜底后，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（多次调用安全）
+     */
+    forceRelease() {
+        if (!this._chatBusy)
+            return;
+        // 递增 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;
+        }
+        this._chatBusy = false;
+        logger.warn('对话锁被强制释放（宿主无进展超时兜底）');
+    }
+    /**
+     * 销毁管理器（Agent.close 时调用）
+     *
+     * 与 forceRelease() 的区别：不记录 warn 日志（close 是正常生命周期，非异常场景）。
+     * 递增 token 使任何进行中的 chat() generator 的 finally 块检测到 token 变化后
+     * 跳过资源清理（close 已接管清理职责）。
+     */
+    dispose() {
+        // 递增 token，使任何进行中的 chat() generator 的 finally 块
+        // 检测到 token 变化后跳过资源清理（close 已接管清理职责）
+        this._chatLockToken++;
+        if (this.chatAbortController) {
+            this.chatAbortController.abort();
+            this.chatAbortController = null;
+        }
+        if (this.chatLockTimer) {
+            clearSafeTimeout(this.chatLockTimer);
+            this.chatLockTimer = null;
+        }
+        this._chatBusy = false;
+    }
+}
+//# sourceMappingURL=chatLockManager.js.map

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

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

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

@@ -1,3 +1,17 @@
+/**
+ * Insight 提取器 — 输入分类 + 记忆提取
+ *
+ * 从 Agent 拆分出来，负责：
+ *   - 三层输入分类（通用规则 → 宿主关键词 → 默认提取）
+ *   - 异步 insight 提取（LLM 判断 + 去重 + 写入 SQLite）
+ *   - 宿主记忆关键词管理
+ *
+ * 关系构建逻辑（ADR-014）已拆分至 RelationBuilder，本类通过 relationBuilder 委托调用。
+ *
+ * 设计原则：
+ *   - 独立于 Agent 生命周期，仅依赖 Provider/Storage/Loop
+ *   - 提取失败不影响主对话流程（fire-and-forget）
+ */
 import type { LlmProvider } from '../../llm/provider.js';
 import type { Memory } from '../../memory/types.js';
 import type { IMemoryStorage } from '../../memory/storageInterface.js';
@@ -23,14 +37,14 @@ export declare class InsightExtractor {
     /** 写入扩展回调（宿主注入 diff 对比确认逻辑） */
     writeExtensions: WriteExtensions | null;
     /**
-     * 关系构建器（P1-3 拆分，ADR-014 关系构建委托给 RelationBuilder）
+     * 关系构建器（ADR-014 关系构建委托给 RelationBuilder）
      * 未注入时跳过所有关系构建（保持向后兼容）
      */
     private readonly relationBuilder;
     /**
      * @param provider - LLM Provider（用于 insight 提取）
      * @param index - 记忆存储（用于去重搜索 + 写入）
-     * @param relationBuilder - 关系构建器（可选，P1-3 拆分后替代直接 relationStore 注入）
+     * @param relationBuilder - 关系构建器（可选，替代直接 relationStore 注入）
      *   未注入时跳过关系构建（保持向后兼容，ADR-014 侧车模型）
      */
     constructor(provider: LlmProvider, index: IMemoryStorage, relationBuilder?: RelationBuilder | null);
@@ -44,7 +58,7 @@ export declare class InsightExtractor {
         content: string;
     }>): void;
     /**
-     * 绑定冲突检测回调（P1-3 拆分后委托给 RelationBuilder）
+     * 绑定冲突检测回调（委托给 RelationBuilder）
      *
      * 由 Agent.init() 在创建 InsightExtractor 后调用（与 bindGetRecentHistory 同模式），
      * 解决 Agent 实例晚于 InsightExtractor 创建的时序循环依赖。
@@ -95,6 +109,20 @@ export declare class InsightExtractor {
      * low → 0.2（快速衰减）
      */
     private scoreByQuality;
+    /**
+     * 利用 LLM 返回的 tags 生成语义化 name
+     *
+     * name 格式：`{清洗后的tag}-{uuid前6位}`（如 "偏好-a1b2c3"）
+     * - 取 tags 数组第一个非空 tag
+     * - 清洗 tag：保留中文/字母/数字，移除其他字符，取前 8 字符
+     * - UUID 前缀保证唯一性，tag 前缀提升 UI 可读性
+     * - 无 tags 或清洗后为空时，回退到 `insight-{uuid前8位}`
+     *
+     * @param tagsRaw - LLM 返回的 tags 字段（类型未知，需运行时校验）
+     * @param insightId - UUID，用于保证 name 唯一性
+     * @returns 语义化 name 字符串
+     */
+    private generateSemanticName;
     /**
      * Layer 1: 通用规则过滤
      *

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

@@ -1 +1 @@
-{"version":3,"file":"insightExtractor.d.ts","sourceRoot":"","sources":["../../../src/agent/managers/insightExtractor.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,WAAW,EAAW,MAAM,mBAAmB,CAAC;AAC9D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAGhD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAInE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE/D,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAC;AAiCzF;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,4CAA4C;IAC5C,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,yCAAyC;IACzC,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAID,qBAAa,gBAAgB;IAoBzB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK;IApBxB,iCAAiC;IACjC,OAAO,CAAC,YAAY,CAA+B;IAEnD,+BAA+B;IACxB,eAAe,EAAE,eAAe,GAAG,IAAI,CAAQ;IAEtD;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAyB;IAEzD;;;;;OAKG;gBAEgB,QAAQ,EAAE,WAAW,EACrB,KAAK,EAAE,cAAc,EACtC,eAAe,GAAE,eAAe,GAAG,IAAW;IAOhD,8DAA8D;IAC9D,OAAO,CAAC,iBAAiB,CAA6E;IAEtG;;OAEG;IACH,oBAAoB,CAClB,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,GAC7E,IAAI;IAIP;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI;IAM/D;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI;IAQ3C;;OAEG;IACH,kBAAkB,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI,GAAG,IAAI;IAOrD;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAe3C;;;;;;;OAOG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAuJ7E;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IAQzB;;;;;OAKG;IACH,OAAO,CAAC,cAAc;IAUtB;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAUvB;;;;OAIG;IACH,OAAO,CAAC,sBAAsB;CAU/B"}
+{"version":3,"file":"insightExtractor.d.ts","sourceRoot":"","sources":["../../../src/agent/managers/insightExtractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,WAAW,EAAW,MAAM,mBAAmB,CAAC;AAC9D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAGhD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAInE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAG/D,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAC;AAiCzF;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,4CAA4C;IAC5C,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,yCAAyC;IACzC,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAsFD,qBAAa,gBAAgB;IAoBzB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK;IApBxB,iCAAiC;IACjC,OAAO,CAAC,YAAY,CAA+B;IAEnD,+BAA+B;IACxB,eAAe,EAAE,eAAe,GAAG,IAAI,CAAQ;IAEtD;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAyB;IAEzD;;;;;OAKG;gBAEgB,QAAQ,EAAE,WAAW,EACrB,KAAK,EAAE,cAAc,EACtC,eAAe,GAAE,eAAe,GAAG,IAAW;IAOhD,8DAA8D;IAC9D,OAAO,CAAC,iBAAiB,CAA6E;IAEtG;;OAEG;IACH,oBAAoB,CAClB,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,GAC7E,IAAI;IAIP;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI;IAM/D;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI;IAQ3C;;OAEG;IACH,kBAAkB,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI,GAAG,IAAI;IAOrD;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAe3C;;;;;;;OAOG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IA6I7E;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IAQzB;;;;;OAKG;IACH,OAAO,CAAC,cAAc;IAQtB;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,oBAAoB;IAuB5B;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAUvB;;;;OAIG;IACH,OAAO,CAAC,sBAAsB;CAU/B"}