@ai-agent-forge/agent-forge 0.86.2 → 0.86.4

package/dist/core/agent-session-compaction.js

@@ -7,12 +7,13 @@
  * spies keep working unchanged. Method-to-method calls go through the session
  * parameter (not direct function calls) to preserve that dispatch.
  */
+import { SUMMARIZATION_SYSTEM_PROMPT } from "@agent-forge/agent-core";
 import { contentText, retryAssistantCall, uuidv7 } from "@agent-forge/ai";
 import { completeSimple, streamSimple } from "@agent-forge/ai/compat";
 import { detachedSessionSnapshot, SessionCancelledError, } from "./agent-session-internal.js";
 import { dispatchCompactionDecisionLifecycle, dispatchCompactionFailedLifecycle } from "./agent-session-lifecycle.js";
 import { formatNoApiKeyFoundMessage, formatNoModelSelectedMessage } from "./auth-guidance.js";
-import { calculateContextTokens, collectEntriesForBranchSummary, estimateContextTokens, estimateTokens, isTurnStartMessage, } from "./compaction/index.js";
+import { calculateContextTokens, collectEntriesForBranchSummary, effectiveKeepRecentTokens, estimateContextTokens, estimateTokens, isTurnStartMessage, } from "./compaction/index.js";
 import { DEFAULT_COMPACTION_POLICY_NAME, SESSION_COMPACTION_COMMIT_EVENT_ID, SESSION_COMPACTION_COMMIT_EVENT_VERSION, } from "./extensions/index.js";
 import { SUMMARY_MODEL_INVOCATION_ERROR_CODES } from "./extensions/public-api.js";
 import { getLatestCompactionEntry } from "./session-manager.js";
@@ -48,11 +49,23 @@ const OVERFLOW_TRIM_STAGE2_TARGET_TOKENS = 10_000;
  * 冷却把"阈值带上反复触发中部改写"的最坏情形封顶。
  */
 const MICROCOMPACT_COOLDOWN_ASSISTANT_RESPONSES = 3;
