illuma-agents 1.0.70 → 1.0.72

package/dist/cjs/graphs/Graph.cjs

@@ -571,6 +571,78 @@ class StandardGraph extends Graph {
         this.signal.removeEventListener('abort', client.abortHandler);
         client.abortHandler = undefined;
     }
+    /**
+     * Perform structured output invocation: creates a fresh model without tools bound,
+     * removes thinking configuration, invokes with the schema, emits the event,
+     * and returns a clean AIMessageChunk without tool_calls.
+     *
+     * Used by both the immediate path (no tools) and the deferred path (after tool use).
+     */
+    async performStructuredOutput({ agentContext, finalMessages, config, }) {
+        const schema = agentContext.getStructuredOutputSchema();
+        if (!schema) {
+            throw new Error('Structured output schema is not configured');
+        }
+        // Get a fresh model WITHOUT tools bound
+        // bindTools() returns RunnableBinding which lacks withStructuredOutput
+        // Also disable thinking mode - Anthropic/Bedrock doesn't allow tool_choice with thinking enabled
+        const structuredClientOptions = { ...agentContext.clientOptions };
+        // Disable streaming for structured output
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        structuredClientOptions.streaming = false;
+        // Remove thinking configuration for Bedrock
+        if (agentContext.provider === _enum.Providers.BEDROCK) {
+            const bedrockOpts = structuredClientOptions;
+            if (bedrockOpts.additionalModelRequestFields) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const additionalFields = Object.assign({}, bedrockOpts.additionalModelRequestFields);
+                delete additionalFields.thinking;
+                delete additionalFields.budgetTokens;
+                bedrockOpts.additionalModelRequestFields = additionalFields;
+            }
+        }
+        // Remove thinking configuration for Anthropic direct API
+        if (agentContext.provider === _enum.Providers.ANTHROPIC) {
+            const anthropicOpts = structuredClientOptions;
+            if (anthropicOpts.thinking) {
+                delete anthropicOpts.thinking;
+            }
+        }
+        const structuredModel = this.getNewModel({
+            provider: agentContext.provider,
+            clientOptions: structuredClientOptions,
+        });
+        const { structuredResponse, rawMessage } = await this.attemptStructuredInvoke({
+            currentModel: structuredModel,
+            finalMessages,
+            schema,
+            structuredOutputConfig: agentContext.structuredOutput,
+            provider: agentContext.provider,
+        }, config);
+        // Emit structured output event
+        await events.safeDispatchCustomEvent(_enum.GraphEvents.ON_STRUCTURED_OUTPUT, {
+            structuredResponse,
+            schema,
+            raw: rawMessage,
+        }, config);
+        // Create a clean message WITHOUT tool_calls for structured output.
+        // The rawMessage contains a tool_call for the structured output schema (e.g., "response"),
+        // which would cause the graph router to send it to the tool node.
+        // We return a clean AI message that ends the graph.
+        let cleanMessage;
+        if (rawMessage) {
+            cleanMessage = new messages.AIMessageChunk({
+                content: JSON.stringify(structuredResponse, null, 2),
+                id: rawMessage.id,
+                response_metadata: rawMessage.response_metadata,
+                usage_metadata: rawMessage.usage_metadata,
+            });
+        }
+        return {
+            messages: cleanMessage ? [cleanMessage] : [],
+            structuredResponse,
+        };
+    }
     createCallModel(agentId = 'default') {
         return async (state, config) => {
             /**
@@ -624,6 +696,38 @@ class StandardGraph extends Graph {
             }
             this.config = config;
             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 &&
+                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 ?? 0;
+                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;
+                }
+            }
             if (!agentContext.pruneMessages &&
                 agentContext.tokenCounter &&
                 agentContext.maxContextTokens != null &&
@@ -646,7 +750,7 @@ class StandardGraph extends Graph {
                     indexTokenCountMap: agentContext.indexTokenCountMap,
                 });
             }
-            if (agentContext.pruneMessages) {
+            if (agentContext.pruneMessages && !delegationInjectedPrePrune) {
                 const { context, indexTokenCountMap } = agentContext.pruneMessages({
                     messages: messages$1,
                     usageMetadata: agentContext.currentUsage,
@@ -655,6 +759,9 @@ class StandardGraph extends Graph {
                 agentContext.indexTokenCountMap = indexTokenCountMap;
                 messagesToUse = context;
             }
+            else if (delegationInjectedPrePrune) {
+                console.info('[Graph] Skipping pruning — delegation will handle context pressure');
+            }
             let finalMessages = messagesToUse;
             if (agentContext.useLegacyContent) {
                 finalMessages = content.formatContentStrings(finalMessages);
@@ -768,12 +875,13 @@ class StandardGraph extends Graph {
             // ====================================================================
             // CONTEXT PRESSURE AWARENESS — Intelligent Sub-Agent Delegation
             //
-            // At EVERY iteration of the agent loop (not just pre-flight), check
-            // context utilization. If the agent has a "task" tool (sub-agents)
-            // and context is filling up, inject a hint telling the LLM to
-            // delegate remaining work to sub-agents instead of continuing to
-            // accumulate context. The LLM then makes the intelligent decision
-            // about WHAT to delegate and HOW to split the work.
+            // 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.
             //
             // This runs mid-chain — so even if tool responses push context up
             // after the first LLM call, subsequent iterations get the hint.
@@ -791,22 +899,80 @@ class StandardGraph extends Graph {
                 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++;
+                            }
+                        }
+                    }
+                }
                 // BASELINE LOG: Always fires so we can verify this code path runs
                 console.info(`[Graph] Context utilization: ${utilization.toFixed(1)}% ` +
                     `(${totalTokens}/${maxTokens} tokens, ${remainingTokens} remaining) | ` +
-                    `hasTaskTool: true | messages: ${finalMessages.length}`);
-                if (utilization > 85) {
-                    // CRITICAL: Context nearly full — MANDATE delegation
+                    `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)
+                const hasAiResponse = finalMessages.some((m) => m._getType?.() === 'ai' || m._getType?.() === 'tool');
+                if (documentCount >= 3 && !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.`,
+                    });
+                    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 almost full. You MUST use the "task" tool to delegate any remaining work to sub-agents.\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 make any more tool calls yourself except "task". Delegate and then synthesize the results.`,
+                            `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.`);
+                        `Injected mandatory delegation hint. ${remainingTokens} tokens remaining. ` +
+                        `prePruneSkipped: ${delegationInjectedPrePrune}`);
                 }
                 else if (utilization > 70) {
                     // WARNING: Context filling up — suggest delegation
@@ -821,85 +987,22 @@ class StandardGraph extends Graph {
                         `Injected delegation suggestion. ${remainingTokens} tokens remaining.`);
                 }
             }
-            // Check if structured output mode is enabled
+            // 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
+            // (see the deferred structured output block after attemptInvoke below).
+            const hasTools = (toolsForBinding?.length ?? 0) > 0;
             if (agentContext.isStructuredOutputMode &&
-                agentContext.structuredOutput) {
-                const schema = agentContext.getStructuredOutputSchema();
-                if (!schema) {
-                    throw new Error('Structured output schema is not configured');
-                }
+                agentContext.structuredOutput &&
+                !hasTools) {
                 try {
-                    // Use structured output invocation (non-streaming)
-                    // Get a fresh model WITHOUT tools bound - bindTools() returns RunnableBinding which lacks withStructuredOutput
-                    // Also disable thinking mode - Anthropic/Bedrock doesn't allow tool_choice with thinking enabled
-                    const structuredClientOptions = { ...agentContext.clientOptions };
-                    // CRITICAL: Disable streaming for structured output
-                    // Structured output uses model.invoke() with tool binding, not streaming
-                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                    structuredClientOptions.streaming = false;
-                    // Remove thinking configuration for Bedrock
-                    // Bedrock uses additionalModelRequestFields.thinking for extended thinking
-                    if (agentContext.provider === _enum.Providers.BEDROCK) {
-                        const bedrockOpts = structuredClientOptions;
-                        if (bedrockOpts.additionalModelRequestFields) {
-                            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                            const additionalFields = Object.assign({}, bedrockOpts.additionalModelRequestFields);
-                            // Remove thinking configuration
-                            delete additionalFields.thinking;
-                            // Remove budget tokens which is also related to thinking
-                            delete additionalFields.budgetTokens;
-                            bedrockOpts.additionalModelRequestFields = additionalFields;
-                        }
-                    }
-                    // Remove thinking configuration for Anthropic direct API
-                    if (agentContext.provider === _enum.Providers.ANTHROPIC) {
-                        const anthropicOpts = structuredClientOptions;
-                        if (anthropicOpts.thinking) {
-                            delete anthropicOpts.thinking;
-                        }
-                    }
-                    const structuredModel = this.getNewModel({
-                        provider: agentContext.provider,
-                        clientOptions: structuredClientOptions,
-                    });
-                    const { structuredResponse, rawMessage } = await this.attemptStructuredInvoke({
-                        currentModel: structuredModel,
+                    const structuredResult = await this.performStructuredOutput({
+                        agentContext,
                         finalMessages,
-                        schema,
-                        structuredOutputConfig: agentContext.structuredOutput,
-                        provider: agentContext.provider,
-                    }, config);
-                    // Emit structured output event
-                    await events.safeDispatchCustomEvent(_enum.GraphEvents.ON_STRUCTURED_OUTPUT, {
-                        structuredResponse,
-                        schema,
-                        raw: rawMessage,
-                    }, config);
-                    agentContext.currentUsage = rawMessage
-                        ? this.getUsageMetadata(rawMessage)
-                        : undefined;
+                        config,
+                    });
+                    agentContext.currentUsage = this.getUsageMetadata(structuredResult.messages?.[0]);
                     this.cleanupSignalListener();
-                    // CRITICAL: Create a clean message WITHOUT tool_calls for structured output
-                    // The rawMessage contains a tool_call for the structured output schema (e.g., "response"),
-                    // which would cause the graph router to send it to the tool node, failing with
-                    // "Tool 'response' not found". We need to return a clean AI message that ends the graph.
-                    let cleanMessage;
-                    if (rawMessage) {
-                        // Create a new AIMessageChunk with the structured response as JSON content
-                        // but WITHOUT the tool_calls that would trigger tool execution
-                        cleanMessage = new messages.AIMessageChunk({
-                            content: JSON.stringify(structuredResponse, null, 2),
-                            id: rawMessage.id,
-                            response_metadata: rawMessage.response_metadata,
-                            usage_metadata: rawMessage.usage_metadata,
-                            // Explicitly exclude tool_calls to prevent routing to tool node
-                        });
-                    }
-                    // Return the clean message (no tool_calls) so the graph ends here
-                    return {
-                        messages: cleanMessage ? [cleanMessage] : [],
-                        structuredResponse,
-                    };
+                    return structuredResult;
                 }
                 catch (structuredError) {
                     console.error('[Graph] Structured output failed:', structuredError);
@@ -1075,6 +1178,57 @@ If I seem to be missing something we discussed earlier, just give me a quick rem
             }
             agentContext.currentUsage = this.getUsageMetadata(result.messages?.[0]);
             this.cleanupSignalListener();
+            // DEFERRED STRUCTURED OUTPUT: When the agent has tools AND structured output configured,
+            // we let the agent use tools normally via attemptInvoke(). Once the agent's response
+            // has NO tool_calls (it's done with tools), we produce the final structured JSON response.
+            if (agentContext.isStructuredOutputMode &&
+                agentContext.structuredOutput &&
+                result) {
+                const lastMessage = result.messages?.[0];
+                const resultHasToolCalls = lastMessage &&
+                    'tool_calls' in lastMessage &&
+                    (lastMessage.tool_calls?.length ?? 0) > 0;
+                if (!resultHasToolCalls) {
+                    try {
+                        // Build messages for structured output: include the full conversation
+                        // plus the agent's text response from attemptInvoke, so the structured
+                        // output model has full context (tool results + agent reasoning).
+                        const messagesForStructured = [...finalMessages];
+                        if (lastMessage) {
+                            messagesForStructured.push(lastMessage);
+                        }
+                        const structuredResult = await this.performStructuredOutput({
+                            agentContext,
+                            finalMessages: messagesForStructured,
+                            config,
+                        });
+                        // Accumulate token usage from both API calls
+                        const structuredUsage = this.getUsageMetadata(structuredResult.messages?.[0]);
+                        if (structuredUsage && agentContext.currentUsage) {
+                            agentContext.currentUsage = {
+                                input_tokens: (agentContext.currentUsage.input_tokens ?? 0) +
+                                    (structuredUsage.input_tokens ?? 0),
+                                output_tokens: (agentContext.currentUsage.output_tokens ?? 0) +
+                                    (structuredUsage.output_tokens ?? 0),
+                                total_tokens: (agentContext.currentUsage.total_tokens ?? 0) +
+                                    (structuredUsage.total_tokens ?? 0),
+                            };
+                        }
+                        else if (structuredUsage) {
+                            agentContext.currentUsage = structuredUsage;
+                        }
+                        return structuredResult;
+                    }
+                    catch (structuredError) {
+                        // Graceful fallback: the agent completed its work with tools,
+                        // but we couldn't format the output as structured JSON.
+                        // Return the unstructured text response from attemptInvoke.
+                        console.error('[Graph] Deferred structured output failed after successful tool use:', structuredError);
+                        console.warn('[Graph] Falling back to unstructured response from tool-use phase');
+                        return result;
+                    }
+                }
+            }
             return result;
         };
     }