@illuma-ai/agents 1.0.90 → 1.0.94

package/src/test/mockTools.js

@@ -0,0 +1,340 @@
+// src/test/mockTools.ts
+/**
+ * Shared mock tools for testing across all test scripts.
+ * Centralizes tool definitions to follow DRY principles.
+ */
+import { tool } from '@langchain/core/tools';
+// ============================================================================
+// Mock Tool Implementations
+// ============================================================================
+/**
+ * Mock get_team_members tool - returns list of team members
+ */
+export function createGetTeamMembersTool() {
+    return tool(async () => {
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        return [
+            { id: 'u1', name: 'Alice', department: 'Engineering' },
+            { id: 'u2', name: 'Bob', department: 'Marketing' },
+            { id: 'u3', name: 'Charlie', department: 'Engineering' },
+        ];
+    }, {
+        name: 'get_team_members',
+        description: 'Get list of team members. Returns array of objects with id, name, and department fields.',
+        schema: { type: 'object', properties: {}, required: [] },
+    });
+}
+/**
+ * Mock get_expenses tool - returns expense records for a user
+ */
+export function createGetExpensesTool() {
+    const expenseData = {
+        u1: [
+            { amount: 150.0, category: 'travel' },
+            { amount: 75.5, category: 'meals' },
+        ],
+        u2: [
+            { amount: 200.0, category: 'marketing' },
+            { amount: 50.0, category: 'meals' },
+            { amount: 300.0, category: 'events' },
+        ],
+        u3: [
+            { amount: 500.0, category: 'equipment' },
+            { amount: 120.0, category: 'travel' },
+            { amount: 80.0, category: 'meals' },
+        ],
+    };
+    return tool(async (input) => {
+        const { user_id } = input;
+        await new Promise((resolve) => setTimeout(resolve, 30));
+        return expenseData[user_id] ?? [];
+    }, {
+        name: 'get_expenses',
+        description: 'Get expense records for a user. Returns array of objects with amount and category fields.',
+        schema: {
+            type: 'object',
+            properties: {
+                user_id: {
+                    type: 'string',
+                    description: 'The user ID to fetch expenses for',
+                },
+            },
+            required: ['user_id'],
+        },
+    });
+}
+/**
+ * Mock get_weather tool - returns weather data for a city
+ */
+export function createGetWeatherTool() {
+    const weatherData = {
+        'San Francisco': { temperature: 65, condition: 'Foggy' },
+        'New York': { temperature: 75, condition: 'Sunny' },
+        London: { temperature: 55, condition: 'Rainy' },
+        Tokyo: { temperature: 80, condition: 'Humid' },
+        SF: { temperature: 65, condition: 'Foggy' },
+        NYC: { temperature: 75, condition: 'Sunny' },
+    };
+    return tool(async (input) => {
+        const { city } = input;
+        await new Promise((resolve) => setTimeout(resolve, 40));
+        const weather = weatherData[city];
+        if (!weather) {
+            throw new Error(`Weather data not available for city: ${city}`);
+        }
+        return weather;
+    }, {
+        name: 'get_weather',
+        description: 'Get current weather for a city. Returns object with temperature (number) and condition (string) fields.',
+        schema: {
+            type: 'object',
+            properties: {
+                city: { type: 'string', description: 'City name' },
+            },
+            required: ['city'],
+        },
+    });
+}
+/**
+ * Mock calculator tool - evaluates mathematical expressions
+ */
+export function createCalculatorTool() {
+    return tool(async (input) => {
+        const { expression } = input;
+        await new Promise((resolve) => setTimeout(resolve, 10));
+        // Simple eval for demo (in production, use a proper math parser)
+        const result = eval(expression);
+        return { expression, result };
+    }, {
+        name: 'calculator',
+        description: 'Evaluate a mathematical expression',
+        schema: {
+            type: 'object',
+            properties: {
+                expression: {
+                    type: 'string',
+                    description: 'Mathematical expression to evaluate',
+                },
+            },
+            required: ['expression'],
+        },
+    });
+}
+// ============================================================================
+// Tool Registry Definitions
+// ============================================================================
+/**
+ * Creates a tool registry for programmatic tool calling tests.
+ * Tools are configured with allowed_callers to demonstrate classification.
+ */
+export function createProgrammaticToolRegistry() {
+    const toolDefs = [
+        {
+            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'], // Programmatic-only
+            defer_loading: false,
+        },
+        {
+            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'], // Programmatic-only
+            defer_loading: false,
+        },
+        {
+            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: ['direct', 'code_execution'], // Both contexts
+            defer_loading: false,
+        },
+        {
+            name: 'calculator',
+            description: 'Evaluate a mathematical expression',
+            parameters: {
+                type: 'object',
+                properties: {
+                    expression: {
+                        type: 'string',
+                        description: 'Mathematical expression to evaluate',
+                    },
+                },
+                required: ['expression'],
+            },
+            allowed_callers: ['code_execution'], // Programmatic-only
+            defer_loading: false,
+        },
+    ];
+    return new Map(toolDefs.map((t) => [t.name, t]));
+}
+/**
+ * Creates a sample tool registry for tool search tests.
+ * Includes mix of deferred and non-deferred tools.
+ */
+export function createToolSearchToolRegistry() {
+    const tools = [
+        {
+            name: 'get_expenses',
+            description: 'Retrieve expense records from the database. Supports filtering by date range, category, and amount.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    start_date: {
+                        type: 'string',
+                        description: 'Start date for filtering',
+                    },
+                    end_date: { type: 'string', description: 'End date for filtering' },
+                    category: { type: 'string', description: 'Expense category' },
+                },
+            },
+            defer_loading: true,
+        },
+        {
+            name: 'calculate_expense_totals',
+            description: 'Calculate total expenses by category or time period. Returns aggregated financial data.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    group_by: {
+                        type: 'string',
+                        description: 'Group by category or month',
+                    },
+                },
+            },
+            defer_loading: true,
+        },
+        {
+            name: 'create_budget',
+            description: 'Create a new budget plan with spending limits for different categories.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    name: { type: 'string', description: 'Budget name' },
+                    limits: { type: 'object', description: 'Category spending limits' },
+                },
+            },
+            defer_loading: true,
+        },
+        {
+            name: 'get_weather',
+            description: 'Get current weather conditions for a specified location.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    location: { type: 'string', description: 'City or coordinates' },
+                },
+            },
+            defer_loading: true,
+        },
+        {
+            name: 'get_forecast',
+            description: 'Get weather forecast for the next 7 days for a location.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    location: { type: 'string', description: 'City or coordinates' },
+                    days: { type: 'number', description: 'Number of days to forecast' },
+                },
+            },
+            defer_loading: true,
+        },
+        {
+            name: 'send_email',
+            description: 'Send an email to one or more recipients with attachments support.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    to: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Recipients',
+                    },
+                    subject: { type: 'string', description: 'Email subject' },
+                    body: { type: 'string', description: 'Email body' },
+                },
+            },
+            defer_loading: true,
+        },
+        {
+            name: 'search_files',
+            description: 'Search for files in the file system by name or content.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    query: { type: 'string', description: 'Search query' },
+                    path: { type: 'string', description: 'Directory to search in' },
+                },
+            },
+            defer_loading: true,
+        },
+        {
+            name: 'run_database_query',
+            description: 'Execute a SQL query against the database and return results.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    query: { type: 'string', description: 'SQL query to execute' },
+                    database: { type: 'string', description: 'Target database' },
+                },
+            },
+            defer_loading: true,
+        },
+        {
+            name: 'generate_report',
+            description: 'Generate a PDF or Excel report from data with customizable templates.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    template: { type: 'string', description: 'Report template name' },
+                    format: { type: 'string', description: 'Output format: pdf or xlsx' },
+                    data: { type: 'object', description: 'Data to include in report' },
+                },
+            },
+            defer_loading: true,
+        },
+        {
+            name: 'translate_text',
+            description: 'Translate text between languages using machine translation.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    text: { type: 'string', description: 'Text to translate' },
+                    source_lang: { type: 'string', description: 'Source language code' },
+                    target_lang: { type: 'string', description: 'Target language code' },
+                },
+            },
+            defer_loading: true,
+        },
+        {
+            name: 'calculator',
+            description: 'Perform mathematical calculations. Supports basic arithmetic and scientific functions.',
+            defer_loading: false, // Not deferred - should be excluded by default
+        },
+    ];
+    return new Map(tools.map((t) => [t.name, t]));
+}
+//# sourceMappingURL=mockTools.js.map

