illuma-agents 1.0.66 → 1.0.67

package/src/prompts/index.ts

@@ -1,2 +1,3 @@
 export * from './collab';
-export * from './taskmanager';
+export * from './taskmanager';
+export * from './taskplanning';

package/src/prompts/taskplanning.ts

@@ -0,0 +1,96 @@
+// src/prompts/taskplanning.ts
+
+/**
+ * System prompt fragment for task planning capabilities.
+ *
+ * Include this in the agent's system prompt when:
+ * - Agent is ephemeral (not a persistent workflow)
+ * - Agent handles complex, multi-step research or coding tasks
+ * - You want visible progress tracking for the user
+ *
+ * Do NOT include for:
+ * - Simple tool-calling agents
+ * - Workflow/builder agents with predefined steps
+ * - Agents with fixed execution patterns
+ */
+export const taskPlanningPrompt = `## Task Planning & Progress
+
+You have access to a \`manage_todo_list\` tool for tracking complex tasks.
+
+### When to Use Task Planning
+- **USE** for complex work requiring 3+ steps (research, multi-file changes, analysis)
+- **SKIP** for simple requests (single file edit, quick lookup, conversational responses)
+
+### Task Workflow
+1. **Plan First**: Before starting complex work, create a todo list with 3-6 clear, actionable items
+2. **One at a Time**: Mark ONE task as "in-progress" before starting work on it
+3. **Multiple Tool Calls OK**: A single task may require multiple tool calls (searches, reads, writes)
+4. **Complete Immediately**: Mark task "completed" right after finishing, don't batch updates
+5. **Iterate**: Move to next task, repeat until done
+
+### Task Best Practices
+- Keep titles short and action-oriented (3-7 words): "Research API options", "Implement auth flow"
+- Group related work into single tasks rather than micro-tasks
+- Update status promptly so user sees real-time progress
+- For simple 1-2 step work, just do it directly without creating todos
+
+### Example Task Breakdown
+For "Add user authentication to the app":
+1. Review existing auth code and dependencies
+2. Implement login endpoint
+3. Add session management
+4. Create protected route middleware
+5. Test authentication flow
+
+Each task above might involve multiple file reads, code writes, and searches - that's expected.
+`;
+
+/**
+ * Short version of task planning prompt for constrained context
+ */
+export const taskPlanningPromptShort = `## Task Tracking
+Use \`manage_todo_list\` for complex multi-step work (3+ steps).
+- Create 3-6 actionable todos before starting
+- Mark one "in-progress" at a time
+- Mark "completed" immediately after finishing
+- Skip for simple 1-2 step tasks
+`;
+
+/**
+ * Function description for structured output agents
+ */
+export const manageTodoListFunctionDescription =
+  'Manage a todo list for tracking progress on complex multi-step tasks. Create todos before starting work, mark in-progress while working, mark completed when done.';
+
+/**
+ * Function parameters schema (for agents using function calling format)
+ */
+export const manageTodoListFunctionParameters = {
+  type: 'object',
+  properties: {
+    todoList: {
+      type: 'array',
+      description: 'Complete array of all todo items (existing and new)',
+      items: {
+        type: 'object',
+        properties: {
+          id: {
+            type: 'number',
+            description: 'Sequential ID starting from 1',
+          },
+          title: {
+            type: 'string',
+            description: 'Short action-oriented title (3-7 words)',
+          },
+          status: {
+            type: 'string',
+            enum: ['not-started', 'in-progress', 'completed'],
+            description: 'Current task status',
+          },
+        },
+        required: ['id', 'title', 'status'],
+      },
+    },
+  },
+  required: ['todoList'],
+};

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/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;