@illuma-ai/agents 1.4.0-alpha.6 → 1.5.1

package/dist/esm/graphs/Graph.mjs

@@ -28,11 +28,13 @@ import { ToolDiscoveryCache } from '../utils/toolDiscoveryCache.mjs';
 import { createPruneCalibration, applyCalibration, updatePruneCalibration } from '../utils/pruneCalibration.mjs';
 import { buildFileManifestBlock } from '../utils/fileManifest.mjs';
 import { isLikelyContextOverflowError } from '../utils/errors.mjs';
-import 'axios';
-import 'https-proxy-agent';
-import '../utils/credentials.mjs';
 import { getChatModelClass, manualToolStreamProviders } from '../llm/providers.mjs';
 import { ToolNode, toolsCondition } from '../tools/ToolNode.mjs';
+import { tool } from '@langchain/core/tools';
+import { resolveSubagentConfigs, SubagentExecutor } from '../tools/subagent/SubagentExecutor.mjs';
+import { buildSubagentToolParams } from '../tools/SubagentTool.mjs';
+import { ToolOutputReferenceRegistry, annotateMessagesForLLM } from '../tools/toolOutputReferences.mjs';
+import { executeHooks } from '../hooks/executeHooks.mjs';
 import { ChatOpenAI, AzureChatOpenAI } from '../llm/openai/index.mjs';
 import { safeDispatchCustomEvent } from '../utils/events.mjs';
 import { mwarn, mlog } from '../utils/logging.mjs';
