@illuma-ai/agents 1.0.96 → 1.0.98

package/dist/cjs/common/constants.cjs

@@ -19,7 +19,32 @@ 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;
 
+exports.CONTEXT_SAFETY_BUFFER = CONTEXT_SAFETY_BUFFER;
 exports.MIN_THINKING_BUDGET = MIN_THINKING_BUDGET;
+exports.MULTI_DOCUMENT_THRESHOLD = MULTI_DOCUMENT_THRESHOLD;
 exports.TOOL_TURN_THINKING_BUDGET = TOOL_TURN_THINKING_BUDGET;
 //# sourceMappingURL=constants.cjs.map

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"],"names":[],"mappings":";;AAAA;AAEA;;;;AAIG;AACI,MAAM,mBAAmB,GAAG;AAEnC;;;;;;;;;;AAUG;AACI,MAAM,yBAAyB,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"],"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;;;;;;;"}

package/dist/cjs/graphs/Graph.cjs

@@ -24,6 +24,7 @@ require('ai-tokenizer');
 require('../utils/toonFormat.cjs');
 var contextAnalytics = require('../utils/contextAnalytics.cjs');
 require('zod-to-json-schema');
+var contextPressure = require('../utils/contextPressure.cjs');
 var providers = require('../llm/providers.cjs');
 var ToolNode = require('../tools/ToolNode.cjs');
 var index = require('../llm/openai/index.cjs');
@@ -950,36 +951,12 @@ class StandardGraph extends Graph {
             let messagesToUse = messages$1;
             // ====================================================================
             // 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$1) {
-                    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 &&
@@ -1002,7 +979,7 @@ class StandardGraph extends Graph {
                     indexTokenCountMap: agentContext.indexTokenCountMap,
                 });
             }
-            if (agentContext.pruneMessages && !delegationInjectedPrePrune) {
+            if (agentContext.pruneMessages) {
                 console.debug(`[Graph:ContextMgmt] Pruning messages | inputCount=${messages$1.length} | maxTokens=${agentContext.maxContextTokens}`);
                 const { context, indexTokenCountMap, messagesToRefine } = agentContext.pruneMessages({
                     messages: messages$1,
@@ -1013,12 +990,14 @@ class StandardGraph extends Graph {
                 messagesToUse = context;
                 console.debug(`[Graph:ContextMgmt] Pruned | kept=${context.length} | discarded=${messagesToRefine.length} | originalCount=${messages$1.length}`);
                 // Summarize discarded messages if callback provided
+                let hasSummary = false;
                 if (messagesToRefine.length > 0 && agentContext.summarizeCallback) {
                     console.debug(`[Graph:ContextMgmt] Summarizing ${messagesToRefine.length} discarded messages`);
                     try {
                         const summary = await agentContext.summarizeCallback(messagesToRefine);
                         console.debug(`[Graph:ContextMgmt] Summary received | len=${summary?.length ?? 0} | hasContent=${summary != null && summary !== ''}`);
                         if (summary != null && summary !== '') {
+                            hasSummary = true;
                             const summaryMsg = new messages.SystemMessage(`[Conversation Summary]\n${summary}`);
                             // Insert after system message (if present), before conversation messages
                             const systemIdx = messagesToUse[0]?.getType() === 'system' ? 1 : 0;
@@ -1034,9 +1013,15 @@ class StandardGraph extends Graph {
                         console.error('[Graph] Summarization callback failed:', err);
                     }
                 }
-            }
-            else if (delegationInjectedPrePrune) {
-                console.info('[Graph] Skipping pruning — delegation will handle context pressure');
+                // Post-prune context note: inform the LLM that context was compressed
+                // without exposing token numbers (prevents voluntary bail-out)
+                if (messagesToRefine.length > 0 && contextPressure.hasTaskTool(agentContext.tools)) {
+                    const postPruneNote = contextPressure.buildPostPruneNote(messagesToRefine.length, hasSummary);
+                    if (postPruneNote) {
+                        messagesToUse = [...messagesToUse, new messages.SystemMessage(postPruneNote)];
+                        console.debug(`[Graph:ContextMgmt] Post-prune note injected | hasSummary=${hasSummary} | discarded=${messagesToRefine.length}`);
+                    }
+                }
             }
             let finalMessages = messagesToUse;
             if (agentContext.useLegacyContent) {
@@ -1149,125 +1134,30 @@ class StandardGraph extends Graph {
                 analytics: contextAnalytics$1,
             }, 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$1.utilizationPercent != null &&
-                contextAnalytics$1.maxContextTokens != null) {
-                const utilization = contextAnalytics$1.utilizationPercent;
-                const totalTokens = contextAnalytics$1.totalTokens;
-                const maxTokens = contextAnalytics$1.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++;
-                            }
-                        }
-                    }
+            if (contextPressure.hasTaskTool(agentContext.tools)) {
+                const { count: documentCount, names: documentNames } = contextPressure.detectDocuments(finalMessages);
+                // Observability log (no token numbers exposed to LLM)
+                if (contextAnalytics$1.utilizationPercent != null) {
+                    console.debug(`[Graph] Context utilization: ${contextAnalytics$1.utilizationPercent.toFixed(1)}% | ` +
+                        `messages: ${finalMessages.length} | docs: ${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)
+                // 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 (contextPressure.shouldInjectMultiDocHint(documentCount, hasAiResponse)) {
                     const pressureMsg = new messages.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: contextPressure.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 messages.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 messages.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