@illuma-ai/agents 1.1.0 → 1.1.2

package/dist/cjs/common/constants.cjs

@@ -53,6 +53,17 @@ const CONTEXT_SAFETY_BUFFER = 0.9;
  * When the context window is ≥80% full, pruning + summarization activates.
  */
 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
+ */
+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,
@@ -94,6 +105,7 @@ exports.CONTEXT_SAFETY_BUFFER = CONTEXT_SAFETY_BUFFER;
 exports.DEDUP_MAX_CONTENT_LENGTH = DEDUP_MAX_CONTENT_LENGTH;
 exports.MIN_THINKING_BUDGET = MIN_THINKING_BUDGET;
 exports.MULTI_DOCUMENT_THRESHOLD = MULTI_DOCUMENT_THRESHOLD;
+exports.PROACTIVE_SUMMARY_THRESHOLD = PROACTIVE_SUMMARY_THRESHOLD;
 exports.PRUNING_EMA_ALPHA = PRUNING_EMA_ALPHA;
 exports.PRUNING_INITIAL_CALIBRATION = PRUNING_INITIAL_CALIBRATION;
 exports.SUMMARIZATION_CONTEXT_THRESHOLD = SUMMARIZATION_CONTEXT_THRESHOLD;

package/dist/cjs/common/constants.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"constants.cjs","sources":["../../../src/common/constants.ts"],"sourcesContent":["// src/common/constants.ts\n\n/**\n * Minimum thinking budget allowed by the Anthropic API.\n * Extended thinking requires at least 1024 budget_tokens.\n * @see https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking\n */\nexport const MIN_THINKING_BUDGET = 1024;\n\n/**\n * Reduced thinking budget for subsequent ReAct iterations (tool-result turns).\n *\n * In a ReAct agent loop, the first LLM call processes the user's query and\n * may need deep reasoning. Subsequent iterations (after tool results return)\n * typically only need to decide \"call next tool\" or \"generate final response\"\n * — 1024 tokens is sufficient for this routing logic.\n *\n * This reduces wall-clock time per iteration from ~20-30s to ~5-10s,\n * compounding across multi-tool conversations (e.g., 10 tool calls).\n */\nexport const TOOL_TURN_THINKING_BUDGET = 1024;\n\n// ============================================================================\n// CONTEXT OVERFLOW MANAGEMENT\n//\n// Context overflow is handled mechanically — no token budget numbers are\n// exposed to the LLM. The system uses: pruning (Graph), summarization\n// (summarizeCallback), and auto-continuation (client.js max_tokens detection).\n//\n// See: docs/context-overflow-architecture.md\n// ============================================================================\n\n/**\n * Minimum number of attached documents before the multi-document delegation\n * hint is injected. Below this threshold, the agent processes documents\n * directly within its own context.\n */\nexport const MULTI_DOCUMENT_THRESHOLD = 3;\n\n/**\n * Context utilization safety buffer multiplier (0-1).\n * Applied as: effectiveMax = (maxContextTokens - maxOutputTokens) * CONTEXT_SAFETY_BUFFER\n *\n * Reserves headroom so the LLM doesn't hit hard token limits mid-generation.\n * 0.9 = 10% reserved for safety.\n */\nexport const CONTEXT_SAFETY_BUFFER = 0.9;\n\n// ============================================================================\n// SUMMARIZATION CONFIGURATION DEFAULTS\n//\n// These constants provide sensible defaults for the SummarizationConfig.\n// They can be overridden per-agent via AgentInputs.summarizationConfig.\n// ============================================================================\n\n/**\n * Default context utilization percentage (0-100) at which summarization triggers.\n * When the context window is ≥80% full, pruning + summarization activates.\n */\nexport const SUMMARIZATION_CONTEXT_THRESHOLD = 80;\n\n/**\n * Default reserve ratio (0-1) — fraction of context window to preserve as recent messages.\n * 0.3 means 30% of the context budget is reserved for the most recent messages,\n * ensuring the model always has immediate conversation history even after aggressive pruning.\n */\nexport const SUMMARIZATION_RESERVE_RATIO = 0.3;\n\n/**\n * Default EMA (Exponential Moving Average) alpha for pruning calibration.\n * Controls how quickly the calibration adapts to new token counts.\n * Higher α = faster adaptation (more responsive to recent changes).\n * Lower α = smoother adaptation (more stable across iterations).\n * 0.3 provides a balance between responsiveness and stability.\n */\nexport const PRUNING_EMA_ALPHA = 0.3;\n\n/**\n * Default initial calibration ratio for EMA pruning.\n * 1.0 means no adjustment on the first iteration (trust the raw token counts).\n * Subsequent iterations will adjust based on actual vs. estimated token usage.\n */\nexport const PRUNING_INITIAL_CALIBRATION = 1.0;\n\n// ============================================================================\n// TOOL DISCOVERY CACHING\n// ============================================================================\n\n/**\n * Maximum number of tool discovery entries to cache per conversation.\n * Prevents unbounded memory growth in very long conversations.\n */\nexport const TOOL_DISCOVERY_CACHE_MAX_SIZE = 200;\n\n// ============================================================================\n// MESSAGE DEDUPLICATION\n// ============================================================================\n\n/**\n * Maximum length of system message content to hash for deduplication.\n * Messages longer than this are always considered unique (hashing would be expensive).\n */\nexport const DEDUP_MAX_CONTENT_LENGTH = 10000;\n"],"names":[],"mappings":";;AAAA;AAEA;;;;AAIG;AACI,MAAM,mBAAmB,GAAG;AAEnC;;;;;;;;;;AAUG;AACI,MAAM,yBAAyB,GAAG;AAEzC;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AAEA;;;;AAIG;AACI,MAAM,wBAAwB,GAAG;AAExC;;;;;;AAMG;AACI,MAAM,qBAAqB,GAAG;AAErC;AACA;AACA;AACA;AACA;AACA;AAEA;;;AAGG;AACI,MAAM,+BAA+B,GAAG;AAE/C;;;;AAIG;AACI,MAAM,2BAA2B,GAAG;AAE3C;;;;;;AAMG;AACI,MAAM,iBAAiB,GAAG;AAEjC;;;;AAIG;AACI,MAAM,2BAA2B,GAAG;AAE3C;AACA;AACA;AAEA;;;AAGG;AACI,MAAM,6BAA6B,GAAG;AAE7C;AACA;AACA;AAEA;;;AAGG;AACI,MAAM,wBAAwB,GAAG;;;;;;;;;;;;;"}
+{"version":3,"file":"constants.cjs","sources":["../../../src/common/constants.ts"],"sourcesContent":["// src/common/constants.ts\n\n/**\n * Minimum thinking budget allowed by the Anthropic API.\n * Extended thinking requires at least 1024 budget_tokens.\n * @see https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking\n */\nexport const MIN_THINKING_BUDGET = 1024;\n\n/**\n * Reduced thinking budget for subsequent ReAct iterations (tool-result turns).\n *\n * In a ReAct agent loop, the first LLM call processes the user's query and\n * may need deep reasoning. Subsequent iterations (after tool results return)\n * typically only need to decide \"call next tool\" or \"generate final response\"\n * — 1024 tokens is sufficient for this routing logic.\n *\n * This reduces wall-clock time per iteration from ~20-30s to ~5-10s,\n * compounding across multi-tool conversations (e.g., 10 tool calls).\n */\nexport const TOOL_TURN_THINKING_BUDGET = 1024;\n\n// ============================================================================\n// CONTEXT OVERFLOW MANAGEMENT\n//\n// Context overflow is handled mechanically — no token budget numbers are\n// exposed to the LLM. The system uses: pruning (Graph), summarization\n// (summarizeCallback), and auto-continuation (client.js max_tokens detection).\n//\n// See: docs/context-overflow-architecture.md\n// ============================================================================\n\n/**\n * Minimum number of attached documents before the multi-document delegation\n * hint is injected. Below this threshold, the agent processes documents\n * directly within its own context.\n */\nexport const MULTI_DOCUMENT_THRESHOLD = 3;\n\n/**\n * Context utilization safety buffer multiplier (0-1).\n * Applied as: effectiveMax = (maxContextTokens - maxOutputTokens) * CONTEXT_SAFETY_BUFFER\n *\n * Reserves headroom so the LLM doesn't hit hard token limits mid-generation.\n * 0.9 = 10% reserved for safety.\n */\nexport const CONTEXT_SAFETY_BUFFER = 0.9;\n\n// ============================================================================\n// SUMMARIZATION CONFIGURATION DEFAULTS\n//\n// These constants provide sensible defaults for the SummarizationConfig.\n// They can be overridden per-agent via AgentInputs.summarizationConfig.\n// ============================================================================\n\n/**\n * Default context utilization percentage (0-100) at which summarization triggers.\n * When the context window is ≥80% full, pruning + summarization activates.\n */\nexport const SUMMARIZATION_CONTEXT_THRESHOLD = 80;\n\n/**\n * Proactive summarization threshold (0-1 fraction of context window).\n * At this utilization level, background summarization fires BEFORE pruning is needed.\n * This gives the summary time to complete so it's ready when context actually fills up.\n *\n * Inspired by VS Code Copilot Chat's 3-tier strategy:\n *   80% → proactive background summary\n *   90% → pruning kicks in (with summary already cached)\n *  100% → graceful: use existing summary + recent messages, never block\n */\nexport const PROACTIVE_SUMMARY_THRESHOLD = 0.8;\n\n/**\n * Default reserve ratio (0-1) — fraction of context window to preserve as recent messages.\n * 0.3 means 30% of the context budget is reserved for the most recent messages,\n * ensuring the model always has immediate conversation history even after aggressive pruning.\n */\nexport const SUMMARIZATION_RESERVE_RATIO = 0.3;\n\n/**\n * Default EMA (Exponential Moving Average) alpha for pruning calibration.\n * Controls how quickly the calibration adapts to new token counts.\n * Higher α = faster adaptation (more responsive to recent changes).\n * Lower α = smoother adaptation (more stable across iterations).\n * 0.3 provides a balance between responsiveness and stability.\n */\nexport const PRUNING_EMA_ALPHA = 0.3;\n\n/**\n * Default initial calibration ratio for EMA pruning.\n * 1.0 means no adjustment on the first iteration (trust the raw token counts).\n * Subsequent iterations will adjust based on actual vs. estimated token usage.\n */\nexport const PRUNING_INITIAL_CALIBRATION = 1.0;\n\n// ============================================================================\n// TOOL DISCOVERY CACHING\n// ============================================================================\n\n/**\n * Maximum number of tool discovery entries to cache per conversation.\n * Prevents unbounded memory growth in very long conversations.\n */\nexport const TOOL_DISCOVERY_CACHE_MAX_SIZE = 200;\n\n// ============================================================================\n// MESSAGE DEDUPLICATION\n// ============================================================================\n\n/**\n * Maximum length of system message content to hash for deduplication.\n * Messages longer than this are always considered unique (hashing would be expensive).\n */\nexport const DEDUP_MAX_CONTENT_LENGTH = 10000;\n"],"names":[],"mappings":";;AAAA;AAEA;;;;AAIG;AACI,MAAM,mBAAmB,GAAG;AAEnC;;;;;;;;;;AAUG;AACI,MAAM,yBAAyB,GAAG;AAEzC;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AAEA;;;;AAIG;AACI,MAAM,wBAAwB,GAAG;AAExC;;;;;;AAMG;AACI,MAAM,qBAAqB,GAAG;AAErC;AACA;AACA;AACA;AACA;AACA;AAEA;;;AAGG;AACI,MAAM,+BAA+B,GAAG;AAE/C;;;;;;;;;AASG;AACI,MAAM,2BAA2B,GAAG;AAE3C;;;;AAIG;AACI,MAAM,2BAA2B,GAAG;AAE3C;;;;;;AAMG;AACI,MAAM,iBAAiB,GAAG;AAEjC;;;;AAIG;AACI,MAAM,2BAA2B,GAAG;AAE3C;AACA;AACA;AAEA;;;AAGG;AACI,MAAM,6BAA6B,GAAG;AAE7C;AACA;AACA;AAEA;;;AAGG;AACI,MAAM,wBAAwB,GAAG;;;;;;;;;;;;;;"}

