@zooique/memora 2.0.3 → 3.0.0

package/dist/agent/loop.d.ts

@@ -1,423 +1,844 @@
 /**
- * Agent Loop — Agent 的核心执行引擎
+ * turn（问答闭环）Act 引擎（AgentLoop）— turn 回答中阶段的 loop（对 step 的编排，官方 Agent Loop 本义）
  *
- * 模型自主决定何时推理、何时调用工具，循环直到输出纯文本
- *
- * 上下文组装公式：
- *   上下文 = 用户主动输入 + Agent 记忆召回结果 + Agent Loop 工作记忆
- * 其中"Agent 记忆召回结果"由 Agent 层通过 processUserInput 的
- * recalledMemories 参数注入。
+ * 概念定位（所有复杂度在单 turn step 循环里承载，无多 turn 任务编排）：
+ *   - step = 一次 LLM 调用 + 可选工具执行（runIterationLoop 内每次循环体）；
+ *   - loop = 对 step 的编排：turn 回答中阶段反复拉起 step 直到输出最终回答；
+ *   - 本类承载 turn（问答闭环）的 Act 引擎（含 loop=step 编排），是 turn 的身体引擎；
+ *   - 复杂任务（task_table_write + 动态规划）在一个 turn 的 step 循环里自然生长，
+ *     不再强制拆成多 turn 编排；
+ *   - 上下文 = 用户输入 + Agent 记忆召回结果 + 运行帧追加。
  */
-import type { LlmProvider, Message } from '../llm/provider.js';
+import type { LlmProvider, Message, ChatOptions } from '../llm/provider.js';
+import type { ProviderRouter } from '../llm/types.js';
 import type { Memory } from '../memory/types.js';
 import type { ToolDefinition } from '../agent/toolExecutor.js';
-import type { AgentChunk, UIMessages } from '../agent/types.js';
+import type { AgentChunk, UIMessages, PreExecutionResult, AskQuestion } from '../agent/types.js';
 import type { ITracer, AgentMetrics } from '../agent/tracer.js';
