@aexol/spectral 0.9.58 → 0.9.59

package/dist/sdk/coding-agent/core/agent-session.js

@@ -14,14 +14,13 @@
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname } from "node:path";
-import { clampThinkingLevel, cleanupSessionResources, getSupportedThinkingLevels, isContextOverflow, modelsAreEqual, resetApiProviders, streamSimple, } from "../../ai/index.js";
-import { AssistantMessageEventStream } from "../../ai/utils/event-stream.js";
+import { clampThinkingLevel, cleanupSessionResources, getSupportedThinkingLevels, isContextOverflow, modelsAreEqual, resetApiProviders, } from "../../ai/index.js";
 import { stripFrontmatter } from "../utils/frontmatter.js";
 import { resolvePath } from "../utils/paths.js";
 import { sleep } from "../utils/sleep.js";
 import { formatNoApiKeyFoundMessage, formatNoModelSelectedMessage } from "./auth-guidance.js";
 import { executeBashWithOperations } from "./bash-executor.js";
-import { calculateContextTokens, collectEntriesForBranchSummary, compact, estimateContextTokens, generateBranchSummary, prepareCompaction, shouldCompact, } from "./compaction/index.js";
+import { calculateContextTokens, collectEntriesForBranchSummary, compactDcpLite, estimateContextTokens, estimateCompactionTokenMetrics, getManualCompactionSettings, normalizeCompactionPolicy, normalizeManualKeepRecentTokens, generateBranchSummary, prepareCompaction, shouldCompact, } from "./compaction/index.js";
 import { DEFAULT_THINKING_LEVEL } from "./defaults.js";
 import { ExtensionRunner, wrapRegisteredTools, } from "./extensions/index.js";
 import { emitSessionShutdownEvent } from "./extensions/runner.js";
@@ -48,11 +47,110 @@ export function parseSkillBlock(text) {
         userMessage: match[4]?.trim() || undefined,
     };
 }
