@zooique/memora 2.0.3 → 3.0.1

package/dist/agent/agent.d.ts

@@ -1,54 +1,31 @@
 import type { AgentLoop } from '../agent/loop.js';
-import type { AgentChunk, ArchiveMode, AgentOptions, AgentContext } from '../agent/types.js';
+import type { AgentChunk, ArchiveMode, AgentOptions, AgentContext, ToolExecutionRecord, SessionCheckpoint } from '../agent/types.js';
+import type { InteractiveInputKind } from '../memory/roundStore.js';
 import type { ToolExecutor } from '../agent/toolExecutor.js';
 import type { MessageHistory } from '../agent/messageHistory.js';
 import { ProjectManager, type ProjectContext } from '../memory/projectManager.js';
 import { SecurityGuard } from '../security/pathGuard.js';
-import type { PersonaManager } from '../persona/personaManager.js';
-import type { UserProfile, UserProfileEntry } from '../memory/userProfile.js';
 import type { SkillManager } from '../skill/skillManager.js';
-import type { InsightExtractor } from '../agent/managers/insightExtractor.js';
+import type { RolePackManager } from '../role-pack/rolePackManager.js';
+import type { BehaviorStrategy } from '../role-pack/types.js';
 import type { SessionArchiveResult } from '../agent/managers/sessionArchiver.js';
 import type { TextPolishManager } from '../agent/managers/textPolishManager.js';
-import type { ConfigManager } from '../agent/managers/configManager.js';
 import type { WorkProjectionManager } from '../agent/managers/workProjection.js';
 import type { MemoryInspector } from '../agent/managers/memoryInspector.js';
-import { SessionManager, type AgentForkResult } from '../agent/managers/sessionManager.js';
+import { type GCResult } from '../memory/gcService.js';
+import type { SessionManager, AgentForkResult } from '../agent/managers/sessionManager.js';
 import { MemoryGovernance } from '../agent/managers/memoryGovernance.js';
 import { type ArchiveTriggerOptions } from '../agent/managers/archiveCoordinator.js';
 import { TypedEventEmitter, type AgentEventMap } from '../utils/eventEmitter.js';
 import type { LlmProvider, Message } from '../llm/provider.js';
-import type { Memory } from '../memory/types.js';
 import type { AgentMetrics } from '../agent/tracer.js';
