@illuma-ai/agents 1.0.96 → 1.1.0

package/dist/esm/common/constants.mjs

@@ -17,6 +17,76 @@ const MIN_THINKING_BUDGET = 1024;
  * compounding across multi-tool conversations (e.g., 10 tool calls).
  */
 const TOOL_TURN_THINKING_BUDGET = 1024;
+// ============================================================================
+// CONTEXT OVERFLOW MANAGEMENT
+//
+// Context overflow is handled mechanically — no token budget numbers are
+// exposed to the LLM. The system uses: pruning (Graph), summarization
+// (summarizeCallback), and auto-continuation (client.js max_tokens detection).
+//
+// See: docs/context-overflow-architecture.md
+// ============================================================================
+/**
+ * Minimum number of attached documents before the multi-document delegation
+ * hint is injected. Below this threshold, the agent processes documents
+ * directly within its own context.
+ */
+const MULTI_DOCUMENT_THRESHOLD = 3;
+/**
+ * Context utilization safety buffer multiplier (0-1).
+ * Applied as: effectiveMax = (maxContextTokens - maxOutputTokens) * CONTEXT_SAFETY_BUFFER
+ *
+ * Reserves headroom so the LLM doesn't hit hard token limits mid-generation.
+ * 0.9 = 10% reserved for safety.
+ */
+const CONTEXT_SAFETY_BUFFER = 0.9;
+// ============================================================================
+// SUMMARIZATION CONFIGURATION DEFAULTS
+//
+// These constants provide sensible defaults for the SummarizationConfig.
+// They can be overridden per-agent via AgentInputs.summarizationConfig.
+// ============================================================================
+/**
+ * Default context utilization percentage (0-100) at which summarization triggers.
+ * When the context window is ≥80% full, pruning + summarization activates.
+ */
+const SUMMARIZATION_CONTEXT_THRESHOLD = 80;
+/**
+ * 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,
+ * ensuring the model always has immediate conversation history even after aggressive pruning.
+ */
+const SUMMARIZATION_RESERVE_RATIO = 0.3;
+/**
+ * Default EMA (Exponential Moving Average) alpha for pruning calibration.
+ * Controls how quickly the calibration adapts to new token counts.
+ * Higher α = faster adaptation (more responsive to recent changes).
+ * Lower α = smoother adaptation (more stable across iterations).
+ * 0.3 provides a balance between responsiveness and stability.
+ */
+const PRUNING_EMA_ALPHA = 0.3;
+/**
+ * Default initial calibration ratio for EMA pruning.
+ * 1.0 means no adjustment on the first iteration (trust the raw token counts).
+ * Subsequent iterations will adjust based on actual vs. estimated token usage.
+ */
+const PRUNING_INITIAL_CALIBRATION = 1.0;
+// ============================================================================
+// TOOL DISCOVERY CACHING
+// ============================================================================
+/**
+ * Maximum number of tool discovery entries to cache per conversation.
+ * Prevents unbounded memory growth in very long conversations.
+ */
+const TOOL_DISCOVERY_CACHE_MAX_SIZE = 200;
+// ============================================================================
+// MESSAGE DEDUPLICATION
+// ============================================================================
+/**
+ * Maximum length of system message content to hash for deduplication.
+ * Messages longer than this are always considered unique (hashing would be expensive).
+ */
+const DEDUP_MAX_CONTENT_LENGTH = 10000;
 
-export { MIN_THINKING_BUDGET, TOOL_TURN_THINKING_BUDGET };
+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 };
 //# sourceMappingURL=constants.mjs.map

package/dist/esm/common/constants.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"constants.mjs","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"],"names":[],"mappings":"AAAA;AAEA;;;;AAIG;AACI,MAAM,mBAAmB,GAAG;AAEnC;;;;;;;;;;AAUG;AACI,MAAM,yBAAyB,GAAG;;;;"}
+{"version":3,"file":"constants.mjs","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;;;;"}

package/dist/esm/graphs/Graph.mjs

@@ -10,9 +10,9 @@ import { createPruneMessages } from '../messages/prune.mjs';
 import { ensureThinkingBlockInMessages } from '../messages/format.mjs';
 import { addCacheControl, addBedrockCacheControl } from '../messages/cache.mjs';
 import { formatContentStrings } from '../messages/content.mjs';
-import { extractToolDiscoveries } from '../messages/tools.mjs';
 import { GraphNodeKeys, Providers, ContentTypes, GraphEvents, MessageTypes, StepTypes, Constants } from '../common/enum.mjs';
