@ai-agent-forge/agent-forge 0.86.1 → 0.86.3

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

@@ -12,7 +12,7 @@ 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";
@@ -37,11 +37,26 @@ function estimateMessagesTokens(messages) {
 const OVERFLOW_TRIM_MAX_STAGES = 3;
 /** 溢出裁剪第 2 级的目标 token 预算（估算）。 */
 const OVERFLOW_TRIM_STAGE2_TARGET_TOKENS = 10_000;
-/** 溢出裁剪失败文案：实际发生过裁剪时附上前缀，0 次保持策略原文。 */
-function overflowTrimFailureMessage(attempts, failureMessage) {
-    return attempts > 0
-        ? `Context overflow persists after compaction and ${attempts} trim attempts. ${failureMessage}`
-        : failureMessage;
+/**
+ * microcompact 冷却长度（按模型请求计数）：relief 落地后置此值，之后每次
+ * assistant message_end（无论 stopReason）减 1，归零前阈值 decide 以
+ * `microcompactEnabled: false` 关闭便宜缓解，落回全量压缩；user message_start
+ * 不复位——冷却按模型请求计数，与 turn 边界无关。
+ *
+ * 微观经济动机：每次 microcompact 触发都是一次中部历史改写，本网关前缀缓存
+ * 不稳定（实测同请求命中 3-99%），改尾部命中 88-99.9%、改中部 40-50%——
+ * 冷却把"阈值带上反复触发中部改写"的最坏情形封顶。
+ */
+const MICROCOMPACT_COOLDOWN_ASSISTANT_RESPONSES = 3;
+/**
+ * 溢出/截断裁剪失败文案：实际发生过裁剪时附上前缀（分语：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
@@ -88,10 +103,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;
@@ -117,12 +132,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;
@@ -133,7 +148,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 };
     }
 }
@@ -255,6 +275,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",
@@ -266,6 +293,11 @@ 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,
     });
     await dispatchCompactionDecisionLifecycle(session, {
@@ -279,6 +311,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);
@@ -521,9 +574,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) {
@@ -636,6 +696,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;
@@ -679,11 +746,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;
@@ -704,11 +772,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",
@@ -772,9 +840,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",
@@ -842,9 +908,11 @@ export async function checkCompaction(session, assistantMessage, skipAbortedChec
         canContinue: false,
         // 便宜缓解的事实输入：策略可以据此先做零成本的本地上下文缓解（如
         // bootstrap 策略的 microcompact），把 LLM 摘要留作兜底。分支快照仅为
-        // 策略读取，内核不解释其内容。
+        // 策略读取，内核不解释其内容。门控（设置开关 ∧ 冷却归零）被挡住时，
+        // 策略直接走全量压缩。
         branchEntries: session.sessionManager.getBranch(),
-        keepRecentTokens: settings.keepRecentTokens,
+        keepRecentTokens: effectiveSettings.keepRecentTokens,
+        microcompactEnabled: effectiveSettings.microcompactEnabled && session._microcompactCooldown === 0,
         signal,
     });
     await dispatchCompactionDecisionLifecycle(session, {
@@ -863,6 +931,9 @@ export async function checkCompaction(session, assistantMessage, skipAbortedChec
         session.sessionManager.appendCustomEntry(decision.relief.customType, decision.relief.data);
         const sessionContext = session.sessionManager.buildSessionContext();
         await session._applyContextTransition(sessionContext.messages, "compaction");
+        // 冷却起点：relief 已落地即开始计数（本次改写后的下一个模型请求起算，
+        // 由 assistant message_end 递减，见 AgentSession）。
+        session._microcompactCooldown = MICROCOMPACT_COOLDOWN_ASSISTANT_RESPONSES;
         session._hostLogger?.info("compaction", "policy relief applied", {
             fields: { customType: decision.relief.customType },
         });
@@ -912,13 +983,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);
@@ -986,22 +1063,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;
         }
@@ -1141,7 +1235,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)) {