@illuma-ai/agents 1.0.81

package/src/tools/__tests__/BrowserTools.test.ts

@@ -0,0 +1,265 @@
+import { describe, it, expect, beforeEach, jest as _jest } from '@jest/globals';
+import {
+  createBrowserTools,
+  hasBrowserCapability,
+  EBrowserTools,
+  type BrowserToolResponse,
+} from '../BrowserTools';
+
+describe('BrowserTools', () => {
+  describe('EBrowserTools enum', () => {
+    it('should have all expected browser tool names', () => {
+      expect(EBrowserTools.CLICK).toBe('browser_click');
+      expect(EBrowserTools.TYPE).toBe('browser_type');
+      expect(EBrowserTools.NAVIGATE).toBe('browser_navigate');
+      expect(EBrowserTools.SCROLL).toBe('browser_scroll');
+      expect(EBrowserTools.EXTRACT).toBe('browser_extract');
+      expect(EBrowserTools.HOVER).toBe('browser_hover');
+      expect(EBrowserTools.WAIT).toBe('browser_wait');
+      expect(EBrowserTools.BACK).toBe('browser_back');
+      expect(EBrowserTools.SCREENSHOT).toBe('browser_screenshot');
+      expect(EBrowserTools.GET_PAGE_STATE).toBe('browser_get_page_state');
+      expect(EBrowserTools.KEYPRESS).toBe('browser_keypress');
+      expect(EBrowserTools.SWITCH_TAB).toBe('browser_switch_tab');
+    });
+
+    it('should have exactly 12 browser tools', () => {
+      expect(Object.keys(EBrowserTools).length).toBe(12);
+    });
+  });
+
+  describe('hasBrowserCapability', () => {
+    it('should return false when no request is provided', () => {
+      expect(hasBrowserCapability()).toBe(false);
+      expect(hasBrowserCapability(undefined)).toBe(false);
+    });
+
+    it('should return false when request has no headers', () => {
+      expect(hasBrowserCapability({})).toBe(false);
+      expect(hasBrowserCapability({ headers: undefined })).toBe(false);
+    });
+
+    it('should return true when X-Ranger-Browser-Extension header is true', () => {
+      const req = {
+        headers: {
+          'x-ranger-browser-extension': 'true',
+        },
+      };
+      expect(hasBrowserCapability(req)).toBe(true);
+    });
+
+    it('should return true when X-Ranger-Browser-Capable header is true', () => {
+      const req = {
+        headers: {
+          'x-ranger-browser-capable': 'true',
+        },
+      };
+      expect(hasBrowserCapability(req)).toBe(true);
+    });
+
+    it('should return false when browser headers are not true', () => {
+      const req = {
+        headers: {
+          'x-ranger-browser-extension': 'false',
+          'x-ranger-browser-capable': 'false',
+        },
+      };
+      expect(hasBrowserCapability(req)).toBe(false);
+    });
+
+    it('should return false when browser headers are missing', () => {
+      const req = {
+        headers: {
+          'content-type': 'application/json',
+        },
+      };
+      expect(hasBrowserCapability(req)).toBe(false);
+    });
+  });
+
+  describe('createBrowserTools', () => {
+    let tools: ReturnType<typeof createBrowserTools>;
+
+    beforeEach(() => {
+      tools = createBrowserTools();
+    });
+
+    it('should create exactly 12 browser tools', () => {
+      expect(tools.length).toBe(12);
+    });
+
+    it('should create tools with correct names', () => {
+      const toolNames = tools.map((t) => t.name);
+      expect(toolNames).toContain('browser_click');
+      expect(toolNames).toContain('browser_type');
+      expect(toolNames).toContain('browser_navigate');
+      expect(toolNames).toContain('browser_scroll');
+      expect(toolNames).toContain('browser_extract');
+      expect(toolNames).toContain('browser_hover');
+      expect(toolNames).toContain('browser_wait');
+      expect(toolNames).toContain('browser_back');
+      expect(toolNames).toContain('browser_screenshot');
+      expect(toolNames).toContain('browser_get_page_state');
+    });
+
+    it('should have descriptions for all tools', () => {
+      for (const tool of tools) {
+        expect(tool.description).toBeDefined();
+        expect(tool.description.length).toBeGreaterThan(0);
+      }
+    });
+
+    describe('browser_click tool', () => {
+      it('should return requiresBrowserExecution marker', async () => {
+        const clickTool = tools.find((t) => t.name === 'browser_click');
+        expect(clickTool).toBeDefined();
+
+        const result = await clickTool!.invoke({ index: 5 });
+        const parsed: BrowserToolResponse = JSON.parse(result);
+
+        expect(parsed.requiresBrowserExecution).toBe(true);
+        expect(parsed.action).toBe('click');
+        expect(parsed.args).toEqual({ index: 5 });
+      });
+    });
+
+    describe('browser_type tool', () => {
+      it('should return requiresBrowserExecution marker with all args', async () => {
+        const typeTool = tools.find((t) => t.name === 'browser_type');
+        expect(typeTool).toBeDefined();
+
+        const result = await typeTool!.invoke({
+          index: 3,
+          text: 'Hello World',
+          pressEnter: true,
+        });
+        const parsed: BrowserToolResponse = JSON.parse(result);
+
+        expect(parsed.requiresBrowserExecution).toBe(true);
+        expect(parsed.action).toBe('type');
+        expect(parsed.args.index).toBe(3);
+        expect(parsed.args.text).toBe('Hello World');
+        expect(parsed.args.pressEnter).toBe(true);
+      });
+    });
+
+    describe('browser_navigate tool', () => {
+      it('should return requiresBrowserExecution marker with URL', async () => {
+        const navigateTool = tools.find((t) => t.name === 'browser_navigate');
+        expect(navigateTool).toBeDefined();
+
+        const result = await navigateTool!.invoke({
+          url: 'https://example.com',
+        });
+        const parsed: BrowserToolResponse = JSON.parse(result);
+
+        expect(parsed.requiresBrowserExecution).toBe(true);
+        expect(parsed.action).toBe('navigate');
+        expect(parsed.args.url).toBe('https://example.com');
+      });
+    });
+
+    describe('browser_scroll tool', () => {
+      it('should return requiresBrowserExecution marker with direction', async () => {
+        const scrollTool = tools.find((t) => t.name === 'browser_scroll');
+        expect(scrollTool).toBeDefined();
+
+        const result = await scrollTool!.invoke({
+          direction: 'down',
+          amount: 500,
+        });
+        const parsed: BrowserToolResponse = JSON.parse(result);
+
+        expect(parsed.requiresBrowserExecution).toBe(true);
+        expect(parsed.action).toBe('scroll');
+        expect(parsed.args.direction).toBe('down');
+        expect(parsed.args.amount).toBe(500);
+      });
+    });
+
+    describe('browser_hover tool', () => {
+      it('should return requiresBrowserExecution marker with index', async () => {
+        const hoverTool = tools.find((t) => t.name === 'browser_hover');
+        expect(hoverTool).toBeDefined();
+
+        const result = await hoverTool!.invoke({ index: 2 });
+        const parsed: BrowserToolResponse = JSON.parse(result);
+
+        expect(parsed.requiresBrowserExecution).toBe(true);
+        expect(parsed.action).toBe('hover');
+        expect(parsed.args.index).toBe(2);
+      });
+    });
+
+    describe('browser_wait tool', () => {
+      it('should return requiresBrowserExecution marker with duration', async () => {
+        const waitTool = tools.find((t) => t.name === 'browser_wait');
+        expect(waitTool).toBeDefined();
+
+        const result = await waitTool!.invoke({ duration: 2000 });
+        const parsed: BrowserToolResponse = JSON.parse(result);
+
+        expect(parsed.requiresBrowserExecution).toBe(true);
+        expect(parsed.action).toBe('wait');
+        expect(parsed.args.duration).toBe(2000);
+      });
+    });
+
+    describe('browser_back tool', () => {
+      it('should return requiresBrowserExecution marker', async () => {
+        const backTool = tools.find((t) => t.name === 'browser_back');
+        expect(backTool).toBeDefined();
+
+        const result = await backTool!.invoke({});
+        const parsed: BrowserToolResponse = JSON.parse(result);
+
+        expect(parsed.requiresBrowserExecution).toBe(true);
+        expect(parsed.action).toBe('back');
+      });
+    });
+
+    describe('browser_screenshot tool', () => {
+      it('should return requiresBrowserExecution marker', async () => {
+        const screenshotTool = tools.find(
+          (t) => t.name === 'browser_screenshot'
+        );
+        expect(screenshotTool).toBeDefined();
+
+        const result = await screenshotTool!.invoke({});
+        const parsed: BrowserToolResponse = JSON.parse(result);
+
+        expect(parsed.requiresBrowserExecution).toBe(true);
+        expect(parsed.action).toBe('screenshot');
+      });
+    });
+
+    describe('browser_get_page_state tool', () => {
+      it('should return requiresBrowserExecution marker', async () => {
+        const pageStateTool = tools.find(
+          (t) => t.name === 'browser_get_page_state'
+        );
+        expect(pageStateTool).toBeDefined();
+
+        const result = await pageStateTool!.invoke({});
+        const parsed: BrowserToolResponse = JSON.parse(result);
+
+        expect(parsed.requiresBrowserExecution).toBe(true);
+        expect(parsed.action).toBe('get_page_state');
+      });
+    });
+
+    describe('browser_extract tool', () => {
+      it('should return requiresBrowserExecution marker', async () => {
+        const extractTool = tools.find((t) => t.name === 'browser_extract');
+        expect(extractTool).toBeDefined();
+
+        const result = await extractTool!.invoke({ query: 'main content' });
+        const parsed: BrowserToolResponse = JSON.parse(result);
+
+        expect(parsed.requiresBrowserExecution).toBe(true);
+        expect(parsed.action).toBe('extract');
+        expect(parsed.args.query).toBe('main content');
+      });
+    });
+  });
+});

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

