@illuma-ai/agents 1.1.2 → 1.1.4

package/dist/esm/main.mjs

@@ -26,7 +26,7 @@ export { createSearchTool } from './tools/search/tool.mjs';
 export { DATE_RANGE, DEFAULT_COUNTRY_DESCRIPTION, DEFAULT_QUERY_DESCRIPTION, WebSearchToolDefinition, WebSearchToolDescription, WebSearchToolName, WebSearchToolSchema, countrySchema, dateSchema, imagesSchema, newsSchema, querySchema, videosSchema } from './tools/search/schema.mjs';
 export { createValidationErrorMessage, isValidJsonSchema, normalizeJsonSchema, prepareSchemaForProvider, validateStructuredOutput, zodToJsonSchema } from './schemas/validate.mjs';
 export { Callback, CommonEvents, Constants, ContentTypes, EdgeType, EnvVar, FinishReasons, GraphEvents, GraphNodeActions, GraphNodeKeys, MessageTypes, Providers, StepTypes, TitleMethod, ToolCallTypes } from './common/enum.mjs';
-export { CONTEXT_SAFETY_BUFFER, DEDUP_MAX_CONTENT_LENGTH, MIN_THINKING_BUDGET, MULTI_DOCUMENT_THRESHOLD, PROACTIVE_SUMMARY_THRESHOLD, PRUNING_EMA_ALPHA, PRUNING_INITIAL_CALIBRATION, SUMMARIZATION_CONTEXT_THRESHOLD, SUMMARIZATION_RESERVE_RATIO, TOOL_DISCOVERY_CACHE_MAX_SIZE, TOOL_TURN_THINKING_BUDGET } from './common/constants.mjs';
+export { COMPACTION_RECENT_ROUNDS, CONTEXT_SAFETY_BUFFER, DEDUP_MAX_CONTENT_LENGTH, MIN_THINKING_BUDGET, MULTI_DOCUMENT_THRESHOLD, PROACTIVE_SUMMARY_THRESHOLD, PRUNING_EMA_ALPHA, PRUNING_INITIAL_CALIBRATION, SUMMARIZATION_CONTEXT_THRESHOLD, SUMMARIZATION_RESERVE_RATIO, TOOL_DISCOVERY_CACHE_MAX_SIZE, TOOL_TURN_THINKING_BUDGET } from './common/constants.mjs';
 export { joinKeys, resetIfNotEmpty } from './utils/graph.mjs';
 export { isGoogleLike, isOpenAILike } from './utils/llm.mjs';
 export { isPresent, unescapeObject } from './utils/misc.mjs';

package/dist/types/common/constants.d.ts

@@ -46,6 +46,15 @@ export declare const SUMMARIZATION_CONTEXT_THRESHOLD = 80;
  *  100% → graceful: use existing summary + recent messages, never block
  */
 export declare const PROACTIVE_SUMMARY_THRESHOLD = 0.8;
+/**
+ * Number of recent conversation rounds (human+AI pairs) to keep in the
+ * windowed view when a summary is available. Everything older is covered
+ * by the summary. 2 rounds = last 2 user questions + 2 AI responses.
+ *
+ * This prevents wasting tokens on raw messages the summary already covers
+ * and keeps context tight for the LLM.
+ */
+export declare const COMPACTION_RECENT_ROUNDS = 2;
 /**
  * Default reserve ratio (0-1) — fraction of context window to preserve as recent messages.
  * 0.3 means 30% of the context budget is reserved for the most recent messages,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@illuma-ai/agents",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",

package/src/common/constants.ts

@@ -71,6 +71,16 @@ export const SUMMARIZATION_CONTEXT_THRESHOLD = 80;
  */
 export const PROACTIVE_SUMMARY_THRESHOLD = 0.8;
 
