illuma-agents 1.0.47 → 1.0.50

package/src/tools/CodeExecutor.ts

@@ -1,4 +1,3 @@
-import { z } from 'zod';
 import { config } from 'dotenv';
 import fetch, { RequestInit } from 'node-fetch';
 import { HttpsProxyAgent } from 'https-proxy-agent';
@@ -21,25 +20,33 @@ const accessMessage =
 const emptyOutputMessage =
   'stdout: Empty. Ensure you\'re writing output explicitly.\n';
 
-const CodeExecutionToolSchema = z.object({
-  lang: z
-    .enum([
-      'py',
-      'js',
-      'ts',
-      'c',
-      'cpp',
-      'java',
-      'php',
-      'rs',
-      'go',
-      'd',
-      'f90',
-      'r',
-    ])
-    .describe('The programming language or runtime to execute the code in.'),
-  code: z.string()
-    .describe(`The complete, self-contained code to execute, without any truncation or minimization.
+const SUPPORTED_LANGUAGES = [
+  'py',
+  'js',
+  'ts',
+  'c',
+  'cpp',
+  'java',
+  'php',
+  'rs',
+  'go',
+  'd',
+  'f90',
+  'r',
+] as const;
+
+const CodeExecutionToolSchema = {
+  type: 'object',
+  properties: {
+    lang: {
+      type: 'string',
+      enum: SUPPORTED_LANGUAGES,
+      description:
+        'The programming language or runtime to execute the code in.',
+    },
+    code: {
+      type: 'string',
+      description: `The complete, self-contained code to execute, without any truncation or minimization.
 - The environment is stateless; variables and imports don't persist between executions.
 - Generated files from previous executions are automatically available in "/mnt/data/".
 - Files from previous executions are automatically available and can be modified in place.
@@ -50,21 +57,26 @@ const CodeExecutionToolSchema = z.object({
 - py: Matplotlib: Use \`plt.savefig()\` to save plots as files.
 - js: use the \`console\` or \`process\` methods for all outputs.
 - r: IMPORTANT: No X11 display available. ALL graphics MUST use Cairo library (library(Cairo)).
-- Other languages: use appropriate output functions.`),
-  args: z
-    .array(z.string())
-    .optional()
-    .describe(
-      'Additional arguments to execute the code with. This should only be used if the input code requires additional arguments to run.'
-    ),
-});
+- Other languages: use appropriate output functions.`,
+    },
+    args: {
+      type: 'array',
+      items: { type: 'string' },
+      description:
+        'Additional arguments to execute the code with. This should only be used if the input code requires additional arguments to run.',
+    },
+  },
+  required: ['lang', 'code'],
+} as const;
 
 const baseEndpoint = getCodeBaseURL();
 const EXEC_ENDPOINT = `${baseEndpoint}/exec`;
 
+type SupportedLanguage = (typeof SUPPORTED_LANGUAGES)[number];
+
 function createCodeExecutionTool(
   params: t.CodeExecutionToolParams = {}
-): DynamicStructuredTool<typeof CodeExecutionToolSchema> {
+): DynamicStructuredTool {
   const apiKey =
     params[EnvVar.CODE_API_KEY] ??
     params.apiKey ??
@@ -96,8 +108,13 @@ Rules:
 - Generated files auto-delivered (no download links needed)
 `.trim();
 
-  return tool<typeof CodeExecutionToolSchema>(
-    async ({ lang, code, ...rest }, config) => {
+  return tool(
+    async (rawInput, config) => {
+      const { lang, code, ...rest } = rawInput as {
+        lang: SupportedLanguage;
+        code: string;
+        args?: string[];
+      };
       /**
        * Extract session context from config.toolCall (injected by ToolNode).
        * - session_id: For API to associate with previous session

package/src/tools/ProgrammaticToolCalling.ts

@@ -1,5 +1,4 @@
 // src/tools/ProgrammaticToolCalling.ts
-import { z } from 'zod';
 import { config } from 'dotenv';
 import fetch, { RequestInit } from 'node-fetch';
 import { HttpsProxyAgent } from 'https-proxy-agent';
@@ -33,12 +32,13 @@ const DEFAULT_TIMEOUT = 60000;
 // Schema
 // ============================================================================
 
-const ProgrammaticToolCallingSchema = z.object({
-  code: z
-    .string()
-    .min(1)
-    .describe(
-      `Python code that calls tools programmatically. Tools are available as async functions.
+const ProgrammaticToolCallingSchema = {
+  type: 'object',
+  properties: {
+    code: {
+      type: 'string',
+      minLength: 1,
+      description: `Python code that calls tools programmatically. Tools are available as async functions.
 
 CRITICAL - STATELESS EXECUTION:
 Each call is a fresh Python interpreter. Variables, imports, and data do NOT persist between calls.
@@ -66,19 +66,19 @@ Rules:
 - Just write code with await—auto-wrapped in async context
 - DO NOT define async def main() or call asyncio.run()
 - Tools are pre-defined—DO NOT write function definitions
-- Only print() output returns to the model`
-    ),
-  timeout: z
-    .number()
-    .int()
-    .min(1000)
-    .max(300000)
-    .optional()
-    .default(DEFAULT_TIMEOUT)
-    .describe(
-      'Maximum execution time in milliseconds. Default: 60 seconds. Max: 5 minutes.'
-    ),
-});
+- Only print() output returns to the model`,
+    },
+    timeout: {
+      type: 'integer',
+      minimum: 1000,
+      maximum: 300000,
+      default: DEFAULT_TIMEOUT,
+      description:
+        'Maximum execution time in milliseconds. Default: 60 seconds. Max: 5 minutes.',
+    },
+  },
+  required: ['code'],
+} as const;
 
 // ============================================================================
 // Helper Functions
@@ -241,7 +241,7 @@ export async function fetchSessionFiles(
     const fetchOptions: RequestInit = {
       method: 'GET',
       headers: {
-        'User-Agent': 'LibreChat/1.0',
+        'User-Agent': 'Illuma/1.0',
         'X-API-Key': apiKey,
       },
     };
@@ -576,7 +576,7 @@ export function formatCompletedResponse(
  */
 export function createProgrammaticToolCallingTool(
   initParams: t.ProgrammaticToolCallingParams = {}
-): DynamicStructuredTool<typeof ProgrammaticToolCallingSchema> {
+): DynamicStructuredTool {
   const apiKey =
     (initParams[EnvVar.CODE_API_KEY] as string | undefined) ??
     initParams.apiKey ??
@@ -616,8 +616,9 @@ Example (complete pipeline):
   data = await query_db(sql="..."); df = process(data); await save_to_sheet(data=df); print("Done")
 `.trim();
 
-  return tool<typeof ProgrammaticToolCallingSchema>(
-    async (params, config) => {
+  return tool(
+    async (rawParams, config) => {
+      const params = rawParams as { code: string; timeout?: number };
       const { code, timeout = DEFAULT_TIMEOUT } = params;
 
       // Extra params injected by ToolNode (follows web_search pattern)

package/src/tools/ToolNode.ts

@@ -21,7 +21,8 @@ import type { StructuredToolInterface } from '@langchain/core/tools';
 import type * as t from '@/types';
 import { RunnableCallable } from '@/utils';
 import { processToolOutput } from '@/utils/toonFormat';
-import { Constants } from '@/common';
+import { safeDispatchCustomEvent } from '@/utils/events';
+import { Constants, GraphEvents } from '@/common';
 
 /**
  * Helper to check if a value is a Send object
@@ -82,6 +83,12 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
   private programmaticCache?: t.ProgrammaticCache;
   /** Reference to Graph's sessions map for automatic session injection */
   private sessions?: t.ToolSessionMap;
+  /** When true, dispatches ON_TOOL_EXECUTE events instead of invoking tools directly */
+  private eventDrivenMode: boolean = false;
+  /** Tool definitions for event-driven mode */
+  private toolDefinitions?: Map<string, t.LCTool>;
+  /** Agent ID for event-driven mode */
+  private agentId?: string;
 
   constructor({
     tools,
@@ -94,6 +101,9 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     loadRuntimeTools,
     toolRegistry,
     sessions,
+    eventDrivenMode,
+    toolDefinitions,
+    agentId,
   }: t.ToolNodeConstructorParams) {
     super({ name, tags, func: (input, config) => this.run(input, config) });
     this.toolMap = toolMap ?? new Map(tools.map((tool) => [tool.name, tool]));
@@ -104,6 +114,9 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     this.toolUsageCount = new Map<string, number>();
     this.toolRegistry = toolRegistry;
     this.sessions = sessions;
+    this.eventDrivenMode = eventDrivenMode ?? false;
+    this.toolDefinitions = toolDefinitions;
+    this.agentId = agentId;
   }
 
   /**
@@ -316,11 +329,115 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     }
   }
 
+  /**
+   * Execute all tool calls via ON_TOOL_EXECUTE event dispatch.
+   * Used in event-driven mode where the host handles actual tool execution.
+   */
+  private async executeViaEvent(
+    toolCalls: ToolCall[],
+    config: RunnableConfig,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    input: any
+  ): Promise<T> {
+    const requests: t.ToolCallRequest[] = toolCalls.map((call) => {
+      const turn = this.toolUsageCount.get(call.name) ?? 0;
+      this.toolUsageCount.set(call.name, turn + 1);
+      return {
+        id: call.id!,
+        name: call.name,
+        args: call.args as Record<string, unknown>,
+        stepId: this.toolCallStepIds?.get(call.id!),
+        turn,
+      };
+    });
+
+    const results = await new Promise<t.ToolExecuteResult[]>(
+      (resolve, reject) => {
+        const request: t.ToolExecuteBatchRequest = {
+          toolCalls: requests,
+          userId: config.configurable?.user_id as string | undefined,
+          agentId: this.agentId,
+          configurable: config.configurable as
+            | Record<string, unknown>
+            | undefined,
+          metadata: config.metadata as Record<string, unknown> | undefined,
+          resolve,
+          reject,
+        };
+
+        safeDispatchCustomEvent(GraphEvents.ON_TOOL_EXECUTE, request, config);
+      }
+    );
+
+    const outputs: ToolMessage[] = results.map((result) => {
+      const request = requests.find((r) => r.id === result.toolCallId);
+      const toolName = request?.name ?? 'unknown';
+      const stepId = this.toolCallStepIds?.get(result.toolCallId) ?? '';
+
+      let toolMessage: ToolMessage;
+      let contentString: string;
+
+      if (result.status === 'error') {
+        contentString = `Error: ${result.errorMessage ?? 'Unknown error'}\n Please fix your mistakes.`;
+        toolMessage = new ToolMessage({
+          status: 'error',
+          content: contentString,
+          name: toolName,
+          tool_call_id: result.toolCallId,
+        });
+      } else {
+        contentString =
+          typeof result.content === 'string'
+            ? result.content
+            : JSON.stringify(result.content);
+        toolMessage = new ToolMessage({
+          status: 'success',
+          content: contentString,
+          name: toolName,
+          tool_call_id: result.toolCallId,
+        });
+      }
+
+      const tool_call: t.ProcessedToolCall = {
+        args:
+          typeof request?.args === 'string'
+            ? request.args
+            : JSON.stringify(request?.args ?? {}),
+        name: toolName,
+        id: result.toolCallId,
+        output: contentString,
+        progress: 1,
+      };
+
+      const runStepCompletedData = {
+        result: {
+          id: stepId,
+          index: request?.turn ?? 0,
+          type: 'tool_call' as const,
+          tool_call,
+        },
+      };
+
+      safeDispatchCustomEvent(
+        GraphEvents.ON_RUN_STEP_COMPLETED,
+        runStepCompletedData,
+        config
+      );
+
+      return toolMessage;
+    });
+
+    return (Array.isArray(input) ? outputs : { messages: outputs }) as T;
+  }
+
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   protected async run(input: any, config: RunnableConfig): Promise<T> {
     let outputs: (BaseMessage | Command)[];
 
     if (this.isSendInput(input)) {
+      if (this.eventDrivenMode) {
+        return this.executeViaEvent([input.lg_tool_call], config, input);
+      }
       outputs = [await this.runTool(input.lg_tool_call, config)];
     } else {
       let messages: BaseMessage[];
@@ -362,21 +479,26 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
         this.programmaticCache = undefined; // Invalidate cache on toolMap change
       }
 
+      const filteredCalls =
+        aiMessage.tool_calls?.filter((call) => {
+          /**
+           * Filter out:
+           * 1. Already processed tool calls (present in toolMessageIds)
+           * 2. Server tool calls (e.g., web_search with IDs starting with 'srvtoolu_')
+           *    which are executed by the provider's API and don't require invocation
+           */
+          return (
+            (call.id == null || !toolMessageIds.has(call.id)) &&
+            !(call.id?.startsWith('srvtoolu_') ?? false)
+          );
+        }) ?? [];
+
+      if (this.eventDrivenMode && filteredCalls.length > 0) {
+        return this.executeViaEvent(filteredCalls, config, input);
+      }
+
       outputs = await Promise.all(
-        aiMessage.tool_calls
-          ?.filter((call) => {
-            /**
-             * Filter out:
-             * 1. Already processed tool calls (present in toolMessageIds)
-             * 2. Server tool calls (e.g., web_search with IDs starting with 'srvtoolu_')
-             *    which are executed by the provider's API and don't require invocation
-             */
-            return (
-              (call.id == null || !toolMessageIds.has(call.id)) &&
-              !(call.id?.startsWith('srvtoolu_') ?? false)
-            );
-          })
-          .map((call) => this.runTool(call, config)) ?? []
+        filteredCalls.map((call) => this.runTool(call, config))
       );
     }
 

package/src/tools/ToolSearch.ts

@@ -1,5 +1,4 @@
 // src/tools/ToolSearch.ts
-import { z } from 'zod';
 import * as okapibm25Module from 'okapibm25';
 import { config } from 'dotenv';
 
@@ -40,20 +39,25 @@ const MAX_REGEX_COMPLEXITY = 5;
 /** Default search timeout in milliseconds */
 const SEARCH_TIMEOUT = 5000;
 
-/** Zod schema type for tool search parameters */
-type ToolSearchSchema = z.ZodObject<{
-  query: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-  fields: z.ZodDefault<
-    z.ZodOptional<z.ZodArray<z.ZodEnum<['name', 'description', 'parameters']>>>
-  >;
-  max_results: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
-  mcp_server: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString>]>>;
-}>;
+/** JSON schema type for tool search parameters */
+interface ToolSearchSchema {
+  type: 'object';
+  properties: Record<string, unknown>;
+  required: string[];
+}
+
+/** Input params type for tool search */
+interface ToolSearchParams {
+  query?: string;
+  fields?: ('name' | 'description' | 'parameters')[];
+  max_results?: number;
+  mcp_server?: string | string[];
+}
 
 /**
- * Creates the Zod schema with dynamic query description based on mode.
+ * Creates the JSON schema with dynamic query description based on mode.
  * @param mode - The search mode determining query interpretation
- * @returns Zod schema for tool search parameters
+ * @returns JSON schema for tool search parameters
  */
 function createToolSearchSchema(mode: t.ToolSearchMode): ToolSearchSchema {
   const queryDescription =
@@ -61,33 +65,39 @@ function createToolSearchSchema(mode: t.ToolSearchMode): ToolSearchSchema {
       ? 'Search term to find in tool names and descriptions. Case-insensitive substring matching. Optional if mcp_server is provided.'
       : 'Regex pattern to search tool names and descriptions. Optional if mcp_server is provided.';
 
-  return z.object({
-    query: z
-      .string()
-      .max(MAX_PATTERN_LENGTH)
-      .optional()
-      .default('')
-      .describe(queryDescription),
-    fields: z
-      .array(z.enum(['name', 'description', 'parameters']))
-      .optional()
-      .default(['name', 'description'])
-      .describe('Which fields to search. Default: name and description'),
-    max_results: z
-      .number()
-      .int()
-      .min(1)
-      .max(50)
-      .optional()
-      .default(10)
-      .describe('Maximum number of matching tools to return'),
-    mcp_server: z
-      .union([z.string(), z.array(z.string())])
-      .optional()
-      .describe(
-        'Filter to tools from specific MCP server(s). Can be a single server name or array of names. If provided without a query, lists all tools from those servers.'
-      ),
-  });
+  return {
+    type: 'object',
+    properties: {
+      query: {
+        type: 'string',
+        maxLength: MAX_PATTERN_LENGTH,
+        default: '',
+        description: queryDescription,
+      },
+      fields: {
+        type: 'array',
+        items: { type: 'string', enum: ['name', 'description', 'parameters'] },
+        default: ['name', 'description'],
+        description: 'Which fields to search. Default: name and description',
+      },
+      max_results: {
+        type: 'integer',
+        minimum: 1,
+        maximum: 50,
+        default: 10,
+        description: 'Maximum number of matching tools to return',
+      },
+      mcp_server: {
+        oneOf: [
+          { type: 'string' },
+          { type: 'array', items: { type: 'string' } },
+        ],
+        description:
+          'Filter to tools from specific MCP server(s). Can be a single server name or array of names. If provided without a query, lists all tools from those servers.',
+      },
+    },
+    required: [],
+  };
 }
 
 /**
@@ -748,7 +758,7 @@ function formatServerListing(
  */
 function createToolSearch(
   initParams: t.ToolSearchParams = {}
-): DynamicStructuredTool<ReturnType<typeof createToolSearchSchema>> {
+): DynamicStructuredTool {
   const mode: t.ToolSearchMode = initParams.mode ?? 'code_interpreter';
   const defaultOnlyDeferred = initParams.onlyDeferred ?? true;
   const schema = createToolSearchSchema(mode);
@@ -802,10 +812,11 @@ Searches deferred tools by regex pattern.
 ${mcpNote}${toolsListSection}
 `.trim();
 
-  return tool<typeof schema>(
-    async (params, config) => {
+  return tool(
+    async (rawParams, config) => {
+      const params = rawParams as ToolSearchParams;
       const {
-        query,
+        query = '',
         fields = ['name', 'description'],
         max_results = 10,
         mcp_server,
@@ -946,7 +957,7 @@ ${mcpNote}${toolsListSection}
           method: 'POST',
           headers: {
             'Content-Type': 'application/json',
-            'User-Agent': 'LibreChat/1.0',
+            'User-Agent': 'Illuma/1.0',
             'X-API-Key': apiKey,
           },
           body: JSON.stringify(postData),

package/src/tools/__tests__/ProgrammaticToolCalling.integration.test.ts

@@ -4,6 +4,9 @@
  * These tests hit the LIVE Code API and verify end-to-end functionality.
  *
  * Run with: npm test -- ProgrammaticToolCalling.integration.test.ts
+ *
+ * Requires CODE_EXECUTOR_API_KEY environment variable.
+ * Tests are skipped when the API key is not available.
  */
 import { config as dotenvConfig } from 'dotenv';
 dotenvConfig();
@@ -19,19 +22,17 @@ import {
   createProgrammaticToolRegistry,
 } from '@/test/mockTools';
 
-describe('ProgrammaticToolCalling - Live API Integration', () => {
+const apiKey = process.env.CODE_EXECUTOR_API_KEY;
+const shouldSkip = apiKey == null || apiKey === '';
+
+const describeIfApiKey = shouldSkip ? describe.skip : describe;
+
+describeIfApiKey('ProgrammaticToolCalling - Live API Integration', () => {
   let ptcTool: ReturnType<typeof createProgrammaticToolCallingTool>;
   let toolMap: t.ToolMap;
   let toolDefinitions: t.LCTool[];
 
   beforeAll(() => {
-    const apiKey = process.env.CODE_EXECUTOR_API_KEY;
-    if (apiKey == null || apiKey === '') {
-      throw new Error(
-        'CODE_EXECUTOR_API_KEY not set. Required for integration tests.'
-      );
-    }
-
     const tools = [
       createGetTeamMembersTool(),
       createGetExpensesTool(),
@@ -42,7 +43,7 @@ describe('ProgrammaticToolCalling - Live API Integration', () => {
     toolMap = new Map(tools.map((t) => [t.name, t]));
     toolDefinitions = Array.from(createProgrammaticToolRegistry().values());
 
-    ptcTool = createProgrammaticToolCallingTool({ apiKey });
+    ptcTool = createProgrammaticToolCallingTool({ apiKey: apiKey! });
   });
 
   it('executes simple single tool call', async () => {

package/src/tools/__tests__/ToolSearch.integration.test.ts

@@ -4,6 +4,9 @@
  * These tests hit the LIVE Code API and verify end-to-end search functionality.
  *
  * Run with: npm test -- ToolSearch.integration.test.ts
+ *
+ * Requires CODE_EXECUTOR_API_KEY environment variable.
+ * Tests are skipped when the API key is not available.
  */
 import { config as dotenvConfig } from 'dotenv';
 dotenvConfig();
@@ -12,19 +15,17 @@ import { describe, it, expect, beforeAll } from '@jest/globals';
 import { createToolSearch } from '../ToolSearch';
 import { createToolSearchToolRegistry } from '@/test/mockTools';
 
-describe('ToolSearch - Live API Integration', () => {
+const apiKey = process.env.CODE_EXECUTOR_API_KEY;
+const shouldSkip = apiKey == null || apiKey === '';
+
+const describeIfApiKey = shouldSkip ? describe.skip : describe;
+
+describeIfApiKey('ToolSearch - Live API Integration', () => {
   let searchTool: ReturnType<typeof createToolSearch>;
   const toolRegistry = createToolSearchToolRegistry();
 
   beforeAll(() => {
-    const apiKey = process.env.CODE_EXECUTOR_API_KEY;
-    if (apiKey == null || apiKey === '') {
-      throw new Error(
-        'CODE_EXECUTOR_API_KEY not set. Required for integration tests.'
-      );
-    }
-
-    searchTool = createToolSearch({ apiKey, toolRegistry });
+    searchTool = createToolSearch({ apiKey: apiKey!, toolRegistry });
   });
 
   it('searches for expense-related tools', async () => {

package/src/tools/schema.ts

@@ -0,0 +1,37 @@
+import { tool, type StructuredToolInterface } from '@langchain/core/tools';
+import type { LCTool } from '@/types';
+
+/**
+ * Creates a schema-only tool for LLM binding in event-driven mode.
+ * These tools have valid schemas for the LLM to understand but should
+ * never be invoked directly - ToolNode handles execution via events.
+ */
+export function createSchemaOnlyTool(
+  definition: LCTool
+): StructuredToolInterface {
+  const { name, description, parameters, responseFormat } = definition;
+
+  return tool(
+    async () => {
+      throw new Error(
+        `Tool "${name}" should not be invoked directly in event-driven mode. ` +
+          'ToolNode should dispatch ON_TOOL_EXECUTE events instead.'
+      );
+    },
+    {
+      name,
+      description: description ?? '',
+      schema: parameters ?? { type: 'object', properties: {} },
+      responseFormat: responseFormat ?? 'content_and_artifact',
+    }
+  );
+}
+
+/**
+ * Creates schema-only tools for all definitions in an array.
+ */
+export function createSchemaOnlyTools(
+  definitions: LCTool[]
+): StructuredToolInterface[] {
+  return definitions.map((def) => createSchemaOnlyTool(def));
+}