@aexol/spectral 0.9.58 → 0.9.60

package/dist/sdk/coding-agent/core/compaction/compaction.d.ts

@@ -8,25 +8,53 @@ import type { AgentMessage, StreamFn, ThinkingLevel } from "../../../agent-core/
 import type { Model, Usage } from "../../../ai/index.js";
 import { type SessionEntry } from "../session-manager.js";
 import { type FileOperations } from "./utils.js";
+import { type ConversationCompactionPolicy, type ManualCompactionPolicy } from "./policy.js";
 /** Details stored in CompactionEntry.details for file tracking */
 export interface CompactionDetails {
     readFiles: string[];
     modifiedFiles: string[];
 }
+export type CompactionSkipReason = "non_shrinking";
+export interface CompactionTokenSourceBucket {
+    type: "role" | "tool" | "source";
+    name: string;
+    tokens: number;
+}
 /** Result from compact() - SessionManager adds uuid/parentUuid when saving */
 export interface CompactionResult<T = unknown> {
     summary: string;
     firstKeptEntryId: string;
     tokensBefore: number;
+    /** Estimated tokens in the raw span replaced by the compaction summary. */
+    tokensCompacted?: number;
+    /** Estimated net tokens removed by replacing raw span tokens with summary tokens. */
+    tokensRemoved?: number;
+    /** Estimated tokens added back as the compaction summary. */
+    summaryTokens?: number;
+    /** Estimated percentage of compacted raw tokens removed by the summary. */
+    reductionPercent?: number;
+    /** 1-based compaction ordinal within the current session branch. */
+    compactionNumber?: number;
+    /** Largest estimated token buckets from the span being compacted. */
+    largestTokenSources?: CompactionTokenSourceBucket[];
+    /** True when the compaction was intentionally skipped and no history was pruned. */
+    skipped?: boolean;
+    /** Machine-readable reason for a skipped compaction. */
+    skipReason?: CompactionSkipReason;
+    /** Human-readable skipped/failure message for UI and persisted history. */
+    message?: string;
     /** Extension-specific data (e.g., ArtifactIndex, version markers for structured compaction) */
     details?: T;
 }
-export interface CompactionSettings {
-    enabled: boolean;
-    reserveTokens: number;
-    keepRecentTokens: number;
-}
+export type CompactionSettings = ConversationCompactionPolicy;
 export declare const DEFAULT_COMPACTION_SETTINGS: CompactionSettings;
+export declare const MANUAL_COMPACTION_KEEP_RECENT_TOKENS: number;
+/**
+ * Manual/model-visible compaction is an explicit phase-boundary action. Keep a
+ * smaller recent suffix than automatic threshold compaction so a ~20k-token
+ * default session does not keep the whole eligible branch and compact nothing.
+ */
+export declare function getManualCompactionSettings(settings: CompactionSettings, manualPolicy?: ManualCompactionPolicy): CompactionSettings;
 /**
  * Calculate total context tokens from usage.
  * Uses the native totalTokens field when available, falls back to computing from components.
@@ -70,6 +98,13 @@ export interface CutPointResult {
     /** Whether this cut splits a turn (cut point is not a user message) */
     isSplitTurn: boolean;
 }
+export interface FindCutPointOptions {
+    /**
+     * Explicit phase-boundary compaction should prefer the newest safe boundary
+     * over retaining a large just-finished turn as the recent raw suffix.
+     */
+    phaseBoundary?: boolean;
+}
 /**
  * Find the cut point in session entries that keeps approximately `keepRecentTokens`.
  *
@@ -86,10 +121,14 @@ export interface CutPointResult {
  *
  * Only considers entries between `startIndex` and `endIndex` (exclusive).
  */
