illuma-agents 1.0.65 → 1.0.67

package/src/specs/task-progress.test.ts

@@ -0,0 +1,330 @@
+// src/specs/task-progress.test.ts
+import { GraphEvents } from '@/common';
+import {
+  createTaskProgressTool,
+  TaskProgressToolName,
+  TaskProgressToolDescription,
+  TaskProgressToolSchema,
+  TaskProgressToolDefinition,
+  type TaskItem,
+  type TaskStatus,
+  type TaskProgressPayload,
+} from '@/tools/TaskProgress';
+
+// Mock the safeDispatchCustomEvent
+jest.mock('@/utils/events', () => ({
+  safeDispatchCustomEvent: jest.fn().mockResolvedValue(undefined),
+}));
+
+import { safeDispatchCustomEvent } from '@/utils/events';
+const mockDispatch = safeDispatchCustomEvent as jest.MockedFunction<
+  typeof safeDispatchCustomEvent
+>;
+
+describe('TaskProgress Tool', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('Tool Definition', () => {
+    it('should have correct tool name', () => {
+      expect(TaskProgressToolName).toBe('manage_todo_list');
+    });
+
+    it('should have description with usage guidelines', () => {
+      expect(TaskProgressToolDescription).toContain('todo list');
+      expect(TaskProgressToolDescription).toContain('not-started');
+      expect(TaskProgressToolDescription).toContain('in-progress');
+      expect(TaskProgressToolDescription).toContain('completed');
+    });
+
+    it('should have valid JSON schema', () => {
+      expect(TaskProgressToolSchema.type).toBe('object');
+      expect(TaskProgressToolSchema.required).toContain('todoList');
+      expect(TaskProgressToolSchema.properties.todoList.type).toBe('array');
+    });
+
+    it('should export complete tool definition', () => {
+      expect(TaskProgressToolDefinition.name).toBe(TaskProgressToolName);
+      expect(TaskProgressToolDefinition.description).toBe(
+        TaskProgressToolDescription
+      );
+      expect(TaskProgressToolDefinition.schema).toEqual(TaskProgressToolSchema);
+    });
+  });
+
+  describe('createTaskProgressTool', () => {
+    it('should create a tool with correct name', () => {
+      const tool = createTaskProgressTool();
+      expect(tool.name).toBe('manage_todo_list');
+    });
+
+    it('should create a tool with description', () => {
+      const tool = createTaskProgressTool();
+      expect(tool.description).toBeDefined();
+      expect(tool.description.length).toBeGreaterThan(0);
+    });
+
+    it('should accept onTaskUpdate callback parameter', () => {
+      const mockCallback = jest.fn();
+      const tool = createTaskProgressTool({ onTaskUpdate: mockCallback });
+      expect(tool).toBeDefined();
+    });
+  });
+
+  describe('Tool Invocation', () => {
+    it('should accept valid todo list and return success message', async () => {
+      const tool = createTaskProgressTool();
+
+      const validTodoList: TaskItem[] = [
+        { id: 1, title: 'Research API', status: 'not-started' },
+        { id: 2, title: 'Implement feature', status: 'not-started' },
+      ];
+
+      const result = await tool.invoke({ todoList: validTodoList });
+
+      expect(result).toContain('Todo list updated successfully');
+      expect(result).toContain('0/2 completed');
+      expect(result).toContain('2 remaining');
+    });
+
+    it('should dispatch SSE event with correct event type', async () => {
+      const tool = createTaskProgressTool();
+
+      const todoList: TaskItem[] = [
+        { id: 1, title: 'Task 1', status: 'in-progress' },
+      ];
+
+      await tool.invoke({ todoList });
+
+      expect(mockDispatch).toHaveBeenCalledWith(
+        GraphEvents.ON_TASK_PROGRESS,
+        expect.objectContaining({
+          tasks: todoList,
+          timestamp: expect.any(String),
+          isComplete: false,
+        }),
+        expect.anything() // config object is passed
+      );
+    });
+
+    it('should include timestamp in dispatched payload', async () => {
+      const tool = createTaskProgressTool();
+
+      const todoList: TaskItem[] = [
+        { id: 1, title: 'Task', status: 'not-started' },
+      ];
+
+      await tool.invoke({ todoList });
+
+      const dispatchedPayload = mockDispatch.mock.calls[0][1] as TaskProgressPayload;
+      expect(dispatchedPayload.timestamp).toBeDefined();
+      expect(new Date(dispatchedPayload.timestamp).getTime()).toBeGreaterThan(0);
+    });
+
+    it('should call onTaskUpdate callback when provided', async () => {
+      const mockCallback = jest.fn();
+      const tool = createTaskProgressTool({ onTaskUpdate: mockCallback });
+
+      const todoList: TaskItem[] = [
+        { id: 1, title: 'Task', status: 'completed' },
+      ];
+
+      await tool.invoke({ todoList });
+
+      expect(mockCallback).toHaveBeenCalledWith(todoList);
+    });
+
+    it('should handle async onTaskUpdate callback', async () => {
+      const asyncCallback = jest.fn().mockResolvedValue(undefined);
+      const tool = createTaskProgressTool({ onTaskUpdate: asyncCallback });
+
+      const todoList: TaskItem[] = [
+        { id: 1, title: 'Task', status: 'in-progress' },
+      ];
+
+      await tool.invoke({ todoList });
+
+      expect(asyncCallback).toHaveBeenCalledWith(todoList);
+    });
+
+    it('should not fail if onTaskUpdate throws', async () => {
+      const failingCallback = jest.fn().mockRejectedValue(new Error('Callback error'));
+      const tool = createTaskProgressTool({ onTaskUpdate: failingCallback });
+
+      const todoList: TaskItem[] = [
+        { id: 1, title: 'Task', status: 'in-progress' },
+      ];
+
+      // Should not throw, just warn
+      const result = await tool.invoke({ todoList });
+      expect(result).toContain('Todo list updated successfully');
+    });
+  });
+
+  describe('Status Tracking', () => {
+    it('should correctly count completed tasks', async () => {
+      const tool = createTaskProgressTool();
+
+      const todoList: TaskItem[] = [
+        { id: 1, title: 'Done 1', status: 'completed' },
+        { id: 2, title: 'Done 2', status: 'completed' },
+        { id: 3, title: 'Not done', status: 'not-started' },
+      ];
+
+      const result = await tool.invoke({ todoList });
+
+      expect(result).toContain('2/3 completed');
+    });
+
+    it('should correctly count in-progress tasks', async () => {
+      const tool = createTaskProgressTool();
+
+      const todoList: TaskItem[] = [
+        { id: 1, title: 'Working', status: 'in-progress' },
+        { id: 2, title: 'Not started', status: 'not-started' },
+      ];
+
+      const result = await tool.invoke({ todoList });
+
+      expect(result).toContain('1 in progress');
+    });
+
+    it('should correctly count not-started tasks', async () => {
+      const tool = createTaskProgressTool();
+
+      const todoList: TaskItem[] = [
+        { id: 1, title: 'Task 1', status: 'not-started' },
+        { id: 2, title: 'Task 2', status: 'not-started' },
+        { id: 3, title: 'Task 3', status: 'completed' },
+      ];
+
+      const result = await tool.invoke({ todoList });
+
+      expect(result).toContain('2 remaining');
+    });
+
+    it('should warn about multiple in-progress tasks', async () => {
+      const tool = createTaskProgressTool();
+
+      const todoList: TaskItem[] = [
+        { id: 1, title: 'Task 1', status: 'in-progress' },
+        { id: 2, title: 'Task 2', status: 'in-progress' },
+      ];
+
+      const result = await tool.invoke({ todoList });
+
+      expect(result).toContain('Warning');
+      expect(result).toContain('2 tasks marked as in-progress');
+    });
+
+    it('should support failed status', async () => {
+      const tool = createTaskProgressTool();
+
+      const todoList: TaskItem[] = [
+        { id: 1, title: 'Failed task', status: 'failed' },
+        { id: 2, title: 'Completed', status: 'completed' },
+      ];
+
+      const result = await tool.invoke({ todoList });
+
+      expect(result).toContain('Todo list updated successfully');
+    });
+  });
+
+  describe('Validation', () => {
+    it('should throw on non-array todoList (schema validation)', async () => {
+      const tool = createTaskProgressTool();
+
+      // LangChain schema validation catches this before our code runs
+      await expect(
+        tool.invoke({ todoList: 'not an array' })
+      ).rejects.toThrow();
+    });
+
+    it('should throw on tasks with non-numeric id (schema validation)', async () => {
+      const tool = createTaskProgressTool();
+
+      const invalidTodoList = [
+        { id: 'abc', title: 'Task', status: 'not-started' },
+      ];
+
+      // LangChain schema validation catches this before our code runs
+      await expect(
+        tool.invoke({ todoList: invalidTodoList })
+      ).rejects.toThrow();
+    });
+
+    it('should reject tasks with empty title', async () => {
+      const tool = createTaskProgressTool();
+
+      const invalidTodoList = [{ id: 1, title: '', status: 'not-started' }];
+
+      const result = await tool.invoke({ todoList: invalidTodoList });
+
+      expect(result).toContain('Error');
+      expect(result).toContain('title');
+    });
+
+    it('should throw on tasks with invalid status (schema validation)', async () => {
+      const tool = createTaskProgressTool();
+
+      const invalidTodoList = [
+        { id: 1, title: 'Task', status: 'invalid-status' },
+      ];
+
+      // LangChain schema validation catches this before our code runs
+      await expect(
+        tool.invoke({ todoList: invalidTodoList })
+      ).rejects.toThrow();
+    });
+
+    it('should accept empty todo list', async () => {
+      const tool = createTaskProgressTool();
+
+      const result = await tool.invoke({ todoList: [] });
+
+      expect(result).toContain('Todo list updated successfully');
+      expect(result).toContain('0/0 completed');
+    });
+  });
+
+  describe('Type Exports', () => {
+    it('should export TaskStatus type with correct values', () => {
+      const validStatuses: TaskStatus[] = [
+        'not-started',
+        'in-progress',
+        'completed',
+        'failed',
+      ];
+
+      validStatuses.forEach((status) => {
+        expect(['not-started', 'in-progress', 'completed', 'failed']).toContain(
+          status
+        );
+      });
+    });
+
+    it('should export TaskItem type with required fields', () => {
+      const validTask: TaskItem = {
+        id: 1,
+        title: 'Test task',
+        status: 'not-started',
+      };
+
+      expect(validTask.id).toBe(1);
+      expect(validTask.title).toBe('Test task');
+      expect(validTask.status).toBe('not-started');
+    });
+
+    it('should export TaskProgressPayload type', () => {
+      const payload: TaskProgressPayload = {
+        tasks: [{ id: 1, title: 'Test', status: 'completed' }],
+        timestamp: new Date().toISOString(),
+      };
+
+      expect(payload.tasks).toBeDefined();
+      expect(payload.timestamp).toBeDefined();
+    });
+  });
+});

