@zooique/memora 4.0.0 → 5.0.0

package/dist/agent/loop.js

@@ -62,9 +62,9 @@ function parseCompressTarget(raw) {
  *   - 中断/暂停（interruptQueue + _handleInterrupt + interject 追加用户消息、step 边界 yield paused）
  *     与 sessionStateMachine 的「纯三态 + pendingPause」语义不同源（后者不承载 interject 追加与
  *     step 边界产出）——不并入，维持 loop 自持。
- *   - 消息写入口（append* / clean* + 观测埋点 recordBudget/recordOccupancy/refreshOccupancyDialogue）同判
+ *   - 消息写入口（append* / clean* + 观测埋点 recordBudget/recordOccupancy/refreshOccupancyFromMessages）同判
  *     不拆：写入口持有 messages / currentRoundId / executionTempSystem / offloadDir 四项 loop 私有状态，
- *     并回调 refreshOccupancyDialogue（**写消息→触发观测，跨域**），不满足 progressive-refactor-rules
+ *     并回调 refreshOccupancyFromMessages（**写消息→触发观测，跨域**），不满足 progressive-refactor-rules
  *     §2.2 模式 B「职责正交（不共享状态 / 不互相调用）」前提；模式 A（领域容器提取）只搬字段不搬逻辑，
  *     收益不足以覆盖改点面。保留监控，待自然生长触发。
  *   - 搜索生命周期：软上限/硬上限混沌形同构但为**同一意图的三级级联**——
@@ -81,6 +81,11 @@ function parseCompressTarget(raw) {
 const INTEL_INTRO = '[情报区 · 仅供你私有查看并作为后续作答的参考]。此区内容不要向用户复述或写进项目文档。' +
     '当你从大文本/工具结果获取到新的关键信息时，可用一句简短状态反馈用户进展（如：原来是这样… / 掌握了关键信息 / ' +
     '有一个问题… / 基本收集完毕），但不要在反馈中复述笔记/原文细节。';
+/** 「用户未回答该提问」占位 tool 结果（单一载体）：
+ *  消费点二——`cancelAsk`（整批跳过/超时未答）与 `answerQuestion`（**部分**题缺答案）。
+ *  两处共一常量而非各写字面量：改一处漏一处会让「未回答」这一事实在一条路径上失真，
+ *  而该事实直接进 LLM 决策上下文（静默失效、无报错）。 */
+const ASK_ABORTED_RESULT = '[ASK_ABORTED] 用户未回答该提问';
 export class AgentLoop {
     opts;
     messages = [];
@@ -229,7 +234,7 @@ export class AgentLoop {
     toolExecutedThisTurn = false;
     /** 当前轮次 ID（processUserInput 入口分配一次，各 iteration 共享），用于溯源式摘要 */
     currentRoundId = '';
-    /** 是否正处于自主工具步执行中（内核自用：resumeExecution 预判短路 / canContinueWithoutInput；宿主零消费） */
+    /** 是否正处于自主工具步执行中（内核自用：resumeExecution 预判短路；宿主零消费） */
     inAutonomousStep = false;
     /* 策略类字段（toolCallsBlocked/toolStepLimit/errorHandling/providerRouting 等）定义在
      * 单一 L2RuntimeStrategy 对象（见上方 strategy），读取统一走 this.strategy.<field> */
@@ -433,8 +438,9 @@ export class AgentLoop {
         }
         // 单工具执行器：注入 loop 稳定能力窄面，strategy 经闭包读最新（setStrategy 动态生效）
         this.toolRunner = new ToolRunner({
-            // 原生 outcome 回调逐跳透传：ToolRunner → opts.toolExecutor → toolExecutor.execute
-            execute: (name, args, emitOutcome) => this.opts.toolExecutor(name, args, emitOutcome),
+            // 原生 outcome 回调逐跳透传：ToolRunner → opts.toolExecutor → toolExecutor.execute；
+            // toolCallId 同步透传（web_search 证据配对通道，见 ToolRunnerDeps.execute 第 4 参）
+            execute: (name, args, emitOutcome, toolCallId) => this.opts.toolExecutor(name, args, emitOutcome, toolCallId),
             builtinTools: opts.builtinTools,
             preExecutionCheck: opts.preExecutionCheck,
             onToolExecuted: opts.onToolExecuted,
@@ -571,7 +577,7 @@ export class AgentLoop {
             }
         }
     }
-    /** 是否正处于自主工具步执行中（消费者 = agent.ts 预判短路/canContinueWithoutInput，内核内部） */
+    /** 是否正处于自主工具步执行中（消费者 = agent.ts 预判短路，内核内部） */
     get isInAutonomousStep() {
         return this.inAutonomousStep;
     }
@@ -1487,21 +1493,33 @@ export class AgentLoop {
         for (const q of questions) {
             yield { type: 'question_pending', questions: [q] };
         }
+        // 挂起本身不携带来源：提问的原因/来源已由 onPendingQuestion → requestPause(reason,'agent')
+        // 注册进状态机 pendingPause（与用户暂停同一真源、同一入口），consumeExecutionStream 从 pending 取。
         yield { type: 'paused' };
         return 'paused';
     }
     /**
      * 回答在途提问（宿主在用户作答后调用，随后 continueAfterPause() 续跑）：
      * 答案以 ask_user 工具的 tool result 回填（<tool_result> 包裹防注入，与 assistant.tool_calls 配对）。
-     * answers 与提问按序一对一；不足时复用最后一条/空串兜底。返回 false 表示无在途提问。
+     * answers 与提问按序一对一；**不足的部分落 `[ASK_ABORTED]`「未回答」占位，不复用别题答案**。
+     * 返回 false 表示无在途提问。
      */
     answerQuestion(answers) {
         if (!this.pendingAsk)
             return false;
         const { toolCallIds } = this.pendingAsk;
         toolCallIds.forEach((id, i) => {
-            const answer = answers[i] ?? answers[answers.length - 1] ?? '';
-            this.appendToolMessage(wrapToolResult(ASK_USER_TOOL.name, `[ASK_ANSWER] 用户回答：${answer}`), id);
+            const answer = answers[i];
+            // 逐条按序一对一；**缺答案不得拿别题的答案顶替**。
+            // 旧兜底 `answers[answers.length - 1]`（不足时复用最后一条）会把同一条文本复制到剩余每题
+            // ⇒ 用户只答了一道，LLM 却收到「每题都有答案」——制造假事实、无报错、直接污染决策上下文。
+            // 多题场景下「底部只有一条文本的输入框」必然触发这条兜底（宿主已把回答统一走本入口）。
+            // 现改：缺答案落 [ASK_ABORTED] 占位（与 cancelAsk 同文案同源），把「未答」这一事实
+            // 显式告知模型；配对不变量不变——每条 toolCallId 恒有 tool 消息，不撞兼容端 400。
+            const result = answer === undefined || answer.trim() === ''
+                ? ASK_ABORTED_RESULT
+                : `[ASK_ANSWER] 用户回答：${answer}`;
+            this.appendToolMessage(wrapToolResult(ASK_USER_TOOL.name, result), id);
         });
         // 已作答提问转存快照（runResume 落盘交互输入时随回答持久化），pendingAsk 即清空
         this.lastAnsweredAsk = this.pendingAsk.questions;
@@ -1534,7 +1552,7 @@ export class AgentLoop {
             return;
         const { toolCallIds } = this.pendingAsk;
         for (const id of toolCallIds) {
-            this.appendToolMessage(wrapToolResult(ASK_USER_TOOL.name, '[ASK_ABORTED] 用户未回答该提问'), id);
+            this.appendToolMessage(wrapToolResult(ASK_USER_TOOL.name, ASK_ABORTED_RESULT), id);
         }
         this.lastAnsweredAsk = this.pendingAsk.questions;
         this.pendingAsk = undefined;
@@ -1649,12 +1667,16 @@ export class AgentLoop {
         // 运行时护栏阈值组装（真源分配见 guardRail.GuardThresholds）：
         //  写环=GUARD_THRESHOLDS.writeLoop，读闸=GUARD_THRESHOLDS.readFailed（独立静态真源，
         //  不再与 duplicateCallInterceptor 阈值复用——语义同宽，解开隐藏耦合）；
-        //  提问=strategy.askLimit、搜索=LOOP_CONSTANTS.MAX_WEB_SEARCH_CALLS（动态真源，不入静态默认）。
+        //  提问=strategy.askLimit、搜索=strategy.webSearchLimit（动态真源=角色包策略，缺省值
+        //  定义在 DEFAULT_BEHAVIOR_STRATEGY.global.webSearchLimit）。
         const guardThresholds = {
             writeLoop: GUARD_THRESHOLDS.writeLoop,
             readFailed: GUARD_THRESHOLDS.readFailed,
             askLimit: this.strategy.askLimit,
-            maxWebSearch: LOOP_CONSTANTS.MAX_WEB_SEARCH_CALLS,
+            // webSearchLimit 缺省 6 由 resolveWebSearchLimit 恒给（GUARD-SEARCH-1：
+            // 硬上限 = 角色包策略键 global.webSearchLimit），与下方 SEARCH_LIMIT 文案同源取
+            // strategy，二者禁分头取值（否则文案数字说谎）。
+            maxWebSearch: this.strategy.webSearchLimit,
         };
         for (const tc of toolCalls) {
             this.metrics.toolCallCount++;
@@ -1700,7 +1722,7 @@ export class AgentLoop {
                 }
                 if (!this.searchDisabledHintInjected) {
                     this.searchDisabledHintInjected = true;
-                    this.appendSystemMessage(`[SEARCH_LIMIT] 联网搜索已达 ${LOOP_CONSTANTS.MAX_WEB_SEARCH_CALLS} 次上限，视为未检索到更多相关内容。` +
+                    this.appendSystemMessage(`[SEARCH_LIMIT] 联网搜索已达 ${guardThresholds.maxWebSearch} 次上限，视为未检索到更多相关内容。` +
                         `请停止调用 web_search，直接基于已有信息继续下一步或作答。`, { executionTemp: true });
                 }
                 toolExecs.push({
@@ -2524,24 +2546,41 @@ export class AgentLoop {
         this.lastOccupancy = occupancy;
     }
     /**
-     * 对话占用实时刷新（预算可视化 · 输入区常驻指示器）。
+     * 动态注入占用（`messages[0]` 之外的 system 消息）token 估算。
+     *
+     * 单一真理源 = `this.messages`：最近对话块 / 情报区 / 任务表 / 软上限与压力提示 /
+     * 搜索收敛提示 / 反思与自审查提示等运行时注入，皆以 system 消息落在 index > 0。
+     * 占用快照把它计入「动态注入」段（P1-1 修复）——此前该段未计入任何分段、被静默算进 free，
+     * 导致指示器偏乐观。与对话段共用同一估算器（SSOT）。
+     */
+    getDynamicSystemTokens() {
+        const dynamicSystem = this.messages.filter((m, i) => i > 0 && m.role === 'system');
+        return dynamicSystem.length > 0 ? this.estimateTokens(dynamicSystem) : 0;
+    }
+    /**
+     * 随工作记忆实时刷新占用快照中「由 messages 派生」的两段（预算可视化 · 输入区常驻指示器）。
      *
      * occupancy 主体在 prepare 期 record（见 contextPreparer），但 prepare 发生在 assistant
-     * 生成前，故快照的 dialogue 段天然不含本轮 assistant、且单轮对话结束后不再刷新。
-     * 本方法在 user 消息落库 / assistant 落盘后以最新 this.messages 重算 dialogue 段：
-     *   dialogueCount  = user 消息数（计数标准：一个问答闭环=1，残缺回答如实记录）
-     *   dialogueTokens = 全量 user+assistant 估算（容量诚实统计问答闭环总和）
-     * 其余段（rolePackBase/memory/inputAnchor/outputReserve）沿用 prepare 快照，不重算
+     * 生成前，且动态 system 注入在 prepare 之后陆续发生，故两段须在写入口以最新 this.messages 重算：
+     *   dialogue      = 全量 user+assistant 估算（容量诚实统计问答闭环总和）
+     *   dynamicSystem = `messages[0]` 之外的 system 消息估算（见 getDynamicSystemTokens）
+     * 其余段（rolePackBase/inputAnchor/outputReserve）沿用 prepare 快照，不重算
      * （守 SSOT：宿主只透传，内核单一真相源）。
      * 幂等：无快照时 no-op（如首轮 prepare 尚未发生）。
      */
-    refreshOccupancyDialogue() {
+    refreshOccupancyFromMessages() {
         if (!this.lastOccupancy)
             return;
         const conv = this.getConversationMessages();
         const dialogueCount = conv.filter((m) => m.role === 'user').length;
         const dialogueTokens = this.estimateTokens(conv);
-        this.lastOccupancy = { ...this.lastOccupancy, dialogueCount, dialogueTokens };
+        const dynamicSystemTokens = this.getDynamicSystemTokens();
+        this.lastOccupancy = {
+            ...this.lastOccupancy,
+            dialogueCount,
+            dialogueTokens,
+            dynamicSystemTokens,
+        };
     }
     /**
      * 写入当前激活角色包底盘占用（system prompt 总体 token）。
@@ -2693,6 +2732,65 @@ export class AgentLoop {
     getCurrentRoundId() {
         return this.currentRoundId;
     }
+    /**
+     * 记录 web_search 执行证据（悬案取证轨写点，SEARCH-QUALITY-1 P1-1 观测留痕）
+     *
+     * 驱动方 = 装配层接线 `toolExec.setSearchResultObserver`（toolExecutor 观察到的执行事实
+     * 镜像过来）。ts/meetingRound 构造归 loop（isMeetingRound 私有，与其余三个写点同构）；
+     * 载荷透传不加工（toolCallId/query/endpoint/count/titles 就是 toolExecutor 看到的原样）。
+     * 回答「搜不准」争议的第一现场：结果页之外，query 本身 + 端点 + 结果面落盘可裁。
+     * 护栏硬拦的搜索不走此路（拦截即未执行，无结果面；拦截事实已在 tool 消息可见）。
+     */
+    recordWebSearchEvidence(info) {
+        this.appendRoundEvidence?.({
+            type: 'web_search_result',
+            ts: nowIso(),
+            meetingRound: this.isMeetingRound(),
+            payload: {
+                // toolCallId 透传（宿主渲染据此唯一配对证据回工具行）；缺省 = 未透传，宿主回退 query 启发式
+                toolCallId: info.toolCallId,
+                query: info.query,
+                endpoint: info.endpoint,
+                count: info.count,
+                titles: info.titles,
+            },
+        });
+    }
+    /**
+     * 记录 search_memories 命中明细证据（MEM-EVENT-3：实时事件的落盘副本）
+     *
+     * 驱动方 = 装配层同一处 `setOnMemoryRecalled` 接线（事件广播 + 证据落盘同源一次发射）——
+     * 不新造第二个观测通道，也不在宿主侧二次拼装。
+     * 动机：`memoryRecalled` 是实时专属事件（不进 processEvents），宿主重放历史轮无数据源
+     * ⇒ 命中明细整块消失，「这轮参考了哪几条记忆」回看时不可考。落盘副本让重放可重建。
+     *
+     * 载荷透传不加工（id/name/source 就是搜索结果的现成三字段）；无命中不落盘——内核
+     * `memoryRecalled` 本就只在有命中时发射，证据轨不为「查了但没查到」另造路径。
+     */
+    recordMemoryHitsEvidence(info) {
+        // 防御：无明细 = 4.0.x 形态的载荷（老调用方/直调），没有可重建的内容，不写空证据
+        if (!info.hits || info.hits.length === 0)
+            return;
+        this.appendRoundEvidence?.({
+            type: 'memory_hits',
+            ts: nowIso(),
+            meetingRound: this.isMeetingRound(),
+            payload: {
+                // toolCallId 可选透传：宿主重放据此唯一配对工具行；缺省走轮次级兜底落位
+                ...(info.toolCallId ? { toolCallId: info.toolCallId } : {}),
+                query: info.query,
+                count: info.count,
+                // contentPreview 直接赋值：5.0.0 起实时载荷恒携带；undefined 经 JSON 序列化自然消失
+                //（与可选透传语义一致），重放轨与实时轨同构，宿主缺失时回退 name。
+                hits: info.hits.map((h) => ({
+                    id: h.id,
+                    name: h.name,
+                    source: h.source,
+                    contentPreview: h.contentPreview,
+                })),
+            },
+        });
+    }
     /** 设置当前轮次 ID（appendUser 在 processUserInput 之前调用，故需提前生成供 RoundSummaryGenerator 使用） */
     setCurrentRoundId(roundId) {
         this.currentRoundId = roundId;
@@ -2792,10 +2890,10 @@ export class AgentLoop {
             content: `<user_input>${content}</user_input>`,
             roundId: this.currentRoundId,
         });
-        // 用户输入即刷新占用条数（问答闭环 +1，实时反映到输入区圆环）
-        this.refreshOccupancyDialogue();
+        // 用户输入即刷新占用（问答闭环 +1，实时反映到输入区圆环）
+        this.refreshOccupancyFromMessages();
     }
-    /** 追加一条 system 消息（技能注入、召回、任务表、自审查提示等通用注入通道） */
+    /** 追加一条 system 消息（技能注入、最近对话块、任务表、自审查提示等通用注入通道） */
     appendSystemMessage(content, opts = {}) {
         const msg = { role: 'system', content };
         this.messages.push(msg);
@@ -2803,6 +2901,9 @@ export class AgentLoop {
         if (opts.executionTemp) {
             this.executionTempSystem.add(msg);
         }
+        // system 注入即时刷新「动态注入」占用段（P1-1）：否则指示器只在 user/assistant 写入时更新，
+        // 动态注入占比被静默漏计、free 偏大。无快照时 no-op（首轮 prepare 前）。
+        this.refreshOccupancyFromMessages();
     }
     /** 会议轮判据（裁决证据用，操作化单点）：任务表 active 任务项声明 rolePack = 会议逐项切换生效中 */
     isMeetingRound() {
@@ -2812,7 +2913,7 @@ export class AgentLoop {
     appendAssistantText(content) {
         this.messages.push({ role: 'assistant', content, roundId: this.currentRoundId });
         // assistant 落盘（含残缺/中止回复）后补算对话容量，使圆环即时含本轮回答
-        this.refreshOccupancyDialogue();
+        this.refreshOccupancyFromMessages();
     }
     /** 追加一条带 toolCalls 的 assistant 消息（executeToolCalls 前导）；附当前轮次 roundId */
     appendAssistantToolCall(fullContent, toolCalls) {
@@ -2903,6 +3004,8 @@ export class AgentLoop {
         else {
             this.messages.push({ role: 'system', content });
         }
+        // 情报区属「动态注入」段，刷新占用使指示器即时含其占用（P1-1）
+        this.refreshOccupancyFromMessages();
     }
     /**
      * 指定 toolCallId 的 tool 消息是否仍在上下文中且内容未被改动 —— 「结果仍在上下文」的共用判据。