-export declare function findCutPoint(entries: SessionEntry[], startIndex: number, endIndex: number, keepRecentTokens: number): CutPointResult;
+export declare function findCutPoint(entries: SessionEntry[], startIndex: number, endIndex: number, keepRecentTokens: number, options?: FindCutPointOptions): CutPointResult;
 /**
  * Generate a summary of the conversation using the LLM.
  * If previousSummary is provided, uses the update prompt to merge.
+ *
+ * @deprecated The active coding-agent session path uses deterministic DCP-lite
+ * (`compactDcpLite`) plus `session_before_compact` hook details. This legacy
+ * LLM summarizer remains exported for compatibility with older callers only.
  */
 export declare function generateSummary(currentMessages: AgentMessage[], model: Model<any>, reserveTokens: number, apiKey: string | undefined, headers?: Record<string, string>, signal?: AbortSignal, customInstructions?: string, previousSummary?: string, thinkingLevel?: ThinkingLevel, streamFn?: StreamFn): Promise<string>;
 export interface CompactionPreparation {
@@ -108,8 +147,16 @@ export interface CompactionPreparation {
     fileOps: FileOperations;
     /** Compaction settions from settings.jsonl	*/
     settings: CompactionSettings;
+    /** 1-based compaction ordinal within the current session branch. */
+    compactionNumber: number;
+}
+export interface PrepareCompactionOptions {
+    /** Prefer a caller-provided phase boundary over the usual recent-token suffix. */
+    phaseBoundary?: boolean;
 }
-export declare function prepareCompaction(pathEntries: SessionEntry[], settings: CompactionSettings): CompactionPreparation | undefined;
+export declare function prepareCompaction(pathEntries: SessionEntry[], settings: CompactionSettings, options?: PrepareCompactionOptions): CompactionPreparation | undefined;
+export declare function estimateTextTokens(text: string): number;
+export declare function estimateCompactionTokenMetrics(preparation: Pick<CompactionPreparation, "messagesToSummarize" | "turnPrefixMessages"> & Partial<Pick<CompactionPreparation, "compactionNumber">>, summary: string): Pick<CompactionResult, "tokensCompacted" | "tokensRemoved" | "summaryTokens" | "reductionPercent" | "compactionNumber" | "largestTokenSources">;
 /**
  * Deduplicate repeated tool calls in a message array by keeping only the
  * most recent occurrence of each (tool, args) pair.
@@ -137,6 +184,9 @@ export declare function deduplicateToolCalls(messages: AgentMessage[]): AgentMes
  *
  * @param preparation - Pre-calculated preparation from prepareCompaction()
  * @param customInstructions - Optional custom focus for the summary
+ * @deprecated The active AgentSession compaction flow uses deterministic
+ * DCP-lite (`compactDcpLite`) through `_buildDcpCompactionResult`. Keep this
+ * exported legacy LLM fallback for SDK/harness compatibility only.
  */
 export declare function compact(preparation: CompactionPreparation, model: Model<any>, apiKey: string | undefined, headers?: Record<string, string>, customInstructions?: string, signal?: AbortSignal, thinkingLevel?: ThinkingLevel, streamFn?: StreamFn): Promise<CompactionResult>;
 //# sourceMappingURL=compaction.d.ts.map

package/dist/sdk/coding-agent/core/compaction/compaction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compaction.d.ts","sourceRoot":"","sources":["../../../../../src/sdk/coding-agent/core/compaction/compaction.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"compaction.d.ts","sourceRoot":"","sources":["../../../../../src/sdk/coding-agent/core/compaction/compaction.ts"],"names":[],"mappings":"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"}

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

@@ -8,6 +8,7 @@ import { completeSimple } from "../../../ai/index.js";
 import { convertToLlm, createBranchSummaryMessage, createCompactionSummaryMessage, createCustomMessage, } from "../messages.js";
 import { buildSessionContext } from "../session-manager.js";
 import { computeFileLists, createFileOps, extractFileOpsFromMessage, formatFileOperations, SUMMARIZATION_SYSTEM_PROMPT, serializeConversation, } from "./utils.js";
