@zooique/memora 2.0.0 → 3.0.0

package/dist/utils/errors.js

@@ -1,53 +1,44 @@
 /**
- * 统一错误类型
+ * 统一错误类型——把"系统 Error + 英文 stack"包装成"分类清晰 + 中文友好 + 有下一步建议"。
+ * 展示：标题（一眼看出问题）+ 详情（排查用）+ 建议（怎么修复）。
  *
- * 把"系统 Error + 英文 stack trace"包装成"分类清晰 + 中文友好 + 有下一步建议"的错误
- * 详见 ADR-006 · 安全模型
+ * **形态**：错误类只有 `MemoraError` 一个（承载 title/detail/suggestions/category）；
+ * 分类不靠子类，靠 `category` 字段 —— 工厂函数按分类建实例：
+ * `configError` / `networkError` / `llmError` / `toolError` / `securityError`，
+ * 另有统一文案模板 `chatBusyError`（对话繁忙，内部走 configError）。
+ * ⚠️ 旧注释曾写「4 大类 ConfigError/NetworkError/…」——**本文件不存在这些 PascalCase 类名**
+ * （既非类也非工厂名），且实为 **6 个 category 值**：`security` 由 securityError 产出、
+ * 被 security/pathGuard 生产消费 4 处；`unknown` 为兜底值（当前无工厂产出，供直接构造保留）。
+ * 勿按旧注释去改分类集合。
  *
- * 4 大类：
- *   - ConfigError      配置错误（apiKey 缺失、provider 不支持等）
- *   - NetworkError     网络错误（连接超时、DNS 失败、限流等）
- *   - LlmError         LLM 错误（4xx/5xx、返回异常 JSON）
- *   - ToolError        工具错误（路径越界、参数无效等）
- *
- * 错误展示原则：
- *   1. 标题（中文）—— 一眼看出什么问题
- *   2. 详情（原文）—— 排查用
- *   3. 建议（下一步）—— 怎么修复
+ * ⚠️ 与宿主 `LlmErrorCategory`（'connection'|'timeout'|'unknown'）**不是同一个联合**：
+ * 后者是**流式 error chunk** 的分类（见 hosts shared/protocol.ts），本文件只管 MemoraError。
  */
-// re-export toError 供混合 import 场景使用（如 import { securityError, toError }）
-// 单独需要零 logger 依赖的 toError 时应直接 import from '../utils/toError.js'（浏览器友好）。
-export { toError } from '../utils/toError.js';
 /**
- * 工具错误码 — 用于 AgentLoop 的 Reflection（反思/自修正）逻辑
- *
- * 每个错误码关联一个 retryable 标记：
- *   - retryable：LLM 可以调整参数后重试（如文件路径错误、参数类型错误）
- *   - non-retryable：重试无意义（如权限拒绝、用户拒绝写入）
+ * 工具错误码——供 AgentLoop 的 Reflection（自修正）判断是否可重试：
+ * retryable 表示 LLM 调整参数后可重试；non-retryable 重试无意义。
  */
 export const ToolErrorCode = {
     /** 路径不在白名单内（不可重试） */
     PATH_NOT_ALLOWED: 'PATH_NOT_ALLOWED',
-    /** 文件不存在（可重试 — LLM 可能用错了路径） */
+    /** 文件不存在（可重试） */
     FILE_NOT_FOUND: 'FILE_NOT_FOUND',
     /** 权限不足（不可重试） */
     PERMISSION_DENIED: 'PERMISSION_DENIED',
-    /** 工具参数错误（可重试 — LLM 可以修正参数格式） */
+    /** 参数错误（可重试） */
     ARGUMENT_ERROR: 'ARGUMENT_ERROR',
     /** 用户拒绝写入（不可重试） */
     WRITE_REJECTED: 'WRITE_REJECTED',
-    /** 目录不存在（可重试 — LLM 可能用错了路径） */
+    /** 目录不存在（可重试） */
     DIR_NOT_FOUND: 'DIR_NOT_FOUND',
-    /** 未知工具（不可重试 — 工具未注册） */
+    /** 未知工具（不可重试） */
     UNKNOWN_TOOL: 'UNKNOWN_TOOL',
     /** 自定义工具执行失败（可重试） */
     CUSTOM_TOOL_FAILED: 'CUSTOM_TOOL_FAILED',
     /** 通用错误（不可重试） */
     UNKNOWN: 'UNKNOWN',
 };