+function normalizeManualCompactionOptions(input) {
+    if (typeof input === "string")
+        return { customInstructions: input };
+    return {
+        customInstructions: input?.customInstructions,
+        phaseBoundary: input?.phaseBoundary,
+        keepRecentTokens: input?.keepRecentTokens,
+        memoryHookMode: input?.memoryHookMode === "skip" ? "skip" : "inline",
+    };
+}
+const DCP_LITE_PHASE_BOUNDARY_CUSTOM_TYPE = "spectral.dcp-lite.phase-boundary";
+const DCP_LITE_PHASE_BOUNDARY_MARKER = "DCP-lite phase boundary: prior raw context was compacted. Continue using the compaction summary above.";
+function createVirtualPhaseBoundaryEntry(pathEntries) {
+    const parentId = pathEntries[pathEntries.length - 1]?.id ?? null;
+    return {
+        type: "custom_message",
+        customType: DCP_LITE_PHASE_BOUNDARY_CUSTOM_TYPE,
+        content: DCP_LITE_PHASE_BOUNDARY_MARKER,
+        display: false,
+        details: { virtual: true },
+        id: "__spectral_dcp_lite_phase_boundary_probe__",
+        parentId,
+        timestamp: new Date().toISOString(),
+    };
+}
+function isDcpLitePhaseBoundaryEntry(entry) {
+    return entry?.type === "custom_message" && entry.customType === DCP_LITE_PHASE_BOUNDARY_CUSTOM_TYPE;
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function isObservationalMemoryDetails(details) {
+    if (!isRecord(details))
+        return false;
+    const record = details;
+    return (record.type === "observational-memory" &&
+        (record.version === 3 || record.version === 4) &&
+        Array.isArray(record.observations) &&
+        Array.isArray(record.reflections));
+}
+function buildCompactionTelemetryDetails(result) {
+    const telemetry = {};
+    if (typeof result.tokensCompacted === "number")
+        telemetry.tokensCompacted = result.tokensCompacted;
+    if (typeof result.tokensRemoved === "number")
+        telemetry.tokensRemoved = result.tokensRemoved;
+    if (typeof result.summaryTokens === "number")
+        telemetry.summaryTokens = result.summaryTokens;
+    if (typeof result.reductionPercent === "number")
+        telemetry.reductionPercent = result.reductionPercent;
+    if (typeof result.compactionNumber === "number")
+        telemetry.compactionNumber = result.compactionNumber;
+    if (result.largestTokenSources?.length)
+        telemetry.largestTokenSources = result.largestTokenSources;
+    return telemetry;
+}
+function preserveDcpHookMemoryDetails(dcpResult, extensionCompaction) {
+    if (!extensionCompaction ||
+        !isRecord(extensionCompaction.details) ||
+        !isObservationalMemoryDetails(extensionCompaction.details))
+        return dcpResult;
+    const extensionDetails = extensionCompaction.details;
+    const mergedDetails = {
+        ...extensionDetails,
+        compactionTelemetry: buildCompactionTelemetryDetails(dcpResult),
+    };
+    if (isRecord(dcpResult.details)) {
+        mergedDetails.dcpLite = dcpResult.details;
+    }
+    return {
+        ...dcpResult,
+        details: mergedDetails,
+    };
+}
+function getNonShrinkingSkipMessage(result) {
+    const tokensCompacted = result.tokensCompacted;
+    const summaryTokens = result.summaryTokens;
+    const tokensRemoved = result.tokensRemoved;
+    if (typeof tokensCompacted !== "number" || typeof summaryTokens !== "number")
+        return undefined;
+    if (tokensCompacted <= 0) {
+        return "Compaction skipped: no eligible history to compact.";
+    }
+    if ((tokensRemoved ?? 0) <= 0 || summaryTokens >= tokensCompacted) {
+        return `Compaction skipped: generated summary would not shrink context (` +
+            `compacted ~${tokensCompacted.toLocaleString()} tokens, ` +
+            `summary +~${summaryTokens.toLocaleString()} tokens).`;
+    }
+    return undefined;
+}
+function markCompactionSkipped(result, skipReason, message) {
+    return {
+        ...result,
+        skipped: true,
+        skipReason,
+        message,
+    };
+}
 // ============================================================================
 // Constants
 // ============================================================================
 /** Standard thinking levels */
 const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high"];
+const LENGTH_CONTINUATION_PROMPT = "Your previous assistant response ended because the provider hit its maximum output length. Continue exactly from where it stopped. Do not repeat, recap, or summarize earlier content. If the previous response ended mid-sentence, resume with the next missing word; otherwise continue with the next missing content.";
 // ============================================================================
 // AgentSession Class
 // ============================================================================
@@ -80,6 +178,12 @@ export class AgentSession {
     // Retry state
     _retryAbortController = undefined;
     _retryAttempt = 0;
+    _lengthContinuationAttempts = 0;
+    _lengthContinuationOutputTokens = 0;
+    _pendingInternalLengthContinuationMessages = 0;
+    _internalLengthContinuationUserMessages = new WeakSet();
+    _autoOlderHistoryCooldownTurnsRemaining = 0;
+    _lastAutoOlderHistorySkipSignature;
     // Bash execution state
     _bashAbortController = undefined;
     _pendingBashMessages = [];
@@ -158,13 +262,6 @@ export class AgentSession {
         }
         throw new Error(formatNoApiKeyFoundMessage(model.provider));
     }
-    async _getCompactionRequestAuth(model) {
-        if (this.agent.streamFn === streamSimple) {
-            return this._getRequiredRequestAuth(model);
-        }
-        const result = await this._modelRegistry.getApiKeyAndHeaders(model);
-        return result.ok ? { apiKey: result.apiKey, headers: result.headers } : {};
-    }
     /**
      * Install tool hooks once on the Agent instance.
      *
@@ -243,6 +340,7 @@ export class AgentSession {
         if (event.type === "message_start" && event.message.role === "user") {
             this._overflowRecoveryAttempted = false;
             const messageText = this._getUserMessageText(event.message);
+            this._handleUserMessageStart(messageText, event.message);
             if (messageText) {
                 // Check steering queue first
                 const steeringIndex = this._steeringMessages.indexOf(messageText);
@@ -266,17 +364,7 @@ export class AgentSession {
         this._emit(event.type === "agent_end" ? { ...event, willRetry: this._willRetryAfterAgentEnd(event) } : event);
         // Handle session persistence
         if (event.type === "message_end") {
-            // Check if this is a custom message from extensions
-            if (event.message.role === "custom") {
-                // Persist as CustomMessageEntry
-                this.sessionManager.appendCustomMessageEntry(event.message.customType, event.message.content, event.message.display, event.message.details);
-            }
-            else if (event.message.role === "user" ||
-                event.message.role === "assistant" ||
-                event.message.role === "toolResult") {
-                // Regular LLM message - persist as SessionMessageEntry
-                this.sessionManager.appendMessage(event.message);
-            }
+            this._persistMessageEnd(event.message);
             // Other message types (bashExecution, compactionSummary, branchSummary) are persisted elsewhere
             // Track assistant message for auto-compaction (checked on agent_end)
             if (event.message.role === "assistant") {
@@ -298,6 +386,43 @@ export class AgentSession {
             }
         }
     };
+    _persistMessageEnd(message) {
+        // Check if this is a custom message from extensions
+        if (message.role === "custom") {
+            // Persist as CustomMessageEntry
+            this.sessionManager.appendCustomMessageEntry(message.customType, message.content, message.display, message.details);
+        }
+        else if ((message.role === "user" && !this._shouldSkipMessagePersistence(message)) ||
+            message.role === "assistant" ||
+            message.role === "toolResult") {
+            // Regular LLM message - persist as SessionMessageEntry
+            this.sessionManager.appendMessage(message);
+        }
+    }
+    _handleUserMessageStart(messageText, message) {
+        const isInternalLengthContinuation = messageText === LENGTH_CONTINUATION_PROMPT && this._pendingInternalLengthContinuationMessages > 0;
+        if (isInternalLengthContinuation) {
+            this._pendingInternalLengthContinuationMessages--;
+            this._internalLengthContinuationUserMessages.add(message);
+            return;
+        }
+        this._resetLengthContinuationState();
+        if (this._autoOlderHistoryCooldownTurnsRemaining > 0) {
+            this._autoOlderHistoryCooldownTurnsRemaining--;
+        }
+    }
+    _resetLengthContinuationState() {
+        this._lengthContinuationAttempts = 0;
+        this._lengthContinuationOutputTokens = 0;
+    }
+    _shouldSkipMessagePersistence(message) {
+        if (message.role !== "user")
+            return false;
+        if (!this._internalLengthContinuationUserMessages.has(message))
+            return false;
+        this._internalLengthContinuationUserMessages.delete(message);
+        return true;
+    }
     _willRetryAfterAgentEnd(event) {
         const settings = this.settingsManager.getRetrySettings();
         if (!settings.enabled || this._retryAttempt >= settings.maxRetries) {
@@ -707,8 +832,81 @@ export class AgentSession {
             });
             this._retryAttempt = 0;
         }
+        if (this._shouldAutoContinueLengthStop(msg)) {
+            this._queueInternalLengthContinuation(this._getAssistantOutputTokens(msg));
+            return true;
+        }
         return await this._checkCompaction(msg);
     }
+    _getCompactionPolicy() {
+        const manager = this.settingsManager;
+        return manager.getCompactionPolicy?.() ?? normalizeCompactionPolicy(manager.getCompactionSettings());
+    }
+    _shouldAutoContinueLengthStop(message) {
+        if (message.stopReason !== "length")
+            return false;
+        const policy = this._getCompactionPolicy().truncationContinuation;
+        const outputTokens = this._getAssistantOutputTokens(message);
+        if (this._lengthContinuationAttempts > 0) {
+            this._lengthContinuationOutputTokens += outputTokens;
+        }
+        const contextWindow = this.model?.contextWindow ?? 0;
+        if (isContextOverflow(message, contextWindow)) {
+            this._emitLengthContinuationEvent("skipped", "context_overflow", outputTokens, policy);
+            return false;
+        }
+        if (outputTokens <= 0 || !this._assistantMessageHasVisibleOutput(message)) {
+            this._emitLengthContinuationEvent("skipped", "empty_output", outputTokens, policy);
+            return false;
+        }
+        if (this._lengthContinuationAttempts >= policy.maxAttempts) {
+            this._emitLengthContinuationEvent("skipped", "max_attempts", outputTokens, policy);
+            return false;
+        }
+        if (this._lengthContinuationOutputTokens >= policy.totalOutputTokenBudget) {
+            this._emitLengthContinuationEvent("skipped", "budget_exhausted", outputTokens, policy);
+            return false;
+        }
+        return true;
+    }
+    _getAssistantOutputTokens(message) {
+        const outputTokens = message.usage.output;
+        if (!Number.isFinite(outputTokens) || outputTokens <= 0)
+            return 0;
+        return Math.trunc(outputTokens);
+    }
+    _emitLengthContinuationEvent(status, reason, outputTokens, policy) {
+        this._emit({
+            type: "length_continuation",
+            status,
+            reason,
+            attempt: this._lengthContinuationAttempts,
+            maxAttempts: policy.maxAttempts,
+            outputTokens,
+            continuationOutputTokens: this._lengthContinuationOutputTokens,
+            totalOutputTokenBudget: policy.totalOutputTokenBudget,
+        });
+    }
+    _assistantMessageHasVisibleOutput(message) {
+        return message.content.some((part) => {
+            if (part.type === "text")
+                return part.text.trim().length > 0;
+            if (part.type === "thinking")
+                return part.thinking.trim().length > 0;
+            return false;
+        });
+    }
+    _queueInternalLengthContinuation(outputTokens = 0) {
+        const policy = this._getCompactionPolicy().truncationContinuation;
+        this._lengthContinuationAttempts++;
+        this.agent.followUp({
+            role: "user",
+            content: [{ type: "text", text: LENGTH_CONTINUATION_PROMPT }],
+            timestamp: Date.now(),
+        });
+        this._pendingInternalLengthContinuationMessages++;
+        this._emitLengthContinuationEvent("queued", "length_stop", outputTokens, policy);
+    }
     /**
      * Send a prompt to the agent.
      * - Handles extension commands (registered via spectral.registerCommand) immediately, even during streaming
@@ -1296,25 +1494,94 @@ export class AgentSession {
      * Aborts current agent operation first.
      * @param customInstructions Optional instructions for the compaction summary
      */
-    async compact(customInstructions) {
-        return this._withCompactionLock(() => this._executeCompaction(customInstructions));
+    async compact(options) {
+        return this._withCompactionLock(() => this._executeCompaction(options));
+    }
+    /**
+     * Build the shared deterministic DCP compaction result and stream the bounded
+     * summary through the same progress event used by compaction previews.
+     */
+    _buildDcpCompactionResult(preparation, extensionCompaction) {
+        return preserveDcpHookMemoryDetails(compactDcpLite(preparation), extensionCompaction);
+    }
+    _emitCompactionResultSummary(result) {
+        if (result.summary) {
+            this._emit({
+                type: "compaction_delta",
+                delta: result.summary,
+                content: result.summary,
+            });
+        }
+    }
+    _markIfNonShrinking(result) {
+        const message = getNonShrinkingSkipMessage(result);
+        return message ? markCompactionSkipped(result, "non_shrinking", message) : undefined;
+    }
+    async _emitSessionBeforeCompact(preparation, branchEntries, customInstructions, signal, emitProgress) {
+        const runner = this._extensionRunner;
+        if (!runner?.hasHandlers("session_before_compact"))
+            return undefined;
+        return (await runner.emit({
+            type: "session_before_compact",
+            preparation,
+            branchEntries,
+            customInstructions,
+            signal,
+            emitProgress,
+        }));
     }
     /**
      * Execute a manual compaction under the compaction lock.
      */
-    async _executeCompaction(customInstructions) {
+    async _executeCompaction(options) {
+        const { customInstructions, phaseBoundary, keepRecentTokens, memoryHookMode } = normalizeManualCompactionOptions(options);
         this._disconnectFromAgent();
         await this.abort();
         this._compactionAbortController = new AbortController();
         this._emit({ type: "compaction_start", reason: "manual" });
         try {
-            if (!this.model) {
-                throw new Error(formatNoModelSelectedMessage());
+            let pathEntries = this.sessionManager.getBranch();
+            const policy = this._getCompactionPolicy();
+            let settings = getManualCompactionSettings(policy.conversation, policy.manual);
+            if (typeof keepRecentTokens === "number" && Number.isFinite(keepRecentTokens) && keepRecentTokens > 0) {
+                const normalizedKeepRecentTokens = normalizeManualKeepRecentTokens(keepRecentTokens, policy.manual);
+                if (normalizedKeepRecentTokens > 0) {
+                    settings = { ...settings, keepRecentTokens: normalizedKeepRecentTokens };
+                }
             }
-            const { apiKey, headers } = await this._getCompactionRequestAuth(this.model);
-            const pathEntries = this.sessionManager.getBranch();
-            const settings = this.settingsManager.getCompactionSettings();
-            const preparation = prepareCompaction(pathEntries, settings);
+            if (phaseBoundary && !isDcpLitePhaseBoundaryEntry(pathEntries[pathEntries.length - 1])) {
+                const preflightEntries = [...pathEntries, createVirtualPhaseBoundaryEntry(pathEntries)];
+                const preflightPreparation = prepareCompaction(preflightEntries, settings, { phaseBoundary: true });
+                if (!preflightPreparation) {
+                    const lastEntry = pathEntries[pathEntries.length - 1];
+                    if (lastEntry?.type === "compaction") {
+                        throw new Error("Already compacted");
+                    }
+                    throw new Error("Nothing to compact (session too small)");
+                }
+                const preflightResult = this._buildDcpCompactionResult(preflightPreparation);
+                const preflightSkippedResult = this._markIfNonShrinking(preflightResult);
+                if (preflightSkippedResult) {
+                    this._emit({
+                        type: "compaction_end",
+                        reason: "manual",
+                        result: preflightSkippedResult,
+                        aborted: false,
+                        willRetry: false,
+                        errorMessage: preflightSkippedResult.message,
+                        skipped: true,
+                        skipReason: preflightSkippedResult.skipReason,
+                    });
+                    return preflightSkippedResult;
+                }
+                this.sessionManager.appendCustomMessageEntry(DCP_LITE_PHASE_BOUNDARY_CUSTOM_TYPE, DCP_LITE_PHASE_BOUNDARY_MARKER, false, {
+                    customInstructions,
+                    createdAt: new Date().toISOString(),
+                    reason: "model-visible-compact-context",
+                });
+                pathEntries = this.sessionManager.getBranch();
+            }
+            const preparation = prepareCompaction(pathEntries, settings, { phaseBoundary });
             if (!preparation) {
                 // Check why we can't compact
                 const lastEntry = pathEntries[pathEntries.length - 1];
@@ -1324,97 +1591,44 @@ export class AgentSession {
                 throw new Error("Nothing to compact (session too small)");
             }
             let extensionCompaction;
-            let fromExtension = false;
-            let extensionProgressContent = "";
-            const emitExtensionProgress = (delta, content) => {
-                if (!delta && !content)
-                    return;
-                extensionProgressContent = content ?? `${extensionProgressContent}${delta}`;
-                this._emit({
-                    type: "compaction_delta",
-                    delta,
-                    content: extensionProgressContent,
-                });
-            };
-            if (this._extensionRunner.hasHandlers("session_before_compact")) {
-                const result = (await this._extensionRunner.emit({
-                    type: "session_before_compact",
-                    preparation,
-                    branchEntries: pathEntries,
-                    customInstructions,
-                    signal: this._compactionAbortController.signal,
-                    emitProgress: emitExtensionProgress,
-                }));
-                if (result?.cancel) {
-                    throw new Error("Compaction cancelled");
-                }
-                if (result?.compaction) {
-                    extensionCompaction = result.compaction;
-                    fromExtension = true;
-                }
-            }
-            let summary;
-            let firstKeptEntryId;
-            let tokensBefore;
-            let details;
-            if (extensionCompaction) {
-                // Extension provided compaction content
-                summary = extensionCompaction.summary;
-                firstKeptEntryId = extensionCompaction.firstKeptEntryId;
-                tokensBefore = extensionCompaction.tokensBefore;
-                details = extensionCompaction.details;
-                // Emit the full summary as a compaction_delta so the frontend
-                // displays it in the live preview panel during compaction.
-                if (summary) {
+            if (memoryHookMode !== "skip") {
+                let extensionProgressContent = "";
+                const emitExtensionProgress = (delta, content) => {
+                    if (!delta && !content)
+                        return;
+                    extensionProgressContent = content ?? `${extensionProgressContent}${delta}`;
                     this._emit({
                         type: "compaction_delta",
-                        delta: summary,
-                        content: summary,
+                        delta,
+                        content: extensionProgressContent,
                     });
+                };
+                const beforeCompactResult = await this._emitSessionBeforeCompact(preparation, pathEntries, customInstructions, this._compactionAbortController.signal, emitExtensionProgress);
+                if (!beforeCompactResult?.cancel && beforeCompactResult?.compaction) {
+                    extensionCompaction = beforeCompactResult.compaction;
                 }
             }
-            else {
-                // Wrap streamFn to emit compaction_delta events for live progress.
-                const originalStreamFn = this.agent.streamFn;
-                const wrappedStreamFn = originalStreamFn
-                    ? async (model, context, options) => {
-                        const originalStream = await originalStreamFn(model, context, options);
-                        const wrapperStream = new AssistantMessageEventStream();
-                        let compactionContent = "";
-                        (async () => {
-                            try {
-                                for await (const event of originalStream) {
-                                    wrapperStream.push(event);
-                                    if (event.type === "text_delta") {
-                                        compactionContent += event.delta;
-                                        this._emit({
-                                            type: "compaction_delta",
-                                            delta: event.delta,
-                                            content: compactionContent,
-                                        });
-                                    }
-                                }
-                                wrapperStream.end();
-                            }
-                            catch (err) {
-                                // If the original stream errors, forward the error.
-                                wrapperStream.end();
-                            }
-                        })();
-                        return wrapperStream;
-                    }
-                    : undefined;
-                // Generate compaction result
-                const result = await compact(preparation, this.model, apiKey, headers, customInstructions, this._compactionAbortController.signal, this.thinkingLevel, wrappedStreamFn);
-                summary = result.summary;
-                firstKeptEntryId = result.firstKeptEntryId;
-                tokensBefore = result.tokensBefore;
-                details = result.details;
-            }
+            const compactResult = this._buildDcpCompactionResult(preparation, extensionCompaction);
             if (this._compactionAbortController.signal.aborted) {
                 throw new Error("Compaction cancelled");
             }
-            this.sessionManager.appendCompaction(summary, firstKeptEntryId, tokensBefore, details, fromExtension);
+            const skippedResult = this._markIfNonShrinking(compactResult);
+            if (skippedResult) {
+                this._emit({
+                    type: "compaction_end",
+                    reason: "manual",
+                    result: skippedResult,
+                    aborted: false,
+                    willRetry: false,
+                    errorMessage: skippedResult.message,
+                    skipped: true,
+                    skipReason: skippedResult.skipReason,
+                });
+                return skippedResult;
+            }
+            this._emitCompactionResultSummary(compactResult);
+            const { summary, firstKeptEntryId, tokensBefore, details } = compactResult;
+            this.sessionManager.appendCompaction(summary, firstKeptEntryId, tokensBefore, details, false);
             const newEntries = this.sessionManager.getEntries();
             const sessionContext = this.sessionManager.buildSessionContext();
             this.agent.state.messages = sessionContext.messages;
@@ -1424,15 +1638,10 @@ export class AgentSession {
                 await this._extensionRunner.emit({
                     type: "session_compact",
                     compactionEntry: savedCompactionEntry,
-                    fromExtension,
+                    fromExtension: false,
                 });
             }
-            const compactionResult = {
-                summary,
-                firstKeptEntryId,
-                tokensBefore,
-                details,
-            };
+            const compactionResult = { ...compactResult, details };
             this._emit({
                 type: "compaction_end",
                 reason: "manual",
@@ -1485,8 +1694,8 @@ export class AgentSession {
      * @param skipAbortedCheck If false, include aborted messages (for pre-prompt check). Default: true
      */
     async _checkCompaction(assistantMessage, skipAbortedCheck = true) {
-        const settings = this.settingsManager.getCompactionSettings();
-        if (!settings.enabled)
+        const policy = this._getCompactionPolicy();
+        if (!this._isAutoOlderHistoryCompactionEnabled(policy))
             return false;
         // Skip if message was aborted (user cancelled) - unless skipAbortedCheck is false
         if (skipAbortedCheck && assistantMessage.stopReason === "aborted")
@@ -1550,15 +1759,37 @@ export class AgentSession {
         else {
             contextTokens = calculateContextTokens(assistantMessage.usage);
         }
-        if (shouldCompact(contextTokens, contextWindow, settings)) {
+        if (shouldCompact(contextTokens, contextWindow, this._getAutoOlderHistoryCompactionSettings(policy))) {
             return await this._runAutoCompaction("threshold", false);
         }
         return false;
     }
+    _getAutoOlderHistoryCompactionSettings(policy) {
+        return {
+            ...policy.conversation,
+            enabled: this._isAutoOlderHistoryCompactionEnabled(policy),
+            keepRecentTokens: policy.autoOlderHistory.keepRecentTokens,
+            contextLimitRatio: policy.autoOlderHistory.contextLimitRatio,
+        };
+    }
+    _isAutoOlderHistoryCompactionEnabled(policy) {
+        return policy.conversation.enabled && policy.autoOlderHistory.enabled;
+    }
+    _autoOlderHistorySkipSignature(pathEntries, compactableTokens) {
+        const lastEntryId = pathEntries[pathEntries.length - 1]?.id ?? "none";
+        return `${lastEntryId}:${compactableTokens}`;
+    }
     /**
      * Internal: Run auto-compaction with events.
      */
     async _runAutoCompaction(reason, willRetry) {
+        const policy = this._getCompactionPolicy();
+        if (!this._isAutoOlderHistoryCompactionEnabled(policy)) {
+            return false;
+        }
+        if (reason === "threshold" && this._autoOlderHistoryCooldownTurnsRemaining > 0) {
+            return false;
+        }
         if (this._compactionInProgress) {
             this._emit({
                 type: "compaction_end",
@@ -1570,11 +1801,13 @@ export class AgentSession {
             return false;
         }
         this._compactionInProgress = true;
-        const settings = this.settingsManager.getCompactionSettings();
+        const settings = this._getAutoOlderHistoryCompactionSettings(policy);
         this._emit({ type: "compaction_start", reason });
         this._autoCompactionAbortController = new AbortController();
         try {
-            if (!this.model) {
+            const pathEntries = this.sessionManager.getBranch();
+            const preparation = prepareCompaction(pathEntries, settings, { phaseBoundary: false });
+            if (!preparation) {
                 this._emit({
                     type: "compaction_end",
                     reason,
@@ -1584,40 +1817,34 @@ export class AgentSession {
                 });
                 return false;
             }
-            let apiKey;
-            let headers;
-            if (this.agent.streamFn === streamSimple) {
-                const authResult = await this._modelRegistry.getApiKeyAndHeaders(this.model);
-                if (!authResult.ok || !authResult.apiKey) {
-                    this._emit({
-                        type: "compaction_end",
-                        reason,
-                        result: undefined,
-                        aborted: false,
-                        willRetry: false,
-                    });
-                    return false;
-                }
-                apiKey = authResult.apiKey;
-                headers = authResult.headers;
-            }
-            else {
-                ({ apiKey, headers } = await this._getCompactionRequestAuth(this.model));
+            const compactableTokens = estimateCompactionTokenMetrics(preparation, "").tokensCompacted ?? 0;
+            if (compactableTokens < policy.autoOlderHistory.minRawTokens) {
+                this._lastAutoOlderHistorySkipSignature = this._autoOlderHistorySkipSignature(pathEntries, compactableTokens);
+                this._autoOlderHistoryCooldownTurnsRemaining = policy.autoOlderHistory.cooldownTurns;
+                this._emit({
+                    type: "compaction_end",
+                    reason,
+                    result: undefined,
+                    aborted: false,
+                    willRetry: false,
+                    errorMessage: `Auto-compaction skipped: insufficient compactable raw material (` +
+                        `~${compactableTokens.toLocaleString()} / ${policy.autoOlderHistory.minRawTokens.toLocaleString()} tokens).`,
+                });
+                return false;
             }
-            const pathEntries = this.sessionManager.getBranch();
-            const preparation = prepareCompaction(pathEntries, settings);
-            if (!preparation) {
+            const skipSignature = this._autoOlderHistorySkipSignature(pathEntries, compactableTokens);
+            if (reason === "threshold" && this._lastAutoOlderHistorySkipSignature === skipSignature) {
+                this._autoOlderHistoryCooldownTurnsRemaining = policy.autoOlderHistory.cooldownTurns;
                 this._emit({
                     type: "compaction_end",
                     reason,
                     result: undefined,
                     aborted: false,
                     willRetry: false,
+                    errorMessage: "Auto-compaction skipped: repeated non-shrinking older-history attempt without new raw material.",
                 });
                 return false;
             }
-            let extensionCompaction;
-            let fromExtension = false;
             let extensionProgressContent = "";
             const emitExtensionProgress = (delta, content) => {
                 if (!delta && !content)
@@ -1629,58 +1856,9 @@ export class AgentSession {
                     content: extensionProgressContent,
                 });
             };
-            if (this._extensionRunner.hasHandlers("session_before_compact")) {
-                const extensionResult = (await this._extensionRunner.emit({
-                    type: "session_before_compact",
-                    preparation,
-                    branchEntries: pathEntries,
-                    customInstructions: undefined,
-                    signal: this._autoCompactionAbortController.signal,
-                    emitProgress: emitExtensionProgress,
-                }));
-                if (extensionResult?.cancel) {
-                    this._emit({
-                        type: "compaction_end",
-                        reason,
-                        result: undefined,
-                        aborted: true,
-                        willRetry: false,
-                    });
-                    return false;
-                }
-                if (extensionResult?.compaction) {
-                    extensionCompaction = extensionResult.compaction;
-                    fromExtension = true;
-                }
-            }
-            let summary;
-            let firstKeptEntryId;
-            let tokensBefore;
-            let details;
-            if (extensionCompaction) {
-                // Extension provided compaction content
-                summary = extensionCompaction.summary;
-                firstKeptEntryId = extensionCompaction.firstKeptEntryId;
-                tokensBefore = extensionCompaction.tokensBefore;
-                details = extensionCompaction.details;
-                // Emit the full summary as a compaction_delta so the frontend
-                // displays it in the live preview panel during compaction.
-                if (summary) {
-                    this._emit({
-                        type: "compaction_delta",
-                        delta: summary,
-                        content: summary,
-                    });
-                }
-            }
-            else {
-                // Generate compaction result
-                const compactResult = await compact(preparation, this.model, apiKey, headers, undefined, this._autoCompactionAbortController.signal, this.thinkingLevel, this.agent.streamFn);
-                summary = compactResult.summary;
-                firstKeptEntryId = compactResult.firstKeptEntryId;
-                tokensBefore = compactResult.tokensBefore;
-                details = compactResult.details;
-            }
+            const beforeCompactResult = await this._emitSessionBeforeCompact(preparation, pathEntries, undefined, this._autoCompactionAbortController.signal, emitExtensionProgress);
+            const extensionCompaction = beforeCompactResult?.cancel ? undefined : beforeCompactResult?.compaction;
+            const compactResult = this._buildDcpCompactionResult(preparation, extensionCompaction);
             if (this._autoCompactionAbortController.signal.aborted) {
                 this._emit({
                     type: "compaction_end",
@@ -1691,7 +1869,27 @@ export class AgentSession {
                 });
                 return false;
             }
-            this.sessionManager.appendCompaction(summary, firstKeptEntryId, tokensBefore, details, fromExtension);
+            const skippedResult = this._markIfNonShrinking(compactResult);
+            if (skippedResult) {
+                this._lastAutoOlderHistorySkipSignature = skipSignature;
+                this._autoOlderHistoryCooldownTurnsRemaining = policy.autoOlderHistory.cooldownTurns;
+                this._emit({
+                    type: "compaction_end",
+                    reason,
+                    result: skippedResult,
+                    aborted: false,
+                    willRetry: false,
+                    errorMessage: skippedResult.message,
+                    skipped: true,
+                    skipReason: skippedResult.skipReason,
+                });
+                return false;
+            }
+            this._lastAutoOlderHistorySkipSignature = undefined;
+            this._autoOlderHistoryCooldownTurnsRemaining = policy.autoOlderHistory.cooldownTurns;
+            this._emitCompactionResultSummary(compactResult);
+            const { summary, firstKeptEntryId, tokensBefore, details } = compactResult;
+            this.sessionManager.appendCompaction(summary, firstKeptEntryId, tokensBefore, details, false);
             const newEntries = this.sessionManager.getEntries();
             const sessionContext = this.sessionManager.buildSessionContext();
             this.agent.state.messages = sessionContext.messages;
@@ -1701,15 +1899,10 @@ export class AgentSession {
                 await this._extensionRunner.emit({
                     type: "session_compact",
                     compactionEntry: savedCompactionEntry,
-                    fromExtension,
+                    fromExtension: false,
                 });
             }
-            const result = {
-                summary,
-                firstKeptEntryId,
-                tokensBefore,
-                details,
-            };
+            const result = { ...compactResult, details };
             this._emit({ type: "compaction_end", reason, result, aborted: false, willRetry });
             if (willRetry) {
                 const messages = this.agent.state.messages;
@@ -1917,7 +2110,12 @@ export class AgentSession {
             compact: (options) => {
                 void (async () => {
                     try {
-                        const result = await this.compact(options?.customInstructions);
+                        const result = await this.compact({
+                            customInstructions: options?.customInstructions,
+                            phaseBoundary: options?.phaseBoundary,
+                            keepRecentTokens: options?.keepRecentTokens,
+                            memoryHookMode: options?.memoryHookMode,
+                        });
                         options?.onComplete?.(result);
                     }
                     catch (error) {