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

package/src/scripts/poc-multi-agent-comprehensive.ts

@@ -26,7 +26,7 @@ import {
 import { DynamicStructuredTool } from '@langchain/core/tools';
 import { z } from 'zod';
 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';
@@ -690,7 +690,7 @@ Start with "SUMMARY:" and end with "RECOMMENDATION:"`
     {
       from: 'researcher',
       to: 'analyst',
-      edgeType: 'sequence',
+      edgeType: EdgeType.DIRECT,
       prompt: (messages: BaseMessage[], startIndex: number) => {
         const buffer = getBufferString(messages.slice(startIndex));
         return `Here are the research findings. Analyze them and provide insights:\n\n${buffer}`;
@@ -700,7 +700,7 @@ Start with "SUMMARY:" and end with "RECOMMENDATION:"`
     {
       from: 'analyst',
       to: 'summarizer',
-      edgeType: 'sequence',
+      edgeType: EdgeType.DIRECT,
       prompt: (messages: BaseMessage[], startIndex: number) => {
         const buffer = getBufferString(messages.slice(startIndex));
         return `Here are the combined research and analysis. Synthesize into a final summary:\n\n${buffer}`;
@@ -813,7 +813,7 @@ Start with "REVIEW:" and keep it to 3-4 lines.`
     {
       from: 'data_collector',
       to: 'translator',
-      edgeType: 'sequence',
+      edgeType: EdgeType.DIRECT,
       prompt: (messages: BaseMessage[], startIndex: number) => {
         const buffer = getBufferString(messages.slice(startIndex));
         return `Here is the collected data. Translate the key findings to Spanish:\n\n${buffer}`;
@@ -823,7 +823,7 @@ Start with "REVIEW:" and keep it to 3-4 lines.`
     {
       from: 'translator',
       to: 'reviewer',
-      edgeType: 'sequence',
+      edgeType: EdgeType.DIRECT,
       prompt: (messages: BaseMessage[], startIndex: number) => {
         const buffer = getBufferString(messages.slice(startIndex));
         return `Here is the collected and translated data. Review it for quality:\n\n${buffer}`;
@@ -934,7 +934,7 @@ Format as a brief executive memo (4-5 sentences). Start with "EXECUTIVE SUMMARY:
     {
       from: 'intel_gatherer',
       to: 'market_analyst',
-      edgeType: 'sequence',
+      edgeType: EdgeType.DIRECT,
       prompt: (messages: BaseMessage[], startIndex: number) => {
         const buffer = getBufferString(messages.slice(startIndex));
         return `Here is the gathered intelligence. Analyze the market sentiment and cross-reference with our database:\n\n${buffer}`;
@@ -944,7 +944,7 @@ Format as a brief executive memo (4-5 sentences). Start with "EXECUTIVE SUMMARY:
     {
       from: 'market_analyst',
       to: 'presenter',
-      edgeType: 'sequence',
+      edgeType: EdgeType.DIRECT,
       prompt: (messages: BaseMessage[], startIndex: number) => {
         const buffer = getBufferString(messages.slice(startIndex));
         return `Here is the intelligence and market analysis. Create a polished executive summary:\n\n${buffer}`;
@@ -1070,7 +1070,7 @@ Start with "SENTIMENT ANALYSIS:"`,
     {
       from: 'planner',
       to: 'researcher',
-      edgeType: 'sequence',
+      edgeType: EdgeType.DIRECT,
       prompt: (messages: BaseMessage[], startIndex: number) => {
         const buffer = getBufferString(messages.slice(startIndex));
         return `Here is the content plan. Gather the required data:\n\n${buffer}`;

package/src/scripts/sequential-full-metadata-test.ts

@@ -4,7 +4,7 @@ config();
 import { HumanMessage, BaseMessage } from '@langchain/core/messages';
 import type * as t from '@/types';
 import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
-import { Providers, GraphEvents } from '@/common';
+import { Providers, GraphEvents, EdgeType } from '@/common';
 import { sleep } from '@/utils/run';
 import { Run } from '@/run';
 
@@ -49,7 +49,7 @@ async function testSequentialMetadata() {
 
   // Sequential edge: A -> B (using edgeType not type)
   const edges: t.GraphEdge[] = [
-    { from: 'agent_a', to: 'agent_b', edgeType: 'sequence' },
+    { from: 'agent_a', to: 'agent_b', edgeType: EdgeType.DIRECT },
   ];
 
   const captureMetadata = (

package/src/scripts/subagent-event-driven-debug.ts

@@ -0,0 +1,190 @@
+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 } from '@/stream';
+import { ToolEndHandler, ModelEndHandler } from '@/events';
+import { Providers, GraphEvents, Constants } from '@/common';
+import { Run } from '@/run';
+
+/**
+ * Repro for the reference consumer setup: event-driven tools via `toolDefinitions`
+ * + an ON_TOOL_EXECUTE handler that runs the tool. Self-spawn subagent must
+ * be able to drive the SAME tool pipeline.
+ */
+const apiKey = process.env.OPENAI_API_KEY!;
+if (!apiKey) {
+  console.error('Missing OPENAI_API_KEY');
+  process.exit(1);
+}
+
+// Simulate consumer: tool definitions only, execution routed via event.
+const calculatorDef: t.LCTool = {
+  name: 'calculator',
+  description: 'Evaluate a math expression. Use for any arithmetic.',
+  parameters: {
+    type: 'object',
+    properties: {
+      expression: {
+        type: 'string',
+        description: "A JS math expression, e.g. '42 * 58'",
+      },
+    },
+    required: ['expression'],
+  },
+};
+
+async function main() {
+  console.log('=== Subagent Event-Driven Tool Diagnostic ===\n');
+
+  const parentAgent: t.AgentInputs = {
+    agentId: 'supervisor',
+    provider: Providers.OPENAI,
+    clientOptions: { modelName: 'gpt-4o-mini', apiKey },
+    instructions: `You have calculator AND can spawn a "self" subagent in an isolated context.
+For any arithmetic question, spawn the "self" subagent with the math task.
+The subagent MUST use the calculator tool — never estimate.`,
+    maxContextTokens: 8000,
+    toolDefinitions: [calculatorDef],
+    subagentConfigs: [
+      {
+        type: 'self',
+        self: true,
+        name: 'supervisor',
+        description:
+          'Spawn a copy of this agent in an isolated context for a focused math subtask.',
+      },
+    ],
+  };
+
+  let toolCallCount = 0;
+  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_TOOL_EXECUTE]: {
+      handle: (_event, rawData): void => {
+        const data = rawData as t.ToolExecuteBatchRequest;
+        console.log(
+          `[PARENT ON_TOOL_EXECUTE] agentId=${data.agentId} calls=${data.toolCalls
+            .map((c) => c.name)
+            .join(',')}`
+        );
+        const results: t.ToolExecuteResult[] = data.toolCalls.map((call) => {
+          toolCallCount += 1;
+          const args = call.args as { expression?: string };
+          const expression = args.expression ?? '';
+          let content: string;
+          try {
+            // eslint-disable-next-line no-eval
+            const result = eval(expression);
+            content = `${expression} = ${result}`;
+          } catch (err) {
+            content = `Error: ${String(err)}`;
+          }
+          return {
+            toolCallId: call.id!,
+            status: 'success',
+            content,
+          };
+        });
+        data.resolve(results);
+      },
+    },
+    [GraphEvents.ON_RUN_STEP]: {
+      handle: (event, data): void => {
+        const d = data as { type?: string; runId?: string; agentId?: string };
+        console.log(
+          `[PARENT ${event}] type=${d.type} agentId=${d.agentId ?? '-'} runId=${d.runId ?? '-'}`
+        );
+      },
+    },
+    [GraphEvents.ON_RUN_STEP_COMPLETED]: {
+      handle: (event, data): void => {
+        const r = (
+          data as { result: { type: string; tool_call?: { name?: string } } }
+        ).result;
+        console.log(
+          `[PARENT ${event}] type=${r.type} tool=${r.tool_call?.name ?? '-'}`
+        );
+      },
+    },
+    [GraphEvents.ON_SUBAGENT_UPDATE]: {
+      handle: (_event, rawData): void => {
+        const d = rawData as t.SubagentUpdateEvent;
+        console.log(
+          `[SUBAGENT ${d.phase}] [${d.subagentType}] tool_call_id=${d.parentToolCallId ?? '-'} ${d.label ?? ''}`
+        );
+      },
+    },
+  };
+
+  const run = await Run.create<t.IState>({
+    runId: `sub-evt-${Date.now()}`,
+    graphConfig: { type: 'standard', agents: [parentAgent] },
+    customHandlers,
+  });
+
+  const question = new HumanMessage(
+    'Compute (42 * 58) + (13 ** 3). Use the self subagent, and have it use the calculator.'
+  );
+
+  console.log('User:', question.content, '\n');
+
+  await run.processStream(
+    { messages: [question] },
+    {
+      configurable: { thread_id: `sub-evt` },
+      version: 'v2' as const,
+    }
+  );
+
+  const msgs = (run.getRunMessages() ?? []) as BaseMessage[];
+  console.log('\n--- Run messages ---\n');
+  for (const msg of msgs) {
+    const type = msg._getType();
+    const name = 'name' in msg ? (msg as { name?: string }).name : undefined;
+    const content =
+      typeof msg.content === 'string'
+        ? msg.content.slice(0, 400)
+        : JSON.stringify(msg.content).slice(0, 400);
+    const toolCalls =
+      'tool_calls' in msg
+        ? (msg as { tool_calls?: Array<{ name: string; args: unknown }> })
+            .tool_calls
+        : undefined;
+    console.log(`[${type}]${name ? ` name=${name}` : ''}`);
+    if (toolCalls?.length) {
+      for (const tc of toolCalls) {
+        console.log(
+          `  tool_call: ${tc.name}(${JSON.stringify(tc.args).slice(0, 150)})`
+        );
+      }
+    }
+    console.log(`  content: ${content}\n`);
+  }
+
+  const subagentMsgs = msgs.filter(
+    (m) =>
+      m._getType() === 'tool' &&
+      (m as { name?: string }).name === Constants.SUBAGENT
+  );
+
+  console.log('--- Verification ---');
+  console.log(`subagent tool calls seen (parent): ${subagentMsgs.length}`);
+  console.log(
+    `ON_TOOL_EXECUTE dispatched (parent saw): ${toolCallCount} (expected >= 1 if subagent used calculator)`
+  );
+  if (subagentMsgs[0]) {
+    console.log(
+      `\nsubagent result:\n${(subagentMsgs[0].content as string).slice(0, 600)}`
+    );
+  }
+}
+
+main().catch((err) => {
+  console.error('Script error:', err);
+  process.exit(1);
+});

package/src/scripts/subagent-tools-debug.ts

@@ -0,0 +1,160 @@
+import { config } from 'dotenv';
+config();
+
+import { HumanMessage } from '@langchain/core/messages';
+import type { BaseMessage } from '@langchain/core/messages';
+import { tool } from '@langchain/core/tools';
+import { z } from 'zod';
+import type * as t from '@/types';
+import { ChatModelStreamHandler } from '@/stream';
+import { ToolEndHandler, ModelEndHandler } from '@/events';
+import { Providers, GraphEvents, Constants } from '@/common';
+import { Run } from '@/run';
+
+/**
+ * Diagnostic: verify a self-spawned subagent can call parent's real tools.
+ * Expected before-fix: parent delegates to self; child cannot invoke calculator.
+ */
+const apiKey = process.env.OPENAI_API_KEY!;
+if (!apiKey) {
+  console.error('Missing OPENAI_API_KEY');
+  process.exit(1);
+}
+
+const calculator = tool(
+  async ({ expression }) => {
+    const result = eval(expression); // don't do this in prod
+    return `${expression} = ${result}`;
+  },
+  {
+    name: 'calculator',
+    description: 'Evaluate a math expression. Use for any arithmetic.',
+    schema: z.object({
+      expression: z.string().describe("A JS math expression, e.g. '42 * 58'"),
+    }),
+  }
+);
+
+async function main() {
+  console.log('=== Subagent Tool-Access Diagnostic ===\n');
+
+  const parentAgent: t.AgentInputs = {
+    agentId: 'supervisor',
+    provider: Providers.OPENAI,
+    clientOptions: { modelName: 'gpt-4o-mini', apiKey },
+    instructions: `You have calculator AND can spawn a "self" subagent in an isolated context.
+For any arithmetic question that would bloat your context, spawn the "self" subagent with the math task.
+The subagent must use the calculator tool — never estimate.`,
+    maxContextTokens: 8000,
+    tools: [calculator],
+    subagentConfigs: [
+      {
+        type: 'self',
+        self: true,
+        name: 'supervisor',
+        description:
+          'Spawn a copy of this agent in an isolated context for a focused math subtask.',
+      },
+    ],
+  };
+
+  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]: {
+      handle: (event, data): void => {
+        console.log(
+          `[PARENT EVENT] ${event}`,
+          JSON.stringify(data).slice(0, 200)
+        );
+      },
+    },
+    [GraphEvents.ON_RUN_STEP_COMPLETED]: {
+      handle: (event, data): void => {
+        console.log(
+          `[PARENT EVENT] ${event}`,
+          JSON.stringify(data).slice(0, 200)
+        );
+      },
+    },
+  };
+
+  const run = await Run.create<t.IState>({
+    runId: `subagent-debug-${Date.now()}`,
+    graphConfig: { type: 'standard', agents: [parentAgent] },
+    customHandlers,
+  });
+
+  const question = new HumanMessage(
+    'Compute (42 * 58) + (13 ^ 3). Spawn the self subagent to do this, and have IT use calculator.'
+  );
+
+  console.log('User:', question.content, '\n');
+
+  await run.processStream(
+    { messages: [question] },
+    {
+      configurable: { thread_id: `subagent-debug` },
+      version: 'v2' as const,
+    }
+  );
+
+  const msgs = (run.getRunMessages() ?? []) as BaseMessage[];
+  console.log('\n--- Run messages ---\n');
+  for (const msg of msgs) {
+    const type = msg._getType();
+    const name = 'name' in msg ? (msg as { name?: string }).name : undefined;
+    const content =
+      typeof msg.content === 'string'
+        ? msg.content.slice(0, 400)
+        : JSON.stringify(msg.content).slice(0, 400);
+    const toolCalls =
+      'tool_calls' in msg
+        ? (msg as { tool_calls?: Array<{ name: string; args: unknown }> })
+            .tool_calls
+        : undefined;
+    console.log(`[${type}]${name ? ` name=${name}` : ''}`);
+    if (toolCalls?.length) {
+      for (const tc of toolCalls) {
+        console.log(
+          `  tool_call: ${tc.name}(${JSON.stringify(tc.args).slice(0, 150)})`
+        );
+      }
+    }
+    console.log(`  content: ${content}\n`);
+  }
+
+  const subagentCalls = msgs.filter(
+    (m) =>
+      m._getType() === 'tool' &&
+      'name' in m &&
+      (m as { name?: string }).name === Constants.SUBAGENT
+  );
+  const calculatorCalls = msgs.filter(
+    (m) =>
+      m._getType() === 'tool' &&
+      'name' in m &&
+      (m as { name?: string }).name === 'calculator'
+  );
+
+  console.log('--- Verification ---');
+  console.log(`subagent tool calls seen (parent): ${subagentCalls.length}`);
+  console.log(
+    `calculator tool calls seen (parent): ${calculatorCalls.length} (expected: 0 if subagent did the math)`
+  );
+  if (subagentCalls.length > 0) {
+    const subResult = subagentCalls[0].content as string;
+    console.log(`\nsubagent result snippet:\n${subResult.slice(0, 600)}\n`);
+    if (/\berror\b/i.test(subResult) && /tool/i.test(subResult)) {
+      console.log('⚠️  BUG CONFIRMED: subagent result mentions tool error');
+    } else if (!/\d/.test(subResult)) {
+      console.log('⚠️  POSSIBLY BUGGY: subagent result has no numbers');
+    }
+  }
+}
+
+main().catch((err) => {
+  console.error('Script error:', err);
+  process.exit(1);
+});

package/src/scripts/test-custom-prompt-key.ts

@@ -75,7 +75,7 @@ async function testCustomPromptKey() {
         {
           from: 'supervisor',
           to: 'researcher',
-          edgeType: 'transfer',
+          edgeType: EdgeType.HANDOFF,
           // Custom parameter name: "query"
           prompt: 'The research question or topic to investigate',
           promptKey: 'query',
@@ -83,7 +83,7 @@ async function testCustomPromptKey() {
         {
           from: 'supervisor',
           to: 'designer',
-          edgeType: 'transfer',
+          edgeType: EdgeType.HANDOFF,
           // Custom parameter name: "requirements"
           prompt: 'The design requirements and constraints',
           promptKey: 'requirements',
@@ -91,7 +91,7 @@ async function testCustomPromptKey() {
         {
           from: 'supervisor',
           to: 'coder',
-          edgeType: 'transfer',
+          edgeType: EdgeType.HANDOFF,
           // Custom parameter name: "specification"
           prompt: 'The technical specification for the code to implement',
           promptKey: 'specification',

package/src/scripts/test-handoff-input.ts

@@ -123,7 +123,7 @@ async function testHandoffInput() {
         {
           from: 'supervisor',
           to: ['analyst', 'writer'],
-          edgeType: 'transfer',
+          edgeType: EdgeType.HANDOFF,
           // This prompt field now serves as the description for the input parameter
           prompt:
             'Specific instructions for the specialist to follow. Be detailed about what analysis to perform, what data to focus on, or what content to create.',

package/src/scripts/test-handoff-steering.ts

@@ -121,7 +121,7 @@ When you receive a task, execute it thoroughly. Always identify yourself as the
       {
         from: 'coordinator',
         to: 'specialist',
-        edgeType: 'transfer',
+        edgeType: EdgeType.HANDOFF,
         description: 'Transfer to specialist for detailed work',
         prompt:
           'Provide specific instructions for the specialist about what to analyze or create',
@@ -226,7 +226,7 @@ You must follow the exact format requested.`,
       {
         from: 'manager',
         to: 'writer',
-        edgeType: 'transfer',
+        edgeType: EdgeType.HANDOFF,
         description: 'Transfer to writer for report creation',
         prompt:
           'Provide specific formatting and content instructions for the writer',
@@ -322,7 +322,7 @@ If asked about non-Italian food, politely redirect to Italian alternatives.`,
       {
         from: 'router',
         to: 'chef',
-        edgeType: 'transfer',
+        edgeType: EdgeType.HANDOFF,
         description: 'Transfer to chef',
         prompt: 'Instructions for the chef about how to respond',
         promptKey: 'instructions',

package/src/scripts/test-multi-agent-list-handoff.ts

@@ -170,7 +170,7 @@ async function testSupervisorListHandoff() {
         ],
         description:
           'Transfer to appropriate specialist based on task requirements',
-        edgeType: 'transfer',
+        edgeType: EdgeType.HANDOFF,
       },
     ];
 

package/src/scripts/test-parallel-agent-labeling.ts

@@ -7,7 +7,7 @@ import { HumanMessage, BaseMessage } from '@langchain/core/messages';
 import type * as t from '@/types';
 import { labelContentByAgent, formatAgentMessages } from '@/messages/format';
 import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
-import { Providers, GraphEvents, StepTypes } from '@/common';
+import { Providers, GraphEvents, EdgeType, StepTypes } from '@/common';
 import { ToolEndHandler, ModelEndHandler } from '@/events';
 import { Run } from '@/run';
 
@@ -83,13 +83,13 @@ async function testParallelWithAgentLabeling() {
       from: 'researcher',
       to: ['analyst1', 'analyst2', 'analyst3'],
       description: 'Distribute research to specialist analysts',
-      edgeType: 'sequence',
+      edgeType: EdgeType.DIRECT,
     },
     {
       from: ['analyst1', 'analyst2', 'analyst3'],
       to: 'summarizer',
       description: 'Aggregate analysis results',
-      edgeType: 'sequence',
+      edgeType: EdgeType.DIRECT,
       prompt:
         'Based on the analyses below, provide an integrated summary:\n\n{results}',
     },

package/src/scripts/test-parallel-handoffs.ts

@@ -82,14 +82,14 @@ When delegating, provide clear instructions to each agent about what they should
     {
       from: 'coordinator',
       to: 'researcher',
-      edgeType: 'transfer',
+      edgeType: EdgeType.HANDOFF,
       description: 'Transfer to researcher for research and fact-finding tasks',
       prompt: 'Research task instructions',
     },
     {
       from: 'coordinator',
       to: 'writer',
-      edgeType: 'transfer',
+      edgeType: EdgeType.HANDOFF,
       description: 'Transfer to writer for content creation and writing tasks',
       prompt: 'Writing task instructions',
     },

package/src/scripts/test-thinking-handoff-bedrock.ts

@@ -78,7 +78,7 @@ async function testBedrockThinkingHandoff() {
         from: 'supervisor',
         to: ['code_reviewer'],
         description: 'Transfer to code review specialist',
-        edgeType: 'transfer',
+        edgeType: EdgeType.HANDOFF,
       },
     ];
 

package/src/scripts/test-thinking-handoff.ts

@@ -80,7 +80,7 @@ async function testThinkingHandoff() {
         from: 'supervisor',
         to: ['code_reviewer'],
         description: 'Transfer to code review specialist',
-        edgeType: 'transfer',
+        edgeType: EdgeType.HANDOFF,
       },
     ];
 

package/src/scripts/test-thinking-to-thinking-handoff-bedrock.ts

@@ -97,7 +97,7 @@ async function testThinkingToThinkingHandoffBedrock() {
         from: 'supervisor',
         to: ['code_reviewer'],
         description: 'Transfer to code review specialist',
-        edgeType: 'transfer',
+        edgeType: EdgeType.HANDOFF,
       },
     ];
 

package/src/scripts/test-tool-before-handoff-role-order.ts

@@ -156,7 +156,7 @@ Do NOT write a long response. Just call the tool and hand off.`,
       from: 'router',
       to: 'data_analyst',
       description: 'Transfer to data analyst after checking sessions',
-      edgeType: 'transfer',
+      edgeType: EdgeType.HANDOFF,
       prompt:
         'Provide specific instructions for the data analyst about what to analyze',
       promptKey: 'instructions',

package/src/scripts/test-tools-before-handoff.ts

@@ -133,7 +133,7 @@ async function testToolsBeforeHandoff() {
         from: 'research_coordinator',
         to: 'report_writer',
         description: 'Transfer to report writer after completing research',
-        edgeType: 'transfer',
+        edgeType: EdgeType.HANDOFF,
       },
     ];