-/**
- * 判断错误码是否可重试
- */
+/** 可重试错误码集合 */
 const RETRYABLE_ERROR_CODES = new Set([
     ToolErrorCode.FILE_NOT_FOUND,
     ToolErrorCode.ARGUMENT_ERROR,
@@ -62,7 +53,6 @@ export class MemoraError extends Error {
     detail;
     suggestions;
     category;
-    /** 工具错误码（用于 AgentLoop 反思判断是否可重试） */
     errorCode;
     cause;
     constructor(opts) {
@@ -75,9 +65,7 @@ export class MemoraError extends Error {
         this.errorCode = opts.errorCode;
         this.cause = opts.cause;
     }
-    /**
-     * 格式化为用户可读的展示字符串
-     */
+    /** 格式化为用户可读的展示字符串 */
     format() {
         const lines = [];
         lines.push(`❌ ${this.title}`);
@@ -92,47 +80,61 @@ export class MemoraError extends Error {
         return lines.join('\n');
     }
 }
-/**
- * 工厂：配置错误
- */
+/** 工厂：配置错误 */
 export function configError(title, detail, suggestions, cause) {
     return new MemoraError({ title, detail, suggestions, category: 'config', cause });
 }
-/**
- * 工厂：对话繁忙错误
- *
- * 用于 chat() 进行中时拒绝其他需要独占 Agent 的操作（切换项目/Provider/会话/重载配置等）。
- * 12 处调用点统一使用此工厂，消除 `configError('对话繁忙', ...)` 的重复模板（ADR-017 枝叶层 2 次提取）。
- *
- * @param action 被拒绝的操作描述（如"切换项目"），拼接到"请等待其结束后再"之后
- * @returns MemoraError（config 类别）
- */
+/** 工厂：对话繁忙错误——chat() 进行中拒绝其他需独占 Agent 的操作，统一模板用此工厂 */
 export function chatBusyError(action) {
-    return configError('对话繁忙', `上一轮对话尚未完成，请等待其结束后再${action}`, ['等待上一轮 chat() 的 AsyncGenerator 耗尽（收到 done 事件）']);
+    return configError('对话繁忙', `上一轮对话尚未完成，请等待其结束后再${action}`, [
+        '等待当前对话完成后重试',
+    ]);
 }
-/**
- * 工厂：网络错误
- */
+/** 工厂：网络错误 */
 export function networkError(title, detail, suggestions, cause) {
     return new MemoraError({ title, detail, suggestions, category: 'network', cause });
 }
-/**
- * 工厂：LLM 错误
- */
+/** 工厂：LLM 错误 */
 export function llmError(title, detail, suggestions, cause) {
     return new MemoraError({ title, detail, suggestions, category: 'llm', cause });
 }
-/**
- * 工厂：工具错误
- */
+/** 工厂：工具错误 */
 export function toolError(title, detail, suggestions, cause, errorCode) {
     return new MemoraError({ title, detail, suggestions, category: 'tool', cause, errorCode });
 }
-/**
- * 工厂：安全错误（路径越界、黑名单命中、权限不足等）
- */
+/** 工厂：安全错误（路径越界、黑名单命中、权限不足等） */
 export function securityError(title, detail, suggestions, cause) {
     return new MemoraError({ title, detail, suggestions, category: 'security', cause });
 }
-// toError 实现位于 ./toError.ts（纯逻辑，零依赖），此处 re-export 保持向后兼容
+/** 判断是否为 AbortError（用户主动取消或超时中断）——统一基于 err.name === 'AbortError'，
+ *  兼容原生 DOMException / 普通 Error 子类 / toError() 规范化后对象。 */
+export function isAbortError(err) {
+    return err instanceof Error && err.name === 'AbortError';
+}
+/** 判断 AbortSignal 是否为「超时中断」（chat 锁超时 / LLM 无响应超时统一以 TimeoutError reason 标识）。
+ *  与用户取消（abort() 无 reason / AbortError reason）区分——锁超时中断不能谎报成用户取消。 */
+export function isTimeoutAbortSignal(signal) {
+    return (signal?.aborted === true &&
+        signal.reason instanceof DOMException &&
+        signal.reason.name === 'TimeoutError');
+}
+/**
+ * 判断**抛出的错误**是否为「超时」（非 abort 路径的载体）。
+ *
+ * 与 `isTimeoutAbortSignal` 是**同一语义的两种载体**（同判 `name === 'TimeoutError'`）：
+ * 前者看 `signal.reason`（signal 被 abort 的路径），本函数看**被抛出的错误对象**——
+ * 典型场景 = `openaiCompatible.parseSseStream` 的 SSE 停摆看门狗（`Promise.race` 竞速闸
+ * reject `DOMException('…','TimeoutError')`），它不经过 abort signal，故被归类为「失败」
+ * 而非「中断」，最终由 `consumeExecutionStream` 的通用 catch 收口。
+ *
+ * **用途（否则宿主文案不可达）**：把超时归入 `error.category = 'timeout'`，让宿主
+ * `chatPanel` 的 `friendlyByCategory.timeout`（「对话处理超时，请稍后重试」）真正生效；
+ * 缺该分类时宿主只能回退**原始技术文案**（DOMException message），用户读到的是侦探材料。
+ *
+ * 注：`toError()` 对 Error 实例原样返回（实测 `DOMException instanceof Error === true`），
+ * 故经 `llmCaller` 的 `toError(err)` 再 rethrow 后 `name` 不丢，本判据在链路末端依然成立。
+ */
+export function isTimeoutError(err) {
+    return err instanceof Error && err.name === 'TimeoutError';
+}
 //# sourceMappingURL=errors.js.map

package/dist/utils/errors.js.map

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

package/dist/utils/eventEmitter.d.ts

@@ -1,101 +1,179 @@
-/** Agent 事件映射表（事件名 → 事件载荷类型） */
-export interface AgentEventMap {
-    /** 记忆被写入存储（insight 提取、rule 注入、skill 注入等） */
+import type { AskQuestion } from '../agent/types.js';
+/** Agent 事件名常量（运行时真理源，与 AgentEventMap 键集一致） */
+export declare const AGENT_EVENTS: {
+    readonly memoryAdded: "memoryAdded";
+    readonly rolePackSwitched: "rolePackSwitched";
+    readonly memoryRecalled: "memoryRecalled";
+    readonly sessionForked: "sessionForked";
+    readonly projectSwitched: "projectSwitched";
+    readonly archiveFailed: "archiveFailed";
+    readonly contextTruncated: "contextTruncated";
+    /** LLM 主动压缩完成（第二级压缩，与 contextTruncated 的内核自动截断区分） */
+    readonly contextCompressed: "contextCompressed";
+    readonly configReloaded: "configReloaded";
+    readonly archiveModeChanged: "archiveModeChanged";
+    readonly rolePackSwitchLocked: "rolePackSwitchLocked";
+    readonly workProjectionGenerated: "workProjectionGenerated";
+    readonly dedupCompleted: "dedupCompleted";
+    readonly sessionPauseTimedOut: "sessionPauseTimedOut";
+    readonly sessionResumeBlocked: "sessionResumeBlocked";
+    /** 订阅时宿主据此判断重要事件并 toast 提示 */
+    readonly sessionResumeFailed: "sessionResumeFailed";
+    /** 装配前判负（洞 3）：触发输入过大，剩余预算无法支撑至少一轮正文——与软上限不同失败原因 */
+    readonly inputTooLarge: "inputTooLarge";
+    /** 回答中 LLM 调 ask_user 工具主动提问（唯一「提问后暂停」通道） */
+    readonly questionPending: "questionPending";
+    readonly goalDriftDetected: "goalDriftDetected";
+    readonly sessionPaused: "sessionPaused";
+    readonly sessionResumed: "sessionResumed";
+    readonly sessionError: "sessionError";
+    readonly sessionRecovered: "sessionRecovered";
+    /** 会话标题被 LLM 自动更新（SessionNamer 完成后触发，宿主据此刷新 UI） */
+    readonly sessionTitleUpdated: "sessionTitleUpdated";
+    /**
+     * 轮次摘要生成完成（round-summary fire-and-forget 后台任务收口信号）。
+     * 宿主据此解锁「问答闭环完整结束」的 UI 状态（删除/分叉按钮解禁）——
+     * 避免 done 后立即删除导致孤儿 round-summary（摘要还在生成就删了源）。
+     * 一次 chat() 只触发一次，载荷带 roundId 溯源。
+     */
+    readonly roundSummaryGenerated: "roundSummaryGenerated";
+};
+/** 事件名联合类型（由 AGENT_EVENTS 推导，新增事件只需在此加一项） */
+export type AgentEventName = keyof typeof AGENT_EVENTS;
+/** 运行时校验用集合（由 AGENT_EVENTS 派生） */
+export declare const AGENT_EVENT_SET: ReadonlySet<string>;
+/** 事件名 → 载荷类型映射（键集受 AgentEventName 约束） */
+export interface AgentEventMap extends Record<AgentEventName, unknown> {
     memoryAdded: {
         id: string;
         source: string;
         name: string;
     };
-    /** 角色被切换（自动匹配或手动指定） */
-    personaSwitched: {
+    rolePackSwitched: {
         from: string | null;
         to: string;
     };
-    /** 记忆衰减完成 */
-    decayCompleted: {
-        decayedCount: number;
-    };
-    /** 记忆被召回（用于宿主 UI 展示"想起 X 条记忆"） */
     memoryRecalled: {
         count: number;
         query: string;
     };
-    /** 会话被分叉 */
     sessionForked: {
         from: string;
         to: string;
-        messageCount: number;
-    };
-    /** 洞察被提取 */
-    insightExtracted: {
-        source: string;
-        insight: string;
+        roundCount: number;
     };
-    /** 记忆冲突被检测到（contradicts 关系写入时触发，宿主可通知用户） */
-    conflictDetected: {
-        newMemoryId: string;
-        newInsight: string;
-        targetId: string;
-        targetContent: string;
-    };
-    /** 项目被切换（宿主 UI 可据此刷新项目相关界面） */
     projectSwitched: {
         from: string | null;
         to: string;
         projectName: string;
     };
-    /** 技能被匹配（宿主 UI 可据此展示当前激活技能） */
-    skillMatched: {
-        skill: string;
-        score: number;
-    };
-    /** 归档操作失败（fire-and-forget catch 分支发射，宿主可通知用户） */
     archiveFailed: {
-        /** 失败阶段：profile（用户画像）/ insight（洞察提取） */
-        stage: 'profile' | 'insight';
-        /** 失败原因摘要（error.message，截断 200 字符避免 payload 过大） */
+        stage: 'session';
         message: string;
     };
+    contextTruncated: {
+        skippedCount: number;
+        keptCount: number;
+    };
+    /** LLM 主动压缩完成载荷：压缩目标 + 被替换消息数 + 摘要长度 */
+    contextCompressed: {
+        target: 'earliest_round' | 'largest_tool_result';
+        replacedCount: number;
+        summaryLength: number;
+    };
+    configReloaded: {
+        source: string;
+    };
+    archiveModeChanged: {
+        from: string;
+        to: string;
+    };
+    rolePackSwitchLocked: {
+        reason: string;
+        lockedSeconds: number;
+    };
+    workProjectionGenerated: {
+        sourcePath: string;
+        summary: string;
+    };
+    dedupCompleted: {
+        deduplicatedCount: number;
+        demotedIds: string[];
+    };
+    sessionPauseTimedOut: {
+        sessionId: string;
+        pauseDuration: number;
+        date?: string;
+        session?: string;
+    };
+    sessionResumeBlocked: {
+        sessionId: string;
+        reason: string;
+    };
+    sessionResumeFailed: {
+        sessionId?: string;
+        reason: string;
+    };
+    /** 装配前判负载荷：剩余预算详情 + 给宿主的降级提示（建议放文件用 read_file 读） */
+    inputTooLarge: {
+        inputLength: number;
+        remainingTokens: number;
+        hint: string;
+    };
+    questionPending: AskQuestion[];
+    goalDriftDetected: {
+        sessionId: string;
+        mainGoal: string;
+        newGoal: string;
+        similarity: number;
+        level: 'same' | 'confirm' | 'drift';
+        constraints: string[];
+        /** 原名 goalVersion，仅载荷不承担校验 */
+        goalChangeSeq: number;
+    };
+    sessionPaused: {
+        reason: string;
+        source: string;
+        sessionId?: string;
+    };
+    sessionResumed: {
+        sessionId?: string;
+    };
+    sessionError: {
+        cause: string;
+        sessionId?: string;
+    };
+    sessionRecovered: {
+        sessionId?: string;
+    };
+    /** 会话标题更新载荷：会话 ID + 新标题 */
+    sessionTitleUpdated: {
+        sessionId: string;
+        title: string;
+    };
+    /** 轮次摘要生成完成载荷：本轮 roundId（溯源）+ 成功/失败（失败时宿主仍需兜底解锁） */
+    roundSummaryGenerated: {
+        roundId: string;
+        success: boolean;
+    };
 }
-/** 事件名联合类型 */
-export type AgentEventName = keyof AgentEventMap;
 /** 事件处理器类型 */
 export type AgentEventHandler<T> = (event: T) => void;
 /**
- * 类型安全的事件发射器
- *
- * 泛型参数 EventMap 约束了合法的事件名和对应的载荷类型，
- * 调用方在编译期就能获得类型检查和自动补全。
+ * 类型安全事件发射器——泛型 EventMap 约束合法事件名与载荷类型，
+ * 调用方在编译期获得类型检查和自动补全。
  */
 export declare class TypedEventEmitter<EventMap extends object> {
     private readonly listeners;
-    /**
-     * 订阅事件
-     * @param event - 事件名
-     * @param handler - 事件处理器
-     */
+    /** 订阅事件（同一 handler 引用加入 Set，天然避免重复监听） */
     on<K extends keyof EventMap & string>(event: K, handler: (event: EventMap[K]) => void): void;
-    /**
-     * 取消订阅
-     * @param event - 事件名
-     * @param handler - 要移除的处理器（必须是同一个引用）
-     */
+    /** 取消订阅（必须是与 on 相同的引用） */
     off<K extends keyof EventMap & string>(event: K, handler: (event: EventMap[K]) => void): void;
-    /**
-     * 订阅事件（仅触发一次，触发后自动移除）
-     * @param event - 事件名
-     * @param handler - 事件处理器
-     */
+    /** 一次性订阅：触发后自动移除，再转发给 handler（防泄漏） */
     once<K extends keyof EventMap & string>(event: K, handler: (event: EventMap[K]) => void): void;
-    /**
-     * 发射事件
-     * @param event - 事件名
-     * @param payload - 事件载荷
-     */
+    /** 发射事件；单处理器异常不阻断其余监听器 */
     protected emit<K extends keyof EventMap & string>(event: K, payload: EventMap[K]): void;
-    /**
-     * 移除所有监听器（用于 close() 清理）
-     */
+    /** 移除所有监听器（用于 close() 清理） */
     protected removeAllListeners(): void;
 }
 //# sourceMappingURL=eventEmitter.d.ts.map

package/dist/utils/eventEmitter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"eventEmitter.d.ts","sourceRoot":"","sources":["../../src/utils/eventEmitter.ts"],"names":[],"mappings":"AAaA,gCAAgC;AAChC,MAAM,WAAW,aAAa;IAC5B,4CAA4C;IAC5C,WAAW,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1D,uBAAuB;IACvB,eAAe,EAAE;QAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IACrD,aAAa;IACb,cAAc,EAAE;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;IACzC,kCAAkC;IAClC,cAAc,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACjD,YAAY;IACZ,aAAa,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;IAClE,YAAY;IACZ,gBAAgB,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACtD,4CAA4C;IAC5C,gBAAgB,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;IACvG,+BAA+B;IAC/B,eAAe,EAAE;QAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1E,+BAA+B;IAC/B,YAAY,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C,iDAAiD;IACjD,aAAa,EAAE;QACb,wCAAwC;QACxC,KAAK,EAAE,SAAS,GAAG,SAAS,CAAC;QAC7B,mDAAmD;QACnD,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAED,cAAc;AACd,MAAM,MAAM,cAAc,GAAG,MAAM,aAAa,CAAC;AAEjD,cAAc;AACd,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;AAEtD;;;;;GAKG;AACH,qBAAa,iBAAiB,CAAC,QAAQ,SAAS,MAAM;IACpD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoD;IAE9E;;;;OAIG;IACH,EAAE,CAAC,CAAC,SAAS,MAAM,QAAQ,GAAG,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,IAAI;IAS5F;;;;OAIG;IACH,GAAG,CAAC,CAAC,SAAS,MAAM,QAAQ,GAAG,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,IAAI;IAI7F;;;;OAIG;IACH,IAAI,CAAC,CAAC,SAAS,MAAM,QAAQ,GAAG,MAAM,EACpC,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,IAAI,GACpC,IAAI;IAQP;;;;OAIG;IACH,SAAS,CAAC,IAAI,CAAC,CAAC,SAAS,MAAM,QAAQ,GAAG,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI;IAYvF;;OAEG;IACH,SAAS,CAAC,kBAAkB,IAAI,IAAI;CAGrC"}
+{"version":3,"file":"eventEmitter.d.ts","sourceRoot":"","sources":["../../src/utils/eventEmitter.ts"],"names":[],"mappings":"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"}

package/dist/utils/eventEmitter.js

@@ -1,28 +1,57 @@
 /**
- * 轻量类型事件发射器 — 零外部依赖
- *
- * 供 Agent 向宿主项目广播对话外事件（记忆变更、角色切换、衰减完成等）。
- * 不依赖 Node.js EventEmitter，保持"零 native 依赖内核"约束。
- *
- * 使用方式：
- *   agent.on('memoryAdded', (e) => console.log(e.source, e.name));
- *   agent.off('memoryAdded', handler);
+ * 轻量类型事件发射器（零 native 依赖）——Agent 向宿主广播外层事件：
+ * agent.on('memoryAdded', (e) => ...)；off 解绑。
  */
 import { getLogger } from '../utils/loggerHolder.js';
 import { toError } from '../utils/toError.js';
+/** Agent 事件名常量（运行时真理源，与 AgentEventMap 键集一致） */
+export const AGENT_EVENTS = {
+    memoryAdded: 'memoryAdded',
+    rolePackSwitched: 'rolePackSwitched',
+    memoryRecalled: 'memoryRecalled',
+    sessionForked: 'sessionForked',
+    projectSwitched: 'projectSwitched',
+    archiveFailed: 'archiveFailed',
+    contextTruncated: 'contextTruncated',
+    /** LLM 主动压缩完成（第二级压缩，与 contextTruncated 的内核自动截断区分） */
+    contextCompressed: 'contextCompressed',
+    configReloaded: 'configReloaded',
+    archiveModeChanged: 'archiveModeChanged',
+    rolePackSwitchLocked: 'rolePackSwitchLocked',
+    workProjectionGenerated: 'workProjectionGenerated',
+    dedupCompleted: 'dedupCompleted',
+    sessionPauseTimedOut: 'sessionPauseTimedOut',
+    sessionResumeBlocked: 'sessionResumeBlocked',
+    /** 订阅时宿主据此判断重要事件并 toast 提示 */
+    sessionResumeFailed: 'sessionResumeFailed',
+    /** 装配前判负（洞 3）：触发输入过大，剩余预算无法支撑至少一轮正文——与软上限不同失败原因 */
+    inputTooLarge: 'inputTooLarge',
+    /** 回答中 LLM 调 ask_user 工具主动提问（唯一「提问后暂停」通道） */
+    questionPending: 'questionPending',
+    goalDriftDetected: 'goalDriftDetected',
+    sessionPaused: 'sessionPaused',
+    sessionResumed: 'sessionResumed',
+    sessionError: 'sessionError',
+    sessionRecovered: 'sessionRecovered',
+    /** 会话标题被 LLM 自动更新（SessionNamer 完成后触发，宿主据此刷新 UI） */
+    sessionTitleUpdated: 'sessionTitleUpdated',
+    /**
+     * 轮次摘要生成完成（round-summary fire-and-forget 后台任务收口信号）。
+     * 宿主据此解锁「问答闭环完整结束」的 UI 状态（删除/分叉按钮解禁）——
+     * 避免 done 后立即删除导致孤儿 round-summary（摘要还在生成就删了源）。
+     * 一次 chat() 只触发一次，载荷带 roundId 溯源。
+     */
+    roundSummaryGenerated: 'roundSummaryGenerated',
+};
+/** 运行时校验用集合（由 AGENT_EVENTS 派生） */
+export const AGENT_EVENT_SET = new Set(Object.values(AGENT_EVENTS));
 /**
- * 类型安全的事件发射器
- *
- * 泛型参数 EventMap 约束了合法的事件名和对应的载荷类型，
- * 调用方在编译期就能获得类型检查和自动补全。
+ * 类型安全事件发射器——泛型 EventMap 约束合法事件名与载荷类型，
+ * 调用方在编译期获得类型检查和自动补全。
  */
 export class TypedEventEmitter {
     listeners = new Map();
-    /**
-     * 订阅事件
-     * @param event - 事件名
-     * @param handler - 事件处理器
-     */
+    /** 订阅事件（同一 handler 引用加入 Set，天然避免重复监听） */
     on(event, handler) {
         let set = this.listeners.get(event);
         if (!set) {
@@ -31,19 +60,11 @@ export class TypedEventEmitter {
         }
         set.add(handler);
     }
-    /**
-     * 取消订阅
-     * @param event - 事件名
-     * @param handler - 要移除的处理器（必须是同一个引用）
-     */
+    /** 取消订阅（必须是与 on 相同的引用） */
     off(event, handler) {
         this.listeners.get(event)?.delete(handler);
     }
-    /**
-     * 订阅事件（仅触发一次，触发后自动移除）
-     * @param event - 事件名
-     * @param handler - 事件处理器
-     */
+    /** 一次性订阅：触发后自动移除，再转发给 handler（防泄漏） */
     once(event, handler) {
         const wrapper = ((data) => {
             this.off(event, wrapper);
@@ -51,11 +72,7 @@ export class TypedEventEmitter {
         });
         this.on(event, wrapper);
     }
-    /**
-     * 发射事件
-     * @param event - 事件名
-     * @param payload - 事件载荷
-     */
+    /** 发射事件；单处理器异常不阻断其余监听器 */
     emit(event, payload) {
         const set = this.listeners.get(event);
         if (!set || set.size === 0)
@@ -69,9 +86,7 @@ export class TypedEventEmitter {
             }
         }
     }
-    /**
-     * 移除所有监听器（用于 close() 清理）
-     */
+    /** 移除所有监听器（用于 close() 清理） */
     removeAllListeners() {
         this.listeners.clear();
     }

package/dist/utils/eventEmitter.js.map

@@ -1 +1 @@
-{"version":3,"file":"eventEmitter.js","sourceRoot":"","sources":["../../src/utils/eventEmitter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAqC7C;;;;;GAKG;AACH,MAAM,OAAO,iBAAiB;IACX,SAAS,GAAG,IAAI,GAAG,EAAyC,CAAC;IAE9E;;;;OAIG;IACH,EAAE,CAAoC,KAAQ,EAAE,OAAqC;QACnF,IAAI,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACpC,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;YAChB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QACjC,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,OAAmC,CAAC,CAAC;IAC/C,CAAC;IAED;;;;OAIG;IACH,GAAG,CAAoC,KAAQ,EAAE,OAAqC;QACpF,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,OAAmC,CAAC,CAAC;IACzE,CAAC;IAED;;;;OAIG;IACH,IAAI,CACF,KAAQ,EACR,OAAqC;QAErC,MAAM,OAAO,GAAG,CAAC,CAAC,IAAiB,EAAE,EAAE;YACrC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,OAAuC,CAAC,CAAC;YACzD,OAAO,CAAC,IAAI,CAAC,CAAC;QAChB,CAAC,CAAiC,CAAC;QACnC,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAC1B,CAAC;IAED;;;;OAIG;IACO,IAAI,CAAoC,KAAQ,EAAE,OAAoB;QAC9E,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACtC,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,KAAK,CAAC;YAAE,OAAO;QACnC,KAAK,MAAM,OAAO,IAAI,GAAG,EAAE,CAAC;YAC1B,IAAI,CAAC;gBACH,OAAO,CAAC,OAAO,CAAC,CAAC;YACnB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,SAAS,EAAE,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,WAAW,CAAC,CAAC;YACtE,CAAC;QACH,CAAC;IACH,CAAC;IAED;;OAEG;IACO,kBAAkB;QAC1B,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;IACzB,CAAC;CACF"}
+{"version":3,"file":"eventEmitter.js","sourceRoot":"","sources":["../../src/utils/eventEmitter.ts"],"names":[],"mappings":"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"}

package/dist/utils/fileSafe.d.ts

@@ -0,0 +1,20 @@
+import { type Stats } from 'node:fs';
+/**
+ * 内容文件读取长度上限（字符）——防超大文件撑爆上下文
+ *
+ * SSOT 说明：角色包侧原以 `MAX_CONTENT_FILE_LEN` 使用本值；提升为共享原语后，
+ * 全局技能读取 L3 资源与 validateFile 也获得同等级保护。
+ */
+export declare const DEFAULT_MAX_CONTENT_LEN = 200000;
+/**
+ * 读取文本文件内容，超限截断；失败返回 null（不告警，由调用方决定语义）。
+ *
+ * @param filePath 文件绝对路径
+ * @param maxLen 最大长度（字符），超限截断
+ */
+export declare function readFileCapped(filePath: string, maxLen?: number): Promise<string | null>;
+/** 安全的 stat 同步调用：不可访问返回 null，不抛异常（返回完整 `Stats`，调用方按需取字段） */
+export declare function statSyncSafe(path: string): Stats | null;
+/** 安全的存在性同步调用：不可访问按不存在处理，不抛异常（实现即 `existsSync`，名字与之一致） */
+export declare function existsSyncSafe(path: string): boolean;
+//# sourceMappingURL=fileSafe.d.ts.map

package/dist/utils/fileSafe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileSafe.d.ts","sourceRoot":"","sources":["../../src/utils/fileSafe.ts"],"names":[],"mappings":"AAcA,OAAO,EAAwB,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAE3D;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,SAAU,CAAC;AAE/C;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,EAChB,MAAM,GAAE,MAAgC,GACvC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAOxB;AAED,4DAA4D;AAC5D,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI,CAMvD;AAED,0DAA0D;AAC1D,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAMpD"}