-/** 溢出裁剪失败文案：实际发生过裁剪时附上前缀，0 次保持策略原文。 */
-function overflowTrimFailureMessage(attempts, failureMessage) {
-    return attempts > 0
-        ? `Context overflow persists after compaction and ${attempts} trim attempts. ${failureMessage}`
-        : failureMessage;
+/** 摘要自批判评审轮 prompt（gemini-cli 同款思路，compaction.summarySelfCritique 开启时启用）。 */
+function summarySelfCritiquePrompt(summary) {
+    return `Critically evaluate the summary in <summary> tags: it is the only context a continuation model will receive. Check for omissions that would break continuity - exact file paths, function/identifier names, error messages, user-stated constraints and preferences, decisions with rationale, and current task state. If something important is missing or wrong, output the corrected summary in the same format. If it is already complete, output it again verbatim. Output ONLY the summary.
+
+<summary>
+${summary}
+</summary>`;
+}
+/**
+ * 溢出/截断裁剪失败文案：实际发生过裁剪时附上前缀（分语：context overflow
+ * 维持既有精确文案，recoverable length 用截断响应措辞），0 次保持策略原文。
+ */
+function overflowTrimFailureMessage(attempts, failureMessage, kind) {
+    if (attempts <= 0)
+        return failureMessage;
+    const head = kind === "contextOverflow" ? "Context overflow" : "Truncated response";
+    return `${head} persists after compaction and ${attempts} trim attempts. ${failureMessage}`;
 }
 /**
  * Trim the runtime projection for one overflow-recovery stage: drop the oldest
@@ -99,10 +112,10 @@ function trimOverflowProjection(messages, stage, keepRecentTokens) {
     const floorStart = turnStarts[turnStarts.length - 1];
     return floorStart === 0 ? messages : messages.slice(floorStart);
 }
-export async function getRequiredRequestAuth(session, model) {
+export async function getRequiredRequestAuth(session, model, signal) {
     let result;
     try {
-        result = await session._modelRuntime.getAuth(model);
+        result = await session._modelRuntime.getAuth(model, { signal });
     }
     catch (error) {
         const cause = error instanceof Error ? error.cause : undefined;
@@ -128,12 +141,12 @@ export async function getRequiredRequestAuth(session, model) {
     }
     throw new Error(formatNoApiKeyFoundMessage(model.provider));
 }
-export async function getSummarizationRequestAuth(session, model) {
+export async function getSummarizationRequestAuth(session, model, signal) {
     if (session.agent.streamFunction === streamSimple) {
-        return getRequiredRequestAuth(session, model);
+        return getRequiredRequestAuth(session, model, signal);
     }
     try {
-        const result = await session._modelRuntime.getAuth(model);
+        const result = await session._modelRuntime.getAuth(model, { signal });
         if (!result)
             return { model };
         const requestModel = result.auth.baseUrl ? { ...model, baseUrl: result.auth.baseUrl } : model;
@@ -144,7 +157,12 @@ export async function getSummarizationRequestAuth(session, model) {
             env: result.env,
         };
     }
-    catch {
+    catch (error) {
+        // Auth resolution normally falls back to an unauthenticated summary when
+        // it fails, but an abort must not be swallowed into that fallback: the
+        // caller's signal decided this run is over.
+        if (signal?.aborted)
+            throw error;
         return { model };
     }
 }
@@ -266,6 +284,13 @@ export async function compactBeforeNextAssistantResponse(session, context, signa
     if (!model || model.contextWindow <= 0) {
         return context;
     }
+    // Adaptive keepRecentTokens：小窗口把近期保护预算钳到可摘要窗口的一半
+    //（effectiveKeepRecentTokens，动机见其注释；大窗口原值不变），本路径与
+    // checkCompaction/compactInternal/runAutoCompactionInternal 一致使用 effective 值。
+    const effectiveSettings = {
+        ...settings,
+        keepRecentTokens: effectiveKeepRecentTokens(settings.keepRecentTokens, model.contextWindow, settings.reserveTokens),
+    };
     const contextTokens = estimateContextTokens(context.messages).tokens;
     const decision = await decideCompaction(session, {
         reason: "threshold",
@@ -277,7 +302,10 @@ export async function compactBeforeNextAssistantResponse(session, context, signa
             reserveTokens: settings.reserveTokens,
         },
         canContinue: false,
-        // 设置开关 ∧ 冷却归零：被任一条件挡住时策略不做便宜缓解，直接走全量压缩。
+        // 便宜缓解的事实输入与门控，与 checkCompaction 的 threshold decide 相同
+        //（设置开关 ∧ 冷却归零）：被任一条件挡住时策略不做便宜缓解，直接走全量压缩。
+        branchEntries: session.sessionManager.getBranch(),
+        keepRecentTokens: effectiveSettings.keepRecentTokens,
         microcompactEnabled: settings.microcompactEnabled && session._microcompactCooldown === 0,
         signal: signal ?? session._policyDecisionAbortController?.signal,
     });
@@ -292,6 +320,27 @@ export async function compactBeforeNextAssistantResponse(session, context, signa
         reserveTokens: settings.reserveTokens,
         ...(decision.failureMessage === undefined ? {} : { failureMessage: decision.failureMessage }),
     });
+    // 策略便宜缓解（通用通道），镜像 checkCompaction 的 relief 落地分支：宿主原样
+    // 追加条目并重投影上下文，条目语义与投影归策略。执行上下文：本函数经默认
+    // prepareNextTurn loop link 在 agent 回合之间被 agent run await，不在
+    // _compactionQueue 内；手动压缩入口 compactInternal 先 _abortInternal() 等待
+    // 活跃回合结束，而本路径位于回合执行链上，回合结束前必先完成——relief 落地
+    // （同步 append + 投影）不会与手动压缩的摘要/提交交错，与 postAgentRun 的
+    // relief 落地同模式，不加队列锁。
+    if (decision.relief !== undefined && !decision.compact) {
+        session.sessionManager.appendCustomEntry(decision.relief.customType, decision.relief.data);
+        const sessionContext = session.sessionManager.buildSessionContext();
+        await session._applyContextTransition(sessionContext.messages, "compaction");
+        // 冷却起点：relief 已落地即开始计数（由 assistant message_end 递减）。
+        session._microcompactCooldown = MICROCOMPACT_COOLDOWN_ASSISTANT_RESPONSES;
+        session._hostLogger?.info("compaction", "policy relief applied", {
+            fields: { customType: decision.relief.customType, path: "pre-response" },
+        });
+        return {
+            ...context,
+            messages: session.agent.state.messages.slice(),
+        };
+    }
     if (!decision.compact)
         return context;
     await session._runAutoCompaction("threshold", false);
@@ -330,8 +379,39 @@ export async function runCompactionSummary(session, preparation, auth, customIns
         context: { version: 1, sessionId: session.sessionId, phase: "compaction" },
         execution,
     });
+    let summary = result.summary;
+    let usage = result.usage;
+    // 摘要自批判评审轮（settings compaction.summarySelfCritique，默认关闭）：
+    // 摘要是续接模型的全部上下文，漏一处路径/约束就断一环——多花一次小请求换
+    // 一遍"漏了什么"的自检（gemini-cli 两段式压缩的同款思路）。失败/中止/空文
+    // 本时保持第一轮摘要，评审轮不产生降级路径。
+    if (session.settingsManager.getCompactionSettings().summarySelfCritique && summary.trim() && !signal.aborted) {
+        const critique = await createSummaryModelInvocationV1(session, auth, summarizationRetryPolicy(session, execution.operationId, execution.inputRevision, signal), summarizationRetryCallbacks(session, { source: "compaction", reason }), { routingSessionId: session.sessionId }).invoke({
+            version: 1,
+            systemPrompt: SUMMARIZATION_SYSTEM_PROMPT,
+            prompt: summarySelfCritiquePrompt(summary),
+            maxTokens: 8192,
+            thinkingLevel: session.thinkingLevel === "off" ? "off" : "low",
+        }, signal);
+        if (critique.status === "completed" && critique.text && critique.text.trim()) {
+            summary = critique.text;
+            // 公共契约的 usage 是不透明透传；评审轮实际回传 provider Usage 形状，
+            // 这里按字段防御性收窄后并入压缩 usage。
+            const critiqueUsage = critique.usage;
+            if (usage && critiqueUsage) {
+                const add = (a, b) => a + (b ?? 0);
+                usage = {
+                    ...usage,
+                    input: add(usage.input, critiqueUsage.input),
+                    output: add(usage.output, critiqueUsage.output),
+                    cacheRead: add(usage.cacheRead ?? 0, critiqueUsage.cacheRead),
+                    cacheWrite: add(usage.cacheWrite ?? 0, critiqueUsage.cacheWrite),
+                };
+            }
+        }
+    }
     // 包内收窄：invocation 结果按 provider 原样透传 usage；压缩 usage 合并需要内部 Usage 形状。
-    return { ...result, usage: result.usage };
+    return { ...result, summary, usage };
 }
 export async function decideCompaction(session, input) {
     const runtime = session._capabilityRuntime;
@@ -534,9 +614,16 @@ export async function compactInternal(session, customInstructions) {
         if (!session.model) {
             throw new Error(formatNoModelSelectedMessage());
         }
-        const auth = await getSummarizationRequestAuth(session, session.model);
+        const auth = await getSummarizationRequestAuth(session, session.model, session._compactionAbortController.signal);
         const { pathEntries, expectedRevision, operationId } = captureCompactionCommitBoundary(session, "manual");
-        const settings = session.settingsManager.getCompactionSettings();
+        const rawSettings = session.settingsManager.getCompactionSettings();
+        // Adaptive keepRecentTokens（effectiveKeepRecentTokens，动机见其注释）：手动
+        // 压缩与自动路径同一 effective 值，小窗口下 /compact 不再因保护预算吃满
+        // 整个可摘要窗口而报 "Nothing to compact"。
+        const settings = {
+            ...rawSettings,
+            keepRecentTokens: effectiveKeepRecentTokens(rawSettings.keepRecentTokens, session.model.contextWindow, rawSettings.reserveTokens),
+        };
         const execution = executionFacts(session, "compaction", operationId);
         const preparation = await prepareCompaction(session, pathEntries, settings, execution, session._compactionAbortController.signal);
         if (!preparation) {
@@ -649,6 +736,13 @@ export async function checkCompaction(session, assistantMessage, skipAbortedChec
     if (signal?.aborted)
         return false;
     const settings = session.settingsManager.getCompactionSettings();
+    // Adaptive keepRecentTokens（effectiveKeepRecentTokens，动机见其注释：座席实测
+    // 30K 窗口 20K 保护预算使可摘要前缀为零，阈值反复命中却无事可做）。一次性
+    // 替换后全文一致使用：下方 trim 阶梯 stage 0 目标与 threshold decide 请求。
+    const effectiveSettings = {
+        ...settings,
+        keepRecentTokens: effectiveKeepRecentTokens(settings.keepRecentTokens, session.model?.contextWindow ?? 0, settings.reserveTokens),
+    };
     // Skip if message was aborted (user cancelled) - unless skipAbortedCheck is false
     if (skipAbortedCheck && assistantMessage.stopReason === "aborted")
         return false;
@@ -692,11 +786,12 @@ export async function checkCompaction(session, assistantMessage, skipAbortedChec
             ...(decision.failureMessage === undefined ? {} : { failureMessage: decision.failureMessage }),
         });
         if (!decision.compact) {
-            // 溢出裁剪兜底：压缩恢复（recoveryAttempted）后仍 context overflow 时，
-            // 先对运行时投影做逐级裁剪重试，3 级全失败才走策略 failureMessage 失败
-            // 路径。执行逻辑归 AgentSession，策略接口与事件面不变。
+            // 溢出裁剪兜底：压缩恢复（recoveryAttempted）后仍 context overflow 或
+            // recoverable length（截断响应=输出被掐，缩输入可让输出有空间，turn 边界
+            // 裁剪对两种溢出同样有效）时，先对运行时投影做逐级裁剪重试，3 级全失败才
+            // 走策略 failureMessage 失败路径。执行逻辑归 AgentSession，策略接口与事件面不变。
             if (decision.failureMessage &&
-                contextOverflow &&
+                (contextOverflow || recoverableLength) &&
                 session._overflowRecoveryAttempted &&
                 session._overflowTrimStage < OVERFLOW_TRIM_MAX_STAGES) {
                 const stage = session._overflowTrimStage;
@@ -717,11 +812,11 @@ export async function checkCompaction(session, assistantMessage, skipAbortedChec
                         const base = messages.length > 0 && messages[messages.length - 1].role === "assistant"
                             ? messages.slice(0, -1)
                             : messages;
-                        const trimmed = trimOverflowProjection(base, stage, settings.keepRecentTokens);
+                        const trimmed = trimOverflowProjection(base, stage, effectiveSettings.keepRecentTokens);
                         // 返回原引用 = 已无可裁（估算已在目标内或无 turn 边界）：重试注定
                         // 同样溢出，不空转请求，按策略失败文案直接失败（级数未增，无前缀）。
                         if (trimmed.length === 0 || trimmed === base) {
-                            const errorMessage = overflowTrimFailureMessage(stage, failureMessage);
+                            const errorMessage = overflowTrimFailureMessage(stage, failureMessage, contextOverflow ? "contextOverflow" : "recoverableLength");
                             session._emit({
                                 type: "compaction_end",
                                 reason: "overflow",
@@ -785,9 +880,7 @@ export async function checkCompaction(session, assistantMessage, skipAbortedChec
                 });
             }
             if (decision.failureMessage) {
-                const errorMessage = contextOverflow
-                    ? overflowTrimFailureMessage(session._overflowTrimStage, decision.failureMessage)
-                    : decision.failureMessage;
+                const errorMessage = overflowTrimFailureMessage(session._overflowTrimStage, decision.failureMessage, contextOverflow ? "contextOverflow" : "recoverableLength");
                 session._emit({
                     type: "compaction_end",
                     reason: "overflow",
@@ -858,8 +951,8 @@ export async function checkCompaction(session, assistantMessage, skipAbortedChec
         // 策略读取，内核不解释其内容。门控（设置开关 ∧ 冷却归零）被挡住时，
         // 策略直接走全量压缩。
         branchEntries: session.sessionManager.getBranch(),
-        keepRecentTokens: settings.keepRecentTokens,
-        microcompactEnabled: settings.microcompactEnabled && session._microcompactCooldown === 0,
+        keepRecentTokens: effectiveSettings.keepRecentTokens,
+        microcompactEnabled: effectiveSettings.microcompactEnabled && session._microcompactCooldown === 0,
         signal,
     });
     await dispatchCompactionDecisionLifecycle(session, {
@@ -930,13 +1023,19 @@ export async function runAutoCompactionInternal(session, reason, willRetry) {
             session._autoCompactionAbortController = undefined;
             throw error;
         }
-        const settings = session.settingsManager.getCompactionSettings();
+        const rawSettings = session.settingsManager.getCompactionSettings();
+        // Adaptive keepRecentTokens（effectiveKeepRecentTokens，动机见其注释）：
+        // 小窗口下可摘要前缀不再被保护预算吃满，阈值命中的压缩真实落地而非空转。
+        const settings = {
+            ...rawSettings,
+            keepRecentTokens: effectiveKeepRecentTokens(rawSettings.keepRecentTokens, session.model?.contextWindow ?? 0, rawSettings.reserveTokens),
+        };
         let started = false;
         try {
             if (!session.model) {
                 return false;
             }
-            const auth = await getSummarizationRequestAuth(session, session.model);
+            const auth = await getSummarizationRequestAuth(session, session.model, autoCompactionSignal);
             const { pathEntries, expectedRevision, operationId } = captureCompactionCommitBoundary(session, reason);
             const execution = executionFacts(session, "compaction", operationId);
             const preparation = await prepareCompaction(session, pathEntries, settings, execution, autoCompactionSignal);
@@ -1004,22 +1103,39 @@ export async function runAutoCompactionInternal(session, reason, willRetry) {
             return session.agent.hasQueuedMessages();
         }
         catch (error) {
-            const errorMessage = error instanceof Error ? error.message : "compaction failed";
+            const message = error instanceof Error ? error.message : "compaction failed";
+            // Cancellation is decided by the controller state, not the error shape:
+            // aborts surface as AbortError from the summary pipeline, but so can
+            // unrelated failures — only the signal tells them apart.
+            const aborted = autoCompactionSignal.aborted;
             if (started) {
-                const formattedErrorMessage = reason === "overflow"
-                    ? `Context overflow recovery failed: ${errorMessage}`
-                    : `Auto-compaction failed: ${errorMessage}`;
-                session._emit({
-                    type: "compaction_end",
-                    reason,
-                    result: undefined,
-                    aborted: false,
-                    willRetry: false,
-                    errorMessage: formattedErrorMessage,
-                });
-                // 压缩失败打点：与下方 failed 事件同一事实；started 前的取消路径不打点。
-                session._hostLogger?.error("compaction", "compaction failed", { fields: { reason }, cause: error });
-                await dispatchCompactionFailedLifecycle(session, { reason, errorMessage: formattedErrorMessage });
+                if (aborted) {
+                    // 取消按正常结果收场（aborted:true、无错误文案），不打失败日志、
+                    // 不 dispatch failed lifecycle（契约见 dispatchCompactionFailedLifecycle 注释）。
+                    session._emit({
+                        type: "compaction_end",
+                        reason,
+                        result: undefined,
+                        aborted: true,
+                        willRetry: false,
+                    });
+                }
+                else {
+                    const formattedErrorMessage = reason === "overflow"
+                        ? `Context overflow recovery failed: ${message}`
+                        : `Auto-compaction failed: ${message}`;
+                    session._emit({
+                        type: "compaction_end",
+                        reason,
+                        result: undefined,
+                        aborted: false,
+                        willRetry: false,
+                        errorMessage: formattedErrorMessage,
+                    });
+                    // 压缩失败打点：与下方 failed 事件同一事实；取消路径不打点。
+                    session._hostLogger?.error("compaction", "compaction failed", { fields: { reason }, cause: error });
+                    await dispatchCompactionFailedLifecycle(session, { reason, errorMessage: formattedErrorMessage });
+                }
             }
             return false;
         }
@@ -1159,7 +1275,7 @@ export async function navigateTree(session, targetId, options = {}) {
         let summaryUsage;
         if (options.summarize && entriesToSummarize.length > 0) {
             const model = session.model;
-            const auth = await getSummarizationRequestAuth(session, model);
+            const auth = await getSummarizationRequestAuth(session, model, session._branchSummaryAbortController.signal);
             const branchSummarySettings = session.settingsManager.getBranchSummarySettings();
             const runtime = session._capabilityRuntime;
             if (!runtime || !runtime.hasBranchSummaryPolicy(session._branchSummaryPolicyName)) {