package/dist/cjs/graphs/Graph.cjs

@@ -102,6 +102,15 @@ class StandardGraph extends Graph {
     _pruneCalibration;
     /** Run-scoped tool discovery cache — avoids re-parsing conversation history on every iteration */
     _toolDiscoveryCache;
+    /**
+     * SCALE: Tracks whether a summary call is already in-flight for this Graph instance.
+     * Prevents multiple concurrent summary LLM calls when rapid tool iterations each
+     * trigger pruning. At 2000 users with 3+ tool calls per turn, this prevents
+     * 6000+ summary calls/turn from becoming 2000.
+     */
+    _summaryInFlight = false;
+    /** Messages accumulated across tool iterations while a summary call is in-flight */
+    _pendingMessagesToRefine = [];
     /** Map of agent contexts by agent ID */
     agentContexts = new Map();
     /** Default agent ID to use */
@@ -157,9 +166,11 @@ class StandardGraph extends Graph {
         this.messageStepHasToolCalls = graph.resetIfNotEmpty(this.messageStepHasToolCalls, new Map());
         this.prelimMessageIdsByStepKey = graph.resetIfNotEmpty(this.prelimMessageIdsByStepKey, new Map());
         this.invokedToolIds = graph.resetIfNotEmpty(this.invokedToolIds, undefined);
-        // Reset EMA calibration and tool discovery cache for fresh run
+        // Reset EMA calibration, tool discovery cache, and summary debounce for fresh run
         this._pruneCalibration = pruneCalibration.createPruneCalibration();
         this._toolDiscoveryCache.reset();
+        this._summaryInFlight = false;
+        this._pendingMessagesToRefine = [];
         for (const context of this.agentContexts.values()) {
             context.reset();
         }
@@ -1071,6 +1082,47 @@ class StandardGraph extends Graph {
                     this._pruneCalibration = pruneCalibration.updatePruneCalibration(this._pruneCalibration, agentContext.currentUsage.input_tokens, estimatedTokens);
                 }
             }
+            // ── 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 = prune.getContextUtilization(agentContext.indexTokenCountMap, agentContext.instructionTokens, agentContext.maxContextTokens);
+                const threshold = (agentContext.summarizationConfig?.triggerThreshold ?? constants.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$1.length * 0.3));
+                    const oldMessages = messages$1.slice(messages$1[0]?.getType() === 'system' ? 1 : 0, Math.max(1, messages$1.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({
                     messages: messages$1,
@@ -1121,17 +1173,34 @@ class StandardGraph extends Graph {
                         }
                         // Single consolidated log for the entire prune+summarize decision
                         console.debug(`[Graph:ContextMgmt] Pruned ${messages$1.length}→${context.length} msgs (${messagesToRefine.length} discarded) | summary=${summarySource}${summary ? ` (len=${summary.length})` : ''} | calibration=${this._pruneCalibration.ratio.toFixed(3)}(${this._pruneCalibration.iterations})`);
-                        // Fire background summarization — updates cache for next iteration/turn
-                        agentContext
-                            .summarizeCallback(messagesToRefine)
-                            .then((updated) => {
-                            if (updated != null && updated !== '') {
-                                this._cachedRunSummary = updated;
-                            }
-                        })
-                            .catch((err) => {
-                            console.error('[Graph] Background summary failed (non-fatal):', err);
-                        });
+                        // 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 (this._summaryInFlight) {
+                            this._pendingMessagesToRefine.push(...messagesToRefine);
+                            console.debug(`[Graph:ContextMgmt] Summary in-flight, queued ${messagesToRefine.length} msgs (pending=${this._pendingMessagesToRefine.length})`);
+                        }
+                        else {
+                            this._summaryInFlight = true;
+                            const allMessages = this._pendingMessagesToRefine.length > 0
+                                ? [...this._pendingMessagesToRefine, ...messagesToRefine]
+                                : messagesToRefine;
+                            this._pendingMessagesToRefine = [];
+                            agentContext
+                                .summarizeCallback(allMessages)
+                                .then((updated) => {
+                                if (updated != null && updated !== '') {
+                                    this._cachedRunSummary = updated;
+                                }
+                            })
+                                .catch((err) => {
+                                console.error('[Graph] Background summary failed (non-fatal):', err);
+                            })
+                                .finally(() => {
+                                this._summaryInFlight = false;
+                            });
+                        }
                         if (summary != null && summary !== '') {
                             hasSummary = true;
                             const summaryMsg = new messages.SystemMessage(`[Conversation Summary]\n${summary}`);