@@ -0,0 +1,319 @@
+// src/tools/__tests__/ProgrammaticToolCalling.integration.test.ts
+/**
+ * Integration tests for Programmatic Tool Calling.
+ * 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();
+
+import { describe, it, expect, beforeAll } from '@jest/globals';
+import type * as t from '@/types';
+import { createProgrammaticToolCallingTool } from '../ProgrammaticToolCalling';
+import {
+  createGetTeamMembersTool,
+  createGetExpensesTool,
+  createGetWeatherTool,
+  createCalculatorTool,
+  createProgrammaticToolRegistry,
+} from '@/test/mockTools';
+
+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 tools = [
+      createGetTeamMembersTool(),
+      createGetExpensesTool(),
+      createGetWeatherTool(),
+      createCalculatorTool(),
+    ];
+
+    toolMap = new Map(tools.map((t) => [t.name, t]));
+    toolDefinitions = Array.from(createProgrammaticToolRegistry().values());
+
+    ptcTool = createProgrammaticToolCallingTool({ apiKey: apiKey! });
+  });
+
+  it('executes simple single tool call', async () => {
+    const args = {
+      code: `
+result = await get_weather(city="San Francisco")
+print(f"Temperature: {result['temperature']}°F")
+print(f"Condition: {result['condition']}")
+      `,
+    };
+    const toolCall = {
+      name: 'programmatic_code_execution',
+      args,
+      toolMap,
+      toolDefs: toolDefinitions,
+    };
+
+    const output = await ptcTool.invoke(args, { toolCall });
+
+    // When responseFormat is 'content_and_artifact', invoke() returns just the content
+    // The artifact is available via other methods or when used in a graph
+    expect(typeof output).toBe('string');
+    expect(output).toContain('stdout:');
+    expect(output).toContain('Temperature: 65°F');
+    expect(output).toContain('Condition: Foggy');
+  }, 10000);
+
+  it('executes sequential tool calls in a loop', async () => {
+    const args = {
+      code: `
+team = await get_team_members()
+print(f"Team size: {len(team)}")
+
+total = 0
+for member in team:
+    expenses = await get_expenses(user_id=member['id'])
+    member_total = sum(e['amount'] for e in expenses)
+    total += member_total
+    print(f"{member['name']}: \${member_total:.2f}")
+
+print(f"Grand total: \${total:.2f}")
+      `,
+    };
+    const toolCall = {
+      name: 'programmatic_code_execution',
+      args,
+      toolMap,
+      toolDefs: toolDefinitions,
+    };
+
+    const output = await ptcTool.invoke(args, { toolCall });
+
+    expect(output).toContain('Team size: 3');
+    expect(output).toContain('Alice:');
+    expect(output).toContain('Bob:');
+    expect(output).toContain('Charlie:');
+    expect(output).toContain('Grand total:');
+  }, 15000);
+
+  it('executes parallel tool calls with asyncio.gather', async () => {
+    const args = {
+      code: `
+import asyncio
+
+cities = ["San Francisco", "New York", "London"]
+results = await asyncio.gather(*[
+    get_weather(city=city)
+    for city in cities
+])
+
+for city, weather in zip(cities, results):
+    print(f"{city}: {weather['temperature']}°F, {weather['condition']}")
+      `,
+    };
+    const toolCall = {
+      name: 'programmatic_code_execution',
+      args,
+      toolMap,
+      toolDefs: toolDefinitions,
+    };
+
+    const output = await ptcTool.invoke(args, { toolCall });
+
+    expect(output).toContain('San Francisco: 65°F, Foggy');
+    expect(output).toContain('New York: 75°F, Sunny');
+    expect(output).toContain('London: 55°F, Rainy');
+  }, 10000);
+
+  it('handles conditional logic', async () => {
+    const args = {
+      code: `
+team = await get_team_members()
+high_spenders = []
+
+for member in team:
+    expenses = await get_expenses(user_id=member['id'])
+    total = sum(e['amount'] for e in expenses)
+    if total > 300:
+        high_spenders.append((member['name'], total))
+
+if high_spenders:
+    print("High spenders (over $300):")
+    for name, amount in high_spenders:
+        print(f"  {name}: \${amount:.2f}")
+else:
+    print("No high spenders found.")
+      `,
+    };
+    const toolCall = {
+      name: 'programmatic_code_execution',
+      args,
+      toolMap,
+      toolDefs: toolDefinitions,
+    };
+
+    const output = await ptcTool.invoke(args, { toolCall });
+
+    expect(output).toContain('High spenders');
+    expect(output).toContain('Bob:');
+    expect(output).toContain('Charlie:');
+  }, 15000);
+
+  it('handles early termination with break', async () => {
+    const args = {
+      code: `
+team = await get_team_members()
+
+for member in team:
+    expenses = await get_expenses(user_id=member['id'])
+    if any(e['category'] == 'equipment' for e in expenses):
+        print(f"First member with equipment: {member['name']}")
+        equipment_total = sum(e['amount'] for e in expenses if e['category'] == 'equipment')
+        print(f"Equipment total: \${equipment_total:.2f}")
+        break
+else:
+    print("No equipment expenses found")
+      `,
+    };
+    const toolCall = {
+      name: 'programmatic_code_execution',
+      args,
+      toolMap,
+      toolDefs: toolDefinitions,
+    };
+
+    const output = await ptcTool.invoke(args, { toolCall });
+
+    expect(output).toContain('First member with equipment: Charlie');
+    expect(output).toContain('Equipment total: $500.00');
+  }, 15000);
+
+  it('handles tool execution errors gracefully', async () => {
+    const args = {
+      code: `
+cities = ["San Francisco", "InvalidCity", "New York"]
+
+for city in cities:
+    try:
+        weather = await get_weather(city=city)
+        print(f"{city}: {weather['temperature']}°F")
+    except Exception as e:
+        print(f"{city}: Error - {e}")
+      `,
+    };
+    const toolCall = {
+      name: 'programmatic_code_execution',
+      args,
+      toolMap,
+      toolDefs: toolDefinitions,
+    };
+
+    const output = await ptcTool.invoke(args, { toolCall });
+
+    expect(output).toContain('San Francisco: 65°F');
+    expect(output).toContain('InvalidCity: Error');
+    expect(output).toContain('New York: 75°F');
+  }, 15000);
+
+  it('uses calculator tool', async () => {
+    const args = {
+      code: `
+result1 = await calculator(expression="2 + 2 * 3")
+result2 = await calculator(expression="(10 + 5) / 3")
+
+print(f"2 + 2 * 3 = {result1['result']}")
+print(f"(10 + 5) / 3 = {result2['result']:.2f}")
+      `,
+    };
+    const toolCall = {
+      name: 'programmatic_code_execution',
+      args,
+      toolMap,
+      toolDefs: toolDefinitions,
+    };
+
+    const output = await ptcTool.invoke(args, { toolCall });
+
+    expect(output).toContain('2 + 2 * 3 = 8');
+    expect(output).toContain('(10 + 5) / 3 = 5.00');
+  }, 10000);
+
+  it('mixes parallel and sequential execution', async () => {
+    const args = {
+      code: `
+import asyncio
+
+# Step 1: Get team (sequential)
+team = await get_team_members()
+print(f"Fetched {len(team)} team members")
+
+# Step 2: Get all expenses in parallel
+all_expenses = await asyncio.gather(*[
+    get_expenses(user_id=member['id'])
+    for member in team
+])
+
+# Step 3: Process
+print("\\nExpense summary:")
+for member, expenses in zip(team, all_expenses):
+    total = sum(e['amount'] for e in expenses)
+    print(f"  {member['name']}: \${total:.2f} ({len(expenses)} items)")
+      `,
+    };
+    const toolCall = {
+      name: 'programmatic_code_execution',
+      args,
+      toolMap,
+      toolDefs: toolDefinitions,
+    };
+
+    const output = await ptcTool.invoke(args, { toolCall });
+
+    expect(output).toContain('Fetched 3 team members');
+    expect(output).toContain('Expense summary:');
+    expect(output).toContain('Alice:');
+    expect(output).toContain('Bob:');
+    expect(output).toContain('Charlie:');
+    expect(output).toContain('(2 items)');
+    expect(output).toContain('(3 items)');
+  }, 15000);
+
+  it('uses only provided tool definitions (subset)', async () => {
+    const weatherToolDef = toolDefinitions.find(
+      (t) => t.name === 'get_weather'
+    );
+
+    const args = {
+      code: `
+import asyncio
+
+sf, nyc = await asyncio.gather(
+    get_weather(city="San Francisco"),
+    get_weather(city="New York")
+)
+
+print(f"SF: {sf['temperature']}°F vs NYC: {nyc['temperature']}°F")
+difference = abs(sf['temperature'] - nyc['temperature'])
+print(f"Temperature difference: {difference}°F")
+      `,
+    };
+    const toolCall = {
+      name: 'programmatic_code_execution',
+      args,
+      toolMap,
+      toolDefs: [weatherToolDef!],
+    };
+
+    const output = await ptcTool.invoke(args, { toolCall });
+
+    expect(output).toContain('SF: 65°F vs NYC: 75°F');
+    expect(output).toContain('Temperature difference: 10°F');
+  }, 10000);
+});