+import { DEFAULT_COMPACTION_POLICY, normalizeManualKeepRecentTokens, } from "./policy.js";
 /**
  * Extract file operations from messages and previous compaction entries.
  */
@@ -64,10 +65,20 @@ function getMessageFromEntryForCompaction(entry) {
     return getMessageFromEntry(entry);
 }
 export const DEFAULT_COMPACTION_SETTINGS = {
-    enabled: true,
-    reserveTokens: 16384,
-    keepRecentTokens: 20000,
+    ...DEFAULT_COMPACTION_POLICY.conversation,
 };
+export const MANUAL_COMPACTION_KEEP_RECENT_TOKENS = DEFAULT_COMPACTION_POLICY.manual.keepRecentTokens;
+/**
+ * Manual/model-visible compaction is an explicit phase-boundary action. Keep a
+ * smaller recent suffix than automatic threshold compaction so a ~20k-token
+ * default session does not keep the whole eligible branch and compact nothing.
+ */
+export function getManualCompactionSettings(settings, manualPolicy = DEFAULT_COMPACTION_POLICY.manual) {
+    const manualKeepRecentTokens = normalizeManualKeepRecentTokens(manualPolicy.keepRecentTokens, manualPolicy);
+    if (settings.keepRecentTokens <= manualKeepRecentTokens)
+        return settings;
+    return { ...settings, keepRecentTokens: manualKeepRecentTokens };
+}
 // ============================================================================
 // Token calculation
 // ============================================================================
@@ -149,7 +160,11 @@ export function estimateContextTokens(messages) {
 export function shouldCompact(contextTokens, contextWindow, settings) {
     if (!settings.enabled)
         return false;
-    return contextTokens > contextWindow - settings.reserveTokens;
+    if (!Number.isFinite(contextWindow) || contextWindow <= 0)
+        return false;
+    if (!Number.isFinite(contextTokens) || contextTokens < 0)
+        return false;
+    return contextTokens >= contextWindow * settings.contextLimitRatio;
 }
 // ============================================================================
 // Cut point detection
@@ -285,6 +300,20 @@ export function findTurnStartIndex(entries, entryIndex, startIndex) {
     }
     return -1;
 }
+function isTurnBoundaryEntry(entry) {
+    if (!entry)
+        return false;
+    if (entry.type === "branch_summary" || entry.type === "custom_message")
+        return true;
+    if (entry.type !== "message")
+        return false;
+    const role = entry.message.role;
+    return role === "user" ||
+        role === "bashExecution" ||
+        role === "custom" ||
+        role === "branchSummary" ||
+        role === "compactionSummary";
+}
 /**
  * Find the cut point in session entries that keeps approximately `keepRecentTokens`.
  *
@@ -301,31 +330,38 @@ export function findTurnStartIndex(entries, entryIndex, startIndex) {
  *
  * Only considers entries between `startIndex` and `endIndex` (exclusive).
  */