package/src/test/mockTools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mockTools.js","sourceRoot":"","sources":["mockTools.ts"],"names":[],"mappings":"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"}

package/src/tools/AskUser.ts

@@ -0,0 +1,159 @@
+import { tool } from '@langchain/core/tools';
+import { z } from 'zod';
+import { Constants } from '@/common';
+
+export const AskUserToolName = Constants.ASK_USER;
+
+export const AskUserDescription =
+  'Ask the user clarification questions with structured options before taking action. ' +
+  'For a single key question, use question+options. For multiple related questions, use steps[] (max 3 steps). ' +
+  'Each step can be single-select or multi-select. After receiving answers, proceed immediately.';
+
+const AskUserOptionSchema = z.object({
+  label: z.string().describe('Short display label'),
+  value: z.string().describe('Machine-readable value returned when selected'),
+  description: z.string().optional().describe('Optional longer description'),
+});
+
+export const AskUserStepSchema = z.object({
+  question: z.string().describe('The question to ask the user for this step'),
+  options: z
+    .array(AskUserOptionSchema)
+    .min(2)
+    .max(6)
+    .describe('Structured options for this step (2-6 choices)'),
+  type: z
+    .enum(['single', 'multi'])
+    .default('single')
+    .describe('Selection type: single-select or multi-select'),
+});
+
+export type AskUserStep = z.infer<typeof AskUserStepSchema>;
+
+const AskUserSchema = z
+  .object({
+    question: z
+      .string()
+      .optional()
+      .describe('The question to ask the user. Be specific and clear.'),
+    options: z
+      .array(AskUserOptionSchema)
+      .min(2)
+      .max(6)
+      .optional()
+      .describe('Structured options for the user (2-6 choices)'),
+    context: z.string().optional().describe('Why you are asking this question'),
+    steps: z
+      .array(AskUserStepSchema)
+      .min(1)
+      .max(5)
+      .optional()
+      .describe('Multi-step wizard: array of question steps (1-5 steps)'),
+  })
+  // passthrough() preserves extra fields like _selectedOption injected by the
+  // approval flow's modifiedArgs — without this, Zod strips unknown keys.
+  .passthrough()
+  .refine(
+    (data) => {
+      // Must have either steps[] OR question+options (legacy format)
+      const hasSteps = Array.isArray(data.steps) && data.steps.length > 0;
+      const hasLegacy =
+        typeof data.question === 'string' && Array.isArray(data.options);
+      return hasSteps || hasLegacy;
+    },
+    {
+      message: 'Either steps[] or question+options must be provided',
+    }
+  );
+
+/**
+ * Represents a single step selection from the multi-step wizard UI.
+ * Exported for use by both ranger web client and browser extension.
+ */
+export type StepSelection = {
+  values: string[];
+  customInput?: string;
+};
+
+/** Field names injected into modifiedArgs by the approval flow */
+export const HITL_FIELDS = {
+  SELECTIONS: '_selections',
+  SELECTED_OPTION: '_selectedOption',
+  CUSTOM_INPUT: '_customInput',
+} as const;
+
+/**
+ * Creates an ask_user tool that lets the LLM ask clarification questions mid-conversation.
+ *
+ * How it works:
+ * 1. LLM calls ask_user(question, options) OR ask_user(steps)
+ * 2. ToolNode.requiresApproval() → always true (per-tool rule in askUserRules.js)
+ * 3. ToolNode.requestApproval() promotes options/question/steps to top-level fields on the event
+ * 4. Frontend HumanInputPopover renders option cards + freeform text input
+ * 5. User selects option(s) OR types custom input →
+ *    backend resolves with modifiedArgs containing _selections, _selectedOption, or _customInput
+ * 6. Tool executes, reads the user's choice, returns result to LLM
+ */
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+export function createAskUserTool() {
+  return tool(
+    async (args) => {
+      const extArgs = args as Record<string, unknown>;
+      const selections = extArgs[HITL_FIELDS.SELECTIONS] as
+        | StepSelection[]
+        | undefined;
+      const customInput = extArgs[HITL_FIELDS.CUSTOM_INPUT] as
+        | string
+        | undefined;
+      const selectedOption = extArgs[HITL_FIELDS.SELECTED_OPTION] as
+        | string
+        | undefined;
+
+      // Multi-step wizard flow: _selections is an array of { values, customInput? } per step
+      if (
+        selections &&
+        Array.isArray(selections) &&
+        Array.isArray(args.steps)
+      ) {
+        const lines: string[] = [];
+        for (let i = 0; i < args.steps.length; i++) {
+          const step = args.steps[i];
+          const sel = selections[i];
+          if (!sel || (sel.values.length === 0 && !sel.customInput)) {
+            lines.push(`${i + 1}. ${step.question} → (skipped)`);
+            continue;
+          }
+          if (sel.customInput) {
+            lines.push(`${i + 1}. ${step.question} → "${sel.customInput}"`);
+            continue;
+          }
+          // Resolve value(s) to labels
+          const labels = sel.values.map((v) => {
+            const opt = step.options.find((o) => o.value === v);
+            return opt?.label || v;
+          });
+          lines.push(`${i + 1}. ${step.question} → ${labels.join(', ')}`);
+        }
+        return `User responses:\n${lines.join('\n')}`;
+      }
+
+      // Legacy: custom freeform input takes priority — user explicitly chose "none of these"
+      if (customInput) {
+        return `User provided custom response: "${customInput}"`;
+      }
+
+      if (selectedOption) {
+        const option = args.options?.find((o) => o.value === selectedOption);
+        return `User selected: "${option?.label || selectedOption}" (value: ${selectedOption})`;
+      }
+
+      // Fallback — should not happen in interactive mode since approval always fires first
+      return 'No user response received.';
+    },
+    {
+      name: AskUserToolName,
+      description: AskUserDescription,
+      schema: AskUserSchema,
+    }
+  );
+}