@@ -61,6 +63,65 @@ class Graph {
     /** Set of invoked tool call IDs from non-message run steps completed mid-run, if any */
     invokedToolIds;
     handlerRegistry;
+    /** Optional hook registry threaded down from Run; consumed by ToolNode for tool-lifecycle hooks. */
+    hookRegistry;
+    /**
+     * Optional tool-output reference registry threaded down from Run
+     * (PR #114). When set, every ToolNode built by this graph
+     * stores successful outputs here and resolves `{{tool<i>turn<n>}}`
+     * placeholders in args before invoking the tool.
+     *
+     * @deprecated Prefer `toolOutputReferences` config + the lazy
+     * `getOrCreateToolOutputRegistry()` accessor — keeps the registry
+     * lifecycle explicit (cleared in `clearHeavyState()`). Existing
+     * direct-set callers still work for backwards compat.
+     */
+    toolOutputRegistry;
+    /**
+     * Run-scoped tool output reference configuration (PR #117).
+     * When `enabled` is true, the graph lazily allocates a single
+     * `ToolOutputReferenceRegistry` on first `getOrCreateToolOutputRegistry()`
+     * call and shares it with every ToolNode the graph compiles, so
+     * cross-agent `{{tool<i>turn<n>}}` substitutions resolve.
+     */
+    toolOutputReferences;
+    /**
+     * Lazy single-instance registry for the run. Constructed on first
+     * `getOrCreateToolOutputRegistry()` call when
+     * `toolOutputReferences.enabled` is true. Cleared (and recreated on
+     * next access) by `clearHeavyState()`.
+     */
+    _toolOutputRegistry;
+    /**
+     * Returns the shared `ToolOutputReferenceRegistry` for this run,
+     * constructing it on first access. Returns `undefined` when the
+     * feature is disabled. All ToolNodes compiled from this graph share
+     * this single instance so cross-agent `{{...}}` references resolve.
+     *
+     * @internal Public so `attemptInvoke` can read it through the typed
+     * `InvokeContext` and project ToolMessages into LLM-facing annotated
+     * copies right before each provider call (see `annotateMessagesForLLM`).
+     * Host code should not call this directly — registry mutations outside
+     * the ToolNode lifecycle break the partitioning, eviction, and
+     * turn-counter invariants.
+     */
+    getOrCreateToolOutputRegistry() {
+        // Direct-set instance (legacy path) takes precedence so existing
+        // Run plumbing keeps working.
+        if (this.toolOutputRegistry != null) {
+            return this.toolOutputRegistry;
+        }
+        if (this.toolOutputReferences?.enabled !== true) {
+            return undefined;
+        }
+        if (this._toolOutputRegistry == null) {
+            this._toolOutputRegistry = new ToolOutputReferenceRegistry({
+                maxOutputSize: this.toolOutputReferences.maxOutputSize,
+                maxTotalSize: this.toolOutputReferences.maxTotalSize,
+            });
+        }
+        return this._toolOutputRegistry;
+    }
     /**
      * Tool session contexts for automatic state persistence across tool invocations.
      * Keyed by tool name (e.g., Constants.EXECUTE_CODE).
@@ -624,6 +685,8 @@ class StandardGraph extends Graph {
                 streamingToolCallBuffer: this.streamingToolCallBuffer,
                 errorHandler: (data, metadata) => StandardGraph.handleToolCallErrorStatic(this, data, metadata),
                 toolApprovalConfig,
+                hookRegistry: this.hookRegistry,
+                toolOutputRegistry: this.toolOutputRegistry,
             });
         }
         const graphTools = agentContext?.graphTools;
@@ -670,6 +733,8 @@ class StandardGraph extends Graph {
             sessions: this.sessions,
             directToolNames,
             toolApprovalConfig,
+            hookRegistry: this.hookRegistry,
+            toolOutputRegistry: this.toolOutputRegistry,
         });
     }
     initializeModel({ provider, tools, clientOptions, }) {
@@ -730,6 +795,17 @@ class StandardGraph extends Graph {
         if (!model) {
             throw new Error('No model found');
         }
+        /**
+         * Lazy tool-output reference annotation (PR #117). Right
+         * before the message array hits the provider, walk it and apply
+         * `[ref: tool<i>turn<n>]` prefixes / `_ref` JSON fields to a
+         * transient copy. The persisted ToolMessages stay clean — only what
+         * the LLM sees gets the annotation, and only when the registry
+         * actually has the referenced output. No-op when the registry is
+         * absent (the common case until a host opts in).
+         */
+        const annotatedRunId = config?.configurable?.run_id;
+        finalMessages = annotateMessagesForLLM(finalMessages, this.toolOutputRegistry, annotatedRunId);
         if (model.stream) {
             /**
              * Process all model output through a local ChatModelStreamHandler in the
@@ -1147,12 +1223,53 @@ class StandardGraph extends Graph {
                     if (oldMessages.length > 0) {
                         this._summaryInFlight = true;
                         mlog(`[Graph:ProactiveSummary] Context at ${utilization.toFixed(1)}% (threshold ${threshold}%) — summarizing ${oldMessages.length} older msgs in background`);
-                        agentContext
-                            .summarizeCallback(oldMessages)
+                        /**
+                         * Fire PreCompact (#103) before the LLM call. Observational —
+                         * hosts may use the input to schedule auxiliary work, but a
+                         * deny/ask decision does NOT block compaction here because
+                         * the summarizer runs in the background and a refusal
+                         * has nowhere to go: pruning still needs to happen at 100%
+                         * regardless. Errors are swallowed so a hook bug cannot
+                         * masquerade as a context-overflow failure.
+                         */
+                        const sessionId = this.runId ?? '';
+                        const preCompactPromise = this.hookRegistry?.hasHookFor('PreCompact', sessionId) === true
+                            ? executeHooks({
+                                registry: this.hookRegistry,
+                                input: {
+                                    hook_event_name: 'PreCompact',
+                                    runId: sessionId,
+                                    agentId: agentContext.agentId,
+                                    messagesBeforeCount: oldMessages.length,
+                                    trigger: agentContext.summarizationConfig?.trigger?.type ??
+                                        agentContext.summarizationConfig?.triggerType ??
+                                        'default',
+                                },
+                                sessionId,
+                            }).catch(() => undefined)
+                            : Promise.resolve(undefined);
+                        preCompactPromise
+                            .then(() => agentContext.summarizeCallback(oldMessages))
                             .then((updated) => {
                             if (updated != null && updated !== '') {
                                 this._cachedRunSummary = updated;
                                 mlog(`[Graph:ProactiveSummary] Background summary ready (len=${updated.length})`);
+                                if (this.hookRegistry?.hasHookFor('PostCompact', sessionId) ===
+                                    true) {
+                                    void executeHooks({
+                                        registry: this.hookRegistry,
+                                        input: {
+                                            hook_event_name: 'PostCompact',
+                                            runId: sessionId,
+                                            agentId: agentContext.agentId,
+                                            summary: updated,
+                                            messagesAfterCount: 0,
+                                        },
+                                        sessionId,
+                                    }).catch(() => {
+                                        /* PostCompact is observational — swallow errors */
+                                    });
+                                }
                             }
                         })
                             .catch((err) => {
@@ -1876,6 +1993,66 @@ If I seem to be missing something we discussed earlier, just give me a quick rem
         if (!agentContext) {
             throw new Error(`Agent context not found for agentId: ${agentId}`);
         }
+        /**
+         * Subagent injection (Tier 5): when the agent has SubagentConfig
+         * entries and depth budget remaining, inject a `subagent` DynamicStructuredTool
+         * into graphTools. The tool's executor receives this graph's hookRegistry and
+         * a lazy handler-registry getter (Run wires handlerRegistry AFTER createWorkflow,
+         * so direct capture would be undefined at construction time).
+         */
+        const effectiveSubagentDepth = agentContext.maxSubagentDepth ?? 1;
+        if (agentContext.subagentConfigs != null &&
+            agentContext.subagentConfigs.length > 0 &&
+            effectiveSubagentDepth > 0) {
+            const resolvedConfigs = resolveSubagentConfigs(agentContext.subagentConfigs, agentContext);
+            if (resolvedConfigs.length > 0) {
+                const getParentHandlerRegistry = () => this.handlerRegistry;
+                const executor = new SubagentExecutor({
+                    configs: new Map(resolvedConfigs.map((c) => [c.type, c])),
+                    parentSignal: this.signal,
+                    hookRegistry: this.hookRegistry,
+                    parentHandlerRegistry: getParentHandlerRegistry,
+                    parentRunId: this.runId ?? '',
+                    parentAgentId: agentContext.agentId,
+                    tokenCounter: agentContext.tokenCounter,
+                    maxDepth: effectiveSubagentDepth,
+                    createChildGraph: (input) => new StandardGraph(input),
+                });
+                const subagentTool = tool(async (rawInput, config) => {
+                    const input = rawInput;
+                    const description = typeof input.description === 'string' &&
+                        input.description.trim().length > 0
+                        ? input.description
+                        : 'No task description provided';
+                    const subagentType = typeof input.subagent_type === 'string' ? input.subagent_type : '';
+                    const threadId = config.configurable?.thread_id;
+                    const toolCall = config.toolCall;
+                    const parentToolCallId = typeof toolCall?.id === 'string' ? toolCall.id : undefined;
+                    const result = await executor.execute({
+                        description,
+                        subagentType,
+                        threadId,
+                        parentToolCallId,
+                    });
+                    return result.content;
+                }, buildSubagentToolParams(resolvedConfigs));
+                if (!agentContext.graphTools) {
+                    agentContext.graphTools = [];
+                }
+                agentContext.graphTools.push(subagentTool);
+                if (agentContext.tokenCounter) {
+                    const { tokenCounter, baseIndexTokenCountMap } = agentContext;
+                    agentContext.tokenCalculationPromise = agentContext
+                        .calculateInstructionTokens(tokenCounter)
+                        .then(() => {
+                        agentContext.updateTokenMapWithInstructions(baseIndexTokenCountMap);
+                    })
+                        .catch((err) => {
+                        console.error('Error recalculating instruction tokens after subagent tool injection:', err);
+                    });
+                }
+            }
+        }
         const agentNode = `${AGENT}${agentId}`;
         const toolNode = `${TOOLS}${agentId}`;
         const routeMessage = (state, config) => {