@illuma-ai/agents 1.0.81

package/src/scripts/code_exec_multi_session.ts

@@ -0,0 +1,241 @@
+// src/scripts/code_exec_multi_session.ts
+/**
+ * Tests multi-session file tracking for code execution.
+ * Verifies that:
+ * 1. Files from multiple executions are accumulated
+ * 2. Each file tracks its source session_id
+ * 3. Edited/recreated files replace older versions (latest preferred)
+ *
+ * Run with: npm run code_exec_multi_session
+ */
+import { config } from 'dotenv';
+config();
+import { HumanMessage, BaseMessage } from '@langchain/core/messages';
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type * as t from '@/types';
+import { ChatModelStreamHandler } from '@/stream';
+import { ToolEndHandler, ModelEndHandler } from '@/events';
+import { getLLMConfig } from '@/utils/llmConfig';
+import { getArgs } from '@/scripts/args';
+import { Constants, GraphEvents } from '@/common';
+import { Run } from '@/run';
+import { createCodeExecutionTool } from '@/tools/CodeExecutor';
+
+const conversationHistory: BaseMessage[] = [];
+
+/**
+ * Prints session context from the graph
+ */
+function printSessionContext(run: Run<t.IState>, label: string): void {
+  const graph = run.Graph;
+  if (!graph) {
+    console.log(`\n[${label}] No graph available`);
+    return;
+  }
+
+  const session = graph.sessions.get(Constants.EXECUTE_CODE) as
+    | t.CodeSessionContext
+    | undefined;
+
+  console.log(`\n========== ${label} ==========`);
+  if (!session) {
+    console.log('  No session context stored yet');
+    return;
+  }
+
+  console.log(`  Latest session_id: ${session.session_id}`);
+  console.log(`  Files tracked: ${session.files.length}`);
+  for (const file of session.files) {
+    console.log(`    - ${file.name} (session: ${file.session_id})`);
+  }
+}
+
+async function testMultiSessionFiles(): Promise<void> {
+  const { provider } = await getArgs();
+
+  const customHandlers = {
+    [GraphEvents.TOOL_END]: new ToolEndHandler(),
+    [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),
+    [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler(),
+  };
+
+  const llmConfig = getLLMConfig(provider);
+
+  const run = await Run.create<t.IState>({
+    runId: 'multi-session-test',
+    graphConfig: {
+      type: 'standard',
+      llmConfig,
+      tools: [createCodeExecutionTool()],
+      instructions: `You are a coding assistant. Execute code exactly as requested.
+When asked to create files, use Python and save to /mnt/data/.
+When reading files, print their contents.
+Be concise in responses.`,
+    },
+    returnContent: true,
+    customHandlers,
+  });
+
+  const streamConfig: Partial<RunnableConfig> & {
+    version: 'v1' | 'v2';
+    streamMode: string;
+  } = {
+    configurable: {
+      provider,
+      thread_id: 'multi-session-test',
+    },
+    streamMode: 'values',
+    version: 'v2' as const,
+  };
+
+  // ========== TEST 1: Create first file ==========
+  console.log('\n\n' + '='.repeat(60));
+  console.log('TEST 1: Create first file (file_a.txt)');
+  console.log('='.repeat(60));
+
+  conversationHistory.push(
+    new HumanMessage(`
+Create a file called "file_a.txt" with the content:
+"This is file A, version 1"
+Print confirmation when done.
+`)
+  );
+
+  await run.processStream({ messages: conversationHistory }, streamConfig);
+  const messages1 = run.getRunMessages();
+  if (messages1) conversationHistory.push(...messages1);
+
+  printSessionContext(run, 'After Test 1');
+
+  // ========== TEST 2: Create second file (different session) ==========
+  console.log('\n\n' + '='.repeat(60));
+  console.log('TEST 2: Create second file (file_b.txt)');
+  console.log('Expecting: Both file_a.txt and file_b.txt tracked');
+  console.log('='.repeat(60));
+
+  conversationHistory.push(
+    new HumanMessage(`
+Create a NEW file called "file_b.txt" with the content:
+"This is file B"
+Print confirmation when done.
+`)
+  );
+
+  await run.processStream({ messages: conversationHistory }, streamConfig);
+  const messages2 = run.getRunMessages();
+  if (messages2) conversationHistory.push(...messages2);
+
+  printSessionContext(run, 'After Test 2');
+
+  // ========== TEST 3: Read BOTH files (verifies accumulation) ==========
+  console.log('\n\n' + '='.repeat(60));
+  console.log('TEST 3: Read BOTH files from previous executions');
+  console.log('This verifies multi-session file accumulation works');
+  console.log('='.repeat(60));
+
+  conversationHistory.push(
+    new HumanMessage(`
+Read and print the contents of BOTH files:
+1. file_a.txt
+2. file_b.txt
+
+Show me what's in each file.
+`)
+  );
+
+  await run.processStream({ messages: conversationHistory }, streamConfig);
+  const messages3 = run.getRunMessages();
+  if (messages3) conversationHistory.push(...messages3);
+
+  printSessionContext(run, 'After Test 3');
+
+  // ========== TEST 4: Edit file_a.txt (verifies latest-wins) ==========
+  console.log('\n\n' + '='.repeat(60));
+  console.log('TEST 4: Edit file_a.txt (create new version)');
+  console.log('Expecting: Old file_a.txt replaced with new version');
+  console.log('='.repeat(60));
+
+  conversationHistory.push(
+    new HumanMessage(`
+Create an UPDATED version of "file_a.txt" with the content:
+"This is file A, version 2 - UPDATED"
+Print confirmation when done.
+`)
+  );
+
+  await run.processStream({ messages: conversationHistory }, streamConfig);
+  const messages4 = run.getRunMessages();
+  if (messages4) conversationHistory.push(...messages4);
+
+  printSessionContext(run, 'After Test 4');
+
+  // ========== TEST 5: Read file_a.txt (verifies latest version) ==========
+  console.log('\n\n' + '='.repeat(60));
+  console.log('TEST 5: Read file_a.txt to verify it has the UPDATED content');
+  console.log('Expected: "version 2 - UPDATED" NOT "version 1"');
+  console.log('='.repeat(60));
+
+  conversationHistory.push(
+    new HumanMessage(`
+Read and print the contents of file_a.txt.
+Tell me what version it shows.
+`)
+  );
+
+  await run.processStream({ messages: conversationHistory }, streamConfig);
+  const messages5 = run.getRunMessages();
+  if (messages5) conversationHistory.push(...messages5);
+
+  printSessionContext(run, 'Final Session State');
+
+  // ========== SUMMARY ==========
+  console.log('\n\n' + '='.repeat(60));
+  console.log('TEST SUMMARY');
+  console.log('='.repeat(60));
+
+  const finalSession = run.Graph?.sessions.get(Constants.EXECUTE_CODE) as
+    | t.CodeSessionContext
+    | undefined;
+
+  if (finalSession) {
+    const uniqueSessionIds = new Set(
+      finalSession.files.map((f) => f.session_id)
+    );
+    console.log(`\nTotal files tracked: ${finalSession.files.length}`);
+    console.log(`Unique session_ids: ${uniqueSessionIds.size}`);
+    console.log('\nFiles:');
+    for (const file of finalSession.files) {
+      console.log(
+        `  - ${file.name} (session: ${file.session_id?.slice(0, 20)}...)`
+      );
+    }
+
+    // Verify expectations
+    const fileACount = finalSession.files.filter(
+      (f) => f.name === 'file_a.txt'
+    ).length;
+    const fileBCount = finalSession.files.filter(
+      (f) => f.name === 'file_b.txt'
+    ).length;
+
+    console.log('\n✓ Checks:');
+    console.log(`  file_a.txt count: ${fileACount} (expected: 1, latest wins)`);
+    console.log(`  file_b.txt count: ${fileBCount} (expected: 1)`);
+
+    if (fileACount === 1 && fileBCount === 1) {
+      console.log('\n✅ All tests passed! Multi-session tracking works.');
+    } else {
+      console.log('\n❌ Test failed - unexpected file counts');
+    }
+  }
+}
+
+process.on('unhandledRejection', (reason, promise) => {
+  console.error('Unhandled Rejection at:', promise, 'reason:', reason);
+  process.exit(1);
+});
+
+testMultiSessionFiles().catch((err) => {
+  console.error('Test failed:', err);
+  process.exit(1);
+});

package/src/scripts/code_exec_ptc.ts

@@ -0,0 +1,334 @@
+// src/scripts/code_exec_ptc.ts
+/**
+ * Live LLM test for Programmatic Tool Calling (PTC).
+ * Run with: npm run code_exec_ptc
+ *
+ * Tests PTC with a real LLM in the loop, demonstrating:
+ * 1. LLM decides when to use PTC
+ * 2. LLM writes Python code that calls tools programmatically
+ * 3. ToolNode automatically injects programmatic tools
+ * 4. Tools filtered by allowed_callers
+ */
+import { config } from 'dotenv';
+config();
+
+import { randomUUID } from 'crypto';
+import { HumanMessage, BaseMessage } from '@langchain/core/messages';
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type * as t from '@/types';
+import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
+import {
+  // createProgrammaticToolRegistry,
+  createGetTeamMembersTool,
+  createGetExpensesTool,
+  createGetWeatherTool,
+} from '@/test/mockTools';
+import {
+  createMetadataAggregator,
+  ModelEndHandler,
+  ToolEndHandler,
+} from '@/events';
+import { createProgrammaticToolCallingTool } from '@/tools/ProgrammaticToolCalling';
+import { createCodeExecutionTool } from '@/tools/CodeExecutor';
+import { getLLMConfig } from '@/utils/llmConfig';
+import { getArgs } from '@/scripts/args';
+import { GraphEvents } from '@/common';
+import { Run } from '@/run';
+
+const conversationHistory: BaseMessage[] = [];
+
+/**
+ * Creates a tool registry where ALL business tools are code_execution ONLY.
+ * This forces the LLM to use PTC - it cannot call these tools directly.
+ */
+function createPTCOnlyToolRegistry(): t.LCToolRegistry {
+  const toolDefs: t.LCTool[] = [
+    {
+      name: 'get_team_members',
+      description:
+        'Get list of team members. Returns array of objects with id, name, and department fields.',
+      parameters: {
+        type: 'object',
+        properties: {},
+        required: [],
+      },
+      allowed_callers: ['code_execution'], // PTC ONLY - not direct
+    },
+    {
+      name: 'get_expenses',
+      description:
+        'Get expense records for a user. Returns array of objects with amount and category fields.',
+      parameters: {
+        type: 'object',
+        properties: {
+          user_id: {
+            type: 'string',
+            description: 'The user ID to fetch expenses for',
+          },
+        },
+        required: ['user_id'],
+      },
+      allowed_callers: ['code_execution'], // PTC ONLY - not direct
+    },
+    {
+      name: 'get_weather',
+      description:
+        'Get current weather for a city. Returns object with temperature (number) and condition (string) fields.',
+      parameters: {
+        type: 'object',
+        properties: {
+          city: {
+            type: 'string',
+            description: 'City name',
+          },
+        },
+        required: ['city'],
+      },
+      allowed_callers: ['code_execution'], // PTC ONLY - not direct (changed from ['direct', 'code_execution'])
+    },
+  ];
+
+  return new Map(toolDefs.map((def) => [def.name, def]));
+}
+
+async function testProgrammaticToolCalling(): Promise<void> {
+  const { userName, location, provider, currentDate } = await getArgs();
+  const { contentParts, aggregateContent } = createContentAggregator();
+
+  const customHandlers = {
+    [GraphEvents.TOOL_END]: new ToolEndHandler(),
+    [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),
+    [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler(),
+    [GraphEvents.ON_RUN_STEP_COMPLETED]: {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP_COMPLETED,
+        data: t.StreamEventData
+      ): void => {
+        console.log('====== ON_RUN_STEP_COMPLETED ======');
+        console.dir(data, { depth: null });
+        aggregateContent({
+          event,
+          data: data as unknown as { result: t.ToolEndEvent },
+        });
+      },
+    },
+    [GraphEvents.ON_RUN_STEP]: {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP,
+        data: t.StreamEventData
+      ): void => {
+        console.log('====== ON_RUN_STEP ======');
+        console.dir(data, { depth: null });
+        aggregateContent({ event, data: data as t.RunStep });
+      },
+    },
+    [GraphEvents.ON_RUN_STEP_DELTA]: {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP_DELTA,
+        data: t.StreamEventData
+      ): void => {
+        aggregateContent({ event, data: data as t.RunStepDeltaEvent });
+      },
+    },
+    [GraphEvents.ON_MESSAGE_DELTA]: {
+      handle: (
+        event: GraphEvents.ON_MESSAGE_DELTA,
+        data: t.StreamEventData
+      ): void => {
+        aggregateContent({ event, data: data as t.MessageDeltaEvent });
+      },
+    },
+    [GraphEvents.TOOL_START]: {
+      handle: (
+        _event: string,
+        data: t.StreamEventData,
+        metadata?: Record<string, unknown>
+      ): void => {
+        console.log('====== TOOL_START ======');
+        console.dir(data, { depth: null });
+      },
+    },
+  };
+
+  const llmConfig = getLLMConfig(provider);
+
+  // Create mock tool instances
+  const teamTool = createGetTeamMembersTool();
+  const expensesTool = createGetExpensesTool();
+  const weatherTool = createGetWeatherTool();
+
+  // Create special tools
+  const codeExecTool = createCodeExecutionTool();
+  const ptcTool = createProgrammaticToolCallingTool();
+
+  // Build complete tool list and map
+  const allTools = [teamTool, expensesTool, weatherTool, codeExecTool, ptcTool];
+  const toolMap = new Map(allTools.map((t) => [t.name, t]));
+
+  // Create tool registry where ALL business tools are PTC-only
+  // This means the LLM CANNOT call get_team_members, get_expenses, get_weather directly
+  // It MUST use run_tools_with_code to invoke them
+  const toolRegistry = createPTCOnlyToolRegistry();
+
+  console.log('\n' + '='.repeat(70));
+  console.log('Tool Configuration Summary:');
+  console.log('='.repeat(70));
+  console.log('Total tools:', allTools.length);
+  console.log(
+    'Programmatic-allowed:',
+    Array.from(toolRegistry.values())
+      .filter((t) => t.allowed_callers?.includes('code_execution'))
+      .map((t) => t.name)
+      .join(', ')
+  );
+  console.log(
+    'Direct-callable:',
+    Array.from(toolRegistry.values())
+      .filter((t) => !t.allowed_callers || t.allowed_callers.includes('direct'))
+      .map((t) => t.name)
+      .join(', ')
+  );
+  console.log('='.repeat(70) + '\n');
+
+  const run = await Run.create<t.IState>({
+    runId: randomUUID(),
+    graphConfig: {
+      type: 'standard',
+      llmConfig,
+      agents: [
+        {
+          agentId: 'default',
+          provider: llmConfig.provider,
+          clientOptions: llmConfig,
+          tools: allTools,
+          toolMap,
+          toolRegistry,
+          instructions:
+            'You are a friendly AI assistant with advanced coding capabilities.\n\n' +
+            'IMPORTANT: The tools get_team_members(), get_expenses(), and get_weather() are NOT available ' +
+            'for direct function calling. You MUST use the run_tools_with_code tool to invoke them.\n\n' +
+            'When you need to use these tools, write Python code using run_tools_with_code that calls:\n' +
+            '- await get_team_members() - returns list of team members\n' +
+            '- await get_expenses(user_id="...") - returns expenses for a user\n' +
+            '- await get_weather(city="...") - returns weather data\n\n' +
+            'Use asyncio.gather() for parallel execution when calling multiple tools.',
+          additional_instructions: `The user's name is ${userName} and they are located in ${location}. Today is ${currentDate}.`,
+        },
+      ],
+    },
+    returnContent: true,
+    customHandlers,
+  });
+
+  const config: Partial<RunnableConfig> & {
+    version: 'v1' | 'v2';
+    run_id?: string;
+    streamMode: string;
+  } = {
+    configurable: {
+      provider,
+      thread_id: 'ptc-conversation-1',
+    },
+    streamMode: 'values',
+    version: 'v2' as const,
+  };
+
+  console.log('Test 1: Team Expense Analysis with PTC');
+  console.log('='.repeat(70) + '\n');
+
+  const userMessage1 = `Hi ${userName}! I need you to analyze our team's expenses. Please:
+
+1. Get the list of all team members
+2. For each member, fetch their expense records
+3. Calculate the total expenses per member
+4. Identify anyone who spent more than $500
+5. Show me a summary report
+
+IMPORTANT: Use the run_tools_with_code tool to do this efficiently. 
+Don't call each tool separately - write Python code that orchestrates all the calls!`;
+
+  conversationHistory.push(new HumanMessage(userMessage1));
+
+  let inputs = {
+    messages: conversationHistory,
+  };
+
+  const finalContentParts1 = await run.processStream(inputs, config);
+  const finalMessages1 = run.getRunMessages();
+  if (finalMessages1) {
+    conversationHistory.push(...finalMessages1);
+  }
+
+  console.log('\n\n====================\n\n');
+  console.log('Content Parts:');
+  console.dir(contentParts, { depth: null });
+
+  console.log('\n\n' + '='.repeat(70));
+  console.log('Test 2: Conditional Logic and Parallel Execution');
+  console.log('='.repeat(70) + '\n');
+
+  const userMessage2 = `Great job! Now let's test some advanced patterns. Please:
+
+1. Check the weather in both San Francisco and New York (in parallel!)
+2. Based on which city has better weather (warmer), fetch the team members
+3. For the Engineering team members only, calculate their travel expenses
+4. Show me the results
+
+Again, use run_tools_with_code for maximum efficiency. Use asyncio.gather() 
+to check both cities' weather at the same time!`;
+
+  conversationHistory.push(new HumanMessage(userMessage2));
+
+  inputs = {
+    messages: conversationHistory,
+  };
+
+  const finalContentParts2 = await run.processStream(inputs, config);
+  const finalMessages2 = run.getRunMessages();
+  if (finalMessages2) {
+    conversationHistory.push(...finalMessages2);
+  }
+
+  console.log('\n\n====================\n\n');
+  console.log('Final Content Parts:');
+  console.dir(finalContentParts2, { depth: null });
+
+  console.log('\n\n' + '='.repeat(70));
+  console.log('Generating conversation title...');
+  console.log('='.repeat(70) + '\n');
+
+  const { handleLLMEnd, collected } = createMetadataAggregator();
+  const titleResult = await run.generateTitle({
+    provider,
+    inputText: userMessage1,
+    contentParts,
+    chainOptions: {
+      callbacks: [
+        {
+          handleLLMEnd,
+        },
+      ],
+    },
+  });
+
+  console.log('Generated Title:', titleResult);
+  console.log('Collected metadata:', collected);
+}
+
+process.on('unhandledRejection', (reason, promise) => {
+  console.error('Unhandled Rejection at:', promise, 'reason:', reason);
+  console.log('Conversation history:');
+  console.dir(conversationHistory, { depth: null });
+  process.exit(1);
+});
+
+process.on('uncaughtException', (err) => {
+  console.error('Uncaught Exception:', err);
+});
+
+testProgrammaticToolCalling().catch((err) => {
+  console.error(err);
+  console.log('Conversation history:');
+  console.dir(conversationHistory, { depth: null });
+  process.exit(1);
+});