package/src/tools/Calculator.ts

@@ -1,6 +1,28 @@
 import { Tool } from '@langchain/core/tools';
 import * as math from 'mathjs';
 
+export const CalculatorToolName = 'calculator';
+
+export const CalculatorToolDescription =
+  'Useful for getting the result of a math expression. The input to this tool should be a valid mathematical expression that could be executed by a simple calculator.';
+
+export const CalculatorSchema = {
+  type: 'object',
+  properties: {
+    input: {
+      type: 'string',
+      description: 'A valid mathematical expression to evaluate',
+    },
+  },
+  required: ['input'],
+} as const;
+
+export const CalculatorToolDefinition = {
+  name: CalculatorToolName,
+  description: CalculatorToolDescription,
+  schema: CalculatorSchema,
+} as const;
+
 export class Calculator extends Tool {
   static lc_name(): string {
     return 'Calculator';
@@ -10,7 +32,7 @@ export class Calculator extends Tool {
     return [...super.lc_namespace, 'calculator'];
   }
 
-  name = 'calculator';
+  name = CalculatorToolName;
 
   async _call(input: string): Promise<string> {
     try {
@@ -20,6 +42,5 @@ export class Calculator extends Tool {
     }
   }
 
-  description =
-    'Useful for getting the result of a math expression. The input to this tool should be a valid mathematical expression that could be executed by a simple calculator.';
+  description = CalculatorToolDescription;
 }

package/src/tools/CodeExecutor.ts

@@ -35,7 +35,7 @@ const SUPPORTED_LANGUAGES = [
   'r',
 ] as const;
 
-const CodeExecutionToolSchema = {
+export const CodeExecutionToolSchema = {
   type: 'object',
   properties: {
     lang: {
@@ -74,6 +74,23 @@ const EXEC_ENDPOINT = `${baseEndpoint}/exec`;
 
 type SupportedLanguage = (typeof SUPPORTED_LANGUAGES)[number];
 
+export const CodeExecutionToolDescription = `
+Runs code and returns stdout/stderr output from a stateless execution environment, similar to running scripts in a command-line interface. Each execution is isolated and independent.
+
+Usage:
+- No network access available.
+- Generated files are automatically delivered; **DO NOT** provide download links.
+- NEVER use this tool to execute malicious code.
+`.trim();
+
+export const CodeExecutionToolName = Constants.EXECUTE_CODE;
+
+export const CodeExecutionToolDefinition = {
+  name: CodeExecutionToolName,
+  description: CodeExecutionToolDescription,
+  schema: CodeExecutionToolSchema,
+} as const;
+
 function createCodeExecutionTool(
   params: t.CodeExecutionToolParams = {}
 ): DynamicStructuredTool {
@@ -242,7 +259,7 @@ Rules:
       }
     },
     {
-      name: Constants.EXECUTE_CODE,
+      name: CodeExecutionToolName,
       description,
       schema: CodeExecutionToolSchema,
       responseFormat: Constants.CONTENT_AND_ARTIFACT,

package/src/tools/TaskProgress.ts

@@ -0,0 +1,247 @@
+// src/tools/TaskProgress.ts
+import { tool, DynamicStructuredTool } from '@langchain/core/tools';
+import { safeDispatchCustomEvent } from '@/utils/events';
+import { GraphEvents } from '@/common';
+
+/**
+ * Task status enum matching the UI component expectations
+ */
+export type TaskStatus = 'not-started' | 'in-progress' | 'completed' | 'failed';
+
+/**
+ * Individual task item in the todo list
+ */
+export interface TaskItem {
+  /** Unique identifier for the task (sequential number starting from 1) */
+  id: number;
+  /** Short, action-oriented title (3-7 words) */
+  title: string;
+  /** Current status of the task */
+  status: TaskStatus;
+  /** Optional message for additional context */
+  message?: string;
+}
+
+/**
+ * Payload sent via SSE event for task progress updates
+ * This matches the format expected by the Ranger UI
+ */
+export interface TaskProgressPayload {
+  /** Complete list of all tasks */
+  tasks: TaskItem[];
+  /** Timestamp of the update */
+  timestamp: string;
+  /** Optional title for the task group */
+  title?: string;
+  /** Whether all tasks are complete */
+  isComplete?: boolean;
+}
+
+/**
+ * Tool name constant - matches what AI calls
+ */
+export const TaskProgressToolName = 'manage_todo_list';
+
+/**
+ * Tool description for the AI
+ */
+export const TaskProgressToolDescription = `Manage a structured todo list to track progress and plan tasks throughout your session.
+
+**When to use this tool:**
+- Complex multi-step work requiring planning and tracking (3+ steps)
+- When breaking down larger tasks into smaller actionable steps
+- Before starting work on any todo (mark as in-progress)
+- Immediately after completing each todo (mark as completed)
+- To give users visibility into your progress and planning
+
+**When NOT to use:**
+- Single, trivial tasks completed in one step
+- Purely conversational/informational requests
+- Simple file reads or searches
+
+**Critical workflow:**
+1. Plan tasks by creating todo list with specific, actionable items
+2. Mark ONE todo as in-progress before starting work
+3. Complete the work (may involve multiple tool calls)
+4. Mark that todo as completed IMMEDIATELY
+5. Move to next todo and repeat
+
+**Todo states:**
+- not-started: Todo not yet begun
+- in-progress: Currently working (limit ONE at a time)
+- completed: Finished successfully
+- failed: Task could not be completed
+
+**Important:** Mark todos completed as soon as they are done. Do not batch completions.`;
+
+/**
+ * JSON Schema for the tool input
+ */
+export const TaskProgressToolSchema = {
+  type: 'object',
+  properties: {
+    todoList: {
+      type: 'array',
+      description:
+        'Complete array of all todo items. Must include ALL items - both existing and new.',
+      items: {
+        type: 'object',
+        properties: {
+          id: {
+            type: 'number',
+            description:
+              'Unique identifier for the todo. Use sequential numbers starting from 1.',
+          },
+          title: {
+            type: 'string',
+            description:
+              'Concise action-oriented todo label (3-7 words). Displayed in UI.',
+          },
+          status: {
+            type: 'string',
+            enum: ['not-started', 'in-progress', 'completed', 'failed'],
+            description:
+              'not-started: Not begun | in-progress: Currently working (max 1) | completed: Fully finished | failed: Could not complete',
+          },
+        },
+        required: ['id', 'title', 'status'],
+      },
+    },
+  },
+  required: ['todoList'],
+} as const;
+
+/**
+ * Tool definition for registration/export
+ */
+export const TaskProgressToolDefinition = {
+  name: TaskProgressToolName,
+  description: TaskProgressToolDescription,
+  schema: TaskProgressToolSchema,
+} as const;
+
+/**
+ * Parameters for creating the TaskProgress tool
+ */
+export interface TaskProgressToolParams {
+  /**
+   * Optional callback to handle task updates externally
+   * Called with the task list whenever it's updated
+   */
+  onTaskUpdate?: (tasks: TaskItem[]) => void | Promise<void>;
+}
+
+/**
+ * Creates a TaskProgress tool that allows the AI to manage a todo list
+ * and emits events for the UI to display progress.
+ *
+ * This tool is designed for ephemeral agents doing complex, multi-step work.
+ * It should NOT be included for:
+ * - Persistent workflow agents
+ * - Simple tool-calling agents
+ * - No-code/low-code builder workflows (unless explicitly enabled)
+ *
+ * @param params - Optional parameters including external callback
+ * @returns DynamicStructuredTool that can be added to agent tools
+ *
+ * @example
+ * ```typescript
+ * // Add to agent tools for ephemeral research/planning agents
+ * const tools = [
+ *   createTaskProgressTool(),
+ *   // ... other tools
+ * ];
+ * ```
+ */
+export function createTaskProgressTool(
+  params: TaskProgressToolParams = {}
+): DynamicStructuredTool {
+  const { onTaskUpdate } = params;
+
+  return tool(
+    async (rawInput, config) => {
+      const { todoList } = rawInput as { todoList: TaskItem[] };
+
+      // Validate input
+      if (!Array.isArray(todoList)) {
+        return 'Error: todoList must be an array of task items.';
+      }
+
+      // Validate each task
+      for (const task of todoList) {
+        if (typeof task.id !== 'number') {
+          return `Error: Task id must be a number. Got: ${typeof task.id}`;
+        }
+        if (typeof task.title !== 'string' || task.title.trim() === '') {
+          return `Error: Task title must be a non-empty string for task ${task.id}`;
+        }
+        if (
+          !['not-started', 'in-progress', 'completed', 'failed'].includes(
+            task.status
+          )
+        ) {
+          return `Error: Invalid status "${task.status}" for task ${task.id}. Must be one of: not-started, in-progress, completed, failed`;
+        }
+      }
+
+      // Check for multiple in-progress tasks (warning, not error)
+      const inProgressCount = todoList.filter(
+        (t) => t.status === 'in-progress'
+      ).length;
+      const warning =
+        inProgressCount > 1
+          ? `\nWarning: ${inProgressCount} tasks marked as in-progress. Best practice is to work on one task at a time.`
+          : '';
+
+      // Check if all tasks are complete
+      const allComplete =
+        todoList.length > 0 &&
+        todoList.every(
+          (t) => t.status === 'completed' || t.status === 'failed'
+        );
+
+      // Create the payload for SSE event
+      const payload: TaskProgressPayload = {
+        tasks: todoList,
+        timestamp: new Date().toISOString(),
+        isComplete: allComplete,
+      };
+
+      // Dispatch SSE event for UI to consume
+      await safeDispatchCustomEvent(
+        GraphEvents.ON_TASK_PROGRESS,
+        payload,
+        config
+      );
+
+      // Call external callback if provided
+      if (onTaskUpdate) {
+        try {
+          await onTaskUpdate(todoList);
+        } catch (e) {
+          // Don't fail the tool call if callback fails
+          // eslint-disable-next-line no-console
+          console.warn('TaskProgress callback error:', e);
+        }
+      }
+
+      // Build response message
+      const completed = todoList.filter((t) => t.status === 'completed').length;
+      const inProgress = todoList.filter(
+        (t) => t.status === 'in-progress'
+      ).length;
+      const notStarted = todoList.filter(
+        (t) => t.status === 'not-started'
+      ).length;
+
+      return `Todo list updated successfully. Status: ${completed}/${todoList.length} completed, ${inProgress} in progress, ${notStarted} remaining.${warning}`;
+    },
+    {
+      name: TaskProgressToolName,
+      description: TaskProgressToolDescription,
+      schema: TaskProgressToolSchema,
+    }
+  );
+}
+
+export default createTaskProgressTool;

package/src/tools/ToolNode.ts

@@ -392,8 +392,9 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
             : JSON.stringify(result.content);
         toolMessage = new ToolMessage({
           status: 'success',
-          content: contentString,
           name: toolName,
+          content: contentString,
+          artifact: result.artifact,
           tool_call_id: result.toolCallId,
         });
       }

package/src/tools/search/index.ts

@@ -1,2 +1,3 @@
 export * from './tool';
+export * from './schema';
 export type * from './types';