-export function findCutPoint(entries, startIndex, endIndex, keepRecentTokens) {
+export function findCutPoint(entries, startIndex, endIndex, keepRecentTokens, options = {}) {
     const cutPoints = findValidCutPoints(entries, startIndex, endIndex);
     if (cutPoints.length === 0) {
         return { firstKeptEntryIndex: startIndex, turnStartIndex: -1, isSplitTurn: false };
     }
-    // Walk backwards from newest, accumulating estimated message sizes
+    // Walk backwards from newest, accumulating estimated message sizes.
+    // Phase-boundary callers provide an explicit marker, so the newest valid
+    // boundary is the desired cut point and the usual recent-token suffix is not
+    // retained raw.
     let accumulatedTokens = 0;
-    let cutIndex = cutPoints[0]; // Default: keep from first message (not header)
-    for (let i = endIndex - 1; i >= startIndex; i--) {
-        const entry = entries[i];
-        if (entry.type !== "message")
-            continue;
-        // Estimate this message's size
-        const messageTokens = estimateTokens(entry.message);
-        accumulatedTokens += messageTokens;
-        // Check if we've exceeded the budget
-        if (accumulatedTokens >= keepRecentTokens) {
-            // Find the closest valid cut point at or after this entry
-            for (let c = 0; c < cutPoints.length; c++) {
-                if (cutPoints[c] >= i) {
-                    cutIndex = cutPoints[c];
-                    break;
+    let cutIndex = options.phaseBoundary
+        ? cutPoints[cutPoints.length - 1]
+        : cutPoints[0]; // Default: keep from first message (not header)
+    if (!options.phaseBoundary) {
+        for (let i = endIndex - 1; i >= startIndex; i--) {
+            const entry = entries[i];
+            if (entry.type !== "message")
+                continue;
+            // Estimate this message's size
+            const messageTokens = estimateTokens(entry.message);
+            accumulatedTokens += messageTokens;
+            // Check if we've exceeded the budget
+            if (accumulatedTokens >= keepRecentTokens) {
+                // Find the closest valid cut point at or after this entry
+                for (let c = 0; c < cutPoints.length; c++) {
+                    if (cutPoints[c] >= i) {
+                        cutIndex = cutPoints[c];
+                        break;
+                    }
                 }
+                break;
             }
-            break;
         }
     }
     // Scan backwards from cutIndex to include any non-message entries (bash, settings, etc.)
@@ -344,17 +380,22 @@ export function findCutPoint(entries, startIndex, endIndex, keepRecentTokens) {
     }
     // Determine if this is a split turn
     const cutEntry = entries[cutIndex];
-    const isUserMessage = cutEntry.type === "message" && cutEntry.message.role === "user";
-    const turnStartIndex = isUserMessage ? -1 : findTurnStartIndex(entries, cutIndex, startIndex);
+    const isTurnBoundary = isTurnBoundaryEntry(cutEntry);
+    const turnStartIndex = isTurnBoundary ? -1 : findTurnStartIndex(entries, cutIndex, startIndex);
     return {
         firstKeptEntryIndex: cutIndex,
         turnStartIndex,
-        isSplitTurn: !isUserMessage && turnStartIndex !== -1,
+        isSplitTurn: !isTurnBoundary && turnStartIndex !== -1,
     };
 }
 // ============================================================================
 // Summarization
 // ============================================================================
+// Legacy LLM summarization path. AgentSession now builds persisted compaction
+// entries with deterministic DCP-lite (`compactDcpLite`) and lets
+// `session_before_compact` hooks provide memory details. Keep these exports for
+// compatibility with external SDK callers and older harness code, but do not
+// route new session compaction work through this model-generated fallback.
 const SUMMARIZATION_PROMPT = `The messages above are a conversation to summarize. Create a structured context checkpoint summary that another LLM will use to continue the work.
 
 Use this EXACT format:
@@ -442,6 +483,10 @@ async function completeSummarization(model, context, options, streamFn) {
 /**
  * Generate a summary of the conversation using the LLM.
  * If previousSummary is provided, uses the update prompt to merge.
+ *
+ * @deprecated The active coding-agent session path uses deterministic DCP-lite
+ * (`compactDcpLite`) plus `session_before_compact` hook details. This legacy
+ * LLM summarizer remains exported for compatibility with older callers only.
  */
 export async function generateSummary(currentMessages, model, reserveTokens, apiKey, headers, signal, customInstructions, previousSummary, thinkingLevel, streamFn) {
     const maxTokens = Math.min(Math.floor(0.8 * reserveTokens), model.maxTokens > 0 ? model.maxTokens : Number.POSITIVE_INFINITY);
@@ -478,7 +523,7 @@ export async function generateSummary(currentMessages, model, reserveTokens, api
         .join("\n");
     return textContent;
 }
-export function prepareCompaction(pathEntries, settings) {
+export function prepareCompaction(pathEntries, settings, options = {}) {
     if (pathEntries.length > 0 && pathEntries[pathEntries.length - 1].type === "compaction") {
         return undefined;
     }
@@ -499,7 +544,9 @@ export function prepareCompaction(pathEntries, settings) {
     }
     const boundaryEnd = pathEntries.length;
     const tokensBefore = estimateContextTokens(buildSessionContext(pathEntries).messages).tokens;
-    const cutPoint = findCutPoint(pathEntries, boundaryStart, boundaryEnd, settings.keepRecentTokens);
+    const cutPoint = findCutPoint(pathEntries, boundaryStart, boundaryEnd, settings.keepRecentTokens, {
+        phaseBoundary: options.phaseBoundary,
+    });
     // Get UUID of first kept entry
     const firstKeptEntry = pathEntries[cutPoint.firstKeptEntryIndex];
     if (!firstKeptEntry?.id) {
@@ -531,6 +578,7 @@ export function prepareCompaction(pathEntries, settings) {
             extractFileOpsFromMessage(msg, fileOps);
         }
     }
+    const compactionNumber = pathEntries.filter((entry) => entry.type === "compaction").length + 1;
     return {
         firstKeptEntryId,
         messagesToSummarize,
@@ -540,7 +588,73 @@ export function prepareCompaction(pathEntries, settings) {
         previousSummary,
         fileOps,
         settings,
+        compactionNumber,
+    };
+}
+export function estimateTextTokens(text) {
+    if (!text.trim())
+        return 0;
+    return Math.ceil(text.length / 4);
+}
+function estimateMessagesTokens(messages) {
+    let tokens = 0;
+    for (const message of messages) {
+        tokens += estimateTokens(message);
+    }
+    return tokens;
+}
+export function estimateCompactionTokenMetrics(preparation, summary) {
+    const tokensCompacted = estimateMessagesTokens(preparation.messagesToSummarize) +
+        estimateMessagesTokens(preparation.turnPrefixMessages);
+    const summaryTokens = estimateTextTokens(summary);
+    const tokensRemoved = Math.max(0, tokensCompacted - summaryTokens);
+    const reductionPercent = tokensCompacted > 0
+        ? Math.round((tokensRemoved / tokensCompacted) * 10_000) / 100
+        : 0;
+    return {
+        tokensCompacted,
+        tokensRemoved,
+        summaryTokens,
+        reductionPercent,
+        compactionNumber: preparation.compactionNumber,
+        largestTokenSources: collectLargestTokenSources(preparation.messagesToSummarize, preparation.turnPrefixMessages),
+    };
+}
+function addBucket(buckets, bucket) {
+    const key = `${bucket.type}:${bucket.name}`;
+    const previous = buckets.get(key);
+    buckets.set(key, {
+        ...bucket,
+        tokens: (previous?.tokens ?? 0) + bucket.tokens,
+    });
+}
+function collectLargestTokenSources(messagesToSummarize, turnPrefixMessages) {
+    const buckets = new Map();
+    const collect = (messages, source) => {
+        for (const message of messages) {
+            const messageTokens = estimateTokens(message);
+            addBucket(buckets, { type: "source", name: source, tokens: messageTokens });
+            addBucket(buckets, { type: "role", name: message.role, tokens: messageTokens });
+            if (message.role === "toolResult") {
+                addBucket(buckets, { type: "tool", name: message.toolName, tokens: messageTokens });
+                continue;
+            }
+            if (message.role === "assistant") {
+                for (const block of message.content) {
+                    if (block.type !== "toolCall")
+                        continue;
+                    const toolTokens = estimateTextTokens(`${block.name} ${JSON.stringify(block.arguments)}`);
+                    addBucket(buckets, { type: "tool", name: block.name, tokens: toolTokens });
+                }
+            }
+        }
     };
+    collect(messagesToSummarize, "history");
+    collect(turnPrefixMessages, "turn_prefix");
+    return [...buckets.values()]
+        .filter((bucket) => bucket.tokens > 0)
+        .sort((a, b) => b.tokens - a.tokens || a.type.localeCompare(b.type) || a.name.localeCompare(b.name))
+        .slice(0, 5);
 }
 // ============================================================================
 // Tool Call Deduplication
@@ -716,6 +830,9 @@ Be concise. Focus on what's needed to understand the kept suffix.`;
  *
  * @param preparation - Pre-calculated preparation from prepareCompaction()
  * @param customInstructions - Optional custom focus for the summary
+ * @deprecated The active AgentSession compaction flow uses deterministic
+ * DCP-lite (`compactDcpLite`) through `_buildDcpCompactionResult`. Keep this
+ * exported legacy LLM fallback for SDK/harness compatibility only.
  */
 export async function compact(preparation, model, apiKey, headers, customInstructions, signal, thinkingLevel, streamFn) {
     const { firstKeptEntryId, messagesToSummarize, turnPrefixMessages, isSplitTurn, tokensBefore, previousSummary, fileOps, settings, } = preparation;
@@ -744,6 +861,7 @@ export async function compact(preparation, model, apiKey, headers, customInstruc
     // Compute file lists and append to summary
     const { readFiles, modifiedFiles } = computeFileLists(fileOps);
     summary += formatFileOperations(readFiles, modifiedFiles);
+    const tokenMetrics = estimateCompactionTokenMetrics(preparation, summary);
     if (!firstKeptEntryId) {
         throw new Error("First kept entry has no UUID - session may need migration");
     }
@@ -751,6 +869,7 @@ export async function compact(preparation, model, apiKey, headers, customInstruc
         summary,
         firstKeptEntryId,
         tokensBefore,
+        ...tokenMetrics,
         details: { readFiles, modifiedFiles },
     };
 }

package/dist/sdk/coding-agent/core/compaction/dcp-lite.d.ts

@@ -0,0 +1,24 @@
+import { type CompactionDetails, type CompactionPreparation, type CompactionResult, type CompactionTokenSourceBucket } from "./compaction.js";
+export type CompactionMode = "dcp-lite";
+export interface DcpLiteCompactionDetails extends CompactionDetails {
+    method: "dcp-lite";
+    version: 1;
+    compactionNumber: number;
+    tokensCompacted?: number;
+    tokensRemoved?: number;
+    summaryTokens?: number;
+    reductionPercent?: number;
+    largestTokenSources?: CompactionTokenSourceBucket[];
+    summarizedMessages: number;
+    turnPrefixMessages: number;
+    isSplitTurn: boolean;
+}
+/**
+ * Deterministic, local-only compaction for manual DCP-lite mode.
+ *
+ * This intentionally performs no model, provider, extension, or network calls.
+ * It preserves bounded excerpts and counters from CompactionPreparation so the
+ * resulting summary is stable and usually much smaller than the discarded span.
+ */
+export declare function compactDcpLite(preparation: CompactionPreparation): CompactionResult<DcpLiteCompactionDetails>;
+//# sourceMappingURL=dcp-lite.d.ts.map

package/dist/sdk/coding-agent/core/compaction/dcp-lite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dcp-lite.d.ts","sourceRoot":"","sources":["../../../../../src/sdk/coding-agent/core/compaction/dcp-lite.ts"],"names":[],"mappings":"AACA,OAAO,EACN,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EACrB,KAAK,2BAA2B,EAGhC,MAAM,iBAAiB,CAAC;AAKzB,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC;AAExC,MAAM,WAAW,wBAAyB,SAAQ,iBAAiB;IAClE,MAAM,EAAE,UAAU,CAAC;IACnB,OAAO,EAAE,CAAC,CAAC;IACX,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mBAAmB,CAAC,EAAE,2BAA2B,EAAE,CAAC;IACpD,kBAAkB,EAAE,MAAM,CAAC;IAC3B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,WAAW,EAAE,OAAO,CAAC;CACrB;AA8CD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,qBAAqB,GAAG,gBAAgB,CAAC,wBAAwB,CAAC,CA2D7G"}