+import type { BackgroundTaskStats } from '../utils/backgroundTask.js';
 /**
  * Memora Agent 门面类
  *
- * **设计哲学**：单 Agent，单配置，单记忆。每个 Agent 实例拥有独立的
- * 对话管线（AgentLoop）、独立的消息历史（MessageHistory）和独立的
- * 运行时状态（chatBusy）。activeSkill 已移除——技能匹配改为当轮实时注入，无需跨轮状态缓存。
- *
- * **多实例**：宿主可通过 new Agent({ dataDir: './agent2' }) 创建
- * 独立实例。只要 dataDir 不同，它们拥有完全隔离的记忆库和会话。
- * 内核不负责多 Agent 编排——那是宿主层的职责。
- *
- * **fork vs 多实例**：
- * - forkSession() 分叉对话历史，但记忆索引全局共享
- * - new Agent() + 独立 dataDir 实现完全隔离的记忆空间
- *
- * @example
- * ```ts
- * const agent = new Agent({
- *   projectPath: '/path/to/project',
- *   provider: new OpenAIProvider({ apiKey: '...' }),
- *   configDir: '/path/to/config',
- *   dataDir: '/path/to/data',
- *   permission: 'owner',
- *   allowedPaths: ['/path/to/project'],
- * });
- * await agent.init();
- * const iter = agent.chat('你好');
- * for await (const chunk of iter) { ... }
- * ```
+ * 单 Agent，单配置，单记忆：每个实例拥有独立的对话管线、消息历史与运行时状态。
+ * 多实例只需 dataDir 不同即可彻底隔离记忆库与会话；forkSession() 分叉对话历史但记忆索引全局共享。
+ * skill 为当轮实时注入，不跨轮缓存。
  */
 export declare class Agent extends TypedEventEmitter<AgentEventMap> {
     #private;
@@ -56,68 +33,59 @@ export declare class Agent extends TypedEventEmitter<AgentEventMap> {
     private history;
     private loop;
     private toolExec;
-    private personaManager;
     private skillManager;
-    private insightExtractor;
-    private configManager;
+    /** 角色包管理器（角色+技能+规则的唯一真理源） */
+    private _rolePackManager;
     private memoryInspector;
-    /**
-     * 语义去重管理器（L1 LLM 记忆治理）
-     *
-     * SPLIT-3 闭环（2026-07-21）：从 MemoryInspector 拆分出 deduplicateMemories 职责，
-     * 让 MemoryInspector 回归纯存储读写。Agent.deduplicateMemories() 委托本对象。
-     */
-    private dedupManager;
-    /**
-     * 记忆顾问（L3 冲突检测 / sourceHealth / suggest）
-     *
-     * v2 PROXY-1 闭环：Agent.detectConflicts 直接调用 advisor，
-     * 不再经 MemoryInspector 转发，消除 3 层无意义代理。
-     * sourceHealth/suggest 仍由 inspector 转发以保持 agent.memory 统一入口语义。
-     */
-    private memoryAdvisor;
     /** 记忆治理统一门面（L0/L1/L2/L3 + 诊断） */
     private _governance;
-    private workProjection;
-    /** AutoConfigRefiner（模式 3：Agent 智能总结） */
-    private autoConfigRefiner;
-    /** SessionArchiver（会话内容归档器，content 类记忆） */
-    private sessionArchiver;
     /** TextPolishManager（文本润色管理器，LLM 语法修正 + 表达优化） */
     private textPolisher;
     /** 会话管理器（从 Agent 拆分出的会话管理职责） */
     private _sessionManager;
-    private _initialized;
-    private pctx;
+    /** WorkProjectionManager（作品投影极简 JSON 索引，宿主经 works getter 消费） */
+    private workProjection;
     /**
-     * chat() 并发锁管理器（init 时创建，close 时销毁）
-     *
-     * 职责：chat() 并发锁 + token 校验（race condition 防护）+ 超时保护 + 外部 signal 合并。
-     * 详见 ChatLockManager 类注释。
+     * 内部组件聚合对象——收敛 12 个「仅门面内部消费、不对宿主暴露」的专职组件，
+     * 减少门面扁平字段数；宿主 getter 契约字段（memory/works/polish 等）不在此列。
      */
-    private chatLockManager;
+    private internals;
+    private _initialized;
+    private pctx;
     /** 最近一次 chat() 调用的时间戳 */
     private _lastInteractionAt;
     /**
-     * 对话进行中暂存的配置重载请求集合（chatLock 释放后补执行）
-     *
-     * 场景：用户在对话中通过 create_persona / create_skill 工具创建配置，
-     * reloadConfig 因 chatLock 冲突失败时，将 source 暂存于此。
-     * chat() 的 finally 块释放锁后遍历此集合逐个补执行 reloadConfig，
-     * 兑现"对话结束后自动加载"的承诺（见 tools.ts createConfigHandler 提示文案）。
-     *
-     * 用 Set 而非数组：同一 source 多次请求只需补执行一次（去重）。
+     * 流活跃标志：chat()/resumeExecution() 的 AsyncGenerator 生命周期内置 true、finally 置 false。
+     * 与 chatLock.isBusy（并发锁，180s 超时后自动释放但**不中断生成流**）语义解耦——
+     * requestPause 空闲守卫必须用「流是否在产出」而非「锁是否持有」判任务是否结束，
+     * 否则长任务运行超锁期后点暂停会被误判为「任务已结束」——锁超时会自动释放但生成流仍在跑，
+     * 故判据只能是流活跃，不能是锁持有。
+     */
+    private _flowActive;
+    /**
+     * 对话中因 chatLock 冲突暂存的配置重载请求（锁释放后补执行，兑现"对话后自动加载"）；
+     * 用 Set 去重——同一 source 只需补执行一次。
      */
     private pendingConfigReload;
-    /** 记忆衰减调度器（init 时创建，close 时销毁） */
-    private memoryDecayScheduler;
-    /** 归档协调器（归档操作委托给 ArchiveCoordinator） */
-    private archiveCoordinator;
     constructor(opts: AgentOptions);
     /**
      * 初始化 Agent：加载索引、组装内部组件
      */
     init(projectPathOverride?: string): Promise<ProjectContext>;
+    /**
+     * 登记作品投影实时刷新处理器：register_work 工具 / 右键登记成功后，
+     * 内核 WorkProjectionManager 触发 workProjectionGenerated 事件（携带已写入内存 entries 的投影），
+     * 立即重建 AgentLoop 的 systemPromptPrefix，使 AI 在下一轮对话即可感知新索引——
+     * 否则需切角色包 / reloadConfig / 开新会话才生效。
+     * 与 registerPauseTimeoutArchiver 同生命周期（init 内注册，close 的 removeAllListeners 兜底）。
+     */
+    private registerWorkProjectionRefresh;
+    /**
+     * 注册暂停超时归档处理器（SessionManager 两条超时路径——启动加载与运行时定时器——统一在此消费）
+     * 注册在 init() 内（close() 的 removeAllListeners + init 起始的 disposePreviousInstance 保证实例周期内恰好一个监听器），
+     * 挂在生命周期稳定的 Agent 上，rebuildComponents() 重建管理器后仍有效。
+     */
+    private registerPauseTimeoutArchiver;
     /**
      * 关闭旧实例（如果已初始化），失败不阻塞重建
      */
@@ -134,6 +102,16 @@ export declare class Agent extends TypedEventEmitter<AgentEventMap> {
      * 创建 init() 后期组件（初始化完成后才需要的组件）
      */
     private createPostInitComponents;
+    /**
+     * 构造种子闭环编排器，注入门面稳定能力（getParts 快照 + 工具暴露 + 流收口协议）
+     *
+     * 构造偏好在 agent.ts 而非 assembler.ts（方案的"assembler 构造"）：seed 依赖
+     * sessionNamer（post-init 才创建）与 consumeExecutionStream（门面私有流收口协议），
+     * 二者均无法在 assembler 阶段就绪，故收敛到 post-init 门面组装处。
+     *
+     * @returns 已接线门面能力的 SeedOrchestrator
+     */
+    private createSeedOrchestrator;
     /**
      * 流式对话（核心 API）
      */
@@ -146,15 +124,6 @@ export declare class Agent extends TypedEventEmitter<AgentEventMap> {
      * 获取对话锁 — 返回锁上下文
      */
     private acquireChatLock;
-    /**
-     * 准备对话上下文：角色匹配 → 记忆召回 → 技能注入 → 用户消息写历史
-     * @returns 召回的记忆列表（供 loop.processUserInput 注入为 system 消息）
-     */
-    private prepareChatContext;
-    /**
-     * 执行 LLM 流式循环 → 追加助手消息 → 触发后处理
-     */
-    private executeChatLoop;
     /**
      * 补执行对话期间暂存的配置重载请求
      */
@@ -162,466 +131,465 @@ export declare class Agent extends TypedEventEmitter<AgentEventMap> {
     /**
      * 强制释放对话锁
      *
-     * 场景：宿主主进程"无进展超时"兜底后，generator 可能仍卡在不可中断的 await 点
-     *   （executeToolCalls 和 generateContextSummary 已覆盖 signal 响应，但其他
-     *   第三方库或未来新增的 await 点仍可能不响应 signal）。
-     *   此时 _chatBusy 锁未释放，用户再发消息会被 chat() 的竞态保护拒绝，
-     *   表现为"UI 能操作但发不出消息"，需等到 3 分钟锁超时才能恢复。
-     *
-     * 本方法让宿主在确认 generator 挂起后强制释放锁，让用户能立即发起新对话。
-     *
-     * 安全机制（委托至 ChatLockManager.forceRelease）：
-     *   - 递增 _chatLockToken，让原 chat() 的 finally 块检测到 token 不匹配后
-     *     跳过资源清理（避免误清新调用者的 _chatBusy/chatAbortController）
-     *   - abort chatAbortController，让响应 signal 的 await 点（如 fetch）退出
-     *   - 原 generator 仍可能在后台运行（无法真正中断不响应 signal 的 await），
-     *     但其 finally 块的 token 校验会阻止它影响新调用
-     *
-     * 幂等性：_chatBusy 已 false 时 no-op（多次调用安全）
-     *
-     * 使用约束：
-     *   - 仅在宿主确认 generator 挂起（如无进展超时）后调用
-     *   - 不应在常规 abort 路径调用（常规 abort 走 signal，generator 自然退出）
-     *   - 调用后不应再消费原 chat() generator 的后续 chunk（token 已变，chunk 无意义）
+     * 宿主在"无进展超时"确认 generator 挂起后调用，使用户能立即发起新对话（否则需等锁超时）。
+     * 安全机制委托 ChatLockManager.forceRelease：递增 token 让原 chat() 的 finally 跳过清理、abort signal 让响应点退出；
+     * 原 generator 仍可能后台运行但不影响新调用。幂等（未忙时 no-op）。
      */
     forceReleaseChatLock(): void;
     /**
-     * 召回记忆 + 注入最近对话上下文
-     *
-     * 从 chat() 中提取，职责：
-     *   1. 双通道召回（语义 + 关键词）
-     *   2. Layer 5: 最近对话注入
-     *
-     * @param input 用户输入
-     * @returns 召回的记忆列表
+     * 发送用户消息，非流式返回完整回复
      */
-    private recallAndInject;
+    chatSync(input: string, signal?: AbortSignal): Promise<string>;
     /**
-     * 匹配技能并立即注入本轮对话（当轮生效，不延迟到下一轮）
+     * 软暂停后续跑（不中断工作模型 v2.1）
      *
-     * 与 persona 的 tryAutoMatchPersona 同模式：匹配 → 注入 → 本轮 LLM 即生效。
-     * 原设计为 injectActiveSkill（注入上一轮匹配结果），导致用户说"写代码"的第一轮
-     * 得不到技能增强，需再发一条消息才生效。已改为实时匹配注入。
+     * 翻状态机为 RUNNING（触发 sessionResumed → 宿主转发 STATUS{running}），
+     * 驱动 loop.continueAfterPause 续跑并转发 chunk，完成后追加历史 + 后处理（同 chat 尾处理）。
+     * 硬停止（signal.abort）仍是唯一霸道中止路径，与软暂停严格区分。
      *
-     * 匹配策略：regex trigger 优先（score=1.0），其次关键词匹配（阈值 0.3）。
-     * 清理机制：cleanTemporarySystemMessages() 每轮开头清除临时 system 消息，
-     * 技能 prompt 自然不会累积到下一轮。
+     * 归属：补充输入归属当前问答闭环（复用 prepare 分配的闭环节点 roundId，不分裂新轮），
+     * 以 kind 区分交互类型（question-answer=主动提问回答 / supplement=暂停/流中补充）。
      *
-     * @param input 用户输入文本
+     * @param input - 可选补充输入（空=续跑原路径；有=注入修正后续轮）
+     * @param signal - 可选 AbortSignal（硬停止仍走此路径）
+     * @param kind - 交互输入类型（默认 supplement；对主动提问的回答传 'question-answer'）
      */
-    private matchAndInjectSkill;
+    resumeExecution(input?: string, signal?: AbortSignal, kind?: InteractiveInputKind): AsyncGenerator<AgentChunk, void, unknown>;
     /**
-     * 对话后处理：用户画像归档、角色匹配、技能匹配、Insight 提取
+     * 消费执行流的单一真理源
      *
-     * 所有归档/匹配操作均为 best-effort：任何子步骤失败不应影响用户已收到的回答，
-     * 失败仅记录日志，不向上抛出异常。
+     * chat() 与续跑（continueAfterPause）必须共用同一份消费逻辑——两份同构实现会漂移
+     * （实证：续跑漏 paused 分支导致三方分叉）；收口于此，新增 chunk 类型只需改一处。
+     * 暂停幂等锁的释放放 finally——清理是"退出本作用域的不变式"而非某分支动作，新增 return 分支无遗漏。
      *
-     * ADR-015 归档模式控制：
-     * - 角色匹配 + 技能匹配不受 archiveMode 影响（每轮都执行，非归档行为）
-     * - `manual` 模式跳过所有自动归档（profile + insight），需用户手动调用
-     *   archiveProfileFacts() / archiveInsight() 触发
-     * - `full` / `insights-only` 模式下 profile + insight 都自动归档
-     *   （会话归档实现后，`insights-only` 将跳过对话原始内容自动归档）
+     * @returns 消费结果；failed 为 true 时调用方应立即 return（错误 chunk 已 yield）
      */
-    private postProcess;
+    private consumeExecutionStream;
     /**
-     * postProcess 内部实现（为 span 埋点提供 try/finally 包裹边界）
-     *
-     * 原 postProcess 逻辑完整保留于此，由外层 postProcess 负责 span 生命周期管理。
+     * 暂停会话（用户/Agent/系统均可触发，暂停前自动创建检查点）
+     * @param lowRisk 低风险暂停不计入连续暂停计数（默认 false）
      */
-    private doPostProcess;
+    pause(reason: string, source?: 'user' | 'agent' | 'system', lowRisk?: boolean): boolean;
     /**
-     * 发送用户消息，非流式返回完整回复
+     * 恢复会话（从 PAUSED 恢复到 RUNNING）
      */
-    chatSync(input: string, signal?: AbortSignal): Promise<string>;
+    resume(): boolean;
     /**
-     * 分叉当前会话（委托至 SessionManager）
+     * 自动恢复暂停状态（chat() 与续跑共用）：
+     * ERROR 态直接 throw（拒绝，须先 recover 保持状态一致）；PAUSED 态尝试自动恢复。
+     * 续跑（continueAfterPause）不走自动恢复，由独立的暂停恢复短路逻辑处理。
      *
-     * 分叉后原会话完整保留，新分支拥有独立消息历史。
-     * 记忆索引（IMemoryStorage）全局共享，不受分叉影响。
+     * @returns true=恢复成功或无需恢复；false=恢复失败（暂停超时等）
      */
-    forkSession(targetSession?: string): AgentForkResult;
+    private autoResumeIfPaused;
     /**
-     * 切换到指定项目
+     * 请求软暂停（不中断工作模型 v2.1）
      *
-     * 切换后自动 rebuildComponents()，无需手动调用。
-     * Agent 级记忆（memora.db）保留，项目级配置（.memora/）重新加载。
+     * 经 sm.requestPause 暂存 pending（SessionStateMachine 是 pending 真理源）+ loop.pauseRequested
+     * 入 interruptQueue（在下一 step 边界挂起，不 abort）。
+     * 状态机翻 PAUSED 延后到 loop 边界真正挂起时——内核事实驱动而非申请即翻转；与硬停止（abort）严格区分，
+     * 软暂停保留历史、可经 resumeExecution 续跑。
+     *
+     * @returns true=请求已注册（下一 step 边界生效）；false=无法暂停
      */
-    switchProject(nameOrPath: string): Promise<AgentContext>;
+    requestPause(reason: string, source?: 'user' | 'agent' | 'system'): boolean;
     /**
-     * 组装所有运行时组件（委托给 assembler 工厂）
+     * 取消待处理的软暂停请求：清空 loop 的 pauseRequested 标志（与 requestPause 对称），
+     * 并同步清理 SessionStateMachine 的 pending 暂停状态。
      */
-    private assembleComponents;
+    cancelPauseRequest(): void;
     /**
-     * 用当前 pctx 重建 history / loop
+     * 是否存在待处理的暂停申请（申请已发、尚未在 loop 边界挂起）
+     *
+     * 供宿主 UI 区分三态：无申请（暂停）/ 申请在途（取消暂停）/ 已暂停（继续）。
+     * 状态真理源 SessionStateMachine.isPausePending()：流中 requestPause 置位、边界挂起后 consumePendingPause 消费、
+     * cancelPauseRequest 主动清理；空闲态由 requestPause 空闲守卫作废（见上，return false 不触达状态机）——
+     * isPausePending 仅在流中「申请在途」时为 true（空闲态不翻 PAUSED）。
      */
-    private rebuildComponentsWithCurrentCtx;
+    isPausePending(): boolean;
     /**
-     * 创建会话管理器（提取重复的 forwardEvent + SessionManager 构造逻辑）
+     * 放弃当前暂停检查点（宿主 stop 语义的内核出口）
      *
-     * assembleComponents 和 rebuildComponentsWithCurrentCtx 共享同一套构造逻辑：
-     * - 通过回调访问当前组件（支持 rebuild 后自动获取最新引用）
-     * - 事件转发桥接：SessionManager 使用宽类型 (string, Record<string,unknown>)，
-     *   Agent 内部桥接到 TypedEventEmitter 的强类型 emit
-     * - 运行时校验事件名是否在 AgentEventMap 中，避免不安全的类型断言
+     * 与 pause() 对称：pause 创建检查点；discardCurrentCheckpoint 销毁检查点。
+     * 宿主 handleStop 在 paused 态调用——用户决定彻底放弃暂停执行，不再 resume。
      *
-     * @returns 新的 SessionManager 实例
+     * 除转发 SessionManager.discardCheckpoint（清内存 + 状态机 resetToRunning——检查点不落盘，无存储清理动作），
+     *  还须协同 loop.clearPendingInterjections() 清排队插话——pause 生效时 step 边界优先返回不消费 queue，
+     *  只清 checkpoint 会留孤儿 queue，下次 chat() 首个 step 误消费残留（坑）。
+     *  返回值以 checkpoint 清理为主（queue 有残留不判失败）。
+     * @returns true=成功清理；false=无暂停检查点（空闲态调了个空）
      */
-    private createSessionManager;
-    setProvider(provider: LlmProvider): void;
-    setBackgroundProvider(provider: LlmProvider | null): void;
+    discardCurrentCheckpoint(): boolean;
     /**
-     * 运行时切换归档模式
+     * 执行中插话（申请）：把用户补充输入排队，当前 step 完成后在 step 边界统一注入为 user 消息。
      *
-     * 与 setProvider 一致，对话进行中禁止切换（避免本轮 postProcess 行为不一致）。
+     * 与 requestPause（step 边界挂起待续跑）同为「申请 → 气口生效」——不中断当前 LLM/工具执行，
+     * 只在边界拿到补充输入后开始下一轮 step。插话是唯一写入口（interject → pendingInterjections 排队），
+     * 无「立即中断」模式：只有单一申请模式（无 inputInterrupt 立即中断通道）。
      *
-     * @param mode 目标模式
+     * 归属：插话同时以「补充」交互输入持久化到当前闭环节点（interactiveInputs），
+     * 保证跨重启重放时插话内容不丢失、不分裂新轮。持久化 fire-and-forget（appendUser 内部
+     * 已 catch 写入失败，仅记日志），不阻塞插话本身。
      */
-    setArchiveMode(mode: ArchiveMode): void;
+    interject(content: string): void;
     /**
-     * 查询当前归档模式
-     *
-     * 宿主 UI（如设置面板）可据此同步显示当前模式。
+     * 删除待注入的插话（宿主 UI 层用户后悔）。与 interject 对称。
+     * 注意：interject 时已持久化到 history（交互输入归属），此处只从内核队列移除，不删除已落盘记录——
+     * 未来若需完整"撤回"需额外方案（如软删标记），当前先保证 step 边界不会注入已删除的补充。
+     * @param index 要删除的插话在队列中的位置（宿主镜像数组与内核队列同序同长度）
+     * @returns true=成功删除；false=index 越界或队列为空
      */
-    getArchiveMode(): ArchiveMode;
+    removePendingInterject(index: number): boolean;
     /**
-     * 手动切换角色（宿主 UI 角色选择器入口）
-     *
-     * 与 doPostProcess 中的自动匹配走同一条事件链路，确保：
-     *   1. AgentLoop 的 systemPromptPrefix 立即刷新（下一次对话使用新角色 prompt）
-     *   2. 发射 personaSwitched 事件，触发 spriteLifecycleManager 的完整副作用：
-     *      - emit('personaChanged') 通知宿主 UI
-     *      - proactiveEngine.addNotice('persona', ...) 记录通知
-     *      - perceptionCoordinator.refreshBeforeChat() 基于新角色 traits 重新推导情感基调
-     *
-     * 对话进行中切换角色会破坏当前 system prompt，与项目切换一致拒绝。
+     * 清空全部待注入插话（宿主「全部清空」按钮触发，或 stop→discard 协同清理）。
      *
-     * @param name 目标角色名
-     * @returns 切换成功返回新角色的 system prompt 段；角色不存在或切换失败返回 null
+     * 逻辑下沉 loop.clearPendingInterjections 原子方法——清队列唯一入口在内核，
+     *  宿主不维护队列镜像，避免镜像与内核双写不一致；discardCurrentCheckpoint 经同一方法协同清理。
+     *  @returns 被清除的条目数（宿主可用于 notice 反馈；无队列时返回 0）
      */
-    switchPersona(name: string): string | null;
+    clearPendingInterjections(): number;
     /**
-     * 获取角色切换锁定状态（透传 PersonaManager，P0-2 用户体验打磨）
-     *
-     * 与 switchPersona 分离：switchPersona 仍返回 string | null 不变，
-     * 锁定原因查询走独立路径，避免破坏既有契约（cli.ts、sprite.test.ts 等消费者无感）。
-     *
-     * 宿主 IPC 层调用此方法前置判断锁定状态，区分"切换失败"原因
-     * （locked / busy / not_found / invalid），让用户知道为什么没反应。
-     *
-     * @returns locked 是否处于锁定状态；unlockAt 锁定自动恢复时间戳（ms epoch），未锁定时为 null
+     * 读取当前待注入插话队列快照（宿主渲染层只读镜像，不修改内核状态）。
+     * 返回副本，宿主无法暗改内核 queue；宿主渲染直接读本快照，不另维护队列镜像。
      */
-    getPersonaSwitchLockStatus(): {
-        locked: boolean;
-        unlockAt: number | null;
-    };
+    getPendingInterjections(): readonly string[];
     /**
-     * 刷新 AgentLoop 的 systemPromptPrefix（角色 prompt + profile prompt）
-     *
-     * 提取自 doPostProcess 自动匹配 + switchPersona 手动切换两处共用逻辑（ADR-017 枝叶层 2 次提取）。
-     * 组装规则：[personaPrompt, profilePrompt].filter(Boolean).join('\n\n') + 末尾分隔符 '---'
-     *
-     * 调用时机：
-     * - tryAutoMatchPersona 中角色自动匹配成功后（chat() 回答前）
-     * - switchPersona 手动切换成功后
-     * - loop 为 null 时静默跳过（init 前或 close 后的边界场景）
+     * 放弃在途主动提问（ask_user 工具挂起后，宿主「跳过/取消提问」时调用）：
+     * 委托 loop.cancelAsk 补占位 tool 结果（防 assistant.tool_calls 无配对 → 400），
+     * 随后 resumeExecution() 续跑。与 answerQuestion 二选一消费在途提问。
      */
-    private refreshPersonaPrefixOnLoop;
+    cancelAsk(): void;
     /**
-     * 角色自动匹配（best-effort：失败不阻塞对话流程）
+     * 回答在途主动提问（ask_user 工具）：
+     * 答案以 ask_user 的 tool result 回填（与 assistant.tool_calls 配对，结构合法）。
+     * 调用后宿主以 resumeExecution(回答文本, undefined, 'question-answer') 续跑——
+     * 回答文本同时作为新 user 输入注入并记录为闭环节点交互输入（round 不分裂），
+     * 与既有续跑主流程一致（本方法只负责结构化回填，不做历史记录，避免双写）。
+     * 返回 false 表示无在途提问（提供方未调用 / 已消费）。
+     */
+    answerQuestion(answers: readonly string[]): boolean;
+    /**
+     * 追加计划任务项（SESSION_APPEND_TASK 落点）：在现有 plan 末尾追加新任务项
+     */
+    appendPlanItem(description: string): number;
+    /**
+     * 卸载运行态挂载物：清空检查点计划与任务项推进日志（宿主任务流结束/停止/异常广播 idle 前调用），
+     * 回到"空闲 = 无挂载物"的资源层常态；会话历史与记忆等资源层内容不受影响。
+     */
+    clearPlan(): void;
+    /**
+     * turn 结束自动收尾：非暂停态 → 无条件 clearPlan（任务表收紧为 turn 内能力，不跨 turn 残留）。
      *
-     * 在 chat() 回答前执行，确保本轮 LLM 调用就用匹配到的角色 system prompt。
-     * 两层匹配策略：关键词高置信度 → LLM 辅助（低置信度且 backgroundProvider 已注入时）。
-     * LLM 辅助匹配在 agent 层执行，遵循 backend_layers_rules §分层职责（persona/ 不直接调 LLM）。
+     * 任务表生命周期 = 单个 turn：LLM 在 turn 内编排并完成任务表；chat() 流退出（turn 真正结束）
+     * 时，无论任务项是否全部标记完成，都清空运行时挂载物（checkpoint.plan 与 planItemLog）。这样：
+     * ① 宏任务一个 turn 完不成 → 本 turn 结束兜底丢弃，下个 turn 由 LLM 重新规划全新任务表；
+     * ② 续跑轮（resumeExecution = ask_user 问答/暂停补充）是同一 turn 的闭环收尾，与 chat() 同构
+     * 走本方法——turn 真正结束即无条件清空，chat() 与续跑轮共用本收口点。
      *
-     * 匹配成功时：切换角色 + 发射 personaSwitched 事件 + 刷新 AgentLoop 前缀。
-     * 匹配失败/异常时：静默降级，保持当前角色。
+     * 唯一例外是暂停态（pauseMeta）：turn 尚未真正结束，暂停恢复后要继续用 plan 推进，
+     * 故保留不清；恢复完成后该 turn 最终退出时仍会走本方法无条件清空。
      *
-     * @param input 用户输入文本
+     * 运行时状态（plan/planItemLog）清空，但对话记录里的 round-block 折叠块已沉淀为历史（不落盘删除）。
+     * 挂点：chat() 与 resumeExecution 的 finally 块（generator close 时触发，确保所有 yield 已被宿主消费）
      */
-    private tryAutoMatchPersona;
+    private clearPlanOnTurnEnd;
     /**
-     * 判断是否应回退到默认角色
+     * 内核→宿主信号：当前会话是否可"无输入续跑"（决定暂停按钮显隐 + 暂停后继续 UI）
      *
-     * 回退条件（全部满足）：
-     *   1. 当前激活角色不是默认角色（已在默认角色则无需回退）
-     *   2. 角色管理器存在且非锁定状态（锁定时 switchPersona 也会被拦截，回退无意义）
+     * 真值条件：① 状态机已 paused（已软暂停必可续跑，最高优先级——pauseRequested 在下一 step 边界才挂起，
+     * 彼时 inAutonomousStep 已重置为 false，仅看它会误报）；② loop 在自主工具步（可暴露暂停按钮在边界挂起）；
+     * ③ 存在未完成的计划任务项（多轮任务可续跑下一轮）。三者皆否（纯单轮、无待续目标）→ 隐藏暂停按钮（仅停止）。
+     */
+    canContinueWithoutInput(): boolean;
+    /**
+     * 触发会话异常（公开 API，宿主显式调用）：仅 RUNNING 状态可触发，异常时自动创建检查点保存状态。
+     * 生产内部无调用者——运行时异常（LLM 超时/工具失败）走 yield {type:'error'} 事件流不翻状态机；
+     * 本 API 供宿主在自定义异常（如外部服务故障）显式触发，或经检查点恢复回填进入 ERROR 态。
+     */
+    triggerError(cause: string): boolean;
+    /**
+     * 从异常恢复：校验恢复条件（error.recovered === true 且 cause 已解除）
+     */
+    recover(): boolean;
+    /**
+     * 创建会话检查点：快照当前运行时状态（热记忆等），生成纯内存态快照
+     * （不落盘、无序列化/恢复路径——中止/断电走「中断轮补全为完整 turn」）。
+     * 无 role/standard 会话能力位，createCheckpoint 仅收 mainGoal。
+     */
+    createCheckpoint(mainGoal?: string): SessionCheckpoint | null;
+    /**
+     * 获取当前检查点
+     */
+    getCheckpoint(): SessionCheckpoint | null;
+    /**
+     * 获取最近一次处理线程的工具执行历史（loop 域聚合出口，补待办 #3）
      *
-     * 注意：bgProvider 未配置时也会触发回退——因为关键词 + LLM 均未命中说明当前角色不匹配本轮对话，
-     * 回退默认角色比卡在错误角色上更合理。
+     * 数据源自 sessionManager 检查点的 completedToolCalls（已由
+     * AGENT_CONSTANTS.COMPLETED_TOOL_CALLS_MAX 做 FIFO 封顶）。本方法剥离「恢复/幂等」内部
+     * 语义，提供稳定的 execute 域只读契约——宿主可在透明面板/观测面消费本轮及历史的工具调用
+     * 明细（工具名 / 成败 / 结果摘要），与累计 AgentMetrics.tools 互补。
      *
-     * @returns 是否应回退到默认角色
+     * @param limit 返回条数上限（默认取封顶上限，超界由调用方控制，取最近 limit 条）
+     * @returns 工具执行记录（记录顺序：时间正序即旧→新；无记录返回空数组；返回浅拷贝防宿主改动检查点）
      */
-    private shouldFallbackToDefault;
+    getRecentToolExecutions(limit?: number): ToolExecutionRecord[];
     /**
-     * 手动触发 profile facts 归档（manual 模式下使用）
+     * 向 loop 注入 system 消息
+     */
+    injectSystemMessage(message: string): void;
+    /**
+     * 从指定 Round 位置分叉当前会话（委托至 SessionManager）：
+     * round-based 模式唯一分叉方式——创建新会话，复制 Round ID 列表（指针复制），
+     * 新会话是完全平等的普通会话。记忆索引全局共享不受影响。
      *
-     * manual 模式下 postProcess 跳过自动归档，用户需通过此 API 主动归档。
-     * full / insights-only 模式下也可调用（会重复归档，但不推荐）。
+     * 自动命名场景（未传 targetSession）：分叉后异步触发 SessionNamer 为新会话生成标题
+     * （best-effort，不阻塞分叉返回）；用户显式指定会话名时尊重用户命名，不触发 LLM 覆盖。
      *
-     * FIX-P1-4：新增 options 参数透传给 ArchiveCoordinator。
-     * 宿主自动触发时传 `{ autoTriggered: true }`，由 ArchiveCoordinator 内部按模式判断；
-     * 用户手动触发时无需传 options（默认 autoTriggered=false，无条件执行）。
+     * @param roundId - 分叉点的 Round ID（可选；不传默认使用最后一个 Round）
+     * @param targetSession - 可选，自定义新会话名
+     */
+    forkSession(roundId?: string, targetSession?: string): AgentForkResult;
+    /**
+     * 分叉会话首轮命名（best-effort，fire-and-forget）
      *
-     * 归档逻辑已委托给 ArchiveCoordinator
+     * 分叉新会话是平等普通会话，自动命名（未提供 targetSession）时应拥有 LLM 生成的语义标题。
+     * 取新会话第一个 Round 的用户消息作为命名输入（分叉点即新会话起点，语义=首轮问答）；
+     * SessionNamer 内部已有 autoName 存在即跳过（幂等），LLM 失败/无价值降级占位标题。
      *
-     * @param input 本轮用户输入
-     * @param options 触发选项（autoTriggered 默认 false，即手动触发）
-     * @returns 写入/更新的 UserProfileEntry 列表
+     * @param result - 分叉结果（含新会话名/日期/Round 列表）
      */
-    archiveProfileFacts(input: string, options?: ArchiveTriggerOptions): Promise<UserProfileEntry[]>;
+    private ensureForkSessionTitle;
     /**
-     * 手动触发 insight 提取（manual 模式下使用）
+     * 切换到指定项目：切换后自动 rebuildComponents()；Agent 级记忆存储（宿主注入，实例不随项目切换重建）保留，项目级配置（.memora/）重新加载
      *
-     * manual 模式下 postProcess 跳过自动归档，用户需通过此 API 主动归档。
-     * 内部仍走 classify 判断（避免无价值输入浪费 LLM 调用）。
+     * `nameOrPath` 只接受两种输入：① 项目注册表中的项目名（依赖注册表跨项目共享，见 dataDir/registryDir）；
+     * ② 项目根目录的**绝对路径**。二者都不满足时抛 configError——否则相对串会以 process.cwd()
+     * 为基准解析，静默造出非预期的项目目录并占用其锁。
+     */
+    switchProject(nameOrPath: string): Promise<AgentContext>;
+    /**
+     * 组装所有运行时组件（一行委托给 assembler 工厂）
      *
-     * FIX-P1-4：新增 options 参数透传给 ArchiveCoordinator。
-     * 宿主自动触发时传 `{ autoTriggered: true }`，由 ArchiveCoordinator 内部按模式判断；
-     * 用户手动触发时无需传 options（默认 autoTriggered=false，无条件执行）。
+     * 接线回调（工具幂等 outbox / 任务表 / loop 回调 / createSessionManager）与装配私有状态
+     * （暂存队列 / 停滞计数器）全部由 assembler 组装收口——Agent 只注入稳定能力（hooks）。
+     */
+    private assembleComponents;
+    setProvider(provider: LlmProvider): void;
+    /**
+     * 运行时更新上下文窗口上限（token）
      *
-     * 归档逻辑已委托给 ArchiveCoordinator
+     * 模型热切换配套：同步三处装配期值拷贝（loop 截断/软上限、ContextManager 阈值、
+     * ContextPreparer 预算与占用快照），全部对新窗口即刻生效。对话进行中禁止更新
+     * （与 setProvider 同守卫）。
      *
-     * @param input 本轮用户输入
-     * @param assistantContent 本轮助手回复内容
-     * @param options 触发选项（autoTriggered 默认 false，即手动触发）
-     * @returns 写入/更新的 Memory 列表
+     * @param tokens 新窗口 token 数
      */
-    archiveInsight(input: string, assistantContent: string, options?: ArchiveTriggerOptions): Promise<Memory[]>;
+    setContextWindow(tokens: number): void;
     /**
-     * 手动归档会话内容（content 类记忆）
+     * 运行时更新 per-LLM 输出预算默认值（token）
      *
-     * 适用于 `insights-only` / `manual` 模式下用户手动触发会话内容归档。
-     * `full` 模式下由宿主在会话切换前自动调用，无需用户干预。
+     * Provider 热切换配套（与 setContextWindow 同链路）：同步 #config 拷贝并即时生效于 loop——
+     * 切换 Provider 后新配置的 maxTokens 无需重装 Agent。undefined = 清除（回服务端默认）。
+     * 不设 assertNotBusy：maxTokens 是请求参数（非上下文结构），轮内下一迭代即用新值，无一致性风险。
      *
-     * FIX-P1-4：新增 options 参数透传给 ArchiveCoordinator。
-     * 宿主自动触发时传 `{ autoTriggered: true }`，由 ArchiveCoordinator 内部按模式判断；
-     * 用户手动触发时无需传 options（默认 autoTriggered=false，无条件执行）。
+     * @param tokens 新输出预算（token）；undefined 清除
+     */
+    setMaxTokens(tokens: number | undefined): void;
+    /**
+     * 读取本轮请求体**实际**携带的 max_tokens（生效值），供宿主取证面写 meta。
      *
-     * 归档逻辑已委托给 ArchiveCoordinator
+     * 薄委托：优先级裁决收敛在 AgentLoop.buildChatOptions（见其注释），此处不复制规则——
+     * 否则「谁压过谁」会在宿主侧长出第二真理源。loop 未装配时返回 undefined。
+     */
+    getEffectiveMaxTokens(): number | undefined;
+    setBackgroundProvider(provider: LlmProvider | null): void;
+    /**
+     * 运行时切换归档模式：对话进行中禁止切换（避免本轮 postProcess 行为不一致），无变更幂等返回
+     */
+    setArchiveMode(mode: ArchiveMode): void;
+    /**
+     * 查询当前归档模式（宿主 UI 可据此同步显示）
+     */
+    getArchiveMode(): ArchiveMode;
+    /**
+     * 获取角色包切换锁定状态（透传 RolePackManager，宿主 IPC 层据此区分"切换失败"原因）
+     * @returns locked 是否锁定；unlockAt 锁定自动恢复时间戳（ms epoch），未锁定时为 null
+     */
+    getRolePackSwitchLockStatus(): {
+        locked: boolean;
+        unlockAt: number | null;
+    };
+    /**
+     * 获取当前激活角色包的 traits（宿主情感计算 API）
      *
-     * @param date 会话日期 YYYY-MM-DD
-     * @param session 会话标识（不含日期前缀）
-     * @param options 触发选项（autoTriggered 默认 false，即手动触发）
-     * @returns 归档结果（memories 可能为空，表示无归档价值或 LLM 失败）
+     * @returns traits 键值对，无激活角色包或无 traits 时返回 undefined
      */
-    archiveSessionContent(date: string, session: string, options?: ArchiveTriggerOptions): Promise<SessionArchiveResult>;
+    getActiveTraits(): Record<string, number> | undefined;
     /**
-     * 获取 pending 归档队列长度（MIND2-C3）
+     * 刷新 AgentLoop 的 systemPromptPrefix（SSOT：buildSystemPromptPrefix）
      *
-     * 返回待重试的失败归档数。归档失败时输入入队，下次同阶段归档调用时自动重试。
-     * 供宿主 UI 展示"N 条待补归档"提示，或判断是否需要手动触发重试。
+     * 角色包是 system prompt 的唯一注入源。调用时机：手动切换成功后、reloadConfig 重载后；
+     * loop 为 null 时静默跳过（init 前或 close 后边界）。统一走 buildSystemPromptPrefix 真理源，
+     * 全局技能清单也在该前缀内（不能只拼 rolePackPrompt）。等价于「按 activePack 视角刷新」（roundRole=null）。
+     */
+    private refreshRolePackPrefixOnLoop;
+    /**
+     * 会议阶梯推进：按当前 active 任务项的 rolePack 派生本轮装配视角。
      *
-     * @returns pending 队列长度（0 表示无待补）
+     * 由 assembler.getTaskTable 每轮注入时驱动（hooks.applyActivePlanItemAssembly），与任务表渲染同源，
+     * 保证后继 step 换角色即时生效（装配视角不能只在 prepare.run 设一次，否则展示层正确/装配层冻结）。
+     * roundRole=candidate（可能为 null，无有效覆盖时回落 activePack 组长），调 refreshRolePackPrefixForRound 重建前缀。
+     * 防重：candidate 与 rolePackManager 当前 roundAssemblyPerspective 一致则跳过，避免每轮迭代重复重建。
      */
-    getPendingArchiveCount(): number;
+    private applyActivePlanItemAssemblyIfChanged;
     /**
-     * 重载配置类记忆：从 configDir 重新扫描指定 source 的配置文件并更新内存缓存 + SQLite 索引
+     * 按本轮表层装配视角刷新 AgentLoop 前缀（会议机制）
      *
-     * 解决方案：installSkill 写入文件后或 confirmConfigSuggestion 写入配置文件后，
-     * 调用此方法使当前会话立即生效，无需重启 Agent。
+     * roundRole=null（日常态）→ 回落 activePack 前缀；roundRole 为任务项角色 → 该角色
+     * persona/rules/skills 全量表层装配（buildSystemPrompt(name)）。策略键恒为 activePack：
+     * ChatOptions（temperature/outputLimit）由 activePack 策略构建，不随视角变（键不换防抖动）。
+     * 由 seed prepare 每轮调用（`refreshRolePackPrefixForRound` 契约），保证前缀始终匹配本轮装配角色。
+     */
+    private refreshRolePackPrefixForRound;
+    /**
+     * 从当前激活的角色包策略构建 ChatOptions 覆盖项
+     * 将 act.temperature / act.outputLimit 映射到 ChatOptions 字段；输出上限最终与 per-LLM 默认值
+     * 取**更小值**（两者皆为「上限」，须同时满足）——收敛在 `buildChatOptions`，此处不裁决大小。
+     */
+    private buildChatOptionsFromStrategy;
+    /**
+     * 角色包系统的唯一切换入口（自动匹配 + 手动切换共用）：activate 更新激活态 → 发射 rolePackSwitched 事件
+     * → 刷新 AgentLoop 前缀 → 同步工具白名单。
+     * @returns 是否切换成功。false 有两种成因（**均不发射切换事件**）：角色包不存在、
+     * 切换锁已激活（30s 内超 5 次限流）；调用方须以 getRolePackSwitchLockStatus() 区分，
+     * 不可由「返回 false + 未收到 rolePackSwitchLocked」推断为"不存在"（被锁时该事件不发射，
+     * 仅在**触发锁定**的那一次切换中发射，而那一次返回 true）。同名切换幂等返回 true。
+     */
+    switchRolePack(name: string): boolean;
+    /**
+     * 手动归档会话（更新 SessionMeta，委托 ArchiveCoordinator）
      *
-     * 支持的 source：
-     * - 'skill' → SkillManager.reload() 清空缓存重新扫描 skills/ 目录
-     * - 'persona' → PersonaManager.reload() 清空缓存重新扫描 personas/ 目录（保持激活角色）
-     * - 'rule' → 无操作（rule 类型由 ConfigManager CRUD 即时同步 bootstrap 段，详见 deleteRule/updateRule）
-     * - 'guardrail' → 抛错（guardrail 是 AgentLoop 的 readonly 数组，需 rebuildComponents 才能重载）
-     * - undefined → 重载 skill + persona（全量重载，不含 guardrail）
+     * 适用于 manual 模式（用户手动触发；full 模式由宿主切换前自动调用）。
+     * options 透传给 ArchiveCoordinator：宿主自动触发传 { autoTriggered: true }（按其模式判断），
+     * 用户手动触发省略 options（默认 autoTriggered=false，无条件执行）。
      *
-     * @param source 配置类型，缺省时重载全部可热更新的配置
-     * @returns 重载结果统计
+     * @returns 归档结果（updatedFields 可能为空，表示无归档价值或 LLM 失败）
+     */
+    archiveSession(date: string, session: string, options?: ArchiveTriggerOptions): Promise<SessionArchiveResult>;
+    /**
+     * 重载配置类记忆：从 configDir 重新扫描指定 source 并更新内存缓存（设定记忆纯文件装载，不写记忆库），使当前会话立即生效（无需重启）。
+     * - 'skill' → SkillManager.reload() 重扫 skills/
+     * - 'rolePack' → RolePackManager.reload() 重扫 role-packs/（保持激活角色，刷新 AgentLoop 前缀）
+     * - 'rule' → 经角色包管理机制热更新（即 rolePack）
+     * - undefined → 全量重载 skill + rolePack
      */
     reloadConfig(source?: string): Promise<{
         skill: number;
-        persona: number;
+        rolePack: number;
     }>;
     /**
-     * 重建内部组件（history / loop / managers）
-     *
-     * 通常不需要手动调用——switchProject() 已自动执行 rebuild。
-     * 仅在宿主项目需要强制刷新组件时使用（如热更新配置后）。
+     * 重建内部组件（history / loop / managers）：通常由 switchProject() 自动触发，仅强制刷新时手动调用
      */
     rebuildComponents(): Promise<void>;
     /**
-     * 检查 Agent 是否已初始化
-     *
-     * @param methodName 调用方法名（用于错误消息）
-     * @param requires 需要检查的组件列表
+     * 检查 Agent 是否已初始化（methodName 用于错误消息，requires 为需检查的组件列表）
      */
     private assertInitialized;
     /**
-     * 断言对话未进行中 — 统一守卫，避免在 chat() 进行中执行会破坏状态一致性的操作
-     *
-     * 提取原因：switchProject / setProvider / setBackgroundProvider / setArchiveMode /
-     * switchPersona / rebuildComponents 等 6 处方法均有相同的 `if (isBusy) throw chatBusyError('XXX')` 守卫，
-     * 违反 DRY 原则（v2 神木回天 REPEAT-4 闭环）。
-     *
-     * 注意：reloadConfig 不使用本方法——它在 isBusy 时需暂存 source 而非直接抛错。
-     *
-     * @param operation 操作名称（用于错误消息，如 "切换项目"）
+     * 断言对话未进行中（统一守卫）：破坏状态一致性的入口统一在此做 isBusy 检查。
+     * reloadConfig 不使用本方法——它在 isBusy 时需暂存 source 而非直接抛错。
      */
     private assertNotBusy;
+    private get requireLoop();
+    private get requireArchiveCoordinator();
+    private get requireSessionManager();
     /**
-     * 断言 getter：获取 loop，若 null 则抛出明确错误
-     * 替代 `this.loop!` 非空断言，提供更好的重构安全性
+     * 获取角色包管理器（system prompt 的唯一注入源，返回 null 表示 Agent 未初始化）
      */
-    private get requireLoop();
+    get rolePackManager(): RolePackManager | null;
     /**
-     * 断言 getter：获取 history，若 null 则抛出明确错误
+     * 获取当前激活的 L2 行为策略：从激活角色包读取，未激活时用全局默认值；供各阶段按策略调整行为
      */
-    private get requireHistory();
+    getActiveStrategy(): BehaviorStrategy;
     /**
-     * 断言 getter：获取 pctx，若 null 则抛出明确错误
+     * 应用当前角色包的工具暴露面（换角色 → 工具集切换）：声明 capabilities 时解析为工具白名单，未声明放行全部。
+     * 空数组（parseCapabilities 对 undefined 返回 []）同样视为"未声明能力"放行全部，避免误解释为"禁止所有"。
+     * toolMode=block 全禁与此正交；变更经 setToolWhitelist → onToolsChanged 链路同步 loop 快照与 system prompt。
      */
-    private get requirePctx();
-    private get requireArchiveCoordinator();
-    private get requireSessionManager();
+    private applyRolePackToolExposure;
     /**
-     * 关闭 Agent，释放 SQLite 连接等资源
+     * 立即执行一次孤儿 Round 垃圾回收（宿主手动触发入口）。
+     *
+     * roundStore+storage 未注入时返回空统计（降级不报错）；
+     * 对话进行中（chatLock busy）经 shouldSkip 跳过并返回空统计。
+     *
+     * @returns GC 结果统计（scanned/deleted/memoryCleaned 等）
+     */
+    gcNow(): GCResult;
+    /**
+     * 关闭 Agent，释放存储连接等资源
      */
     close(): Promise<void>;
     /**
-     * 统一 null 化所有组件字段（新增 Manager 时在此处追加一行）
-     *
-     * 仅处理"纯 null 化"字段，带副作用的清理（dispose/stop/close/shutdown）
-     * 仍由 close() 显式调用，顺序敏感不可合并。
+     * 统一 null 化所有组件字段（新增 Manager 时在此追加一行）；带副作用的清理仍由 close() 显式调用，顺序敏感不可合并
      */
     private nullifyAllComponents;
     get initialized(): boolean;
     get context(): AgentContext | null;
     /**
-     * @deprecated 直接暴露 AgentLoop 破坏封装，将在下一主版本移除。
-     * 使用 getMessages() / getMessageCount() 等有界接口替代。
+     * 获取 AgentLoop 实例（宿主集成面，用于 restoreHistory 等底层操作；getMessages/getMessageCount 无法替代）
      */
     get agentLoop(): AgentLoop | null;
     /**
-     * 获取当前消息列表（只读副本，不可绕过 Agent 编排链路直接修改）
+     * 获取当前消息列表（只读副本，不可绕过编排链路直接修改）
      */
     getMessages(): readonly Message[];
     /** 获取当前消息数量 */
     getMessageCount(): number;
     /**
-     * @deprecated 直接暴露 MessageHistory 破坏封装，将在下一主版本移除。
-     * 使用 Agent 的对话管理方法（chat/chatSync/forkSession）替代直接操作。
+     * 获取 MessageHistory 实例（宿主集成面，用于日期/会话判断等底层操作；
+     * currentDateValue/currentSessionValue 等只读属性无替代接口）
      */
     get agentHistory(): MessageHistory | null;
     /**
-     * 注入情感基调到 system prompt（Phase 2.1：AffectController）
-     *
-     * 委托至 AgentLoop.injectAffect()，在角色前缀和 bootstrap 记忆之间插入情感描述。
-     * 与角色切换独立——切换角色不会清除情感注入。
-     *
-     * @param affectString 情感描述文本，传空字符串清除注入
+     * 注入情感基调到 system prompt：委托 AgentLoop.injectAffect()，在角色前缀与 bootstrap 记忆间插入情感描述；
+     * 与角色切换独立（切换角色不清除情感注入），传空串清除。
      */
     injectAffect(affectString: string): void;
     get provider(): LlmProvider;
     get isBusy(): boolean;
     get lastInteractionAt(): Date | null;
-    /**
-     * 记忆治理统一门面（L0 衰减 / L1 去重 / L2 时效性 / L3 冲突 / 诊断 / 推荐）
-     *
-     * 统一入口替代散落在 Agent 上的 6 个独立方法：
-     *   agent.governance.decay()           → 原 runMemoryDecayOnce()
-     *   agent.governance.deduplicate()     → 原 deduplicateMemories()
-     *   agent.governance.evaluateTimeliness() → 原 evaluateTimeliness()
-     *   agent.governance.detectConflicts() → 原 detectConflicts()
-     *   agent.governance.sourceHealth()    → 原 sourceHealth()
-     *   agent.governance.suggest()         → 原 suggest()
-     */
+    /** 记忆治理统一门面（语义去重 / 来源健康诊断 / 冲突检测 / 建议推荐），Agent 上的记忆管理方法统一收口于此（无显式衰减层面） */
     get governance(): MemoryGovernance | null;
     /**
-     * 获取 Agent 运行时指标快照（可观测性增强）
-     *
-     * 聚合 AgentLoop 指标（LLM 调用、记忆召回、工具调用、上下文管理）
-     * 与 Agent 层指标（记忆衰减），返回完整的 AgentMetrics 快照。
-     *
-     * 未初始化时返回全零指标（合理的默认值，不抛异常）。
-     * 纯只读、同步、零副作用——适合宿主项目定期轮询构建监控面板。
-     *
-     * 使用方式：
-     *   const metrics = agent.getMetrics();
-     *   console.log(`LLM 调用 ${metrics.llm.callCount} 次，命中率 ${metrics.recall.hitRate}`);
-     *
-     * @returns AgentMetrics 完整快照（含衰减指标）
+     * 后台任务统计快照（宿主观测后台副作用健康度，纯只读转发 utils 单例）。
+     * @returns 在途 / 成功 / 失败计数
      */
-    getMetrics(): AgentMetrics;
+    getBackgroundTaskStats(): BackgroundTaskStats;
     /**
-     * 角色管理器（可能为 null）
-     *
-     * 返回 null 时表示 Agent 未初始化或角色系统未加载。
-     * 链式调用建议使用可选链：`agent.persona?.activeName`
-     */
-    get persona(): PersonaManager | null;
-    /**
-     * 工具执行器（可能为 null）
-     *
-     * 返回 null 时表示 Agent 未初始化。
+     * 获取 Agent 运行时指标快照（可观测性）：聚合 AgentLoop 指标与 Agent 层治理指标；
+     * 未初始化返回全零默认值（不抛异常），纯只读同步零副作用，适合宿主定期轮询监控面板。
      */
+    getMetrics(): AgentMetrics;
+    /** 角色包管理器（角色+技能+规则的唯一真理源，system prompt 的唯一注入源） */
+    get rolePack(): RolePackManager | null;
+    /** 工具执行器（返回 null 表示 Agent 未初始化） */
     get tools(): ToolExecutor | null;
-    /**
-     * 技能管理器（可能为 null）
-     *
-     * 返回 null 时表示 Agent 未初始化或技能系统未加载。
-     */
+    /** 技能管理器（返回 null 表示未初始化或技能系统未加载） */
     get skills(): SkillManager | null;
-    /**
-     * 配置管理器（可能为 null）—— 规则/技能注入 + 配置建议
-     *
-     * 返回 null 时表示 Agent 未初始化。
-     */
-    get config(): ConfigManager | null;
-    /**
-     * Insight 提取器（可能为 null）—— 输入分类 + 记忆提取
-     *
-     * 返回 null 时表示 Agent 未初始化或 LLM Provider 未配置。
-     */
-    get insight(): InsightExtractor | null;
-    /**
-     * 记忆查看器（可能为 null）—— 快照 + 搜索 + 统计
-     *
-     * 返回 null 时表示 Agent 未初始化或存储层未就绪。
-     * 宿主项目常用模式：`const mem = agent.memory; if (!mem) return [];`
-     */
+    /** 角色包管理器（返回 null 表示未初始化或角色包系统未加载） */
+    get rolePacks(): RolePackManager | null;
+    /** 记忆查看器（快照 + 搜索 + 统计；宿主常用 `const mem = agent.memory; if (!mem) return []`） */
     get memory(): MemoryInspector | null;
-    /**
-     * 项目管理器（可能为 null）
-     *
-     * 返回 null 时表示 Agent 未初始化。
-     */
+    /** 项目管理器（返回 null 表示 Agent 未初始化） */
     get projects(): ProjectManager | null;
-    /**
-     * 用户画像管理器（可能为 null）—— 实时归档 + 确认/拒绝
-     *
-     * 返回 null 时表示 Agent 未初始化。
-     * 宿主常用模式：
-     *   - `agent.userProfile?.getPending()` 查询待确认条目
-     *   - `await agent.userProfile?.confirm(id)` 确认条目
-     *   - `await agent.userProfile?.reject(id)` 拒绝条目
-     */
-    get userProfile(): UserProfile | null;
-    /**
-     * 安全守卫（可能为 null）—— 写入确认回调注册
-     *
-     * 返回 null 时表示 Agent 未初始化或 projectPath 未设置。
-     * 宿主常用模式：
-     *   - `agent.security?.onWriteConfirmation(callback)` 注册写入确认回调
-     *   - 回调返回 true 允许写入，返回 false 拒绝写入
-     *
-     * 详见 M1 写入确认 UI 闭环
-     */
+    /** 安全守卫（写入确认回调注册：`onWriteConfirmation` 返回 true 放行、false 拒绝；未初始化/projectPath 未设为 null） */
     get security(): SecurityGuard | null;
-    /**
-     * 作品投影管理器（可能为 null）—— 文件内容 → 概要+结构+决策
-     *
-     * 返回 null 时表示 Agent 未初始化。
-     * 宿主常用模式：
-     *   - `agent.works?.ensureProjection(filePath, content)` 读取文件后触发生成
-     *   - `agent.works?.loadAll()` 获取所有投影
-     */
+    /** 作品投影管理器（用户主动登记的 JSON 极简索引；`registerWork`/`listWorks`/`loadAndGetContextBlock`/`isFileMalformed`） */
     get works(): WorkProjectionManager | null;
-    /** 会话管理器（宿主可通过此 getter 访问会话恢复/切换/分叉功能） */
+    /** 会话管理器（会话恢复/切换/分叉功能） */
     get sessionManager(): SessionManager | null;
-    /** 文本润色管理器（宿主可通过此 getter 调用 polish 方法） */
+    /** 文本润色管理器（polish 方法） */
     get polish(): TextPolishManager | null;
 }
 //# sourceMappingURL=agent.d.ts.map