+/**
+ * Number of recent conversation rounds (human+AI pairs) to keep in the
+ * windowed view when a summary is available. Everything older is covered
+ * by the summary. 2 rounds = last 2 user questions + 2 AI responses.
+ *
+ * This prevents wasting tokens on raw messages the summary already covers
+ * and keeps context tight for the LLM.
+ */
+export const COMPACTION_RECENT_ROUNDS = 2;
+
 /**
  * Default reserve ratio (0-1) — fraction of context window to preserve as recent messages.
  * 0.3 means 30% of the context budget is reserved for the most recent messages,

package/src/graphs/Graph.ts

@@ -56,6 +56,7 @@ import {
   TOOL_TURN_THINKING_BUDGET,
   SUMMARIZATION_CONTEXT_THRESHOLD,
   PROACTIVE_SUMMARY_THRESHOLD,
+  COMPACTION_RECENT_ROUNDS,
 } from '@/common';
 import {
   ToolDiscoveryCache,
@@ -1606,86 +1607,196 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       }
 
       if (agentContext.pruneMessages) {
-        const { context, indexTokenCountMap, messagesToRefine } =
-          agentContext.pruneMessages({
-            messages,
-            usageMetadata: agentContext.currentUsage,
-          });
-        agentContext.indexTokenCountMap = indexTokenCountMap;
-        messagesToUse = context;
-
-        // ── Non-blocking summarization ──────────────────────────────────
-        // NEVER block the LLM call waiting for summarization. Instead:
-        //   1. If _cachedRunSummary exists → use it, fire async update
-        //   2. If persistedSummary exists → use it as fallback, fire async update
-        //   3. If NOTHING exists (first-ever prune) → skip summary, fire async generation
-        // The summary catches up asynchronously and is available for subsequent
-        // iterations (tool calls) and the next conversation turn.
+        // ── Context Compaction (Copilot-style: never delete messages) ─────
         //
-        // SummarizationConfig integration:
-        //   - triggerType/triggerThreshold control WHEN summarization fires
-        //   - reserveRatio is enforced via calibrated maxTokens (above)
-        //   - initialSummary provides cross-run seeding as fallback before persistedSummary
-        let hasSummary = false;
-        const sumConfig = agentContext.summarizationConfig;
-        const shouldSummarize = this.shouldTriggerSummarization(
-          messagesToRefine.length,
-          agentContext.maxContextTokens ?? 0,
-          agentContext.indexTokenCountMap,
-          agentContext.instructionTokens,
-          sumConfig
-        );
+        // DESIGN: Original messages are NEVER removed from the array.
+        // Instead, we build a "windowed view" for the LLM:
+        //   [system prompt] + [summary of older turns] + [recent turns that fit]
+        //
+        // This ensures:
+        //   - No context is ever lost (summary covers older turns)
+        //   - We can always re-summarize from originals if summary is stale
+        //   - Conversation chaining works naturally across turns
+        //
+        // Flow:
+        //   1. Resolve best available summary (cached > persisted > seed)
+        //   2. Calculate token budget available for recent messages
+        //   3. Walk newest→oldest, build view of messages that fit
+        //   4. Assemble: [system] + [summary] + [recent window]
+        //   5. Fire background summary update for messages outside the window
 
-        if (
-          messagesToRefine.length > 0 &&
-          agentContext.summarizeCallback &&
-          shouldSummarize
+        const sumConfig = agentContext.summarizationConfig;
+        const tokenCounter = agentContext.tokenCounter;
+        const maxTokens = agentContext.maxContextTokens ?? 0;
+
+        // Step 1: Resolve best available summary
+        let summary: string | undefined;
+        let summarySource: string;
+
+        if (this._cachedRunSummary != null) {
+          summary = this._cachedRunSummary;
+          summarySource = 'cached';
+        } else if (
+          agentContext.persistedSummary != null &&
+          agentContext.persistedSummary !== ''
         ) {
-          try {
-            let summary: string | undefined;
-            let summarySource: string;
+          summary = agentContext.persistedSummary;
+          this._cachedRunSummary = summary;
+          summarySource = 'persisted';
+        } else if (
+          sumConfig?.initialSummary != null &&
+          sumConfig.initialSummary !== ''
+        ) {
+          summary = sumConfig.initialSummary;
+          this._cachedRunSummary = summary;
+          summarySource = 'initial-seed';
+        } else {
+          summarySource = 'none';
+        }
 
-            if (this._cachedRunSummary != null) {
-              summary = this._cachedRunSummary;
-              summarySource = 'cached';
-            } else if (
-              agentContext.persistedSummary != null &&
-              agentContext.persistedSummary !== ''
-            ) {
-              summary = agentContext.persistedSummary;
-              this._cachedRunSummary = summary;
-              summarySource = 'persisted';
-            } else if (
-              sumConfig?.initialSummary != null &&
-              sumConfig.initialSummary !== ''
-            ) {
-              // Cross-run seed: use initialSummary when no persisted summary exists
-              summary = sumConfig.initialSummary;
-              this._cachedRunSummary = summary;
-              summarySource = 'initial-seed';
-            } else {
-              summarySource = 'none';
+        // Step 2: Calculate token budget
+        // Apply EMA calibration for accuracy across iterations
+        const calibratedMax = applyCalibration(maxTokens, this._pruneCalibration);
+        const systemMsg = messages[0]?.getType() === 'system' ? messages[0] : null;
+        const systemTokens = systemMsg != null
+          ? (agentContext.indexTokenCountMap[0] ?? 0)
+          : 0;
+        const summaryMsg = summary != null && summary !== ''
+          ? new SystemMessage(`[Conversation Summary]\n${summary}`)
+          : null;
+        const summaryTokens = summaryMsg != null && tokenCounter != null
+          ? tokenCounter(summaryMsg)
+          : 0;
+
+        // Budget for recent messages = total - system - summary - 3 (assistant priming)
+        const recentBudget = calibratedMax - systemTokens - summaryTokens - 3;
+
+        // Step 3: Determine window of recent messages to include.
+        //
+        // Two modes:
+        // A) No summary available → fill the budget (all messages that fit)
+        // B) Summary available → keep last 2 conversation rounds (H+A pairs)
+        //    + any trailing tool messages. The summary covers everything else.
+        //    This avoids wasting tokens on raw messages the summary already covers.
+        //
+        // A "round" = one human message + one AI response (+ any tool messages between).
+        const contentStart = systemMsg != null ? 1 : 0;
+        let usedTokens = 0;
+        let windowStart = messages.length; // index where the recent window begins
+
+        if (summary == null || summary === '') {
+          // Mode A: No summary — include as many recent messages as fit in budget
+          for (let i = messages.length - 1; i >= contentStart; i--) {
+            const msgTokens = agentContext.indexTokenCountMap[i] ?? 0;
+            if (usedTokens + msgTokens > recentBudget) {
+              break;
             }
+            usedTokens += msgTokens;
+            windowStart = i;
+          }
+        } else {
+          // Mode B: Summary exists — keep last 2 rounds (4 core messages: H+A+H+A)
+          // Walk backward counting human messages as round boundaries.
+          const MAX_RECENT_ROUNDS = COMPACTION_RECENT_ROUNDS;
+          let roundsSeen = 0;
+          for (let i = messages.length - 1; i >= contentStart; i--) {
+            const msgType = messages[i]?.getType();
+            const msgTokens = agentContext.indexTokenCountMap[i] ?? 0;
+
+            // Budget guard — even in round-limited mode, don't exceed budget
+            if (usedTokens + msgTokens > recentBudget) {
+              break;
+            }
+            usedTokens += msgTokens;
+            windowStart = i;
+
+            // Count a human message as a round boundary
+            if (msgType === 'human') {
+              roundsSeen++;
+              if (roundsSeen >= MAX_RECENT_ROUNDS) {
+                break;
+              }
+            }
+          }
+        }
 
-            // Single consolidated log for the entire prune+summarize decision
-            console.debug(
-              `[Graph:ContextMgmt] Pruned ${messages.length}→${context.length} msgs (${messagesToRefine.length} discarded) | summary=${summarySource}${summary ? ` (len=${summary.length})` : ''} | calibration=${this._pruneCalibration.ratio.toFixed(3)}(${this._pruneCalibration.iterations})`
-            );
+        // Ensure we don't split tool-call / tool-result pairs.
+        // If windowStart lands on a ToolMessage, walk back to include its AI message.
+        while (
+          windowStart > contentStart &&
+          messages[windowStart]?.getType() === 'tool'
+        ) {
+          windowStart--;
+          usedTokens += agentContext.indexTokenCountMap[windowStart] ?? 0;
+        }
+
+        const recentMessages = messages.slice(windowStart);
+        const compactedMessages = messages.slice(contentStart, windowStart);
+        const hasSummary = summaryMsg != null;
+
+        // Step 4: Assemble the windowed view
+        // [system] + [summary (covers compacted messages)] + [recent window]
+        const viewParts: BaseMessage[] = [];
+        if (systemMsg != null) {
+          viewParts.push(systemMsg);
+        }
+        if (summaryMsg != null) {
+          viewParts.push(summaryMsg);
+        }
+        viewParts.push(...recentMessages);
+        messagesToUse = viewParts;
+
+        // Rebuild indexTokenCountMap for the windowed view so downstream
+        // analytics and summarization triggers see accurate token counts.
+        const viewTokenMap: Record<string, number | undefined> = {};
+        let viewIdx = 0;
+        if (systemMsg != null) {
+          viewTokenMap[viewIdx] = systemTokens;
+          viewIdx++;
+        }
+        if (summaryMsg != null) {
+          viewTokenMap[viewIdx] = summaryTokens;
+          viewIdx++;
+        }
+        for (let i = windowStart; i < messages.length; i++) {
+          viewTokenMap[viewIdx] = agentContext.indexTokenCountMap[i];
+          viewIdx++;
+        }
+        agentContext.indexTokenCountMap = viewTokenMap;
+
+        console.debug(
+          `[Graph:Compaction] View: ${messages.length}→${viewParts.length} msgs ` +
+          `(${compactedMessages.length} behind summary, ${recentMessages.length} in window) | ` +
+          `summary=${summarySource}${summary ? ` (len=${summary.length})` : ''} | ` +
+          `budget=${recentBudget}/${calibratedMax} used=${usedTokens}`
+        );
 
-            // SCALE: Debounce background summarization — if a summary call is already
-            // in-flight (from a prior tool iteration), accumulate messages instead of
-            // firing another concurrent LLM call. At 2000 users with 3+ tool calls
-            // per turn, this prevents 3x summary call volume.
+        // Step 5: Fire background summary update (non-blocking)
+        // Summarize messages outside the window so next iteration has a fresh summary.
+        // Only trigger if there are compacted messages worth summarizing.
+        if (
+          compactedMessages.length > 0 &&
+          agentContext.summarizeCallback
+        ) {
+          const shouldSummarize = this.shouldTriggerSummarization(
+            compactedMessages.length,
+            maxTokens,
+            agentContext.indexTokenCountMap,
+            agentContext.instructionTokens,
+            sumConfig
+          );
+
+          if (shouldSummarize) {
             if (this._summaryInFlight) {
-              this._pendingMessagesToRefine.push(...messagesToRefine);
+              this._pendingMessagesToRefine.push(...compactedMessages);
               console.debug(
-                `[Graph:ContextMgmt] Summary in-flight, queued ${messagesToRefine.length} msgs (pending=${this._pendingMessagesToRefine.length})`
+                `[Graph:Compaction] Summary in-flight, queued ${compactedMessages.length} msgs (pending=${this._pendingMessagesToRefine.length})`
               );
             } else {
               this._summaryInFlight = true;
               const allMessages = this._pendingMessagesToRefine.length > 0
-                ? [...this._pendingMessagesToRefine, ...messagesToRefine]
-                : messagesToRefine;
+                ? [...this._pendingMessagesToRefine, ...compactedMessages]
+                : compactedMessages;
               this._pendingMessagesToRefine = [];
 
               agentContext
@@ -1697,7 +1808,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
                 })
                 .catch((err) => {
                   console.error(
-                    '[Graph] Background summary failed (non-fatal):',
+                    '[Graph:Compaction] Background summary update failed (non-fatal):',
                     err
                   );
                 })
@@ -1705,44 +1816,13 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
                   this._summaryInFlight = false;
                 });
             }
-
-            if (summary != null && summary !== '') {
-              hasSummary = true;
-              const summaryMsg = new SystemMessage(
-                `[Conversation Summary]\n${summary}`
-              );
-              const systemIdx =
-                messagesToUse[0]?.getType() === 'system' ? 1 : 0;
-              messagesToUse = [
-                ...messagesToUse.slice(0, systemIdx),
-                summaryMsg,
-                ...messagesToUse.slice(systemIdx),
-              ];
-            }
-          } catch (err) {
-            console.error('[Graph] Summarization failed:', err);
           }
-        } else if (messagesToRefine.length > 0) {
-          // Log pruning even when no summarize callback (discard mode)
-          console.debug(
-            `[Graph:ContextMgmt] Pruned ${messages.length}→${context.length} msgs (${messagesToRefine.length} discarded, no summary callback) | calibration=${this._pruneCalibration.ratio.toFixed(3)}`
-          );
         }
 
-        // Deduplicate system messages that accumulate from repeated tool iterations
-        const { messages: dedupedMessages, removedCount } =
-          deduplicateSystemMessages(messagesToUse);
-        if (removedCount > 0) {
-          messagesToUse = dedupedMessages;
-          console.debug(
-            `[Graph:Dedup] Removed ${removedCount} duplicate system message(s)`
-          );
-        }
-
-        // Post-prune context note for task-tool-enabled agents
-        if (messagesToRefine.length > 0 && hasTaskTool(agentContext.tools)) {
+        // Post-compaction context note for task-tool-enabled agents
+        if (compactedMessages.length > 0 && hasTaskTool(agentContext.tools)) {
           const postPruneNote = buildPostPruneNote(
-            messagesToRefine.length,
+            compactedMessages.length,
             hasSummary
           );
           if (postPruneNote) {
@@ -1754,6 +1834,18 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         }
       }
 
+      // Deduplicate system messages — ALWAYS runs, not just during compaction.
+      // Duplicate system messages accumulate from repeated tool iterations,
+      // summary injections, and context notes across turns.
+      const { messages: dedupedMessages, removedCount } =
+        deduplicateSystemMessages(messagesToUse);
+      if (removedCount > 0) {
+        messagesToUse = dedupedMessages;
+        console.debug(
+          `[Graph:Dedup] Removed ${removedCount} duplicate system message(s)`
+        );
+      }
+
       let finalMessages = messagesToUse;
       if (agentContext.useLegacyContent) {
         finalMessages = formatContentStrings(finalMessages);