-import { TOOL_TURN_THINKING_BUDGET } from '../common/constants.mjs';
+import { TOOL_TURN_THINKING_BUDGET, SUMMARIZATION_CONTEXT_THRESHOLD } from '../common/constants.mjs';
+import { deduplicateSystemMessages } from '../messages/dedup.mjs';
 import { resetIfNotEmpty, joinKeys } from '../utils/graph.mjs';
 import { isOpenAILike, isGoogleLike } from '../utils/llm.mjs';
 import { ChatModelStreamHandler } from '../stream.mjs';
@@ -22,6 +22,9 @@ import 'ai-tokenizer';
 import '../utils/toonFormat.mjs';
 import { buildContextAnalytics } from '../utils/contextAnalytics.mjs';
 import 'zod-to-json-schema';
+import { hasTaskTool, buildPostPruneNote, detectDocuments, shouldInjectMultiDocHint, buildMultiDocHintContent } from '../utils/contextPressure.mjs';
+import { ToolDiscoveryCache } from '../utils/toolDiscoveryCache.mjs';
+import { createPruneCalibration, applyCalibration, updatePruneCalibration } from '../utils/pruneCalibration.mjs';
 import { getChatModelClass, manualToolStreamProviders } from '../llm/providers.mjs';
 import { ToolNode, toolsCondition } from '../tools/ToolNode.mjs';
 import { ChatOpenAI, AzureChatOpenAI } from '../llm/openai/index.mjs';
@@ -90,6 +93,13 @@ class StandardGraph extends Graph {
     runId;
     startIndex = 0;
     signal;
+    /** Cached summary from the first prune in this run.
+     * Reused for subsequent prunes to avoid blocking LLM calls on every tool iteration. */
+    _cachedRunSummary;
+    /** EMA-based pruning calibration state — smooths token budget adjustments across iterations */
+    _pruneCalibration;
+    /** Run-scoped tool discovery cache — avoids re-parsing conversation history on every iteration */
+    _toolDiscoveryCache;
     /** Map of agent contexts by agent ID */
     agentContexts = new Map();
     /** Default agent ID to use */
@@ -110,6 +120,19 @@ class StandardGraph extends Graph {
             this.agentContexts.set(agentConfig.agentId, agentContext);
         }
         this.defaultAgentId = agents[0].agentId;
+        // Seed cached summary from persisted storage so the first prune in a
+        // resumed conversation can also skip the synchronous LLM summarization call
+        const primaryContext = this.agentContexts.get(this.defaultAgentId);
+        if (primaryContext?.persistedSummary) {
+            this._cachedRunSummary = primaryContext.persistedSummary;
+        }
+        // Initialize EMA pruning calibration
+        this._pruneCalibration = createPruneCalibration();
+        // Initialize tool discovery cache, seeded with any pre-existing discoveries
+        this._toolDiscoveryCache = new ToolDiscoveryCache();
+        if (primaryContext?.discoveredToolNames.size) {
+            this._toolDiscoveryCache.seed([...primaryContext.discoveredToolNames]);
+        }
     }
     /* Init */
     resetValues(keepContent) {
@@ -132,6 +155,9 @@ class StandardGraph extends Graph {
         this.messageStepHasToolCalls = resetIfNotEmpty(this.messageStepHasToolCalls, new Map());
         this.prelimMessageIdsByStepKey = resetIfNotEmpty(this.prelimMessageIdsByStepKey, new Map());
         this.invokedToolIds = resetIfNotEmpty(this.invokedToolIds, undefined);
+        // Reset EMA calibration and tool discovery cache for fresh run
+        this._pruneCalibration = createPruneCalibration();
+        this._toolDiscoveryCache.reset();
         for (const context of this.agentContexts.values()) {
             context.reset();
         }
@@ -220,6 +246,62 @@ class StandardGraph extends Graph {
         }
         return clientOptions;
     }
+    /**
+     * Determines whether summarization should trigger based on SummarizationConfig.
+     *
+     * Supports three trigger strategies:
+     * - contextPercentage (default): Trigger when context utilization >= threshold%
+     * - messageCount: Trigger when pruned message count >= threshold
+     * - tokenThreshold: Trigger when total estimated tokens >= threshold
+     *
+     * When no config is provided, always triggers (preserves backward compatibility).
+     *
+     * @param prunedMessageCount - Number of messages that were pruned
+     * @param maxContextTokens - Maximum context token budget
+     * @param indexTokenCountMap - Token count map by message index
+     * @param instructionTokens - Token count for instructions/system message
+     * @param config - Optional SummarizationConfig
+     * @returns Whether summarization should be triggered
+     */
+    shouldTriggerSummarization(prunedMessageCount, maxContextTokens, indexTokenCountMap, instructionTokens, config) {
+        // No pruned messages means nothing to summarize
+        if (prunedMessageCount === 0) {
+            return false;
+        }
+        // No config = backward compatible (always summarize when messages are pruned)
+        if (!config || !config.triggerType) {
+            return true;
+        }
+        const threshold = config.triggerThreshold;
+        switch (config.triggerType) {
+            case 'contextPercentage': {
+                if (maxContextTokens <= 0)
+                    return true;
+                const effectiveThreshold = threshold ?? SUMMARIZATION_CONTEXT_THRESHOLD;
+                let totalTokens = instructionTokens;
+                for (const key in indexTokenCountMap) {
+                    totalTokens += indexTokenCountMap[key] ?? 0;
+                }
+                const utilization = (totalTokens / maxContextTokens) * 100;
+                return utilization >= effectiveThreshold;
+            }
+            case 'messageCount': {
+                const effectiveThreshold = threshold ?? 5;
+                return prunedMessageCount >= effectiveThreshold;
+            }
+            case 'tokenThreshold': {
+                if (threshold == null)
+                    return true;
+                let totalTokens = instructionTokens;
+                for (const key in indexTokenCountMap) {
+                    totalTokens += indexTokenCountMap[key] ?? 0;
+                }
+                return totalTokens >= threshold;
+            }
+            default:
+                return true;
+        }
+    }
     /**
      * Returns the normalized finish/stop reason from the last LLM invocation.
      * Used by callers to detect when the response was truncated due to max_tokens.
@@ -358,7 +440,6 @@ class StandardGraph extends Graph {
     /* Misc.*/
     getRunMessages() {
         const result = this.messages.slice(this.startIndex);
-        console.debug(`[Graph] getRunMessages() | totalMessages=${this.messages.length} | startIndex=${this.startIndex} | runMessages=${result.length}`);
         return result;
     }
     getContentParts() {
@@ -914,10 +995,12 @@ class StandardGraph extends Graph {
                 });
                 messages = [dynamicContextMessage, ackMessage, ...messages];
             }
