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

package/src/common/enum.ts

@@ -9,6 +9,8 @@ export enum GraphEvents {
 
   /** [Custom] Agent update event in multi-agent graph/workflow */
   ON_AGENT_UPDATE = 'on_agent_update',
+  /** [Custom] Subagent lifecycle event (start, run_step, message_delta, stop, error) */
+  ON_SUBAGENT_UPDATE = 'on_subagent_update',
   /** [Custom] Delta event for run steps (message creation and tool calls) */
   ON_RUN_STEP = 'on_run_step',
   /** [Custom] Delta event for run steps (tool calls) */
@@ -100,12 +102,22 @@ export enum Providers {
 }
 
 export enum EdgeType {
-  /** True agent handoff — parent calls child agent inline, gets result back, continues orchestrating */
+  /**
+   * handoff: one-way routing where the parent agent exits
+   * via a `lc_transfer_to_<destination>` tool call, the child takes over,
+   * and the child responds directly to the user. Replaces what used to be
+   * called "TRANSFER" in older versions; the parent-calls-child
+   * supervisor pattern (formerly `EdgeType.HANDOFF`) is gone — use the
+   * Subagent primitive (Tier 5) for deep delegation instead.
+   */
   HANDOFF = 'handoff',
-  /** One-way transfer — parent exits, child takes over and responds directly to user */
-  TRANSFER = 'transfer',
-  /** Fixed graph edges for automatic sequential/parallel transitions */
-  SEQUENCE = 'sequence',
+  /**
+   * Fixed graph edges for automatic transitions. Standard naming.
+   * Downstream consumers may layer additional wiring on top of this edge
+   * type: fan-in with prompt + {results}, parallel groups, approval-gate
+   * node insertion, and the `excludeResults` agentMessages channel.
+   */
+  DIRECT = 'direct',
 }
 
 export enum GraphNodeKeys {
@@ -183,17 +195,30 @@ export enum Callback {
 export enum Constants {
   OFFICIAL_CODE_BASEURL = 'https://api.illuma.ai/v1',
   EXECUTE_CODE = 'execute_code',
+  /** Tool name for the bash execution primitive (Tier 3). */
+  BASH_TOOL = 'execute_bash',
+  /** Tool name for the bash programmatic-tool-calling variant (Tier 3). */
+  BASH_PROGRAMMATIC_TOOL_CALLING = 'run_tools_with_bash',
+  /** Tool name for the read-file primitive (Tier 3). */
+  READ_FILE = 'read_file',
+  /** Tool name for the SkillTool primitive (Tier 2). */
+  SKILL_TOOL = 'skill',
+  /** Tool name for the Subagent primitive (Tier 5). */
+  SUBAGENT = 'subagent',
   TOOL_SEARCH = 'tool_search',
   PROGRAMMATIC_TOOL_CALLING = 'run_tools_with_code',
   WEB_SEARCH = 'web_search',
   CONTENT_AND_ARTIFACT = 'content_and_artifact',
+  /** Prefix for handoff tool names (parent-exits routing): lc_transfer_to_{agentId}. */
   LC_TRANSFER_TO_ = 'lc_transfer_to_',
-  /** Prefix for handoff tool names: lc_handoff_to_{agentId} */
-  LC_HANDOFF_TO_ = 'lc_handoff_to_',
   /** Tool name for the AskUser structured question tool */
   ASK_USER = 'ask_user',
   /** Delimiter for MCP tools: toolName_mcp_serverName */
   MCP_DELIMITER = '_mcp_',
+  /** Prefix for Anthropic-hosted server tool ids (web_search, code_execution).
+   *  These are issued by Anthropic, not by us, and should be ignored by
+   *  orphan-repair sweeps that don't have ground truth for them. */
+  ANTHROPIC_SERVER_TOOL_PREFIX = 'srvtoolu_',
 }
 
 export enum TitleMethod {
@@ -242,8 +267,14 @@ export enum MessageTypes {
   REMOVE = 'remove',
 }
 
-/** Default max characters for handoff results returned to parent (~8192 tokens at ~4 chars/token) */
-export const DEFAULT_HANDOFF_MAX_RESULT_CHARS = 32768;
-
-/** Default timeout for handoff sub-agent execution in milliseconds (5 minutes) */
-export const HANDOFF_TIMEOUT_MS = 300_000;
+/**
+ * Tool names that use the code execution environment (shared session, file
+ * tracking). Used by ToolNode to inject session context + file refs into
+ * `invokeParams` before tool execution. constant.
+ */
+export const CODE_EXECUTION_TOOLS: ReadonlySet<string> = new Set([
+  Constants.EXECUTE_CODE,
+  Constants.BASH_TOOL,
+  Constants.PROGRAMMATIC_TOOL_CALLING,
+  Constants.BASH_PROGRAMMATIC_TOOL_CALLING,
+]);

package/src/common/index.ts

@@ -1,5 +1,4 @@
 // src/common/index.ts
 export * from './enum';
 export * from './constants';
-export * from './spawnPath';
 export * from '../tools/approval/constants';

package/src/graphs/Graph.ts

@@ -77,6 +77,14 @@ import {
 } from '@/utils/contextAnalytics';
 import { getChatModelClass, manualToolStreamProviders } from '@/llm/providers';
 import { ToolNode as CustomToolNode, toolsCondition } from '@/tools/ToolNode';
+import { tool as makeStructuredTool } from '@langchain/core/tools';
+import { SubagentExecutor, resolveSubagentConfigs } from '@/tools/subagent';
+import { buildSubagentToolParams } from '@/tools/SubagentTool';
+import {
+  annotateMessagesForLLM,
+  ToolOutputReferenceRegistry as ToolOutputReferenceRegistryClass,
+} from '@/tools/toolOutputReferences';
+import { executeHooks } from '@/hooks';
 import { ChatOpenAI, AzureChatOpenAI } from '@/llm/openai';
 import { safeDispatchCustomEvent } from '@/utils/events';
 import { mlog, mwarn } from '@/utils/logging';
@@ -175,6 +183,68 @@ export abstract class Graph<
   /** Set of invoked tool call IDs from non-message run steps completed mid-run, if any */
   invokedToolIds?: Set<string>;
   handlerRegistry: HandlerRegistry | undefined;
+  /** Optional hook registry threaded down from Run; consumed by ToolNode for tool-lifecycle hooks. */
+  hookRegistry?: import('@/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?: import('@/tools/toolOutputReferences').ToolOutputReferenceRegistry;
+  /**
+   * 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?: import('@/types/tools').ToolOutputReferencesConfig;
+  /**
+   * 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()`.
+   */
+  private _toolOutputRegistry?: import('@/tools/toolOutputReferences').ToolOutputReferenceRegistry;
+
+  /**
+   * 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.
+   */
+  public getOrCreateToolOutputRegistry():
+    | import('@/tools/toolOutputReferences').ToolOutputReferenceRegistry
+    | undefined {
+    // 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 ToolOutputReferenceRegistryClass({
+        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).
@@ -875,6 +945,8 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         errorHandler: (data, metadata) =>
           StandardGraph.handleToolCallErrorStatic(this, data, metadata),
         toolApprovalConfig,
+        hookRegistry: this.hookRegistry,
+        toolOutputRegistry: this.toolOutputRegistry,
       });
     }
 
@@ -927,6 +999,8 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       sessions: this.sessions,
       directToolNames,
       toolApprovalConfig,
+      hookRegistry: this.hookRegistry,
+      toolOutputRegistry: this.toolOutputRegistry,
     });
   }
 
@@ -1034,6 +1108,24 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       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 as { run_id?: string } | undefined
+    )?.run_id;
+    finalMessages = annotateMessagesForLLM(
+      finalMessages,
+      this.toolOutputRegistry,
+      annotatedRunId
+    );
+
     if (model.stream) {
       /**
        * Process all model output through a local ChatModelStreamHandler in the
@@ -1624,14 +1716,60 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
               `[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) => {
@@ -2577,6 +2715,88 @@ If I seem to be missing something we discussed earlier, just give me a quick rem
       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 = (): HandlerRegistry | undefined =>
+          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): StandardGraph =>
+            new StandardGraph(input as t.StandardGraphInput),
+        });
+
+        const subagentTool = makeStructuredTool(async (rawInput, config) => {
+          const input = rawInput as {
+            description?: string;
+            subagent_type?: string;
+          };
+          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 as string | undefined;
+          const toolCall = (config as { toolCall?: { id?: string } }).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 as t.GenericTool[]).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}` as const;
     const toolNode = `${TOOLS}${agentId}` as const;