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

package/src/run.ts

@@ -22,9 +22,47 @@ import { GraphEvents, Callback, TitleMethod } from '@/common';
 import { MultiAgentGraph } from '@/graphs/MultiAgentGraph';
 import { StandardGraph } from '@/graphs/Graph';
 import { HandlerRegistry } from '@/events';
+import { executeHooks } from '@/hooks';
+import type { HookRegistry } from '@/hooks';
+import { ToolOutputReferenceRegistry } from '@/tools/toolOutputReferences';
 import { isOpenAILike } from '@/utils/llm';
 import { isPresent } from '@/utils/misc';
 
+function findLastMessageOfType(
+  messages: BaseMessage[],
+  type: string
+): BaseMessage | undefined {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i].getType() === type) {
+      return messages[i];
+    }
+  }
+  return undefined;
+}
+
+function extractPromptText(message: BaseMessage): string {
+  const content = message.content;
+  if (typeof content === 'string') {
+    return content;
+  }
+  if (!Array.isArray(content)) {
+    return String(content);
+  }
+  const parts: string[] = [];
+  for (const block of content) {
+    if (
+      typeof block === 'object' &&
+      'type' in block &&
+      block.type === 'text' &&
+      'text' in block &&
+      typeof block.text === 'string'
+    ) {
+      parts.push(block.text);
+    }
+  }
+  return parts.join('\n');
+}
+
 export const defaultOmitOptions = new Set([
   'stream',
   'thinking',
@@ -42,6 +80,8 @@ export class Run<_T extends t.BaseGraphState> {
   id: string;
   private tokenCounter?: t.TokenCounter;
   private handlerRegistry?: HandlerRegistry;
+  private hookRegistry?: HookRegistry;
+  private toolOutputRegistry?: ToolOutputReferenceRegistry;
   private indexTokenCountMap?: Record<string, number>;
   graphRunnable?: t.CompiledStateWorkflow;
   Graph: StandardGraph | MultiAgentGraph | undefined;
@@ -70,6 +110,26 @@ export class Run<_T extends t.BaseGraphState> {
     }
 
     this.handlerRegistry = handlerRegistry;
+    /**
+     * Capture hookRegistry BEFORE graph compilation so it propagates into
+     * any ToolNode the graph builds during createWorkflow(). createLegacyGraph
+     * threads `this.hookRegistry` onto the graph instance via Graph.hookRegistry
+     * before compile, which Graph.createToolNodeForAgent reads when constructing
+     * each ToolNode.
+     */
+    this.hookRegistry = config.hooks;
+    /**
+     * Same lifecycle for the tool-output reference registry: build it
+     * here (when enabled) and let createLegacyGraph / createMultiAgentGraph
+     * thread it onto the graph before compile so every ToolNode sees the
+     * same instance.
+     */
+    if (config.toolOutputReferences?.enabled === true) {
+      this.toolOutputRegistry = new ToolOutputReferenceRegistry({
+        maxOutputSize: config.toolOutputReferences.maxOutputSize,
+        maxTotalSize: config.toolOutputReferences.maxTotalSize,
+      });
+    }
 
     if (!config.graphConfig) {
       throw new Error('Graph config not provided');
@@ -138,6 +198,12 @@ export class Run<_T extends t.BaseGraphState> {
     });
     /** Propagate compile options from graph config */
     standardGraph.compileOptions = config.compileOptions;
+    if (this.hookRegistry) {
+      standardGraph.hookRegistry = this.hookRegistry;
+    }
+    if (this.toolOutputRegistry) {
+      standardGraph.toolOutputRegistry = this.toolOutputRegistry;
+    }
     this.Graph = standardGraph;
     return standardGraph.createWorkflow();
   }
@@ -160,6 +226,12 @@ export class Run<_T extends t.BaseGraphState> {
       multiAgentGraph.compileOptions = compileOptions;
     }
 
+    if (this.hookRegistry) {
+      multiAgentGraph.hookRegistry = this.hookRegistry;
+    }
+    if (this.toolOutputRegistry) {
+      multiAgentGraph.toolOutputRegistry = this.toolOutputRegistry;
+    }
     this.Graph = multiAgentGraph;
     return multiAgentGraph.createWorkflow();
   }
@@ -216,7 +288,11 @@ export class Run<_T extends t.BaseGraphState> {
    */
   getLastActiveAgentId(): string | undefined {
     if (this.Graph && this.Graph instanceof MultiAgentGraph) {
-      return this.Graph.getLastActiveAgentId();
+      // Last entry in the run's participating agent set is the most-recent
+      // active agent. Derived from contentData step trail rather than
+      // a tracked field — same observation surface, fewer state slots.
+      const ids = this.Graph.getActiveAgentIds();
+      return ids.length > 0 ? ids[ids.length - 1] : undefined;
     }
     return undefined;
   }
@@ -349,6 +425,46 @@ export class Run<_T extends t.BaseGraphState> {
       run_id: this.id,
     });
 
+    const threadId = config.configurable.thread_id as string | undefined;
+
+    if (this.hookRegistry != null) {
+      await executeHooks({
+        registry: this.hookRegistry,
+        input: {
+          hook_event_name: 'RunStart',
+          runId: this.id,
+          threadId,
+          agentId: this.Graph.defaultAgentId,
+          messages: (inputs as { messages?: BaseMessage[] }).messages ?? [],
+        },
+        sessionId: this.id,
+      });
+
+      const messages = (inputs as { messages?: BaseMessage[] }).messages ?? [];
+      const lastHuman = findLastMessageOfType(messages, 'human');
+      if (lastHuman != null) {
+        const promptResult = await executeHooks({
+          registry: this.hookRegistry,
+          input: {
+            hook_event_name: 'UserPromptSubmit',
+            runId: this.id,
+            threadId,
+            agentId: this.Graph.defaultAgentId,
+            prompt: extractPromptText(lastHuman),
+          },
+          sessionId: this.id,
+        });
+        if (
+          promptResult.decision === 'deny' ||
+          promptResult.decision === 'ask'
+        ) {
+          this.hookRegistry.clearSession(this.id);
+          config.callbacks = undefined;
+          return undefined;
+        }
+      }
+    }
+
     const stream = this.graphRunnable.streamEvents(inputs, config, {
       raiseError: true,
       /**
@@ -378,13 +494,51 @@ export class Run<_T extends t.BaseGraphState> {
           await handler.handle(eventName, data, metadata, this.Graph);
         }
       }
+
+      if (this.hookRegistry?.hasHookFor('Stop', this.id) === true) {
+        const inputMessages =
+          (inputs as { messages?: BaseMessage[] }).messages ?? [];
+        await executeHooks({
+          registry: this.hookRegistry,
+          input: {
+            hook_event_name: 'Stop',
+            runId: this.id,
+            threadId,
+            agentId: this.Graph.defaultAgentId,
+            messages: this.Graph.getRunMessages() ?? inputMessages,
+            stopHookActive: false,
+          },
+          sessionId: this.id,
+        }).catch(() => {
+          /* Stop hook errors must not masquerade as stream failures */
+        });
+      }
     } catch (e) {
       // GraphInterrupt is expected when interrupt() fires (HITL approval flow).
       // Exit gracefully so the host can check hasInterrupts() and resume.
       if (isGraphInterrupt(e)) {
         return undefined;
       }
+      if (this.hookRegistry?.hasHookFor('StopFailure', this.id) === true) {
+        const runMessages = this.Graph.getRunMessages() ?? [];
+        await executeHooks({
+          registry: this.hookRegistry,
+          input: {
+            hook_event_name: 'StopFailure',
+            runId: this.id,
+            threadId,
+            agentId: this.Graph.defaultAgentId,
+            error: e instanceof Error ? e.message : String(e),
+            lastAssistantMessage: findLastMessageOfType(runMessages, 'ai'),
+          },
+          sessionId: this.id,
+        }).catch(() => {
+          /* swallow hook errors — original error must propagate */
+        });
+      }
       throw e;
+    } finally {
+      this.hookRegistry?.clearSession(this.id);
     }
 
     /**

package/src/scripts/multi-agent-chain.ts

@@ -7,7 +7,7 @@ import {
   getBufferString,
 } from '@langchain/core/messages';
 import { Run } from '@/run';
-import { Providers, GraphEvents } from '@/common';
+import { Providers, GraphEvents, EdgeType } from '@/common';
 import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
 import { ToolEndHandler, ModelEndHandler } from '@/events';
 import type * as t from '@/types';
@@ -28,7 +28,7 @@ function createSequentialChainEdges(agentIds: string[]): t.GraphEdge[] {
     edges.push({
       from: fromAgent,
       to: toAgent,
-      edgeType: 'sequence',
+      edgeType: EdgeType.DIRECT,
       // Use a prompt function to create the buffer string from all previous results
       prompt: (messages: BaseMessage[], startIndex: number) => {
         // Get only the messages from this run (after startIndex)

package/src/scripts/multi-agent-document-review-chain.ts

@@ -7,7 +7,7 @@ import {
   getBufferString,
 } from '@langchain/core/messages';
 import { Run } from '@/run';
-import { Providers, GraphEvents } from '@/common';
+import { Providers, GraphEvents, EdgeType } from '@/common';
 import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
 import { ToolEndHandler, ModelEndHandler } from '@/events';
 import type * as t from '@/types';
@@ -22,7 +22,7 @@ function createDocumentReviewChain(agentIds: string[]): t.GraphEdge[] {
     edges.push({
       from: agentIds[i],
       to: agentIds[i + 1],
-      edgeType: 'sequence',
+      edgeType: EdgeType.DIRECT,
       prompt: (messages: BaseMessage[], startIndex: number) => {
         const runMessages = messages.slice(startIndex);
         const bufferString = getBufferString(runMessages);

package/src/scripts/multi-agent-hybrid-flow.ts

@@ -3,7 +3,7 @@ config();
 
 import { HumanMessage, BaseMessage } from '@langchain/core/messages';
 import { Run } from '@/run';
-import { Providers, GraphEvents, Constants } from '@/common';
+import { Providers, GraphEvents, EdgeType, Constants } from '@/common';
 import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
 import { ToolEndHandler, ModelEndHandler } from '@/events';
 import type * as t from '@/types';
@@ -108,7 +108,7 @@ async function testHybridMultiAgent() {
     {
       from: 'primary_agent',
       to: 'standalone_agent',
-      edgeType: 'transfer',
+      edgeType: EdgeType.HANDOFF,
       description: 'Transfer to standalone specialist for complex requests',
       prompt: 'Specific instructions for the specialist',
     },
@@ -116,14 +116,14 @@ async function testHybridMultiAgent() {
     {
       from: 'primary_agent',
       to: 'agent_b',
-      edgeType: 'sequence',
+      edgeType: EdgeType.DIRECT,
       description: 'Continue to Agent B only if no handoff occurs',
     },
     // Direct edge: agent_b automatically continues to agent_c
     {
       from: 'agent_b',
       to: 'agent_c',
-      edgeType: 'sequence',
+      edgeType: EdgeType.DIRECT,
       description: 'Automatic progression from B to C',
     },
   ];

package/src/scripts/multi-agent-parallel.ts

@@ -5,7 +5,7 @@ import { HumanMessage, BaseMessage } from '@langchain/core/messages';
 import type * as t from '@/types';
 import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
 import { ToolEndHandler, ModelEndHandler } from '@/events';
-import { Providers, GraphEvents } from '@/common';
+import { Providers, GraphEvents, EdgeType } from '@/common';
 import { sleep } from '@/utils/run';
 import { Run } from '@/run';
 
@@ -160,13 +160,13 @@ async function testParallelMultiAgent() {
       from: 'researcher',
       to: ['analyst1', 'analyst2', 'analyst3'], // Fan-out to multiple analysts
       description: 'Distribute research to specialist analysts',
-      edgeType: 'sequence', // Explicitly set as direct for automatic transition (enables parallel execution)
+      edgeType: EdgeType.DIRECT, // Explicitly set as direct for automatic transition (enables parallel execution)
     },
     {
       from: ['analyst1', 'analyst2', 'analyst3'], // Fan-in from multiple sources
       to: 'summarizer',
       description: 'Aggregate analysis results',
-      edgeType: 'sequence', // Fan-in is also direct
+      edgeType: EdgeType.DIRECT, // Fan-in is also direct
       // Add prompt when all analysts have provided input
       // prompt: (messages, runStartIndex) => {
       //   // Check if we have analysis content from all three analysts

package/src/scripts/multi-agent-sequence.ts

@@ -3,7 +3,7 @@ config();
 
 import { HumanMessage, BaseMessage } from '@langchain/core/messages';
 import { Run } from '@/run';
-import { Providers, GraphEvents } from '@/common';
+import { Providers, GraphEvents, EdgeType } from '@/common';
 import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
 import { ToolEndHandler, ModelEndHandler } from '@/events';
 import type * as t from '@/types';
@@ -82,13 +82,13 @@ async function testSequentialMultiAgent() {
     {
       from: 'agent_a',
       to: 'agent_b',
-      edgeType: 'sequence', // This creates direct edges without tools
+      edgeType: EdgeType.DIRECT, // This creates direct edges without tools
       description: 'Automatic transition from A to B',
     },
     {
       from: 'agent_b',
       to: 'agent_c',
-      edgeType: 'sequence', // This creates direct edges without tools
+      edgeType: EdgeType.DIRECT, // This creates direct edges without tools
       description: 'Automatic transition from B to C',
     },
   ];

package/src/scripts/multi-agent-subagent.ts

@@ -0,0 +1,246 @@
+import { config } from 'dotenv';
+config();
+
+import { HumanMessage } from '@langchain/core/messages';
+import type { BaseMessage } from '@langchain/core/messages';
+import type * as t from '@/types';
+import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
+import { ToolEndHandler, ModelEndHandler } from '@/events';
+import { Providers, GraphEvents, Constants } from '@/common';
+import { Run } from '@/run';
+
+/**
+ * Manual verification script for the subagent primitive.
+ *
+ * Configures a supervisor agent with two subagent types (researcher, coder),
+ * sends a query, and confirms:
+ * 1. The parent agent delegates to a subagent via the `subagent` tool
+ * 2. The child executes with isolated context (fresh message history)
+ * 3. Only the filtered text result returns to the parent
+ * 4. The parent incorporates the result and responds
+ *
+ * Usage:
+ *   OPENAI_API_KEY=... npx ts-node -r tsconfig-paths/register src/scripts/multi-agent-subagent.ts
+ *
+ * Or with Anthropic:
+ *   ANTHROPIC_API_KEY=... npx ts-node -r tsconfig-paths/register src/scripts/multi-agent-subagent.ts --provider anthropic
+ */
+
+const useAnthropic =
+  process.argv.includes('--provider') &&
+  process.argv[process.argv.indexOf('--provider') + 1] === 'anthropic';
+
+const provider = useAnthropic ? Providers.ANTHROPIC : Providers.OPENAI;
+const apiKey = useAnthropic
+  ? process.env.ANTHROPIC_API_KEY
+  : process.env.OPENAI_API_KEY;
+const modelName = useAnthropic ? 'claude-sonnet-4-20250514' : 'gpt-5.4';
+
+if (!apiKey) {
+  console.error(
+    `Missing ${useAnthropic ? 'ANTHROPIC_API_KEY' : 'OPENAI_API_KEY'} environment variable`
+  );
+  process.exit(1);
+}
+
+async function testSubagentPrimitive() {
+  console.log('=== Subagent Primitive Manual Verification ===\n');
+  console.log(`Provider: ${provider}`);
+  console.log(`Model: ${modelName}\n`);
+
+  const { aggregateContent } = createContentAggregator();
+
+  const parentAgent: t.AgentInputs = {
+    agentId: 'supervisor',
+    provider,
+    clientOptions: { modelName, apiKey },
+    instructions: `You are a supervisor agent. You have access to specialized subagents.
+
+When the user asks a research question, delegate it to the "researcher" subagent.
+When the user asks for code, delegate it to the "coder" subagent.
+
+After receiving the subagent's result, synthesize it into a clear final answer for the user.
+Always use a subagent for research or coding tasks — do not answer directly.`,
+    maxContextTokens: 16000,
+    subagentConfigs: [
+      {
+        type: 'researcher',
+        name: 'Research Specialist',
+        description:
+          'Researches topics and provides detailed summaries with sources.',
+        agentInputs: {
+          agentId: 'researcher',
+          provider,
+          clientOptions: { modelName, apiKey },
+          instructions: `You are a research specialist working in an isolated context.
+You receive a single task description and must answer it thoroughly.
+Be concise but comprehensive. Include key facts and details.`,
+          maxContextTokens: 8000,
+        },
+      },
+      {
+        type: 'coder',
+        name: 'Coding Specialist',
+        description:
+          'Writes, reviews, and explains code in any programming language.',
+        agentInputs: {
+          agentId: 'coder',
+          provider,
+          clientOptions: { modelName, apiKey },
+          instructions: `You are a coding specialist working in an isolated context.
+You receive a single task description and must provide working code.
+Include brief explanations. Use clean, idiomatic code.`,
+          maxContextTokens: 8000,
+        },
+      },
+    ],
+  };
+
+  const customHandlers: Record<string, t.EventHandler> = {
+    [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler(),
+    [GraphEvents.TOOL_END]: new ToolEndHandler(),
+    [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),
+    [GraphEvents.ON_RUN_STEP_COMPLETED]: {
+      handle: (event: string, data: t.StreamEventData): void => {
+        aggregateContent({
+          event: event as GraphEvents,
+          data: data as t.RunStep,
+        });
+      },
+    },
+    [GraphEvents.ON_RUN_STEP]: {
+      handle: (event: string, data: t.StreamEventData): void => {
+        aggregateContent({
+          event: event as GraphEvents,
+          data: data as t.RunStep,
+        });
+      },
+    },
+    [GraphEvents.ON_RUN_STEP_DELTA]: {
+      handle: (event: string, data: t.StreamEventData): void => {
+        aggregateContent({
+          event: event as GraphEvents,
+          data: data as t.RunStepDeltaEvent,
+        });
+      },
+    },
+    [GraphEvents.ON_MESSAGE_DELTA]: {
+      handle: (event: string, data: t.StreamEventData): void => {
+        aggregateContent({
+          event: event as GraphEvents,
+          data: data as t.MessageDeltaEvent,
+        });
+      },
+    },
+  };
+
+  const run = await Run.create<t.IState>({
+    runId: `subagent-manual-${Date.now()}`,
+    graphConfig: {
+      type: 'standard',
+      agents: [parentAgent],
+    },
+    returnContent: true,
+    customHandlers,
+  });
+
+  console.log('--- Run created ---');
+  console.log(
+    `Subagent tool present: ${
+      (
+        (run.Graph as import('@/graphs/Graph').StandardGraph).agentContexts.get(
+          'supervisor'
+        )?.graphTools as t.GenericTool[] | undefined
+      )?.some((t) => 'name' in t && t.name === Constants.SUBAGENT) ?? false
+    }\n`
+  );
+
+  const conversationHistory: BaseMessage[] = [];
+
+  // Turn 1: Research question (should delegate to researcher subagent)
+  console.log('=== Turn 1: Research Question ===\n');
+  console.log(
+    'User: What are the three laws of thermodynamics? Explain briefly.\n'
+  );
+
+  const userMessage = new HumanMessage(
+    'What are the three laws of thermodynamics? Explain briefly.'
+  );
+  conversationHistory.push(userMessage);
+
+  const callerConfig = {
+    configurable: { thread_id: 'subagent-verify' },
+    streamMode: 'values' as const,
+    version: 'v2' as const,
+  };
+
+  console.log('--- Streaming response ---\n');
+  const result = await run.processStream(
+    { messages: conversationHistory },
+    callerConfig
+  );
+
+  const runMessages = run.getRunMessages();
+  console.log('\n\n--- Run Messages ---\n');
+
+  if (runMessages) {
+    for (const msg of runMessages) {
+      const type = msg._getType();
+      if (type === 'tool') {
+        const name = 'name' in msg ? msg.name : 'unknown';
+        const rawContent =
+          typeof msg.content === 'string'
+            ? msg.content
+            : JSON.stringify(msg.content);
+        const content = rawContent.slice(0, 200);
+        const truncated = rawContent.length > 200 ? '...' : '';
+        console.log(`[ToolMessage] name=${name}`);
+        console.log(`  content: ${content}${truncated}\n`);
+      } else if (type === 'ai') {
+        const content =
+          typeof msg.content === 'string'
+            ? msg.content.slice(0, 300)
+            : JSON.stringify(msg.content).slice(0, 300);
+        const toolCalls = 'tool_calls' in msg ? msg.tool_calls : undefined;
+        console.log(`[AIMessage]`);
+        if (toolCalls && Array.isArray(toolCalls) && toolCalls.length > 0) {
+          for (const tc of toolCalls) {
+            console.log(
+              `  tool_call: ${tc.name}(${JSON.stringify(tc.args).slice(0, 100)}...)`
+            );
+          }
+        }
+        console.log(
+          `  content: ${content}${content.length >= 300 ? '...' : ''}\n`
+        );
+      }
+    }
+
+    const subagentToolMessages = runMessages.filter(
+      (msg) =>
+        msg._getType() === 'tool' &&
+        'name' in msg &&
+        msg.name === Constants.SUBAGENT
+    );
+    console.log(`\n--- Verification ---`);
+    console.log(`Subagent tool calls found: ${subagentToolMessages.length}`);
+    console.log(`Total run messages: ${runMessages.length}`);
+    console.log(`Result content parts: ${result?.length ?? 0}`);
+
+    if (subagentToolMessages.length > 0) {
+      console.log(
+        '\nSUCCESS: Subagent was invoked and returned a filtered result.'
+      );
+      console.log(
+        'The child context was isolated — only the final text came back.'
+      );
+    } else {
+      console.log('\nNOTE: No subagent tool calls detected.');
+      console.log('The LLM may have answered directly without delegating.');
+    }
+  }
+
+  console.log('\n=== Done ===');
+}
+
+testSubagentPrimitive().catch(console.error);

package/src/scripts/multi-agent-supervisor.ts

@@ -255,32 +255,32 @@ async function testSupervisorMultiAgent() {
         to: 'data_analyst',
         description:
           'Transfer to data analyst for statistical analysis and metrics',
-        edgeType: 'transfer',
+        edgeType: EdgeType.HANDOFF,
       },
       {
         from: 'supervisor',
         to: 'security_expert',
         description: 'Transfer to security expert for cybersecurity assessment',
-        edgeType: 'transfer',
+        edgeType: EdgeType.HANDOFF,
       },
       {
         from: 'supervisor',
         to: 'product_designer',
         description: 'Transfer to product designer for UX/UI design',
-        edgeType: 'transfer',
+        edgeType: EdgeType.HANDOFF,
       },
       {
         from: 'supervisor',
         to: 'devops_engineer',
         description:
           'Transfer to DevOps engineer for infrastructure and deployment',
-        edgeType: 'transfer',
+        edgeType: EdgeType.HANDOFF,
       },
       {
         from: 'supervisor',
         to: 'legal_advisor',
         description: 'Transfer to legal advisor for compliance and licensing',
-        edgeType: 'transfer',
+        edgeType: EdgeType.HANDOFF,
       },
     ];