-            // Extract tool discoveries from current turn only (similar to formatArtifactPayload pattern)
-            const discoveredNames = extractToolDiscoveries(messages);
-            if (discoveredNames.length > 0) {
-                agentContext.markToolsAsDiscovered(discoveredNames);
+            // Tool discovery caching: only scan new messages since last iteration
+            // instead of re-parsing the full history via extractToolDiscoveries()
+            const cachedDiscoveries = this._toolDiscoveryCache.getNewDiscoveries(messages);
+            if (cachedDiscoveries.length > 0) {
+                agentContext.markToolsAsDiscovered(cachedDiscoveries);
+                console.debug(`[Graph:ToolDiscovery] Cached ${cachedDiscoveries.length} new tools (total: ${this._toolDiscoveryCache.size})`);
             }
             const toolsForBinding = agentContext.getToolsForBinding();
             // PERF: Detect subsequent ReAct iterations (tool results present in messages)
@@ -948,36 +1031,12 @@ class StandardGraph extends Graph {
             let messagesToUse = messages;
             // ====================================================================
             // PRE-PRUNING DELEGATION CHECK
-            // Before pruning strips messages (losing context), check if we should
-            // delegate instead. If context would be pruned AND the agent has the
-            // task tool, inject a delegation hint and SKIP pruning — preserving
-            // the content for the LLM to understand what to delegate.
             // ====================================================================
-            let delegationInjectedPrePrune = false;
-            const hasTaskToolPrePrune = agentContext.tools?.some((tool) => {
-                const toolName = typeof tool === 'object' && 'name' in tool
-                    ? tool.name
-                    : '';
-                return toolName === 'task';
-            });
-            if (hasTaskToolPrePrune === true &&
-                agentContext.tokenCounter &&
-                agentContext.maxContextTokens != null) {
-                // Estimate total tokens in messages BEFORE pruning
-                let prePruneTokens = 0;
-                for (const msg of messages) {
-                    prePruneTokens += agentContext.tokenCounter(msg);
-                }
-                // Add instruction tokens (system prompt)
-                prePruneTokens += agentContext.instructionTokens;
-                const prePruneUtilization = (prePruneTokens / agentContext.maxContextTokens) * 100;
-                if (prePruneUtilization > 70) {
-                    console.warn(`[Graph] PRE-PRUNE delegation check: ${prePruneUtilization.toFixed(1)}% utilization ` +
-                        `(${prePruneTokens}/${agentContext.maxContextTokens} tokens). ` +
-                        'Injecting delegation hint INSTEAD of pruning.');
-                    delegationInjectedPrePrune = true;
-                }
-            }
+            // Context management is now fully mechanical:
+            // - Pruning always runs when needed (no delegation-based skip)
+            // - Auto-continuation in client.js handles max_tokens finish reason
+            // - LLM never sees raw token numbers (prevents voluntary bail-out)
+            // ====================================================================
             if (!agentContext.pruneMessages &&
                 agentContext.tokenCounter &&
                 agentContext.maxContextTokens != null &&
@@ -991,50 +1050,121 @@ class StandardGraph extends Graph {
                     (agentContext.provider === Providers.OPENAI &&
                         agentContext.clientOptions.modelKwargs
                             ?.thinking?.type === 'enabled');
+                // Apply EMA calibration to max token budget — smooths pruning across iterations
+                const calibratedMaxTokens = applyCalibration(agentContext.maxContextTokens, this._pruneCalibration);
                 agentContext.pruneMessages = createPruneMessages({
                     startIndex: this.startIndex,
                     provider: agentContext.provider,
                     tokenCounter: agentContext.tokenCounter,
-                    maxTokens: agentContext.maxContextTokens,
+                    maxTokens: calibratedMaxTokens,
                     thinkingEnabled: isAnthropicWithThinking,
                     indexTokenCountMap: agentContext.indexTokenCountMap,
                 });
             }
-            if (agentContext.pruneMessages && !delegationInjectedPrePrune) {
-                console.debug(`[Graph:ContextMgmt] Pruning messages | inputCount=${messages.length} | maxTokens=${agentContext.maxContextTokens}`);
+            // Update EMA calibration with actual token usage from API response
+            if (agentContext.currentUsage?.input_tokens &&
+                agentContext.maxContextTokens) {
+                const estimatedTokens = Object.values(agentContext.indexTokenCountMap).reduce((sum, v) => (sum ?? 0) + (v ?? 0), 0);
+                if (estimatedTokens > 0) {
+                    this._pruneCalibration = updatePruneCalibration(this._pruneCalibration, agentContext.currentUsage.input_tokens, estimatedTokens);
+                }
+            }
+            if (agentContext.pruneMessages) {
                 const { context, indexTokenCountMap, messagesToRefine } = agentContext.pruneMessages({
                     messages,
                     usageMetadata: agentContext.currentUsage,
-                    // startOnMessageType: 'human',
                 });
                 agentContext.indexTokenCountMap = indexTokenCountMap;
                 messagesToUse = context;
-                console.debug(`[Graph:ContextMgmt] Pruned | kept=${context.length} | discarded=${messagesToRefine.length} | originalCount=${messages.length}`);
-                // Summarize discarded messages if callback provided
-                if (messagesToRefine.length > 0 && agentContext.summarizeCallback) {
-                    console.debug(`[Graph:ContextMgmt] Summarizing ${messagesToRefine.length} discarded messages`);
+                // ── 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.
+                //
+                // 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);
+                if (messagesToRefine.length > 0 &&
+                    agentContext.summarizeCallback &&
+                    shouldSummarize) {
                     try {
-                        const summary = await agentContext.summarizeCallback(messagesToRefine);
-                        console.debug(`[Graph:ContextMgmt] Summary received | len=${summary?.length ?? 0} | hasContent=${summary != null && summary !== ''}`);
+                        let summary;
+                        let summarySource;
+                        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';
+                        }
+                        // 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})`);
+                        // 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);
+                        });
                         if (summary != null && summary !== '') {
+                            hasSummary = true;
                             const summaryMsg = new SystemMessage(`[Conversation Summary]\n${summary}`);
-                            // Insert after system message (if present), before conversation messages
                             const systemIdx = messagesToUse[0]?.getType() === 'system' ? 1 : 0;
                             messagesToUse = [
                                 ...messagesToUse.slice(0, systemIdx),
                                 summaryMsg,
                                 ...messagesToUse.slice(systemIdx),
                             ];
-                            console.debug(`[Graph:ContextMgmt] Summary injected at index ${systemIdx} | finalMsgCount=${messagesToUse.length}`);
                         }
                     }
                     catch (err) {
-                        console.error('[Graph] Summarization callback failed:', 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)) {
+                    const postPruneNote = buildPostPruneNote(messagesToRefine.length, hasSummary);
+                    if (postPruneNote) {
+                        messagesToUse = [
+                            ...messagesToUse,
+                            new SystemMessage(postPruneNote),
+                        ];
                     }
                 }
-            }
-            else if (delegationInjectedPrePrune) {
-                console.info('[Graph] Skipping pruning — delegation will handle context pressure');
             }
             let finalMessages = messagesToUse;
             if (agentContext.useLegacyContent) {
@@ -1147,125 +1277,25 @@ class StandardGraph extends Graph {
                 analytics: contextAnalytics,
             }, config);
             // ====================================================================
-            // CONTEXT PRESSURE AWARENESS — Intelligent Sub-Agent Delegation
-            //
-            // Two triggers for delegation hints:
-            // 1. DOCUMENT COUNT: When 3+ documents are detected in the conversation,
-            //    inject a delegation hint on the FIRST iteration (before the LLM
-            //    has called any tools). This ensures the agent delegates upfront
-            //    rather than trying to process all documents itself.
-            // 2. TOKEN UTILIZATION: At EVERY iteration, if context is filling up
-            //    (70%/85%), inject escalating hints to delegate remaining work.
+            // MULTI-DOCUMENT DELEGATION (task-driven, not budget-driven)
             //
-            // This runs mid-chain — so even if tool responses push context up
-            // after the first LLM call, subsequent iterations get the hint.
+            // Token-based pressure hints have been removed — the LLM never sees
+            // raw token numbers. Context overflow is handled mechanically by
+            // pruning (Graph) + auto-continuation (client.js max_tokens detection).
+            // See: docs/context-overflow-architecture.md
             // ====================================================================
-            const hasTaskToolInContext = agentContext.tools?.some((tool) => {
-                const toolName = typeof tool === 'object' && 'name' in tool
-                    ? tool.name
-                    : '';
-                return toolName === 'task';
-            });
-            if (hasTaskToolInContext === true &&
-                contextAnalytics.utilizationPercent != null &&
-                contextAnalytics.maxContextTokens != null) {
-                const utilization = contextAnalytics.utilizationPercent;
-                const totalTokens = contextAnalytics.totalTokens;
-                const maxTokens = contextAnalytics.maxContextTokens;
-                const remainingTokens = maxTokens - totalTokens;
-                // Count attached documents by scanning for document patterns in HumanMessages:
-                // 1. # "filename" headers in "Attached document(s):" blocks (text content)
-                // 2. **filename1, filename2** in "The user has attached:" blocks (embedded files)
-                // 3. Filenames in file_search tool results
-                let documentCount = 0;
-                const documentNames = [];
-                for (const msg of finalMessages) {
-                    const content = typeof msg.content === 'string'
-                        ? msg.content
-                        : Array.isArray(msg.content)
-                            ? msg.content
-                                .map((p) => {
-                                const part = p;
-                                return String(part.text ?? part.content ?? '');
-                            })
-                                .join(' ')
-                            : '';
-                    // Pattern 1: # "filename" headers in attached document blocks
-                    const docMatches = content.match(/# "([^"]+)"/g);
-                    if (docMatches) {
-                        for (const match of docMatches) {
-                            const name = match.replace(/# "/, '').replace(/"$/, '');
-                            if (!documentNames.includes(name)) {
-                                documentNames.push(name);
-                                documentCount++;
-                            }
-                        }
-                    }
-                    // Pattern 2: "The user has attached: **file1, file2**" (embedded files)
-                    const attachedMatch = content.match(/user has attached:\s*\*\*([^*]+)\*\*/i);
-                    if (attachedMatch) {
-                        const names = attachedMatch[1]
-                            .split(',')
-                            .map((n) => n.trim())
-                            .filter(Boolean);
-                        for (const name of names) {
-                            if (!documentNames.includes(name)) {
-                                documentNames.push(name);
-                                documentCount++;
-                            }
-                        }
-                    }
-                }
-                // BASELINE LOG: Always fires so we can verify this code path runs
-                console.debug(`[Graph] Context utilization: ${utilization.toFixed(1)}% ` +
-                    `(${totalTokens}/${maxTokens} tokens, ${remainingTokens} remaining) | ` +
-                    `hasTaskTool: true | messages: ${finalMessages.length} | docs: ${documentCount}`);
-                // TRIGGER 1: Multi-document delegation (3+ documents detected)
-                // Only inject on first iteration (no AI messages yet = agent hasn't responded)
+            if (hasTaskTool(agentContext.tools)) {
+                const { count: documentCount, names: documentNames } = detectDocuments(finalMessages);
+                // Multi-document delegation: first iteration only (before AI has responded)
                 const hasAiResponse = finalMessages.some((m) => m._getType() === 'ai' || m._getType() === 'tool');
-                if (documentCount >= 3 && !hasAiResponse) {
+                if (shouldInjectMultiDocHint(documentCount, hasAiResponse)) {
                     const pressureMsg = new HumanMessage({
-                        content: `[MULTI-DOCUMENT PROCESSING — ${documentCount} documents detected]\n` +
-                            `Documents: ${documentNames.join(', ')}\n\n` +
-                            `You have ${documentCount} documents attached. For thorough analysis, use the "task" tool ` +
-                            'to delegate each document (or group of related documents) to a sub-agent.\n' +
-                            'Each sub-agent has its own fresh context window and can use file_search to retrieve the full document content.\n' +
-                            'After all sub-agents complete, synthesize their results into a comprehensive response.\n\n' +
-                            'This approach ensures each document gets full attention without context limitations.',
+                        content: buildMultiDocHintContent(documentCount, documentNames),
                     });
                     finalMessages = [...finalMessages, pressureMsg];
                     console.info(`[Graph] Multi-document delegation hint injected for ${documentCount} documents: ` +
                         `${documentNames.join(', ')}`);
                 }
-                // TRIGGER 2: Token utilization thresholds (mid-chain safety net)
-                // Also fires when we skipped pruning due to delegationInjectedPrePrune
-                if (utilization > 85 ||
-                    (delegationInjectedPrePrune && utilization > 50)) {
-                    // CRITICAL: Context is high — MANDATE delegation
-                    const pressureMsg = new HumanMessage({
-                        content: `[CONTEXT BUDGET CRITICAL — ${utilization.toFixed(0)}% used]\n` +
-                            `You have used ${totalTokens} of ${maxTokens} tokens (${remainingTokens} remaining).\n` +
-                            'Your context is very large. You MUST use the "task" tool to delegate work to sub-agents.\n' +
-                            'Each sub-agent runs in its own fresh context window and can use file_search to access documents.\n' +
-                            'Do NOT attempt to process documents directly — delegate each document to a sub-agent, then synthesize results.',
-                    });
-                    finalMessages = [...finalMessages, pressureMsg];
-                    console.warn(`[Graph] Context pressure CRITICAL (${utilization.toFixed(0)}%): ` +
-                        `Injected mandatory delegation hint. ${remainingTokens} tokens remaining. ` +
-                        `prePruneSkipped: ${delegationInjectedPrePrune}`);
-                }
-                else if (utilization > 70) {
-                    // WARNING: Context filling up — suggest delegation
-                    const pressureMsg = new HumanMessage({
-                        content: `[CONTEXT BUDGET WARNING — ${utilization.toFixed(0)}% used]\n` +
-                            `You have used ${totalTokens} of ${maxTokens} tokens (${remainingTokens} remaining).\n` +
-                            'Your context is filling up. Consider using the "task" tool to delegate complex operations to sub-agents.\n' +
-                            "Sub-agents run in fresh context windows and won't consume your remaining budget.",
-                    });
-                    finalMessages = [...finalMessages, pressureMsg];
-                    console.info(`[Graph] Context pressure WARNING (${utilization.toFixed(0)}%): ` +
-                        `Injected delegation suggestion. ${remainingTokens} tokens remaining.`);
-                }
             }
             // Structured output mode: when the agent has NO tools, produce structured JSON immediately.
             // When the agent HAS tools, we defer structured output until after tool use completes
@@ -1659,10 +1689,6 @@ If I seem to be missing something we discussed earlier, just give me a quick rem
                 reducer: (a, b) => {
                     if (!a.length) {
                         this.startIndex = a.length + b.length;
-                        console.debug(`[Graph:Reducer] Initial messages | startIndex=${this.startIndex} | inputMsgCount=${b.length}`);
-                    }
-                    else {
-                        console.debug(`[Graph:Reducer] Appending messages | existing=${a.length} | new=${b.length} | startIndex=${this.startIndex}`);
                     }
                     const result = messagesStateReducer(a, b);
                     this.messages = result;