+import type { ContextBudget, ContextOccupancy } from '../agent/budget.js';
+import type { ICompactionStrategy } from '../agent/compaction.js';
+import type { DuplicateCallInterceptor } from '../agent/types.js';
+import type { RoundEvidenceEvent } from '../memory/roundStore.js';
+import type { L2RuntimeStrategy } from '../role-pack/types.js';
 export interface AgentLoopOptions {
     provider: LlmProvider;
+    /** Provider 路由选择器（多模型路由基础，可选） */
+    providerRouter?: ProviderRouter;
     bootstrapMemories: Memory[];
     toolExecutor: (name: string, args: string) => Promise<string>;
     maxIterations?: number;
-    /** 系统 prompt 前缀（角色 + 用户画像 + 技能），注入到 bootstrap 记忆之前 */
+    /** 系统 prompt 前缀（角色包 prompt），注入到 bootstrap 记忆之前 */
     systemPromptPrefix?: string;
     /**
-     * 情感基调前缀（Phase 2.1：AffectController 注入）
-     *
-     * 在 systemPromptPrefix 和 bootstrapMemories 之间插入。
-     * 由 Agent.injectAffect() 设置，角色切换时保留。
+     * 当前激活角色包底盘占用（system prompt 总体 token），装配时即确定。
+     * 早于 prepare 写入，使冷启动 / 重启首屏即可显示真实占比；prepare 期以其实际值覆盖，口径一致。
      */
+    rolePackBaseTokens?: number;
+    /** 情感基调前缀，插在 systemPromptPrefix 与 bootstrapMemories 之间（injectAffect 设置，角色切换时保留） */
     affectPrefix?: string;
-    /** v4.0：工具定义列表（内置 + 自定义），用于 system prompt 追加工具描述 */
+    /** 任务表触发覆盖钩子：宿主可覆写 needsPlanning 判定。
+     *  缺省用内核内置 detectNeedsPlanning（确定性判定）。返回 true → 首迭代注入命令式强引导。 */
+    needsPlanningOverride?: (text: string) => boolean;
+    /** 工具定义列表（内置 + 自定义），用于 system prompt 追加工具描述 */
     toolDefinitions?: ToolDefinition[];
-    /**
-     * 上下文窗口 token 上限（默认 32000）
-     *
-     * 桌面精灵等长运行场景下，messages 数组随对话轮次无限增长会爆 LLM 上下文窗口。
-     * 当估算 token 数超过此阈值时，保留 system prompt + 最近 N 条消息，
-     * 裁剪中间段，确保 LLM 请求不因上下文溢出而失败。
-     *
-     * 保守默认值 32000 token 对多数模型安全（DeepSeek 128K / GPT-4o 128K / 豆包 8K），
-     * 宿主可通过 AgentLoopOptions 覆盖。
-     */
+    /** 内置工具定义列表，仅含内置工具，供只读模式（toolReadonly）查询 readonly 标记 */
+    builtinTools?: ToolDefinition[];
+    /** 上下文窗口 token 上限（默认 120_000）。估算 token 超此阈值时裁剪中间段，
+     *  仅保留 system prompt + 最近 N 条消息，防上下文溢出。 */
     maxContextTokens?: number;
     /** 可观测性 Tracer（宿主注入，默认 NOOP_TRACER 静默丢弃所有 span） */
     tracer?: ITracer;
-    /**
-     * 内容护栏规则（启动时从 configDir 加载的 guardrail 记忆）
-     *
-     * 每条规则包含 pattern（正则字符串）和 action（block/warn）。
-     * 在对话输入和输出阶段分别检查，命中 block 时阻断对话。
-     * 护栏自身异常时降级为"放行 + 记日志"，不阻断用户对话。
-     */
-    guardrailRules?: readonly Memory[];
-    /**
-     * Reflection（反思/自修正）最大重试次数（默认 2）
-     *
-     * 当工具执行失败且错误码标记为 retryable 时，
-     * AgentLoop 会将错误上下文回传给 LLM 重新尝试，
-     * 而非立即结束当前迭代。超过此上限后放弃反思。
-     */
+    /** Reflection 最大重试次数（默认 2）。工具失败且错误码 retryable 时回传 LLM 重试，超限放弃 */
     maxReflectionRetries?: number;
     /** 宿主可覆盖的 UI 消息文本（默认英文） */
     messages?: UIMessages;
-    /**
-     * 上下文超限时是否自动生成摘要（默认 true）
-     *
-     * 开启后，当消息历史超过 maxContextTokens 时，
-     * 会对被裁剪的消息调用 provider 生成一段摘要注入到系统提示中，
-     * 避免关键信息永久丢失。（首次触发时增加 ~1-2s 延迟）
-     */
+    /** 上下文超限时是否自动生成摘要（默认 true）。会调 provider 为被裁剪消息生成摘要注入
+     *  系统提示，避免关键信息丢失（首次触发约 +1-2s 延迟） */
     enableContextSummary?: boolean;
-    /**
-     * 上下文截断回调（宿主可据此发射 contextTruncated 事件通知用户）
-     *
-     * 每次 truncateMessages 触发截断时调用，传入被裁剪和保留的消息数量。
-     * 未注入时静默忽略。
-     */
+    /** 上下文截断回调（传被裁剪/保留消息数），宿主可据此发 contextTruncated 事件；未注入静默忽略 */
     onContextTruncated?: (skippedCount: number, keptCount: number) => void;
-    /**
-     * 护栏规则正则编译失败回调（宿主可据此发射 guardrailError 事件通知用户）
-     *
-     * 每次 runGuardrails 遇到正则编译异常时调用。
-     * 未注入时仅记日志（降级优先原则，不阻断对话）。
-     */
-    onGuardrailError?: (rule: string, message: string) => void;
+    /** LLM 主动压缩完成回调（第二级压缩，传压缩目标/被替换消息数/摘要长度）；未注入静默忽略 */
+    onContextCompressed?: (target: 'earliest_round' | 'largest_tool_result', replacedCount: number, summaryLength: number) => void;
+    /** 工具执行完成回调（供 outbox 模式恢复时判断工具是否已执行过，避免重复执行）；未注入静默忽略 */
+    onToolExecuted?: (name: string, args: string, result: string, ok: boolean) => void;
+    /** 工具执行前检查回调（宿主闸门）。三态：放行（可携 overrideArgs 改写参数）/ 跳过
+     * （返回 previousResult 幂等去重）/ 拒绝（阻止执行）；未注入时正常执行 */
+    preExecutionCheck?: (name: string, args: string) => PreExecutionResult;
+    /** 主动提问回调（回答中 LLM 调 ask_user 工具时调用，loop 只回调不处理 UI） */
+    onPendingQuestion?: (questions: AskQuestion[]) => void;
+    /** 已存轮次摘要加载器。截断生成摘要前优先取持久化 round-summary（零成本保真），仅无已存时才现调 LLM */
+    roundSummaryLoader?: () => string;
+    /** 截断时最少保留的最近原始对话轮数（默认 0），宿主可据 provider prompt caching 能力放宽 */
+    minRecentRounds?: number;
+    /** ChatOptions 覆盖项（角色包策略注入 temperature/outputLimit 等；与默认值的关系见 defaultMaxTokens） */
+    chatOptions?: Partial<ChatOptions>;
+    /**
+     * per-LLM 输出预算默认值（token，宿主 per-LLM 配置透传）：buildChatOptions 填入底座，
+     * 与角色包策略覆盖项（chatOptions，act.outputLimit）**取更小值**（两者都是「上限」性质，
+     * 须同时满足——对齐上下文窗口 min(provider 窗口, 角色包 contextLimit) 的语义）。
+     * undefined = 不传 max_tokens（回服务端默认）。请求层只做形态归一（非正整数不传），
+     * 上限不裁决——本层与请求层均不设上限（真实上限由服务端裁决，见 normalizeMaxTokens）。
+     */
+    defaultMaxTokens?: number;
+    /** 上下文压缩策略（微压缩层，每轮把旧 tool_result 替换为占位符省空间）；
+     *  默认 ResultReplacementStrategy（保留最近 3 次完整结果），宿主可注入自定义策略。
+     *  作为两级空间管理的**第二级**（tool_result 占位）参与压缩链 */
+    compactionStrategy?: ICompactionStrategy;
+    /** 已存轮次摘要按 roundId 取（替换式压缩第一级用）；未注入时替换层降级为 no-op（返回 null） */
+    getRoundSummary?: (roundId: string) => string | null;
+    /** 替换式压缩保留最近正文轮数（默认 DEFAULT_REPLACE_KEEP_RECENT_ROUNDS=5，LRU 最早先换） */
+    replaceRoundsKeepRecent?: number;
+    /** 工具结果卸载（入口关）的落盘目录（装配注入项目 `memoraDir` 下的 outputs 子目录）。
+     *  未注入则入口关不生效（超阈结果原样入上下文）——内核不派生此路径，防产出信任根外、
+     *  `read_file` 读不回的假引用（OFFLOAD-1 教训） */
+    offloadDir?: string;
+    /** 重复工具调用拦截器。每轮工具执行后调用 check() 决定注入 warning 或 block；
+     *  未注入时用 DefaultDuplicateCallInterceptor（哈希机械检测），宿主可注入差异化策略 */
+    duplicateCallInterceptor?: DuplicateCallInterceptor;
 }
 export declare class AgentLoop {
+    #private;
     private readonly opts;
     private messages;
     private readonly maxIterations;
-    /** 上下文窗口 token 上限（默认 32000，约 96K 中文字符） */
-    private readonly maxContextTokens;
+    /** provider 上下文窗口（原始声明值，默认 120_000）。模型热切换经 setContextWindow 写入。 */
+    private providerContextWindow;
+    /** **有效上下文窗口** = min(providerContextWindow, strategy.contextLimit>0 ? contextLimit : ∞)。
+     *  派生值（非独立真源）：由 #recomputeEffectiveWindow 在「provider 窗口变更」与「角色策略变更」
+     *  两个入口重算；是截断 / 软上限 / 占用快照统一消费的唯一窗口数字。 */
+    private maxContextTokens;
     /** 可观测性 Tracer（默认 NOOP_TRACER 零开销） */
     private readonly tracer;
-    /** 内容护栏规则（启动时加载，运行时不可变） */
-    private readonly guardrailRules;
     /** Reflection 最大重试次数（默认 2） */
     private readonly maxReflectionRetries;
-    /**
-     * 当前轮次已推送的 REFLECTION_HINT 次数（显式计数器）
-     *
-     * 替代旧实现通过 messages.filter(startsWith('[REFLECTION_HINT]')).length 推断的方式——
-     * 当 ContextManager 裁剪中间段消息时，REFLECTION_HINT 可能被裁掉导致计数失真。
-     * 显式字段不受 messages 数组变动影响，状态机更健壮。
-     */
+    /** 上下文压缩策略（微压缩层），默认 ResultReplacementStrategy，经 options 可注入自定义策略 */
+    private readonly compactionStrategy;
+    /** 重复工具调用拦截器实例，默认 DefaultDuplicateCallInterceptor（哈希机械检测） */
+    private readonly duplicateCallInterceptor;
+    /** 重复工具调用检测阈值（默认 3 次，供拦截器 context 使用） */
+    private readonly duplicateToolCallThreshold;
+    /**
+     * 执行期临时 system 消息引用集（self-review / reflection / duplicate-warning / metaNote）。
+     * 与 prepare 阶段的「装配性注入」（召回、最近对话）区分：装配注入每轮由 prepare 重建、
+     * 不算临时，吃 cleanTemporarySystemMessages；执行期临时的清理由每轮闭环入口自动执行
+     * （cleanExecutionTemporary），保证跨步残留不堆积。replaceContext 走浅拷贝，
+     * 引用保持有效，按引用 filter 即可安全移除。
+     */
+    private readonly executionTempSystem;
+    /** 上一轮工具调用的哈希（运行时状态，拦截器判定时使用） */
+    private lastToolCallsHash;
+    /** 连续重复次数（运行时状态，拦截器判定时使用） */
+    private duplicateToolCallCount;
+    /** 当前迭代序号（processUserInput 循环内维护，供拦截器 context 与 toolResultCache 老化使用）。
+     *  语义边界：本计数 = **循环内**迭代号（runIterationLoop 重启即从头）；轮粒度 step 序号
+     *  （thought 归属打标）另见 roundStepIndex——两者重置域不同（循环 vs 轮），勿互替。 */
+    private currentIteration;
+    /** 当前轮次已推送的 REFLECTION_HINT 次数。用显式计数器而非 filter 推断，
+     *  避免上下文中段消息被裁剪后计数失真 */
     private reflectionCountThisTurn;
+    /** 搜索收敛护栏：本闭环内成功 web_search 次数（executeToolCalls 累计，_prepareContext 检查） */
+    private successfulWebSearchCount;
+    /** 搜索收敛护栏：本轮是否已注入收敛提示（幂等，防迭代累积刷屏） */
+    private searchConvergenceHintInjected;
+    /** 搜索硬上限：本闭环内 web_search 调用次数（含被拒绝的，达到上限后后续搜索直接拒绝） */
+    private searchCallCount;
+    /** 搜索硬上限命中后：从后续 LLM 调用的工具集确定性移除 web_search（双闸的第二闸，
+     *  与 system 提示互补，彻底终结「拒绝风暴」耗尽迭代/上下文导致问答闭环中断） */
+    private searchDisabled;
+    /** 搜索硬上限提示注入标记（幂等，防迭代累积重复注入） */
+    private searchDisabledHintInjected;
+    /** 软上限收尾信号注入标记（幂等，防迭代累积刷屏）：摘要层饱和是跨迭代持续态，
+     *  同一 turn 内经本 flag 最多注入一次收尾信号；随 resetTurnState 重置——
+     *  每个新 turn（新用户输入）重新注入一次（每轮回答都需要收敛提醒），
+     *  防的是「同 turn 多步迭代各注一条」的刷屏（口径与搜索收敛 flag 同构）。 */
+    private softLimitWrapupInjected;
+    /** 规划层：本 turn 是否判定为需任务表规划（processUserInput 入口由检测结果设值，
+     *  continueAfterPause 续跑不重判——plan 已建则无需 nudge） */
+    private planNeedsNudge;
+    /** 规划层：本 turn 是否已注入命令式引导（幂等，仅首迭代一次，随 resetTurnState 重置） */
+    private planNudgeInjected;
+    /** 工具结果防重缓存（闭环内有效，每轮 resetTurnState 清空）。
+     *  拦截 read_file/list_dir/web_search 的同 key 重复调用，返回 [ALREADY_READ] 拒绝文案，
+     *  终结 LLM 在同一批文件上反复轮询导致的死循环（token 爆炸 + maxIterations 撞线） */
+    private readonly toolResultCache;
+    /** 文件覆盖度台账（账本・解耦侧）：读到的行区间 + 轻量替身摘要。
+     *  闭环内有效（resetTurnState 清），与 toolResultCache 同生命周期。
+     *  替身回显分支据此在「原文已压缩」时回显摘要，而非放行重读（永动机）或空拦（死锁）。 */
+    private readonly fileExposure;
+    /** 运行时护栏注册表（SSOT）：判定序 / 文案 / 阈值单一真理源在 guardRail.ts；
+     *  本字段只是 loop 的装载点（createDefaultGuards 出厂即覆盖 5 类前置拦截型护栏）。
+     *  write_loop/read_failed 的计数状态内聚进其 guard 实例闭包，loop 仅负责
+     *  装载 registry + 调 evaluateBlocked 判定 + 调 notifyExec 写侧喂数 + reset 归零。 */
+    private readonly guardier;
+    /** 队列中是否有待消费的 pause 申请 */
+    private hasPendingPause;
+    /** 幂等申请 pause 入队（已存在则不重复追加） */
+    private requestPauseEntry;
+    /** 移除队列中的 pause 条目（保留 interject 条目） */
+    private cancelPauseEntry;
+    /** step 边界气口申请统一队列（pause/interject 统一入队，无独立 pauseRequested flag）。
+     *  用户申请的气口（pause/interject）统一入队，_handleInterrupt 在 step 边界消费：
+     *  先注入型（interject → appendUser），后挂起型（pause → yield paused）。 */
+    private interruptQueue;
+    /** 主动提问回调（LLM 调 ask_user 工具时调用，Agent 注入，loop 只回调不处理 UI） */
+    onPendingQuestion?: (questions: AskQuestion[]) => void;
+    /** 有效窗口变更回调（Agent 注入）：把 loop 算出的**有效窗口**分发给 loop 之外仍持有窗口拷贝的
+     *  组件（ContextPreparer 等）。计算点唯一在 loop（#recomputeEffectiveWindow），本回调只做分发。 */
+    onContextWindowChanged?: (effectiveTokens: number) => void;
+    /** 单工具执行器（独立可测单元；strategy/回调经闭包读最新） */
+    private readonly toolRunner;
+    /** L2 运行时策略（单一策略对象）。Agent 每轮经 setStrategy 注入，构造期默认 DEFAULT_L2_STRATEGY */
+    private strategy;
+    /** 本 turn 是否已执行过自审查（单次终审：布尔状态，不再需要轮次计数） */
+    private selfReviewDone;
+    /** 本 turn（processUserInput）内是否实际执行过工具步。
+     *  自审查的唯一触发门槛：只有多轮 turn（发生过工具调用）才审查，
+     *  一遍过的纯文本问答不触发。由 processUserInput 入口重置（续跑 continueAfterPause 保留）。
+     */
+    private toolExecutedThisTurn;
+    /** 当前轮次 ID（processUserInput 入口分配一次，各 iteration 共享），用于溯源式摘要 */
+    private currentRoundId;
+    /** 是否正处于自主工具步执行中（内核自用：resumeExecution 预判短路 / canContinueWithoutInput；宿主零消费） */
+    private inAutonomousStep;
+    /** step 边界回调——每次迭代（=step）完成时调用（传 assistant 摘要）。消费方（assembler 实现）
+     *  经 logPlanItemBoundary 写 planItemLog 关联当前 active 任务项（时间轴投影）——
+     *  不推进 plan：状态推进唯一写者 = LLM 的 task_table_update；LLM 未显式 update 的最后一个任务项
+     *  由 turn 收尾兜底（orchestrator → concludeActivePlanItemIfPlanFullyReached）补上。
+     *  planItemId 由消费方自查，loop 不传——签名不留空头支票。
+     *  检出时机 = 本迭代 LLM 调用后、工具前（读「本迭代服务的那个任务项」）。 */
+    onPlanItemBoundary?: (planItemInfo: {
+        summary: string;
+    }) => void;
+    /** 任务表获取回调——每次迭代 LLM 调用前调用，返回任务表文本（空字符串=无任务表） */
+    getTaskTable?: () => string;
+    /** active 任务项元信息回调（任务项级折叠）：供 _maybeEmitPlanItemBoundary
+     *  在**迭代开始**（LLM 调用前）调用，返回当前 active 任务项 { planItemId, title, rolePack }；
+     *  无任务表/无 active 任务项返回 null。与 onPlanItemBoundary **时序分叉**：后者读 LLM 调用后、
+     *  工具前的 active（本迭代 LLM 实际服务的任务项），本回调经 _maybeEmitPlanItemBoundary 读迭代
+     *  开始时的 active（以下内容将归属的那个任务项）——plan_item_boundary 事件据此判定
+     *  「active 任务项是否已推进」并分组渲染。两者读的都是同一 checkpoint.plan 真源，仅读取时刻不同。
+     *  rolePack 供裁决证据的会议轮判据（isMeetingRound）消费。 */
+    getActivePlanItemMeta?: () => {
+        planItemId?: string;
+        title?: string;
+        rolePack?: string;
+    } | null;
+    /** 裁决证据落盘钩子（悬案取证轨）：空响应兜底 / 台账替身回显写点产个案证据时回调，
+     *  由装配层接 history.appendEvidence 归属当前闭环轮随 Round 持久化。未注入静默忽略。 */
+    appendRoundEvidence?: (ev: RoundEvidenceEvent) => void;
+    /** 在途任务表判定回调：本 turn 是否已有未完成的计划任务项（会议骨架预置 / 续会）。
+     *  装配来源 = SessionManager.hasInflightPlan（单一真理源）；用途 = needsPlanning nudge 注入前
+     *  判断「是否已有在途表」，有则不重复灌「先拆解建表」。
+     *  刻意**不复用** getActivePlanItemMeta 的存在性——后者原生职责是 plan_item_boundary 事件信号，
+     *  借它回答本命题属语义借用（二者在 ensureActivePlanItem 不变量下当前等价，但职责须分离）。 */
+    hasInflightPlan?: () => boolean;
+    /** 上一任务项边界 ID（去噪）：记录最近一次已 emit plan_item_boundary 的 planItemId，
+     *  仅当 getActivePlanItemMeta 返回的 planItemId 变化时才产新事件；null/undefined 不产（无任务表静默）。 */
+    private lastBoundaryPlanItemId?;
+    /** 轮内 step 序号（轮粒度单调）：「这条思考是第几步产生的」唯一真源计数，thought 归属由它打标。
+     *  每次 LLM 调用（= 一个 step）前递增；随 currentRoundId 分配重置（processUserInput），
+     *  continueAfterPause 续同一轮**不重置**——序号跨续跑段继续单调，同轮各 step 永不撞号。 */
+    private roundStepIndex;
+    /** 主动提问计数（本 turn 粒度，resetTurnState 清零）：ask_user 工具触发次数（askLimit 硬护栏） */
+    private askCountThisTurn;
+    /**
+     * 在途提问登记（ask_user 工具轮挂起后、回答回填前）：记录各 ask_user 调用的 toolCallId
+     * 与解析出的结构化问题。answerQuestion（正常作答）/ cancelAsk（跳过/兜底）二选一消费。
+     */
+    private pendingAsk;
+    /**
+     * 已作答/已取消提问快照（answerQuestion 与 cancelAsk 消费提问后对称转存）：
+     * 提问消费后把 pendingAsk.questions 转存于此，供 orchestrator.runResume
+     * 落盘交互输入时随回答/超时记录一并持久化（回放还原「问了什么+选项」）。
+     * pendingAsk 即清（runIterationLoop 兜底 cancelAsk 依赖其为「未消费」判据）；
+     * 快照由 runResume takeAnsweredAsk 取走，或下次消费覆盖（残留仅进程内、单 turn，无害）。
+     */
+    private lastAnsweredAsk;
     /** 宿主可覆盖的 UI 消息文本（已填充默认值） */
     private readonly ui;
-    /** 护栏规则正则编译失败回调（从 opts.onGuardrailError 提取，用于 GuardrailUI） */
-    private readonly guardrailUI;
     /** 上下文超限时是否自动生成摘要 */
     private readonly enableContextSummary;
+    /** LLM 主动压缩完成回调（第二级压缩，在 compressContext 成功后触发） */
+    private readonly onContextCompressed;
     /** 上下文管理器（从 loop 提取的 token 估算 + 截断 + 摘要职责） */
     private readonly contextManager;
+    /** 被替换轮 roundId 集合（第一级替换把越界轮正文换成已存摘要；装配 exclude 据此防二次召回） */
+    private readonly replacedRoundIds;
+    /** 最近一次输入装配的上下文预算（prepare 期写入，供指标快照透出做预算可视化） */
+    private lastBudget;
+    /** 最近一次输入装配的上下文占用快照（预算可视化，真实用量） */
+    private lastOccupancy;
+    /**
+     * 当前激活角色包底盘占用（system prompt 总体 token）。
+     * 装配 / 切换角色包时经 setRolePackBaseTokens 写入（早于 prepare，冷启动即可用），
+     * prepare 期 recordOccupancy 也以其实际值覆盖，口径一致（同一 estimateTokensMessages 估算器）。
+     */
+    private rolePackBaseTokens;
+    /** 最近一次 _prepareContext 是否发生截断重排（替换层据此跳过——截断提取 key messages 重插中间，roundId 尾部对齐失效） */
+    private isLastContextTruncated;
+    /** 两级空间管理压缩链（第一级替换 → 第二级 tool_result 占位）。超大结果卸载已在入口关处理，不在链上 */
+    private readonly compactionStrategies;
+    /** 入口关落盘目录（装配注入；未注入则入口关不生效）。消费点：appendToolMessage */
+    private readonly offloadDir?;
+    /** 情报区（LLM 私有工作笔记）：LLM 经 remember_intel 自写累积，装配时作为尾部私有 system 消息注入 */
+    private intelNote;
+    /** Provider 路由缓存（单轮内缓存同一 taskType，避免每轮重复路由计算），跨轮清空不复用 */
+    private providerRouteCache;
     private metrics;
+    /** LLM 调用族执行器。**必须在构造函数尾部初始化**——依赖 `contextManager` /
+     *  `tracer` 等构造期赋值的字段（类字段初始化器按声明顺序执行，此处读会得到 undefined）。
+     *  其所有 loop 侧能力均为**取值器 / 回调**：`strategy`（setStrategy 换对象）、
+     *  `opts.provider`（setProvider 热切换）、`toolExecutedThisTurn`（同 turn 内 set true）
+     *  皆运行时可变量，且 `errorHandling` 在重试循环内被读 3 次。
+     *  `providerRouteCache` 仍是 loop 字段（每轮 turn 入口清空），本类只经回调读写。 */
+    private llmCaller;
     constructor(opts: AgentLoopOptions);
     /**
-     * 处理一轮用户输入（编排方法）
-     *
-     * 拆分为 4 个子方法：
-     *   - handleRecallAndInputGuard：召回注入 + 输入护栏
-     *   - handleIteration：单次迭代编排（abort 检查 + LLM 调用 + 分支路由）
-     *   - handleToolCalls：工具调用分支 + Reflection
-     *   - handleTextResponse：纯文本结束 + 输出护栏
-     *
-     * @param userInput - 用户原始输入
-     * @param recalledMemories - 记忆召回结果（Agent.memory.search() 产出），
-     *   可选。传入时自动注入到上下文，实现"Agent 记忆召回结果"层
-     * @param signal - 可选的 AbortSignal，用于取消正在进行的对话
-     *   泊文等宿主 UI 传入 AbortController.signal，用户点击"取消"时触发 abort
-     */
-    processUserInput(userInput: string, recalledMemories?: readonly Memory[], signal?: AbortSignal): AsyncGenerator<AgentChunk, void, unknown>;
+     * 处理一轮用户输入（编排方法：单次迭代/工具分支/纯文本结束）
+     *
+     * 记忆检索唯一入口 = LLM 经 `search_memories` 工具主动触发（builtinToolHandlers.searchMemories），
+     * prepare/loop 不代模型猜测注入（无 recalledMemories 自动注入通道）。
+     *
+     * @param userInput - 用户输入
+     * @param signal - 可选 AbortSignal，宿主导入 controller 触发取消
+     * @param roundId - 外部已分配轮次 ID（保证 user/assistant/摘要同 roundId），未传自生成
+     */
+    processUserInput(userInput: string, signal?: AbortSignal, roundId?: string): AsyncGenerator<AgentChunk, void, unknown>;
+    /**
+     * 软暂停后续跑（在暂停边界后从保留的 this.messages 重新进入 step 循环引擎）
+     *
+     * 有补充输入时先 push 为 user 消息再续跑
+     */
+    continueAfterPause(input?: string, signal?: AbortSignal): AsyncGenerator<AgentChunk, void, unknown>;
+    /**
+     * turn 入口通用 SLO 包装：统一任务计数 + 耗时累加 + 成功/失败判定 + 可选 tracer span 写属性。
+     *
+     * @param span 可选 tracer span（processUserInput 有 responseSpan；续跑路径无 span 传 null）
+     * @param genFn 生成迭代器的工厂函数（惰性求值：在 try 块内调用，保证异常被 catch）
+     */
+    private _runWithSlo;
+    /** 是否正处于自主工具步执行中（消费者 = agent.ts 预判短路/canContinueWithoutInput，内核内部） */
+    get isInAutonomousStep(): boolean;
+    /**
+     * 给子生成器的每个 chunk 附加当前 turn roundId（SSOT：过程事件归属由内核唯一提供）。
+     * 宿主据此把 ProcessEvent 落盘到正确的 Round。
+     * 两个 turn 入口（processUserInput / continueAfterPause）统一经此包装。
+     */
+    private withRound;
+    /**
+     * step 归属打标：给子生成器的 thought chunk 附加所属 step 序号（SSOT：「这条思考是第几步产生的」
+     * 由 loop 唯一提供，随 thought 本体落盘，消费方无需从工具序列推断迭代边界）。
+     * 仅 thought 需要归属（按 step 分桶渲染），其余 chunk 原样透传。
+     * 与 withRound 同构的边界打标模式；被包子生成器带返回值（LlmCallResult），
+     * 故用手动迭代转发返回值（for-await 会丢弃 generator 返回值）。
+     */
+    private withStepIndex;
+    /** 设置 L2 运行时策略（与现策略浅合并）。默认值仅在策略解析层 resolveL2Strategy 归一，loop 不再兜底。
+     *  策略含 contextLimit → 变更后重算有效窗口（截断 / 软上限 / 占用快照随之生效）。 */
+    setStrategy(partial: Partial<L2RuntimeStrategy>): void;
+    /**
+     * 请求在下一 step 边界挂起（软暂停申请入队）。
+     * 委托 requestPauseEntry（幂等入队），step 边界由 _handleInterrupt 消费。
+     * 仅挂起不 abort，可经 continueAfterPause 续跑——与硬停止（signal.abort 无法续跑）严格区分；
+     * 暂停语义与持久化由状态机持有，本方法只控制挂起时机。
+     */
+    requestPause(): void;
+    /** 清除在途的软暂停申请（与 requestPause 对称：用户取消/流结束清理/暂停超时清扫共用）。
+     *  委托 cancelPauseEntry 移除 pause 条目（保留 interject 条目） */
+    clearPauseRequest(): void;
+    /** 插话（申请入队）：把用户补充输入作为 InterruptRequest{kind:'interject'} 入 interruptQueue。
+     *  与 requestPause（queueInterrupt pause）同为「申请 → 气口生效」——不中断当前 LLM/工具执行，
+     *  只在 step 边界统一消费（先注入型 → appendUser，后挂起型 → yield paused）。 */
+    interject(content: string): void;
+    /** 删除待注入的插话（宿主 UI 层用户后悔）。与 interject 对称，在 step 边界消费前可安全删除。
+     *  委托 interruptQueue 中 interject 条目的索引。
+     *  index 越界时静默 no-op（宿主镜像数组和内核队列始终同序同长度，理论上不会越界）。
+     *  @returns true=成功删除；false=index 越界或队列为空 */
+    removePendingInterject(index: number): boolean;
+    /** 清空全部待注入插话（宿主「全部清空」按钮或 stop→discard 协同清理）。
+     *  与 removePendingInterject 单条删除对称，覆盖宿主镜像与内核队列不对称缺口——
+     *  clear_pending_queue handler 若只清镜像不清内核会成单写缺口；
+     *  agent.discardCurrentCheckpoint 若只清 checkpoint 不清队列会留孤儿数据。
+     *  @returns 被清除的条目数（宿主可用于 notice 反馈） */
+    clearPendingInterjections(): number;
+    /** 读取当前待注入插话队列快照（宿主渲染层只读镜像）。
+     *  从 interruptQueue 中筛选 kind='interject' 并提取 content。
+     *  返回副本而非原数组——宿主拿不到内核内部引用，防暗改。
+     *  宿主侧收敛：不再自己维护 _pendingQueue 镜像，每次渲染从内核读。 */
+    getPendingInterjections(): readonly string[];
+    /** 输出"达到最大迭代/步数预算"提示并结束（turn act 收尾兜底，多入口共享） */
+    private emitMaxIterationsReached;
+    /** 重置本轮运行计数状态（反思/重复检测/软暂停/自审查/工具步，每轮独立；续跑入口同样调用） */
+    private resetTurnState;
+    /** 重置 askLimit 计数（turn 入口）：仅 processUserInput 调用，continueAfterPause 不动，
+     *  保证暂停-续跑同属一次用户输入、提问次数跨续跑累计（askLimit 语义：按输入打扰防刷）。 */
+    private resetAskBudget;
+    /**
+     * 单轮 step 循环引擎（turn act 内 step 编排）：一次循环 = 一次 handleIteration（processUserInput/continueAfterPause 共享）。
+     * stepBudget 软上限与 maxIterations 兜底在此统一收敛。
+     * 注：所有复杂度（含 LLM 动态建任务表、会议机制角色切换）在单 turn 内承载（无多 turn 编排）。
+     */
+    private runIterationLoop;
+    /** 处理一次迭代结果（processUserInput/continueAfterPause 共享）。
+     *  continue→继续；paused→终止（step 边界挂起待续跑）；aborted→终止（硬中止，排队插话已留档）；
+     *  done→有自审查/排队插话待注入则继续，否则终止。返回 false 表示调用方应终止循环 */
+    private handleIterationResult;
+    /**
+     * 自审查注入判定（emit selfReview 通知与注入 SELF_REVIEW 提示共用单一真理源）。
+     *
+     * 需同时满足：
+     * 1. 启用自审查（selfReviewEnabled）；
+     * 2. 非工具屏蔽（toolCallsBlocked 时 'done' 来自系统占位文本而非 LLM 回复）；
+     * 3. **单次终审语义**：
+     *    - 多轮 turn 门槛：本 turn 内实际执行过工具步（一遍过的纯文本问答不审查）；
+     *    - **终审即停：本 turn 已审过（selfReviewDone）则一律不再安排**。审查轮产出后
+     *      done 立即真实生效——自审只对「工具循环后的最终交付」做一次把关，不因需修改
+     *      而无限续跑空转（防 done 后反复审查拖长 turn）。深度"审查→
+     *      修正"的迭代属目标模式阶段验收，非单次问答闭环职责。
+     */
+    private shouldInjectSelfReview;
+    /** 单次迭代编排：编排中断检查 → 上下文准备 → LLM 调用 → 结果路由。
+     *  按抽象层拆分为 _handleInterrupt / _prepareContext / _callAndRoute，
+     *  编排者只保留顺序，各阶段职责内聚在小方法（保持单轮 turn 结构完整）。 */
+    private handleIteration;
+    /** 消费申请列表中的注入型（interject → appendUserMessage）条目。
+     *  单一真理源——_handleInterrupt（step 边界，splice 取出的局部列表）和 done 分支
+     *  （LLM 收尾兜底，全局 queue）共用同一遍历 + append 实现，防两处独立实现导致
+     *  消费逻辑漂移（如加去重/计数时改一处漏一处）。
+     *  删除语义留在调用方：_handleInterrupt 的 reqs 已 splice 出队无需再删；
+     *  done 分支消费后自行过滤全局 queue（pause 条目保留待下轮边界消费）。
+     *  @param reqs 待消费的申请列表（只读遍历，不修改）
+     *  @returns 消费的 interject 条目数（调用方可据此决定是否继续迭代） */
+    private _consumeInterjects;
+    /** 中断检查：step 边界统一消费 interruptQueue（pause + interject）+ 硬中止检查。
+     *
+     *  单一气口出口——气口申请统一收在 interruptQueue（无独立 pause flag / 插话数组写位），
+     *  此处统一 queue.splice(0) 取出全部申请，按 kind 分两类处理：
+     *    - 注入型（interject）：先 appendUserMessage，不暂停 loop，让补充输入立刻进入下一轮 step
+     *    - 挂起型（pause）：yield {type:'paused'} + return 'paused'，generator 在 step 边界挂起
+     *
+     *  顺序：先消费注入型 → 再检查挂起型 → 最后硬中止。注入型优先是为了让补充输入在 pause 生效前
+     *  就入史——如果用户同时发了 interject + pause，补充输入应该被看到，而不是被 pause 吞掉。
+     *
+     *  返回 'paused' | 'aborted' 表示本迭代终止；返回合并后的 AbortSignal 表示继续。 */
+    private _handleInterrupt;
+    /** 超时 + 用户已申请暂停 → 路由 paused（续跑）而非 aborted（硬中止）。
+     *  SSOT：LLM 调用 abort 点（_callAndRoute）与工具执行 abort 点（handleToolCalls）统一过此判定，
+     *  消除「pause 优先于 abort」在两处各复制 if 的漂移风险。
+     *  注：step 边界（_handleInterrupt）的气口消费是另一机制——那里 pause 在 abort 之前被优先消费，
+     *  不属 abort 路由，故不经本方法。返回 paused chunk 或 null。 */
+    private _routePausedIfTimeoutAndPause;
+    /** LLM 调用 + 结果路由：上下文准备 → 调 LLM → 按 abort/工具/纯文本 分支路由。
+     *  effectiveSignal 已由 _handleInterrupt 合并好，此处直接使用。 */
+    private _callAndRoute;
+    /** 任务项级折叠边界事件产出（产出的是 plan_item_boundary，**不是** step_boundary——
+     *  方法名与产出事件名必须同阵营，勿据「step」误读为迭代边界）：
+     *  比较 active 任务项是否已推进，推进才产 plan_item_boundary（宿主按任务项分组后续事件）。
+     *  无任务表（null）或 planItemId 未变则不产（lastBoundaryPlanItemId 去噪，避免每迭代发一条空边界）。
+     *
+     *  **检出时机 = 迭代开始、LLM 调用之前（硬，2026-09-26 定案）**：边界的语义是「**以下内容**
+     *  属于该任务项」，故必须产在它所罩住的思考与工具之前——放在工具落定之后，宿主
+     *  「向前找最近边界」的判据对该迭代必然落空 → 每个任务项的首个迭代（思考 + 首批工具）恒掉出
+     *  折叠块，且流式插入后不搬家（「任务项边界产出时机前移」定案）。
+     *
+     *  语义后果（可接受，非缺陷）：任务表若由本轮某迭代的工具**新建**，该迭代仍留在组外——
+     *  那个时刻任务表还不存在。本产出点修的是「任务表在本轮开始前已存在」（续会/预置/上一 turn
+     *  遗留）的场景。
+     *
+     *  与 `onPlanItemBoundary`（写 planItemLog）的**时序分叉仍是设计语义**：后者在 LLM 调用后、
+     *  工具前读 active（= 本迭代 LLM 实际服务的任务项），本处在迭代开始读（= 以下内容将归属的
+     *  任务项）。两者读同一真相源 `sessionManager.getCheckpoint().plan`，只是读取时刻不同。
+     *
+     *  落点还必须在 `_handleInterrupt` 之后：挂起/中止的迭代不应先产一条边界再退出。
+     *  roundId 由 withRound 统一附加（chunk 归属 SSOT），此处不再自带。 */
+    private _maybeEmitPlanItemBoundary;
+    /** 迭代边界产出（迭代原子落盘）：迭代**完成且将继续下一轮**时 emit
+     *  `step_boundary`，宿主据此增量落盘（一次迭代一次落盘）。
+     *
+     *  **为什么单开一个 chunk 而不复用 plan_item_boundary**：plan_item_boundary 的语义是「任务项推进」
+     *  （无任务表静默 + planItemId 未变去噪），把它当落盘时机 → 无任务表的长工具循环零增量落盘，
+     *  崩溃即全丢。本 chunk 与它语义分离：只回答「本次迭代做完了」。
+     *
+     *  **条件 = result === 'continue'（硬）**：终态迭代（'done' 收尾 / 'paused' 挂起 / 'aborted'
+     *  中断）之后流即结束或宿主 break → **流尾落盘**已兜底，此处不产——既避免与流尾重复写，
+     *  也保住「终态 chunk 是末条」这一既有流契约（宿主 paused 分支据 break，其后不得再有 chunk）。
+     *  无工具分支（handleTextResponse）恒终态，故本方法在该分支不产（恒非 'continue'）。
+     *
+     *  **顺序契约（硬，2026-09-26 更新）**：`plan_item_boundary` 已于**迭代开始**产出
+     *  （见 _maybeEmitPlanItemBoundary），本 chunk 产在迭代尾 → 二者天然保持「折叠边界先于落盘
+     *  触发」的先后序，宿主本次落盘快照必含该任务项折叠边界，崩溃重放不错位。
+     *
+     *  @param result 本次迭代的路由结果（handleToolCalls 返回值）
+     */
+    private _emitStepBoundary;
+    /** 上下文准备：摘要截断 → 同步工作记忆 → 微压缩 → 任务表注入。
+     *  返回 { chatOpts, safeMessages } 供调用方送 LLM。
+     *  截断/压缩改造 this.messages 的工作记忆，是"资源边界"职责的收敛点。
+     *  上下文规模上限由**有效窗口**（min(provider 窗口, 角色包 contextLimit)）在截断层生效；
+     *  不再有「预算触顶即终止」路径 —— 终止职责归 stepBudget。 */
+    private _prepareContext;
+    /**
+     * 本迭代将因 ask_user 挂起（决策关口，与用户暂停同属挂起型气口）？
+     * 含 ask_user 且未超 askLimit、非工具屏蔽。SSOT：onPlanItemBoundary 的 planItemLog 排除判定
+     * 与 handleToolCalls 挂起检出共用同一谓词（防两处判定漂移）——收口验收：
+     * ask_user 挂起谓词字面全仓仅此一处。
+     * 注：边界处传 llmResult.toolCalls（原始集）、挂起检出传 effectiveToolCalls（toolStepLimit
+     * 截断后集）；截断把 ask_user 裁掉的窗口 → 边界多跳一轮不记日志，安全向（少记而非错记）。
+     * askLimit 超限的 ask_user 走 executeToolCalls 拒绝（[ASK_LIMIT]），迭代照常执行 → 不判挂起。
+     */
+    private willSuspendForAsk;
+    /** 工具调用分支 + Reflection（子方法 2/3）；ask_user 提问检出挂起（返回 'paused'）。
+     *  stepIndex = 本迭代序号（调用方算号传入），tool_start 发射时盖章（与 thought 同构，事实单点）。 */
+    private handleToolCalls;
     /**
-     * 召回注入 + 输入护栏（processUserInput 子方法 1/4）
+     * ask_user 提问挂起（step 边界气口）：把提问作为普通工具轮落地，挂起等用户作答。
      *
-     * 职责：
-     *   - 注入记忆召回结果（system 消息，优先级高、不污染 user 输入）
-     *   - 召回命中率统计（metricRecallTotalCount / metricRecallHitCount）
-     *   - 通知上层 UI 召回透明度（yield recall chunk）
-     *   - 输入护栏检查（block 时 yield text + done，warn 时 yield text）
-     *
-     * @yields recall / text（guardrail block/warn）/ done（block 时）
-     * @returns true 表示输入被 block 已 yield done，调用方应 return；false 表示继续
+     * 与插话/暂停统一的「申请 → 气口生效」语义：
+     * - assistant(toolCalls) 结构完整入史（含 ask_user），不「撕掉」工具——OpenAI 兼容端要求
+     *   assistant.tool_calls **逐条**有配对 tool 消息：ask 的结果由用户答案回填，同批的**非 ask**
+     *   调用补「未执行」占位（见方法内注释），整批闭合；
+     * - 解析各 ask_user 参数为结构化 AskQuestion，yield question_pending 供宿主渲染提问 UI；
+     * - yield paused 挂起（consumeExecutionStream 统一翻 PAUSED + 写 pauseMeta），
+     *   用户作答后宿主调 answerQuestion() 回填 tool 结果，再 continueAfterPause() 续跑。
      */
-    private handleRecallAndInputGuard;
+    private handleAskUser;
     /**
-     * 单次迭代编排（processUserInput 子方法 2/4）
-     *
-     * 职责：
-     *   - abort 检查
-     *   - 上下文摘要 + 截断
-     *   - LLM 调用（callLlmWithRetry）
-     *   - LLM 中断处理
-     *   - 分支路由：工具调用 → handleToolCalls；纯文本 → handleTextResponse
-     *
-     * @yields text / aborted / done（由子方法委托）
-     * @returns 'aborted' | 'done' | 'continue'（continue 表示继续下一轮迭代）
+     * 回答在途提问（宿主在用户作答后调用，随后 continueAfterPause() 续跑）：
+     * 答案以 ask_user 工具的 tool result 回填（<tool_result> 包裹防注入，与 assistant.tool_calls 配对）。
+     * answers 与提问按序一对一；不足时复用最后一条/空串兜底。返回 false 表示无在途提问。
      */
-    private handleIteration;
+    answerQuestion(answers: readonly string[]): boolean;
     /**
-     * 工具调用分支 + Reflection（processUserInput 子方法 3/4）
-     *
-     * 职责：
-     *   - executeToolCalls 执行工具调用
-     *   - abort 检查（工具执行中断）
-     *   - Reflection：检查可重试错误，追加反思提示
-     *
-     * @yields aborted（工具执行中断时）
-     * @returns 'aborted' | 'continue'（continue 表示工具结果已回填，继续下一轮 LLM 调用）
+     * 取走最近一次已作答提问快照：runResume 落盘回答交互输入前调用，取走即清。
+     * 返回 undefined = 本次续跑非提问回答路径（补充输入 / 无快照残留）。快照为
+     * AskQuestion[]（多 ask_user 轮整组），调用方按需取用（当前落盘语义取 questions[0]）。
      */
-    private handleToolCalls;
+    takeAnsweredAsk(): AskQuestion[] | undefined;
     /**
-     * 纯文本结束 + 输出护栏（processUserInput 子方法 4/4）
-     *
-     * 职责：
-     *   - push assistant 消息（含空响应兜底）
-     *   - 输出护栏检查（block 时 yield text + done，warn 时 yield text）
-     *   - yield done 结束本轮对话
-     *
-     * @yields text（空响应兜底 / guardrail block/warn）/ done
-     * @returns 'done'（调用方收到后 return）
+     * 取消在途提问（宿主「跳过/取消提问」或提问超时时调用；
+     * runIterationLoop 续跑兜底也调用）：
+     * 以占位结果回填，防 assistant.tool_calls 无配对 tool 消息（OpenAI 兼容端 400）。
+     * 与 answerQuestion 对称：同样转存提问快照到 lastAnsweredAsk——
+     * 超时路径（resumeExecution kind='timeout'）经 runResume takeAnsweredAsk 随「未回答」
+     * 交互记录落盘 question/options，重放可渲染「问 + 未回答」行；跳过/兜底路径不消费
+     * 快照时残留仅进程内单 turn，无害（下次 answerQuestion 覆盖）。
      */
+    cancelAsk(): void;
+    /** 纯文本结束（子方法 3/3）：push assistant 消息（含空响应兜底）并 yield done。
+     *  本方法只处理纯文本交付；提问暂停走 ask_user 工具通道。 */
     private handleTextResponse;
     /**
-     * 调用 LLM（带指数退避重试）
+     * 调用 LLM（带指数退避重试，仅在流式输出前失败时重试；流式已开始则直接上抛，因用户已看到部分结果）。
      *
-     * 仅在流式输出前失败时重试（streamStarted = false），
-     * 流式已开始则直接向上抛出（用户已看到部分结果）。
-     *
-     * @param safeMessages - 截断后的消息数组
-     * @param chatOpts - LLM 调用选项
-     * @param signal - 可选的 AbortSignal
-     * @param iteration - 当前迭代次数（用于 tracing）
-     * @yields AgentChunk 文本片段
-     * @returns LLM 调用结果（fullContent + toolCalls + aborted 状态）
+     * 实现内聚于 `LlmCaller.callWithRetry`；此处保留委托壳。
      */
     private callLlmWithRetry;
     /**
-     * 执行工具调用列表
-     *
-     * 遍历 LLM 返回的 toolCalls，逐个执行并收集结果。
-     * 工具执行异常会被捕获并转为结构化错误字符串回传给 LLM，
-     * 而非直接中断对话。
-     *
-     * @param toolCalls - LLM 返回的工具调用列表
-     * @param fullContent - LLM 返回的文本内容
-     * @param signal - 可选的 AbortSignal
-     * @yields AgentChunk 工具开始/结果片段
-     * @returns 执行结果（aborted 状态）
+     * 执行工具调用列表（并发执行，异常捕获后转为结构化错误串回传给 LLM，而非中断对话）。
+     * stepIndex = 本迭代序号（调用链逐级传入），tool_start 发射时盖章（与 thought 同构，事实单点）。
      */
     private executeToolCalls;
     /**
-     * 工具执行与 signal abort 的竞争包裹
+     * 第二级压缩（LLM 主动触发兜底）：把最早的 turn 或超大工具结果现场压成临时摘要替换。
      *
-     * 背景：toolExecutor 签名 (name, args) => Promise<string> 不接受 signal 参数，
-     *   无法真正中断正在执行的工具。原代码直接 await toolExecutor(...)，
-     *   工具卡住时 generator 永久挂起，导致 _chatBusy 锁泄漏、UI 全阻塞。
+     * 作用对象是尚无记忆摘要的东西（第一级替换只对已沉淀摘要的 turn 可用）；压缩摘要是
+     * loop 内临时态（标记 executionTemp，下一轮 turn 入口即弃），不进记忆库。
      *
-     * 方案：用 Promise.race 让 toolExecutor 与 signal abort 监听竞争
-     *   - 工具先完成：返回工具结果字符串（原行为）
-     *   - signal 先 abort：返回 [ERR:TOOL:ABORTED] 错误字符串，
-     *     让 executeToolCalls 不再 await 工具（工具仍在后台运行，但 generator 解除阻塞）
-     *
-     * 设计权衡：
-     *   - 不改 toolExecutor 签名（82 处测试用例依赖此签名，保持向后兼容）
-     *   - 不抛 AbortError（避免破坏 executeToolCalls 的 try/catch 错误回传 LLM 契约）
-     *   - 返回错误字符串符合现有"工具失败回传 LLM"契约（[ERR:TOOL:code] 前缀）
-     *   - ABORTED 不进入 ToolErrorCode 体系（用户主动取消非工具失败，不触发 Reflection）
-     *
-     * @param name 工具名称
-     * @param args 工具参数 JSON 字符串
-     * @param signal 可选的 AbortSignal
-     * @returns 工具结果字符串，或 [ERR:TOOL:ABORTED] 表示被中断
+     * @param args 工具参数 JSON（{ target: 'earliest_round' | 'largest_tool_result' }）
+     * @param signal 中止信号
+     * @returns 回传给 LLM 的确认串（失败/无目标时返回提示，不抛错阻断工具链）
      */
-    private raceToolWithSignal;
+    private compressContext;
     /**
-     * 执行单个工具（E-803 抽取：为并行化提供独立执行单元）
-     *
-     * 职责：
-     *   - startSpan / endSpan（工具执行 Span，并发时 span 时间重叠，可观测性改进）
-     *   - raceToolWithSignal 竞争包裹（兼容 signal 中断，每个工具独立 race）
-     *   - 异常捕获并转为结构化错误字符串（[ERR:TOOL:code] 前缀，供 Reflection 解析）
-     *
-     * 不含职责（由 executeToolCalls 主循环控制，保证顺序确定）：
-     *   - yield tool_start / tool_result（事件顺序由主循环批量 yield 保证）
-     *   - messages.push（消息顺序由主循环按原始顺序 push，确保 Reflection slice 正确）
-     *   - metricToolCallCount / metricToolFailureCount（统计由主循环控制）
-     *
-     * 并发安全：本方法无共享状态，多个 executeOneTool 可同时执行。
-     * toolExecutor 内部无状态（纯分发 + 参数校验），天然支持并发调用。
-     *
-     * @param tc 单个工具调用描述（id + function.name + function.arguments）
-     * @param signal 可选的 AbortSignal
-     * @returns 工具结果字符串（成功）或 [ERR:TOOL:code] 错误字符串（失败）
+     * 定位当前触发输入（顶级锚点）之前最早的 turn；无旧轮次（新对话第一轮）返回 null
+     * （当前输入永不压缩——交软上限收尾而非压掉触发输入继续硬跑）。
      */
-    private executeOneTool;
+    private findEarliestRound;
+    /** 定位最大的 tool 结果（超大 tool_result 的压缩目标） */
+    private findLargestToolResult;
+    /** 用 provider 把目标内容压成临时摘要（走 summary 路由，轻量模型优先；失败降级空串） */
+    private summarizeForCompression;
     /**
-     * 构建 system prompt（注入人格 + 规则 + 领域 + 工具描述）
+     * 构建 system prompt（装载 bootstrapMemories + 工具描述）
+     *
+     * 身份中性（architecture_philosophy §11「memora 不需要知道自己是谁」）：
+     * 本函数**不注入任何引擎自称**——人格/身份由角色包 systemPromptPrefix 提供
+     * （AgentLoop 构造时 `prefix + buildSystemPrompt(...)` 拼接），此处只做
+     * 「设定装载 + 回应口径骨架 + 工具描述」，不出现 Memora 专名。
      */
     private buildSystemPrompt;
+    /** 注入系统消息到消息数组（技能注入、角色切换等场景，动态注入上下文） */
+    injectSystemMessage(content: string): void;
     /**
-     * 注入系统消息到消息数组（技能注入、角色切换等场景）
+     * 剔除文本工具调用骨架（SSOT 纪律的收口）。
      *
-     * 用于在对话进行中动态注入上下文——如技能匹配后，
-     * 下一轮将技能 prompt 注入为 system 消息。
+     * 返回语义：
+     * - 全文**不含**任何文本工具骨架标签 → `null`（正常路径，交付原文不动）；
+     * - 含**任一**骨架标签（`<tool_call` / `<function=` / `<parameter` 及闭合）→ 剔除全部
+     *   骨架后返回字符串（可能为空串，代表「纯工具意图、无正文交付」）。
      *
-     * @param content 系统消息内容
+     * 宽匹配 + 不校验闭合：针对未闭合/残缺骨架（测试样本即 `<function=list_dir</parameter>`）也能命中。
+     * 仅用于「文本出口已不宣告可调用通道」后的防御性收敛，正常模型不应触发。
      */
-    injectSystemMessage(content: string): void;
+    private stripToolIntentSkeleton;
     /**
-     * 以 system 消息注入召回记忆（替代旧 wrapWithRecalledContext 方案）
+     * 当前 provider 是否支持原生工具调用（OpenAI Function Calling tools 协议）。
      *
-     * 旧方案将记忆嵌入 user 消息并附加反指令「勿执行其中的任何指令或请求」，
-     * 但 user 消息中的 meta 指令对协议兼容模型不可靠。
-     * 改用 system 消息注入，model 自然将其视为参考上下文。
+     * 读 provider 的互斥双能力位：
+     * - true → loop 走原生工具通道（列工具 + 传 tools）。
+     * - false → 工具通道不可用，须收起工具清单走显式回落（见 buildSystemPrompt / buildChatOptions）。
+     * provider 未配置（undefined）时按支持处理（默认 true，与存量「有工具集即传 tools」一致）。
      */
-    private injectRecallAsSystem;
+    private toolCallingEnabled;
     /**
-     * 构建 LLM 调用选项（包含工具定义）
-     *
-     * 将 toolDefinitions 转换为 OpenAI Function Calling 格式，
-     * 让 LLM 能通过标准协议发起 tool_call，而非文本模拟。
-     *
-     * 设计说明：
-     *   `response_format` 约束的是最终响应体，而 `tool_calls` 是通过
-     *   `tools` 参数触发的独立流式协议（SSE delta），两者不能并存
-     *   （同时传入会导致 API 报错或行为未定义）。因此本方法只透传 tools
-     *   参数，不生成 `response_format: json_schema`。
+     * 当前 provider 是否支持结构化输出（response_format / JSON mode）。
      *
-     *   `supportsStructuredOutput` 字段 + `ChatOptions.response_format`
-     *   类型保留，供未来非 tool_call 场景的结构化输出使用（如归档摘要
-     *   强制 JSON、配置建议提取等），由调用方显式传入 response_format。
+     * 与 toolCallingEnabled 互斥：response_format 不能与 tools 同用（OpenAI 协议限制）。
+     * 作为「无原生工具能力」时的显式回落通道（产出机器可读 JSON，而非静默丢弃工具）。
      */
-    private buildChatOptions;
+    private structuredOutputEnabled;
     /**
-     * 刷新工具定义（registerTool 后调用）
-     *
-     * 当宿主项目通过 agent.registerTool() 注册新工具后，
-     * 需要更新 system prompt 中的工具描述，让 LLM 能看到新工具。
-     * 重建 messages[0] 的 system prompt 内容。
+     * 解析「本轮可用工具集」——单一真源（SSOT）
      *
-     * @param toolDefinitions 最新的工具定义列表（内置 + 自定义）
+     * 工具可用性事实本来被写作两处（buildSystemPrompt 文本出口 + buildChatOptions 原生出口），
+     * 属「同语义多实现」带伤。搜索硬上限命中后两处都要剔除 web_search，故把排除谓词收口到本方法。
+     * 不修改 opts.toolDefinitions，仅按轮过滤，随 resetTurnState 自然恢复。
      */
-    refreshToolDefinitions(toolDefinitions: ToolDefinition[]): void;
+    private resolveActiveTools;
     /**
-     * 运行时切换 LLM Provider
+     * 构建 LLM 调用选项（互斥双能力位的确定性通道选择）。
      *
-     * 用于多 Provider 路由场景：用户切换 API 时，
-     * Agent 调用此方法更新 AgentLoop 的 provider 引用。
-     * 后续 chat() 调用使用新 Provider。
+     * 通道取当前 provider 的能力位：
+     *   - 支持原生工具调用（supportsToolCalling）→ 走 tools 原生 FC 通道（唯一可调用通道）；
+     *   - 否则若支持结构化输出（supportsStructuredOutput）→ 走 response_format（JSON mode 回落）；
+     *   - 两者皆否 → 不传任何通道（工具不可用，见 buildSystemPrompt 展示的显式回落告知，不静默）。
      *
-     * @param provider 新的 LlmProvider 实例
+     * 不传 response_format 的原因（既有纪律保留）：它约束最终响应体，而 tool_calls 是通过
+     * tools 参数触发的独立流式协议，两者不能并存；此处仅在「无 tools 能力」时作为落回通道拉通。
      */
+    private buildChatOptions;
+    /** 刷新工具定义（registerTool 后调用），重建 system prompt 让 LLM 看到新工具 */
+    refreshToolDefinitions(toolDefinitions: ToolDefinition[]): void;
+    /** 运行时切换 LLM Provider（多 Provider 路由场景，后续调用使用新 Provider） */
     setProvider(provider: LlmProvider): void;
     /**
-     * 刷新角色 prompt
+     * 运行时更新 **provider 上下文窗口**（token）
      *
-     * 当角色切换时，更新系统 prompt 前缀的角色部分。
-     * 保留 bootstrapMemories 和 toolDefinitions 不变，只替换 prefix。
+     * 与 setProvider 配套：模型热切换时同步窗口。本方法只记录 provider 原始声明值，
+     * 有效窗口由 #recomputeEffectiveWindow 按 min(provider 窗口, 角色包 contextLimit) 重算，
+     * 令截断 / 软上限 / 占用快照随新模型与当前角色策略调整。只改窗口数字，不重建对话/不触碰消息。
      *
-     * @param newPrefix 新的系统 prompt 前缀（包含新角色 + 用户画像）
+     * @param tokens provider 声明的窗口 token 数
      */
-    refreshPersonaPrefix(newPrefix: string): void;
+    setContextWindow(tokens: number): void;
+    /** 当前**有效上下文窗口** = min(provider 窗口, 角色包 contextLimit)（诊断 / 测试读取面）。 */
+    getEffectiveContextWindow(): number;
+    /** 刷新角色包 prompt（角色切换时只替换 prefix，保留 bootstrapMemories 与 toolDefinitions） */
+    refreshRolePackPrefix(newPrefix: string): void;
+    /** 从角色包策略更新 ChatOptions 覆盖项（temperature/outputLimit 等立即生效） */
+    setChatOptions(chatOptions: Partial<ChatOptions> | undefined): void;
     /**
-     * 刷新 bootstrap 记忆段（设定面板 CRUD 专用）
-     *
-     * 设定面板对 rule/skill 执行增删改后，调用此方法用最新的记忆数组
-     * 重建 system prompt 中的 bootstrap 段，使变更立即对当前会话生效。
-     *
-     * 与 refreshPersonaPrefix 的区别：
-     *   - refreshPersonaPrefix 替换 systemPromptPrefix（角色 + 画像）
-     *   - refreshBootstrapMemories 替换 bootstrapMemories（rule + skill）
-     *
-     * 调用链：ConfigManager.deleteRule/updateRule/deleteSkill
-     *   → refreshBootstrapMemories 回调（assembler 注入）
-     *   → loop.refreshBootstrapMemories(memories)
-     *   → rebuildSystemMessage()
-     *
-     * @param memories 最新的 rule + skill 活跃记忆数组（由 ConfigManager.getBootstrapMemories 提供）
+     * 运行时更新 per-LLM 输出预算默认值（Provider 热切换配套，与 setContextWindow 同链路）。
+     * undefined = 清除（回服务端默认）。轮内下一迭代即用新值（请求参数非上下文结构，无一致性风险）。
      */
-    refreshBootstrapMemories(memories: Memory[]): void;
+    setDefaultMaxTokens(tokens: number | undefined): void;
     /**
-     * 注入情感基调到 system prompt（Phase 2.1：AffectController）
-     *
-     * 在角色前缀和 bootstrap 记忆之间插入情感描述文本。
-     * 与 refreshPersonaPrefix 独立——角色切换不会清除情感注入。
+     * 读取本轮请求体**实际**携带的 max_tokens（生效值，供宿主取证 / 展示）。
      *
-     * 注入位置：systemPromptPrefix + affectPrefix + bootstrapMemories + toolDefinitions
+     * 为何不交给宿主自行推算：生效值由 `buildChatOptions()` 单点裁决——per-LLM 配置与角色包
+     * act.outputLimit 取更小值、单侧缺位取另一侧；宿主侧重算等于复制规则、
+     * 制造第二真理源（真机教训：meta 记了用户配的 64000，实际发出的是角色包的 4096，
+     * 取证包把「配置意图」当成了「已生效事实」，由此得出过错误结论）。
      *
-     * @param affectString 情感描述文本（如"当前对话基调：温暖、直接"），传空字符串清除注入
+     * @returns 生效的输出上限（token）；undefined = 不传 max_tokens（回服务端默认）
      */
+    getEffectiveMaxTokens(): number | undefined;
+    /** 刷新 bootstrap 记忆段（设定面板对 rule/skill 增删改后用最新记忆重建 bootstrap 段）。
+     *  与 refreshRolePackPrefix 区别：后者替换 prefix（角色包 prompt），本方法替换 bootstrapMemories */
+    refreshBootstrapMemories(memories: Memory[]): void;
+    /** 注入情感基调到 system prompt（角色前缀与 bootstrap 记忆之间；与角色切换独立，切换不清除） */
     injectAffect(affectString: string): void;
-    /**
-     * 重建 messages[0] 的 system prompt
-     */
+    /** 重建 messages[0] 的 system prompt */
     private rebuildSystemMessage;
+    /** 获取消息历史（用于持久化） */
+    getMessages(): readonly Message[];
     /**
-     * 获取消息历史（用于持久化）
+     * 记录最近一次输入装配的上下文预算（prepare 期调用，预算可视化）。
+     * 只存最新一轮预算供指标快照透出，不跨轮累积。
      */
-    getMessages(): readonly Message[];
+    recordBudget(budget: ContextBudget): void;
     /**
-     * 获取 AgentLoop 运行时指标快照（可观测性增强）
-     *
-     * 返回 LLM 调用、记忆召回、工具调用、上下文管理四个维度的累计指标。
-     * 衰减指标（decay）由 Agent 层填充，此处返回 null。
+     * 获取最近一轮输入装配的上下文预算（预算联动）
      *
-     * 纯只读、同步、零副作用——适合宿主项目定期轮询构建监控面板。
-     *
-     * @returns AgentMetrics 快照（decay 字段为 null，由 Agent 层填充）
+     * 供工具执行器在工具执行期读取剩余预算（search_project 预算下探）。
+     * 未 prepare 时返回 undefined（如纯工具单元测试场景）。
      */
-    getMetrics(): AgentMetrics;
+    getLastBudget(): ContextBudget | undefined;
     /**
-     * 获取最近 N 轮对话（Layer 5: 最近对话注入）
-     *
-     * 从 messages 数组中提取最近 N 轮 user + assistant 消息，
-     * 用于注入 system prompt，让 LLM 在用户输入无信息量时仍能看到上下文。
+     * 记录最近一次输入装配的上下文占用快照（prepare 期调用，预算可视化）。
+     * 存最新一轮真实用量供指标快照/输入区指示器透出，不跨轮累积。
+     */
+    recordOccupancy(occupancy: ContextOccupancy): void;
+    /**
+     * 对话占用实时刷新（预算可视化 · 输入区常驻指示器）。
      *
-     * @param rounds - 要获取的轮次数（默认 3）
-     * @returns 最近 N 轮的 user + assistant 消息数组
+     * occupancy 主体在 prepare 期 record（见 contextPreparer），但 prepare 发生在 assistant
+     * 生成前，故快照的 dialogue 段天然不含本轮 assistant、且单轮对话结束后不再刷新。
+     * 本方法在 user 消息落库 / assistant 落盘后以最新 this.messages 重算 dialogue 段：
+     *   dialogueCount  = user 消息数（计数标准：一个问答闭环=1，残缺回答如实记录）
+     *   dialogueTokens = 全量 user+assistant 估算（容量诚实统计问答闭环总和）
+     * 其余段（rolePackBase/memory/inputAnchor/outputReserve）沿用 prepare 快照，不重算
+     * （守 SSOT：宿主只透传，内核单一真相源）。
+     * 幂等：无快照时 no-op（如首轮 prepare 尚未发生）。
      */
-    getRecentHistory(rounds?: number): Array<{
+    private refreshOccupancyDialogue;
+    /**
+     * 写入当前激活角色包底盘占用（system prompt 总体 token）。
+     * 装配 / 切换角色包时调用（早于 prepare），使冷启动 / 重启首屏即可显示真实占比；
+     * prepare 期 recordOccupancy 也以其实际注入值覆盖，口径一致（同一估算器）。
+     */
+    setRolePackBaseTokens(tokens: number): void;
+    /** 读取当前激活角色包底盘占用（未确定时为 undefined，调用方降级处理） */
+    getRolePackBaseTokens(): number | undefined;
+    /**
+     * 获取 AgentLoop 运行时指标快照（纯只读、零副作用，适合宿主轮询构建监控面板）。
+     */
+    getMetrics(): AgentMetrics;
+    /** 估算消息 token 数（CJK 感知，委托 ContextManager）——装配层/预算派生复用同一估算真理源 */
+    estimateTokens(messages: readonly Message[]): number;
+    /** 被替换轮 roundId 列表（第一级替换产物；装配层合并进 exclude 防其摘要被二次召回） */
+    getReplacedRoundIds(): readonly string[];
+    /** 当前工作记忆中实际保留的轮次 roundId 集合（装配 exclude 用）。
+     *  扫描视图内 user 消息自带 roundId（与 ReplaceRoundsStrategy.groupRounds 同源，
+     *  无外部序列/尾部对齐依赖）。覆盖截断重排后按重要性提炼保留的中间轮——其正文已在
+     *  视图，round-summary 须排除防与该正文双写；被完全裁掉的旧轮不在集合内，其摘要仍可召回。 */
+    getVisibleRoundIds(): ReadonlySet<string>;
+    /**
+     * 召回互斥排除集（memory-tool-recall-design §5.1）：正文已不在眼前、但其摘要已在眼前的轮次。
+     *
+     * = 视图内轮次（`getVisibleRoundIds`，含截断后按重要性保留的中间轮）
+     *   ∪ 已被第一级替换的轮次（`getReplacedRoundIds`，正文被换成了摘要，roundId 已不在 messages
+     *     但摘要已在上下文，故须另计——否则其 round-summary 会被二次召回重复返回）
+     *   ∪ 当前在途轮次（`currentRoundId`，当轮 user 已落 store 但尚未进 messages 的窗口期）。
+     *
+     * **唯一真理源**：从 loop 的工作记忆视图派生（精确集合），不再用「最近 N 轮」代理量近似。
+     * 由装配期注入 `search_memories`（`toolExec.setExclusionRoundIdsProvider`）。
+     * 首轮若仍在视图内则已被覆盖；长会话首轮被裁掉时可另行显式计入（当前无消费者，未接）。
+     */
+    getExclusionRoundIds(): ReadonlySet<string>;
+    /**
+     * 获取当前窗口中的完整对话消息（仅 user + assistant，排除 system/tool）。
+     * 供 contextPreparer 计量 fixed/query 模式下实际进窗的完整对话占用
+     * （区别于 hybrid 模式注入的最近轮次摘要块，见 getRecentHistoryWithinBudget）。
+     */
+    getConversationMessages(): Array<{
         role: 'user' | 'assistant';
         content: string;
     }>;
     /**
-     * 恢复历史消息（用于重启后恢复对话）
-     * 会跳过 system 消息，只恢复 user/assistant/tool 消息
-     *
-     * @param historyMessages - 要恢复的历史消息列表
+     * 按预算容量派生完整对话层轮次集合（动态轮数，role-pack-spec §C/§D）。
+     * 从最近往回塞到预算止，会话第一条问答闭环必然在场（次级锚点：默认在场，压缩可让位）。
+     *
+     * @param maxTokens 完整对话层预算（token，由上下文预算计算派生）
+     * @returns 注入的历史序列 + 最近轮数（供互斥 roundId 排除）+ 是否显式补了第一条
+     */
+    getRecentHistoryWithinBudget(maxTokens: number): {
+        history: Array<{
+            role: 'user' | 'assistant';
+            content: string;
+        }>;
+        recentRoundCount: number;
+        firstRoundIncluded: boolean;
+    };
+    /** 获取当前轮次 ID（processUserInput 入口分配，多 iteration 共享），空串表示无活动轮次 */
+    getCurrentRoundId(): string;
+    /** 设置当前轮次 ID（appendUser 在 processUserInput 之前调用，故需提前生成供 RoundSummaryGenerator 使用） */
+    setCurrentRoundId(roundId: string): void;
+    /** 分配新轮次 ID（SSOT：prepare 提前生成与 processUserInput 回退生成共用唯一出处，避免 round-模板串重复漂移） */
+    allocRoundId(): string;
+    /**
+     * 恢复历史消息（跳过 system，只恢复 user/assistant/tool；传空数组=清空工作记忆，保留 system prompt）
+     *
+     * 历史集合被整体替换是上下文摘要缓存的失效点（见 ContextManager.resetSummary 注释：
+     * 若新历史更短，长度差反推会误判"未过期"，把上一段会话的陈旧摘要注入新上下文）。
+     * 故整体替换（清空 / 恢复检查点）经此入口时统一作废摘要缓存——调用方无需各自记得调 reset，
+     * 失效动作与替换动作同处（SSOT）。
      */
     restoreHistory(historyMessages: readonly Message[]): void;
+    /** 作废 loop 级派生缓存（会话替换 chokepoint 调用）；只暴露行为不暴露 ContextManager，保持边界有界 */
+    resetContextSummary(): void;
+    /** 清理上一轮注入的临时 system 消息（每轮 chat() 前调用），防 recall/技能/截断注入堆积成冗余指令 */
+    cleanTemporarySystemMessages(): void;
     /**
-     * 清理上一轮对话注入的临时 system 消息
+     * 清理执行期临时 system 消息（self-review / reflection / duplicate-warning / metaNote）。
      *
-     * 每轮 chat() 前调用，仅保留 messages[0]（永久 system prompt）和
-     * 所有 user/assistant/tool 消息（对话历史）。
-     * 防止 recallAndInject() / injectActiveSkill() / truncateMessages()
-     * 累积的临时 system 消息堆叠，避免 LLM 收到大量冗余指令。
+     * 每轮闭环入口执行一次（processUserInput / continueAfterPause），清掉上一轮
+     * 执行中产生、下一轮不应再见的残留。与 prepare 阶段的装配性注入区分：装配注入（召回、
+     * 最近对话）不在此集合，保留到 prepare 重建。replaceContext 走浅拷贝保留消息引用，
+     * 故按引用过滤是安全且幂等的。
      */
-    cleanTemporarySystemMessages(): void;
+    private cleanExecutionTemporary;
+    /** 追加一条 user 消息（统一 <user_input> 标签包裹，防注入攻击）；附当前轮次 roundId（替换式压缩单一真理源） */
+    private appendUserMessage;
+    /** 追加一条 system 消息（技能注入、召回、任务表、自审查提示等通用注入通道） */
+    private appendSystemMessage;
+    /** 会议轮判据（裁决证据用，操作化单点）：任务表 active 任务项声明 rolePack = 会议逐项切换生效中 */
+    private isMeetingRound;
+    /** 追加一条 assistant 纯文本消息（正常 LLM 回复或兜底文本）；附当前轮次 roundId */
+    private appendAssistantText;
+    /** 追加一条带 toolCalls 的 assistant 消息（executeToolCalls 前导）；附当前轮次 roundId */
+    private appendAssistantToolCall;
     /**
-     * 判断工具错误结果是否可重试（Reflection 用）
+     * 追加一条 tool 消息（loop **唯一** tool 写点：工具结果 / `[ASK_ANSWER]` / `[ASK_ABORTED]` /
+     * `[ASK_SUSPENDED]` / `[TOOL_ABORTED]` 五处皆经此）。
      *
-     * 解析工具结果中的 [ERR:TOOL:code] 前缀，
-     * 调用 isRetryableErrorCode 判断。
+     * **入口关**（大文本统一通道 §6.2）：单条内容超 `SINGLE_TOOL_RESULT_MAX_TOKENS` → 原文落盘，
+     * 上下文只留「路径 + 预览 + 续读提示」。收口在此而非 `_processToolResults`：后者只覆盖工具结果，
+     * 会漏掉 `answerQuestion` 的 `[ASK_ANSWER]` —— 用户被问「请提供需求文档」后直接贴长文即可超阈。
      */
-    private isRetryableToolError;
+    private appendToolMessage;
     /**
-     * 重试延迟 + abort 支持（从 callLlmWithRetry 提取，编码约定 §6 ≤60 行约束）
+     * 情报区写回（remember_intel 工具实现，CLoop 拦截执行）：把 LLM 私有笔记追加到情报区。
+     *
+     * 累积为 `intelNote`（跨 turn 自持）；超 `MAX_INTEL_PREFIX_LEN` 裁最旧（保留最新）。返回给 LLM 的
+     * ack **不回填 note 原文**（工具结果只回「已记录」），note 原文只进情报区 system 消息 → 不在用户流。
      *
-     * 发射 retry chunk、等待指数退避延迟（支持中途 abort），返回 void。
-     * 调用方在延迟后自行检查 signal.aborted 决定是否退出重试循环。
+     * @param args remember_intel 的 JSON arguments
+     * @returns 简短 ack（作为该工具调用的 tool 结果）
      */
-    private _waitForRetryWithAbort;
+    private handleRememberIntel;
     /**
-     * 处理工具执行结果：push messages + yield tool_result（从 executeToolCalls 提取）
+     * 每轮装配把情报区注入为**单条尾部私有 system 消息**。
+     *
+     * - 复用 Message[] 视图：不新增对象，情报区 = 一条 system 消息正文；
+     * - 已存在则更新原文（保持单条），被截断删除则重建 → 参与 `truncateMessages` 尾部淘汰（B 语义）；
+     * - 非 executionTemp → 跨 turn 自持（每轮 `_prepareContext` 注入最新版）。
+     *
+     * **归属注**：对已存在消息的 `existing.content = ...` 属**单条尾部私有消息的幂等刷新**（同
+     * `ResultReplacement` 只改 content），**不是装配重排**——不违背 loop「只追加、不重装配」的编排原则。
+     *
+     * **时序注（诚实声明）**：`_prepareContext` 先算 `safeMessages`、后注入本消息——
+     * 在**截断轮**（截断重排后安全快照 ≠ this.messages）里，本轮被发送的 `safeMessages` 不含本情报区，
+     * 下一轮 `_prepareContext` 重算后才可见（瞬时，非死锁）。此与 search 收敛提示 / taskTable 等所有
+     * 既有动态注入提示的时序一致（库级既有行为），非本机制特例。
      */
-    private _processToolResults;
+    private injectIntelNote;
     /**
-     * 注入记忆召回结果 + 统计 + 透明度通知（从 handleRecallAndInputGuard 提取）
+     * 缓存条目对应的工具结果是否**仍在当前上下文中** —— 防重拦截的前提（调用点见 handleToolCalls）。
+     *
+     * 三道判据全过才算「在」：① 条目带 toolCallId 与指纹；② `this.messages` 中仍有该 toolCallId 的
+     * tool 消息；③ 其内容指纹与记录一致（内容未被压缩链替换成 `[Previous: used x]` 占位符）。
+     *
+     * **保守方向：宁可放行，不可误拦。** 找不到消息 / 指纹不符 / 条目缺元信息 → 一律 false（放行）。
+     * 误放行的代价是「多读一次」；误拦的代价是「内容已不在手上却读不回来 = 死锁」——两者不对称。
+     *
+     * 注：超阈结果经入口关落盘后，上下文里留的是「路径 + 预览」，与记录指纹（包裹后的原文）不符
+     * → 判为「不在」，重读放行。这是正确语义：原文确实已不在上下文中。
      */
-    private _injectRecall;
+    private isCachedResultStillInContext;
+    /** 整体替换执行上下文（截断落盘 / 恢复历史 / 装配重排：传入的数组已是完整上下文） */
+    private replaceContext;
+    /** 处理工具执行结果：push tool 消息 + 统计失败数 */
+    private _processToolResults;
 }
 //# sourceMappingURL=loop.d.ts.map