@illuma-ai/agents 1.1.2 → 1.1.3

package/package.json

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

package/src/graphs/Graph.ts

@@ -1606,86 +1606,143 @@ 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) ─────
+        //
+        // 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
         //
-        // 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;
+        // 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
+
         const sumConfig = agentContext.summarizationConfig;
-        const shouldSummarize = this.shouldTriggerSummarization(
-          messagesToRefine.length,
-          agentContext.maxContextTokens ?? 0,
-          agentContext.indexTokenCountMap,
-          agentContext.instructionTokens,
-          sumConfig
-        );
+        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 !== ''
+        ) {
+          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 (
-          messagesToRefine.length > 0 &&
-          agentContext.summarizeCallback &&
-          shouldSummarize
+        // 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: Walk newest→oldest, collect messages that fit in the budget
+        const contentStart = systemMsg != null ? 1 : 0;
+        let usedTokens = 0;
+        let windowStart = messages.length; // index where the recent window begins
+
+        for (let i = messages.length - 1; i >= contentStart; i--) {
+          const msgTokens = agentContext.indexTokenCountMap[i] ?? 0;
+          if (usedTokens + msgTokens > recentBudget) {
+            break;
+          }
+          usedTokens += msgTokens;
+          windowStart = i;
+        }
+
+        // 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'
         ) {
-          try {
-            let summary: string | undefined;
-            let summarySource: string;
+          windowStart--;
+          usedTokens += agentContext.indexTokenCountMap[windowStart] ?? 0;
+        }
 
-            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';
-            }
+        const recentMessages = messages.slice(windowStart);
+        const compactedMessages = messages.slice(contentStart, windowStart);
+        const hasSummary = summaryMsg != null;
 
-            // 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})`
-            );
+        // 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;
+
+        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}`
+        );
+
+        // 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
+          );
 
-            // 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.
+          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 +1754,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 +1762,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 +1780,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);

package/src/graphs/gapFeatures.test.ts

@@ -627,7 +627,239 @@ describe('Proactive Summarization — Context Pressure', () => {
 
     // Even at 100%+, we use the existing cached summary — no error thrown
     expect(cachedSummary).toBeTruthy();
-    // Pruning will remove oldest messages to fit, and inject cached summary
-    // The key: no blocking, no throwing, just graceful degradation
+    // Compaction builds a windowed view — no messages deleted, no throwing
+  });
+});
+
+// ===========================================================================
+// Context Compaction (Copilot-style: never delete messages)
+// ===========================================================================
+
+import { applyCalibration as _applyCalibration } from '@/utils/pruneCalibration';
+
+describe('Context Compaction — Windowed View (no message deletion)', () => {
+  /**
+   * Simulates the compaction logic from Graph.ts without the full Graph instance.
+   * This tests the windowed-view algorithm directly.
+   */
+  function buildWindowedView(opts: {
+    messages: BaseMessage[];
+    indexTokenCountMap: Record<string, number | undefined>;
+    maxTokens: number;
+    summary?: string;
+    tokenCounter: TokenCounter;
+  }) {
+    const { messages, indexTokenCountMap, maxTokens, summary, tokenCounter } = opts;
+
+    const systemMsg = messages[0]?.getType() === 'system' ? messages[0] : null;
+    const systemTokens = systemMsg != null ? (indexTokenCountMap[0] ?? 0) : 0;
+    const summaryMsg = summary
+      ? new SystemMessage(`[Conversation Summary]\n${summary}`)
+      : null;
+    const summaryTokens = summaryMsg != null ? tokenCounter(summaryMsg) : 0;
+
+    const recentBudget = maxTokens - systemTokens - summaryTokens - 3;
+    const contentStart = systemMsg != null ? 1 : 0;
+    let usedTokens = 0;
+    let windowStart = messages.length;
+
+    for (let i = messages.length - 1; i >= contentStart; i--) {
+      const msgTokens = indexTokenCountMap[i] ?? 0;
+      if (usedTokens + msgTokens > recentBudget) break;
+      usedTokens += msgTokens;
+      windowStart = i;
+    }
+
+    // Don't split tool-call / tool-result pairs
+    while (
+      windowStart > contentStart &&
+      messages[windowStart]?.getType() === 'tool'
+    ) {
+      windowStart--;
+      usedTokens += indexTokenCountMap[windowStart] ?? 0;
+    }
+
+    const recentMessages = messages.slice(windowStart);
+    const compactedMessages = messages.slice(contentStart, windowStart);
+
+    const view: BaseMessage[] = [];
+    if (systemMsg) view.push(systemMsg);
+    if (summaryMsg) view.push(summaryMsg);
+    view.push(...recentMessages);
+
+    return { view, compactedMessages, recentMessages, usedTokens };
+  }
+
+  it('builds a windowed view without deleting any messages', () => {
+    const messages = buildConversation(20, 400); // system + 20 content msgs
+    const indexTokenCountMap: Record<string, number | undefined> = {};
+    for (let i = 0; i < messages.length; i++) {
+      indexTokenCountMap[i] = simpleTokenCounter(messages[i]);
+    }
+
+    const { view, compactedMessages, recentMessages } = buildWindowedView({
+      messages,
+      indexTokenCountMap,
+      maxTokens: 500, // small budget forces windowing
+      tokenCounter: simpleTokenCounter,
+    });
+
+    // View is smaller than original
+    expect(view.length).toBeLessThan(messages.length);
+    // But original messages array is untouched
+    expect(messages.length).toBe(21); // system + 20
+    // Compacted + recent = all non-system messages
+    expect(compactedMessages.length + recentMessages.length).toBe(20);
+    // View starts with system message
+    expect(view[0].getType()).toBe('system');
+  });
+
+  it('injects summary message covering compacted (windowed-out) messages', () => {
+    const messages = buildConversation(20, 400);
+    const indexTokenCountMap: Record<string, number | undefined> = {};
+    for (let i = 0; i < messages.length; i++) {
+      indexTokenCountMap[i] = simpleTokenCounter(messages[i]);
+    }
+
+    const summary = 'Summary of earlier conversation turns';
+    const { view, compactedMessages } = buildWindowedView({
+      messages,
+      indexTokenCountMap,
+      maxTokens: 600,
+      summary,
+      tokenCounter: simpleTokenCounter,
+    });
+
+    // Summary is injected after system message
+    expect(view[1].content).toContain('[Conversation Summary]');
+    expect(view[1].content).toContain(summary);
+    // There should be compacted messages behind the summary
+    expect(compactedMessages.length).toBeGreaterThan(0);
+    // Original array is unchanged
+    expect(messages.length).toBe(21);
+  });
+
+  it('includes all messages when budget is large enough (no compaction)', () => {
+    const messages = buildConversation(5, 100); // small conversation
+    const indexTokenCountMap: Record<string, number | undefined> = {};
+    for (let i = 0; i < messages.length; i++) {
+      indexTokenCountMap[i] = simpleTokenCounter(messages[i]);
+    }
+
+    const { view, compactedMessages } = buildWindowedView({
+      messages,
+      indexTokenCountMap,
+      maxTokens: 100_000, // huge budget
+      tokenCounter: simpleTokenCounter,
+    });
+
+    // All messages fit — no compaction
+    expect(view.length).toBe(messages.length);
+    expect(compactedMessages.length).toBe(0);
+  });
+
+  it('does not split tool-call / tool-result pairs at window boundary', () => {
+    const messages: BaseMessage[] = [
+      new SystemMessage('System'),
+      new HumanMessage('old question'),
+      new AIMessage('old answer'),
+      new HumanMessage('question about tool'),
+      new AIMessageChunk({
+        content: 'Let me search',
+        tool_calls: [{ id: 'tc_1', name: 'web_search', args: {} }],
+      }),
+      new ToolMessage({ content: 'Search results', tool_call_id: 'tc_1', name: 'web_search' }),
+      new AIMessage('Based on the search results...'),
+      new HumanMessage('latest question'),
+      new AIMessage('latest answer'),
+    ];
+    const indexTokenCountMap: Record<string, number | undefined> = {};
+    for (let i = 0; i < messages.length; i++) {
+      indexTokenCountMap[i] = simpleTokenCounter(messages[i]);
+    }
+
+    // Budget that would naturally cut between the AI tool-call and ToolMessage
+    // Force the window to start at the ToolMessage by making budget tight
+    const toolMsgIdx = 5; // ToolMessage index
+    let budgetUpToTool = 3; // priming tokens
+    for (let i = toolMsgIdx; i < messages.length; i++) {
+      budgetUpToTool += indexTokenCountMap[i] ?? 0;
+    }
+    // Budget includes ToolMessage but NOT the AI tool-call before it
+    // The algorithm should walk back to include the AI message too
+    const tightBudget = budgetUpToTool + (indexTokenCountMap[0] ?? 0) + 5;
+
+    const { view } = buildWindowedView({
+      messages,
+      indexTokenCountMap,
+      maxTokens: tightBudget,
+      tokenCounter: simpleTokenCounter,
+    });
+
+    // Verify no ToolMessage appears without its preceding AI message
+    for (let i = 0; i < view.length; i++) {
+      if (view[i].getType() === 'tool' && i > 0) {
+        // The message before a ToolMessage should be an AI message (the tool caller)
+        // or another ToolMessage (multi-tool scenario), or system
+        const prevType = view[i - 1].getType();
+        expect(['ai', 'tool', 'system']).toContain(prevType);
+      }
+    }
+  });
+
+  it('with summary, recent messages use remaining budget after summary tokens', () => {
+    const messages = buildConversation(20, 400);
+    const indexTokenCountMap: Record<string, number | undefined> = {};
+    for (let i = 0; i < messages.length; i++) {
+      indexTokenCountMap[i] = simpleTokenCounter(messages[i]);
+    }
+
+    // Large summary eats into the budget
+    const largeSummary = 'S'.repeat(1000); // ~250 tokens
+    const { view: viewWithSummary, recentMessages: recentWithSummary } = buildWindowedView({
+      messages,
+      indexTokenCountMap,
+      maxTokens: 800,
+      summary: largeSummary,
+      tokenCounter: simpleTokenCounter,
+    });
+
+    // Without summary — more recent messages fit
+    const { recentMessages: recentWithout } = buildWindowedView({
+      messages,
+      indexTokenCountMap,
+      maxTokens: 800,
+      tokenCounter: simpleTokenCounter,
+    });
+
+    // Summary takes budget, so fewer recent messages fit
+    expect(recentWithSummary.length).toBeLessThan(recentWithout.length);
+  });
+
+  it('original messages array is never mutated', () => {
+    const messages = buildConversation(15, 400);
+    const originalLength = messages.length;
+    const originalFirstContent = messages[0].content;
+    const originalLastContent = messages[messages.length - 1].content;
+    const indexTokenCountMap: Record<string, number | undefined> = {};
+    for (let i = 0; i < messages.length; i++) {
+      indexTokenCountMap[i] = simpleTokenCounter(messages[i]);
+    }
+
+    // Run compaction multiple times
+    for (let i = 0; i < 5; i++) {
+      buildWindowedView({
+        messages,
+        indexTokenCountMap,
+        maxTokens: 300,
+        summary: `Summary iteration ${i}`,
+        tokenCounter: simpleTokenCounter,
+      });
+    }
+
+    // Original array unchanged after 5 compaction runs
+    expect(messages.length).toBe(originalLength);
+    expect(messages[0].content).toBe(originalFirstContent);
+    expect(messages[messages.length - 1].content).toBe(originalLastContent);
   });
 });