illuma-agents 1.0.37 → 1.0.39

package/src/tools/ProgrammaticToolCalling.ts

@@ -19,7 +19,7 @@ config();
 const imageMessage = 'Image is already displayed to the user';
 const otherMessage = 'File is already downloaded by the user';
 const accessMessage =
-  'Note: Files are READ-ONLY. Save changes to NEW filenames. To access these files in future executions, provide the `session_id` as a parameter (not in your code).';
+  'Note: Files from previous executions are automatically available and can be modified.';
 const emptyOutputMessage =
   'stdout: Empty. Ensure you\'re writing output explicitly.\n';
 
@@ -68,12 +68,6 @@ Rules:
 - Tools are pre-defined—DO NOT write function definitions
 - Only print() output returns to the model`
     ),
-  session_id: z
-    .string()
-    .optional()
-    .describe(
-      'Session ID for file access (same as regular code execution). Files load into /mnt/data/ and are READ-ONLY.'
-    ),
   timeout: z
     .number()
     .int()
@@ -542,7 +536,7 @@ export function formatCompletedResponse(
       }
     }
 
-    formatted += `\nsession_id: ${response.session_id}\n\n${accessMessage}`;
+    formatted += `\n\n${accessMessage}`;
   }
 
   return [
@@ -613,7 +607,7 @@ Rules:
 - Do NOT define \`async def main()\` or call \`asyncio.run()\`—just write code with await
 - Tools are pre-defined—DO NOT write function definitions
 - Only \`print()\` output returns; tool results are raw dicts/lists/strings
-- Use \`session_id\` param for file persistence across calls
+- Generated files are automatically available in /mnt/data/ for subsequent executions
 - Tool names normalized: hyphens→underscores, keywords get \`_tool\` suffix
 
 When to use: loops, conditionals, parallel (\`asyncio.gather\`), multi-step pipelines.
@@ -624,11 +618,15 @@ Example (complete pipeline):
 
   return tool<typeof ProgrammaticToolCallingSchema>(
     async (params, config) => {
-      const { code, session_id, timeout = DEFAULT_TIMEOUT } = params;
+      const { code, timeout = DEFAULT_TIMEOUT } = params;
 
       // Extra params injected by ToolNode (follows web_search pattern)
-      const { toolMap, toolDefs } = (config.toolCall ?? {}) as ToolCall &
-        Partial<t.ProgrammaticCache>;
+      const { toolMap, toolDefs, session_id, _injected_files } =
+        (config.toolCall ?? {}) as ToolCall &
+          Partial<t.ProgrammaticCache> & {
+            session_id?: string;
+            _injected_files?: t.CodeEnvFile[];
+          };
 
       if (toolMap == null || toolMap.size === 0) {
         throw new Error(
@@ -661,9 +659,15 @@ Example (complete pipeline):
           );
         }
 
-        // Fetch files from previous session if session_id is provided
+        /**
+         * File injection priority:
+         * 1. Use _injected_files from ToolNode (avoids /files endpoint race condition)
+         * 2. Fall back to fetching from /files endpoint if session_id provided but no injected files
+         */
         let files: t.CodeEnvFile[] | undefined;
-        if (session_id != null && session_id.length > 0) {
+        if (_injected_files && _injected_files.length > 0) {
+          files = _injected_files;
+        } else if (session_id != null && session_id.length > 0) {
           files = await fetchSessionFiles(baseUrl, apiKey, session_id, proxy);
         }
 

package/src/tools/ToolNode.ts

@@ -80,6 +80,8 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
   private toolRegistry?: t.LCToolRegistry;
   /** Cached programmatic tools (computed once on first PTC call) */
   private programmaticCache?: t.ProgrammaticCache;
+  /** Reference to Graph's sessions map for automatic session injection */
+  private sessions?: t.ToolSessionMap;
 
   constructor({
     tools,
@@ -91,6 +93,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     handleToolErrors,
     loadRuntimeTools,
     toolRegistry,
+    sessions,
   }: t.ToolNodeConstructorParams) {
     super({ name, tags, func: (input, config) => this.run(input, config) });
     this.toolMap = toolMap ?? new Map(tools.map((tool) => [tool.name, tool]));
@@ -100,6 +103,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     this.errorHandler = errorHandler;
     this.toolUsageCount = new Map<string, number>();
     this.toolRegistry = toolRegistry;
+    this.sessions = sessions;
   }
 
   /**
@@ -170,13 +174,46 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
           toolMap,
           toolDefs,
         };
-      } else if (call.name === Constants.TOOL_SEARCH_REGEX) {
+      } else if (call.name === Constants.TOOL_SEARCH) {
         invokeParams = {
           ...invokeParams,
           toolRegistry: this.toolRegistry,
         };
       }
 
+      /**
+       * Inject session context for code execution tools when available.
+       * Each file uses its own session_id (supporting multi-session file tracking).
+       * Both session_id and _injected_files are injected directly to invokeParams
+       * (not inside args) so they bypass Zod schema validation and reach config.toolCall.
+       */
+      if (
+        call.name === Constants.EXECUTE_CODE ||
+        call.name === Constants.PROGRAMMATIC_TOOL_CALLING
+      ) {
+        const codeSession = this.sessions?.get(Constants.EXECUTE_CODE) as
+          | t.CodeSessionContext
+          | undefined;
+        if (codeSession?.files != null && codeSession.files.length > 0) {
+          /**
+           * Convert tracked files to CodeEnvFile format for the API.
+           * Each file uses its own session_id (set when file was created).
+           * This supports files from multiple parallel/sequential executions.
+           */
+          const fileRefs: t.CodeEnvFile[] = codeSession.files.map((file) => ({
+            session_id: file.session_id ?? codeSession.session_id,
+            id: file.id,
+            name: file.name,
+          }));
+          /** Inject latest session_id and files - bypasses Zod, reaches config.toolCall */
+          invokeParams = {
+            ...invokeParams,
+            session_id: codeSession.session_id,
+            _injected_files: fileRefs,
+          };
+        }
+      }
+
       const output = await tool.invoke(invokeParams, config);
 
       // Handle Command outputs directly
@@ -354,6 +391,13 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     )[] = [];
     let parentCommand: Command | null = null;
 
+    /**
+     * Collect handoff commands (Commands with string goto and Command.PARENT)
+     * for potential parallel handoff aggregation
+     */
+    const handoffCommands: Command[] = [];
+    const nonCommandOutputs: BaseMessage[] = [];
+
     for (const output of outputs) {
       if (isCommand(output)) {
         if (
@@ -361,6 +405,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
           Array.isArray(output.goto) &&
           output.goto.every((send): send is Send => isSend(send))
         ) {
+          /** Aggregate Send-based commands */
           if (parentCommand) {
             (parentCommand.goto as Send[]).push(...(output.goto as Send[]));
           } else {
@@ -369,16 +414,84 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
               goto: output.goto,
             });
           }
+        } else if (output.graph === Command.PARENT) {
+          /**
+           * Handoff Command with destination.
+           * Handle both string ('agent') and array (['agent']) formats.
+           * Collect for potential parallel aggregation.
+           */
+          const goto = output.goto;
+          const isSingleStringDest = typeof goto === 'string';
+          const isSingleArrayDest =
+            Array.isArray(goto) &&
+            goto.length === 1 &&
+            typeof goto[0] === 'string';
+
+          if (isSingleStringDest || isSingleArrayDest) {
+            handoffCommands.push(output);
+          } else {
+            /** Multi-destination or other command - pass through */
+            combinedOutputs.push(output);
+          }
         } else {
+          /** Other commands - pass through */
           combinedOutputs.push(output);
         }
       } else {
+        nonCommandOutputs.push(output);
         combinedOutputs.push(
           Array.isArray(input) ? [output] : { messages: [output] }
         );
       }
     }
 
+    /**
+     * Handle handoff commands - convert to Send objects for parallel execution
+     * when multiple handoffs are requested
+     */
+    if (handoffCommands.length > 1) {
+      /**
+       * Multiple parallel handoffs - convert to Send objects.
+       * Each Send carries its own state with the appropriate messages.
+       * This enables LLM-initiated parallel execution when calling multiple
+       * transfer tools simultaneously.
+       */
+
+      /** Collect all destinations for sibling tracking */
+      const allDestinations = handoffCommands.map((cmd) => {
+        const goto = cmd.goto;
+        return typeof goto === 'string' ? goto : (goto as string[])[0];
+      });
+
+      const sends = handoffCommands.map((cmd, idx) => {
+        const destination = allDestinations[idx];
+        /** Get siblings (other destinations, not this one) */
+        const siblings = allDestinations.filter((d) => d !== destination);
+
+        /** Add siblings to ToolMessage additional_kwargs */
+        const update = cmd.update as { messages?: BaseMessage[] } | undefined;
+        if (update && update.messages) {
+          for (const msg of update.messages) {
+            if (msg.getType() === 'tool') {
+              (msg as ToolMessage).additional_kwargs.handoff_parallel_siblings =
+                siblings;
+            }
+          }
+        }
+
+        return new Send(destination, cmd.update);
+      });
+
+      const parallelCommand = new Command({
+        graph: Command.PARENT,
+        goto: sends,
+      });
+      combinedOutputs.push(parallelCommand);
+    } else if (handoffCommands.length === 1) {
+      /** Single handoff - pass through as-is */
+      combinedOutputs.push(handoffCommands[0]);
+    }
+
     if (parentCommand) {
       combinedOutputs.push(parentCommand);
     }