Function maybeLoadToolsFromExternalFile

src/util/file.ts:487–627

(
  tools: any,
  vars?: Record<string, VarValue>,
)

 * @throws {Error} If the loaded tools are in an invalid format
 */
export async function maybeLoadToolsFromExternalFile(
  tools: any,
  vars?: Record<string, VarValue>,
): Promise<any> {
  const rendered = renderVarsInObject(tools, vars);

  // Check if this is a Python/JS file reference with function name
  // These need special handling to execute the function and get the result
  if (typeof rendered === 'string' && rendered.startsWith('file://')) {
    const { filePath, functionName } = parseFileUrl(rendered);

    if (functionName && (filePath.endsWith('.py') || isJavascriptFile(filePath))) {
      // Execute the function to get tool definitions
      const fileType = filePath.endsWith('.py') ? 'Python' : 'JavaScript';
      logger.debug(
        `[maybeLoadToolsFromExternalFile] Loading tools from ${fileType} file: ${filePath}:${functionName}`,
      );

      try {
        let toolDefinitions: any;

        if (filePath.endsWith('.py')) {
          // Resolve Python path relative to config base directory (same as JavaScript)
          const absPath = safeResolve(cliState.basePath || process.cwd(), filePath);
          logger.debug(`[maybeLoadToolsFromExternalFile] Resolved Python path: ${absPath}`);
          toolDefinitions = await runPython(absPath, functionName, []);
        } else {
          // Use safeResolve for security (prevents path traversal)
          const absPath = safeResolve(cliState.basePath || process.cwd(), filePath);
          logger.debug(`[maybeLoadToolsFromExternalFile] Resolved JavaScript path: ${absPath}`);

          const module = await importModule(absPath);
          const fn = module[functionName] || module.default?.[functionName];

          if (typeof fn !== 'function') {
            const availableExports = Object.keys(module).filter((k) => k !== 'default');
            const basePath = cliState.basePath || process.cwd();
            throw new Error(
              `Function "${functionName}" not found in ${filePath}. ` +
                `Available exports: ${availableExports.length > 0 ? availableExports.join(', ') : '(none)'}\n` +
                `Resolved from: ${basePath}`,
            );
          }

          // Call the function - handle both sync and async functions
          toolDefinitions = await Promise.resolve(fn());
        }

        // Validate the result - must be array or object, not primitive
        if (
          !toolDefinitions ||
          typeof toolDefinitions === 'string' ||
          typeof toolDefinitions === 'number' ||
          typeof toolDefinitions === 'boolean'
        ) {
          throw new Error(
            `Function "${functionName}" must return an array or object of tool definitions, ` +
              `but returned: ${toolDefinitions === null ? 'null' : typeof toolDefinitions}`,