@illuma-ai/agents 1.1.1 → 1.1.2

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, 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 { 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

@@ -35,6 +35,17 @@ export declare const CONTEXT_SAFETY_BUFFER = 0.9;
  * When the context window is ≥80% full, pruning + summarization activates.
  */
 export declare const SUMMARIZATION_CONTEXT_THRESHOLD = 80;
+/**
+ * Proactive summarization threshold (0-1 fraction of context window).
+ * At this utilization level, background summarization fires BEFORE pruning is needed.
+ * This gives the summary time to complete so it's ready when context actually fills up.
+ *
+ * Inspired by VS Code Copilot Chat's 3-tier strategy:
+ *   80% → proactive background summary
+ *   90% → pruning kicks in (with summary already cached)
+ *  100% → graceful: use existing summary + recent messages, never block
+ */
+export declare const PROACTIVE_SUMMARY_THRESHOLD = 0.8;
 /**
  * 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.1",
+  "version": "1.1.2",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",

package/src/common/constants.ts

@@ -59,6 +59,18 @@ export const CONTEXT_SAFETY_BUFFER = 0.9;
  */
 export const SUMMARIZATION_CONTEXT_THRESHOLD = 80;
 
+/**
+ * Proactive summarization threshold (0-1 fraction of context window).
+ * At this utilization level, background summarization fires BEFORE pruning is needed.
+ * This gives the summary time to complete so it's ready when context actually fills up.
+ *
+ * Inspired by VS Code Copilot Chat's 3-tier strategy:
+ *   80% → proactive background summary
+ *   90% → pruning kicks in (with summary already cached)
+ *  100% → graceful: use existing summary + recent messages, never block
+ */
+export const PROACTIVE_SUMMARY_THRESHOLD = 0.8;
+
 /**
  * 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

@@ -35,6 +35,7 @@ import {
   formatAnthropicArtifactContent,
   ensureThinkingBlockInMessages,
   deduplicateSystemMessages,
+  getContextUtilization,
   convertMessagesToContent,
   addBedrockCacheControl,
   modifyDeltaProperties,
@@ -54,6 +55,7 @@ import {
   Constants,
   TOOL_TURN_THINKING_BUDGET,
   SUMMARIZATION_CONTEXT_THRESHOLD,
+  PROACTIVE_SUMMARY_THRESHOLD,
 } from '@/common';
 import {
   ToolDiscoveryCache,
@@ -1542,6 +1544,67 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         }
       }
 
+      // ── Proactive summarization at context pressure ───────────────────
+      // Inspired by VS Code Copilot Chat's 3-tier strategy:
+      //   80% → fire proactive background summary (BEFORE pruning needed)
+      //   90% → pruning kicks in (summary already cached from 80% trigger)
+      //  100% → graceful: use existing summary + recent messages, NEVER block
+      //
+      // This ensures the summary is READY by the time pruning actually occurs,
+      // so the user never waits and never sees a context cliff.
+      if (
+        agentContext.maxContextTokens != null &&
+        agentContext.maxContextTokens > 0 &&
+        agentContext.summarizeCallback &&
+        !this._summaryInFlight &&
+        !this._cachedRunSummary
+      ) {
+        const utilization = getContextUtilization(
+          agentContext.indexTokenCountMap,
+          agentContext.instructionTokens,
+          agentContext.maxContextTokens
+        );
+        const threshold = (agentContext.summarizationConfig?.triggerThreshold ?? PROACTIVE_SUMMARY_THRESHOLD * 100);
+
+        if (utilization >= threshold) {
+          // Identify older messages to summarize proactively.
+          // Keep the last N messages (recent turns) intact — only summarize older history.
+          // This is incremental: the callback checks for existing summary and updates it.
+          const recentTurnCount = Math.max(4, Math.floor(messages.length * 0.3));
+          const oldMessages = messages.slice(
+            messages[0]?.getType() === 'system' ? 1 : 0,
+            Math.max(1, messages.length - recentTurnCount)
+          );
+
+          if (oldMessages.length > 0) {
+            this._summaryInFlight = true;
+            console.debug(
+              `[Graph:ProactiveSummary] Context at ${utilization.toFixed(1)}% (threshold ${threshold}%) — summarizing ${oldMessages.length} older msgs in background`
+            );
+
+            agentContext
+              .summarizeCallback(oldMessages)
+              .then((updated) => {
+                if (updated != null && updated !== '') {
+                  this._cachedRunSummary = updated;
+                  console.debug(
+                    `[Graph:ProactiveSummary] Background summary ready (len=${updated.length})`
+                  );
+                }
+              })
+              .catch((err) => {
+                console.error(
+                  '[Graph:ProactiveSummary] Background summary failed (non-fatal):',
+                  err
+                );
+              })
+              .finally(() => {
+                this._summaryInFlight = false;
+              });
+          }
+        }
+      }
+
       if (agentContext.pruneMessages) {
         const { context, indexTokenCountMap, messagesToRefine } =
           agentContext.pruneMessages({

package/src/graphs/gapFeatures.test.ts

@@ -518,3 +518,116 @@ describe('All Features Combined — Full Pipeline', () => {
     expect(callback).toHaveBeenCalled();
   });
 });
+
+// ===========================================================================
+// Proactive Summarization — Context Pressure
+// ===========================================================================
+
+import { getContextUtilization } from '@/messages/prune';
+import { PROACTIVE_SUMMARY_THRESHOLD } from '@/common/constants';
+
+describe('Proactive Summarization — Context Pressure', () => {
+  it('triggers proactive summary at 80% utilization BEFORE pruning', () => {
+    // Simulate context at 82% utilization
+    const maxContextTokens = 200_000;
+    const indexTokenCountMap: Record<string, number | undefined> = {};
+    // Build messages that fill ~82% of context
+    const msgsNeeded = 40;
+    const tokensPerMsg = Math.floor((maxContextTokens * 0.82) / msgsNeeded);
+    for (let i = 0; i < msgsNeeded; i++) {
+      indexTokenCountMap[String(i)] = tokensPerMsg;
+    }
+
+    const utilization = getContextUtilization(indexTokenCountMap, 0, maxContextTokens);
+    const threshold = PROACTIVE_SUMMARY_THRESHOLD * 100; // 80
+
+    expect(utilization).toBeGreaterThanOrEqual(threshold);
+    // At 82%, proactive summary should fire
+    // But pruning should NOT have happened yet (context < 90% safety factor)
+    const effectiveBudget = Math.floor(maxContextTokens * 0.9); // CONTEXT_SAFETY_FACTOR
+    const totalTokens = Object.values(indexTokenCountMap).reduce((s, v) => (s ?? 0) + (v ?? 0), 0) as number;
+    expect(totalTokens).toBeLessThan(effectiveBudget);
+  });
+
+  it('does NOT trigger proactive summary below 80%', () => {
+    const maxContextTokens = 200_000;
+    const indexTokenCountMap: Record<string, number | undefined> = {};
+    // Fill to 50% utilization
+    const msgsNeeded = 20;
+    const tokensPerMsg = Math.floor((maxContextTokens * 0.5) / msgsNeeded);
+    for (let i = 0; i < msgsNeeded; i++) {
+      indexTokenCountMap[String(i)] = tokensPerMsg;
+    }
+
+    const utilization = getContextUtilization(indexTokenCountMap, 0, maxContextTokens);
+    expect(utilization).toBeLessThan(PROACTIVE_SUMMARY_THRESHOLD * 100);
+  });
+
+  it('selects only older messages for proactive summarization (keeps recent turns)', () => {
+    const messages: BaseMessage[] = [
+      new SystemMessage('System prompt'),
+      ...Array.from({ length: 20 }, (_, i) =>
+        i % 2 === 0
+          ? new HumanMessage(`User message ${i}`)
+          : new AIMessage(`AI response ${i}`)
+      ),
+    ];
+
+    // Simulate the selection logic from Graph.ts proactive summarization
+    const recentTurnCount = Math.max(4, Math.floor(messages.length * 0.3));
+    const oldMessages = messages.slice(
+      1, // skip system message
+      Math.max(1, messages.length - recentTurnCount)
+    );
+
+    // Recent 30% (~6 messages) preserved, older messages selected for summary
+    expect(oldMessages.length).toBeLessThan(messages.length);
+    expect(oldMessages.length).toBeGreaterThan(0);
+    // System message not included
+    expect(oldMessages[0].getType()).not.toBe('system');
+    // Last messages of conversation not included (recent turns preserved)
+    const lastOldIndex = messages.indexOf(oldMessages[oldMessages.length - 1]);
+    expect(lastOldIndex).toBeLessThan(messages.length - recentTurnCount);
+  });
+
+  it('never blocks — proactive summary is always fire-and-forget', async () => {
+    let resolveCallback: ((v: string) => void) | undefined;
+    const slowCallback = jest.fn(
+      () =>
+        new Promise<string>((resolve) => {
+          resolveCallback = resolve;
+        })
+    );
+
+    // Simulate proactive summary fire-and-forget
+    const summaryPromise = slowCallback().then((updated) => {
+      return updated;
+    });
+
+    // Main flow continues immediately — callback hasn't resolved yet
+    expect(slowCallback).toHaveBeenCalledTimes(1);
+
+    // Later, callback resolves (simulating Nova Micro responding)
+    resolveCallback!('Proactive summary result');
+    const result = await summaryPromise;
+    expect(result).toBe('Proactive summary result');
+  });
+
+  it('at 100%+ utilization, uses existing summary without throwing', () => {
+    const maxContextTokens = 200_000;
+    const cachedSummary = 'Previously generated summary of the conversation';
+
+    // Context is at 105% (over budget)
+    const indexTokenCountMap: Record<string, number | undefined> = {
+      '0': 210_000, // system + everything
+    };
+
+    const utilization = getContextUtilization(indexTokenCountMap, 0, maxContextTokens);
+    expect(utilization).toBeGreaterThan(100);
+
+    // 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
+  });
+});