@agentscope-ai/agentscope 0.0.2

package/src/tool/task.test.ts

@@ -0,0 +1,299 @@
+import { Tool } from './base';
+import { ToolResponse } from './response';
+import { TaskCreate, TaskUpdate, TaskGet, TaskList, _resetTaskStore } from './task';
+
+describe('Task Tools', () => {
+    let taskCreate: Tool;
+    let taskUpdate: Tool;
+    let taskGet: Tool;
+    let taskList: Tool;
+
+    beforeEach(() => {
+        _resetTaskStore();
+        taskCreate = TaskCreate();
+        taskUpdate = TaskUpdate();
+        taskGet = TaskGet();
+        taskList = TaskList();
+    });
+
+    const getTextFromResponse = (response: ToolResponse): string => {
+        const textBlock = response.content.find(block => block.type === 'text');
+        return textBlock && 'text' in textBlock ? textBlock.text : '';
+    };
+
+    describe('TaskCreate', () => {
+        it('creates a task with pending status', () => {
+            const response = taskCreate.call!({
+                subject: 'Fix bug',
+                description: 'Fix the authentication bug',
+            }) as ToolResponse;
+            const result = getTextFromResponse(response);
+            expect(result).toContain('Task #1 created successfully');
+            expect(result).toContain('Fix bug');
+        });
+
+        it('increments task IDs', () => {
+            taskCreate.call!({ subject: 'Task 1', description: 'First task' });
+            const response = taskCreate.call!({
+                subject: 'Task 2',
+                description: 'Second task',
+            }) as ToolResponse;
+            const result = getTextFromResponse(response);
+            expect(result).toContain('Task #2 created successfully');
+        });
+
+        it('supports optional activeForm and metadata', () => {
+            const response = taskCreate.call!({
+                subject: 'Run tests',
+                description: 'Execute test suite',
+                activeForm: 'Running tests',
+                metadata: { priority: 'high' },
+            }) as ToolResponse;
+            const result = getTextFromResponse(response);
+            expect(result).toContain('Task #1 created successfully');
+        });
+    });
+
+    describe('TaskUpdate', () => {
+        beforeEach(() => {
+            taskCreate.call!({ subject: 'Task 1', description: 'First task' });
+        });
+
+        it('updates task status', () => {
+            const response = taskUpdate.call!({
+                taskId: '1',
+                status: 'in_progress',
+            }) as ToolResponse;
+            const result = getTextFromResponse(response);
+            expect(result).toContain('Task #1 updated successfully');
+
+            // Verify the update by getting the task
+            const getResponse = taskGet.call!({ taskId: '1' }) as ToolResponse;
+            const getResult = getTextFromResponse(getResponse);
+            expect(getResult).toContain('Status: in_progress');
+        });
+
+        it('updates task subject and description', () => {
+            taskUpdate.call!({
+                taskId: '1',
+                subject: 'Updated subject',
+                description: 'Updated description',
+            });
+
+            const getResponse = taskGet.call!({ taskId: '1' }) as ToolResponse;
+            const result = getTextFromResponse(getResponse);
+            expect(result).toContain('Updated subject');
+            expect(result).toContain('Updated description');
+        });
+
+        it('merges metadata', () => {
+            taskUpdate.call!({
+                taskId: '1',
+                metadata: { key1: 'value1', key2: 'value2' },
+            });
+
+            taskUpdate.call!({
+                taskId: '1',
+                metadata: { key2: 'updated', key3: 'value3' },
+            });
+
+            const getResponse = taskGet.call!({ taskId: '1' }) as ToolResponse;
+            const result = getTextFromResponse(getResponse);
+            expect(result).toContain('key1');
+            expect(result).toContain('value1');
+            expect(result).toContain('key2');
+            expect(result).toContain('updated');
+            expect(result).toContain('key3');
+        });
+
+        it('deletes metadata keys when set to null', () => {
+            taskUpdate.call!({
+                taskId: '1',
+                metadata: { key1: 'value1', key2: 'value2' },
+            });
+
+            taskUpdate.call!({
+                taskId: '1',
+                metadata: { key1: null },
+            });
+
+            const getResponse = taskGet.call!({ taskId: '1' }) as ToolResponse;
+            const result = getTextFromResponse(getResponse);
+            expect(result).not.toContain('key1');
+            expect(result).toContain('key2');
+        });
+
+        it('adds task dependencies', () => {
+            taskCreate.call!({ subject: 'Task 2', description: 'Second task' });
+
+            taskUpdate.call!({
+                taskId: '1',
+                addBlocks: ['2'],
+            });
+
+            taskUpdate.call!({
+                taskId: '2',
+                addBlockedBy: ['1'],
+            });
+
+            const getResponse = taskGet.call!({ taskId: '1' }) as ToolResponse;
+            const result = getTextFromResponse(getResponse);
+            expect(result).toContain('Blocks: 2');
+
+            const getResponse2 = taskGet.call!({ taskId: '2' }) as ToolResponse;
+            const result2 = getTextFromResponse(getResponse2);
+            expect(result2).toContain('Blocked By: 1');
+        });
+
+        it('deduplicates dependencies', () => {
+            taskCreate.call!({ subject: 'Task 2', description: 'Second task' });
+
+            taskUpdate.call!({
+                taskId: '1',
+                addBlocks: ['2'],
+            });
+
+            taskUpdate.call!({
+                taskId: '1',
+                addBlocks: ['2'],
+            });
+
+            const getResponse = taskGet.call!({ taskId: '1' }) as ToolResponse;
+            const result = getTextFromResponse(getResponse);
+            // Should only appear once
+            expect(result.match(/Blocks: 2/g)?.length).toBe(1);
+        });
+
+        it('throws on non-existent task', () => {
+            expect(() => taskUpdate.call!({ taskId: '999', status: 'completed' })).toThrow(
+                'Task not found: 999'
+            );
+        });
+
+        it('throws when adding non-existent dependency', () => {
+            expect(() => taskUpdate.call!({ taskId: '1', addBlocks: ['999'] })).toThrow(
+                'Cannot add dependency: task 999 does not exist'
+            );
+        });
+
+        it('deletes task when status is deleted', () => {
+            const response = taskUpdate.call!({
+                taskId: '1',
+                status: 'deleted',
+            }) as ToolResponse;
+            const result = getTextFromResponse(response);
+            expect(result).toContain('Task #1 deleted successfully');
+
+            // Verify task is gone
+            expect(() => taskGet.call!({ taskId: '1' })).toThrow('Task not found: 1');
+        });
+    });
+
+    describe('TaskGet', () => {
+        it('returns full task details', () => {
+            taskCreate.call!({
+                subject: 'Test task',
+                description: 'Test description',
+                activeForm: 'Testing',
+                metadata: { priority: 'high' },
+            });
+
+            const response = taskGet.call!({ taskId: '1' }) as ToolResponse;
+            const result = getTextFromResponse(response);
+
+            expect(result).toContain('Task #1: Test task');
+            expect(result).toContain('Status: pending');
+            expect(result).toContain('Description: Test description');
+            expect(result).toContain('Active Form: Testing');
+            expect(result).toContain('priority');
+            expect(result).toContain('high');
+            expect(result).toContain('Created:');
+            expect(result).toContain('Updated:');
+        });
+
+        it('throws on non-existent task', () => {
+            expect(() => taskGet.call!({ taskId: '999' })).toThrow('Task not found: 999');
+        });
+    });
+
+    describe('TaskList', () => {
+        it('returns empty message when no tasks exist', () => {
+            const response = taskList.call!({}) as ToolResponse;
+            const result = getTextFromResponse(response);
+            expect(result).toBe('No active tasks found');
+        });
+
+        it('lists pending and in_progress tasks', () => {
+            taskCreate.call!({ subject: 'Task 1', description: 'First' });
+            taskCreate.call!({ subject: 'Task 2', description: 'Second' });
+            taskUpdate.call!({ taskId: '2', status: 'in_progress' });
+
+            const response = taskList.call!({}) as ToolResponse;
+            const result = getTextFromResponse(response);
+
+            expect(result).toContain('#1 [pending] Task 1');
+            expect(result).toContain('#2 [in_progress] Task 2');
+        });
+
+        it('filters out completed tasks', () => {
+            taskCreate.call!({ subject: 'Task 1', description: 'First' });
+            taskCreate.call!({ subject: 'Task 2', description: 'Second' });
+            taskUpdate.call!({ taskId: '1', status: 'completed' });
+
+            const response = taskList.call!({}) as ToolResponse;
+            const result = getTextFromResponse(response);
+
+            expect(result).not.toContain('Task 1');
+            expect(result).toContain('#2 [pending] Task 2');
+        });
+
+        it('filters out deleted tasks', () => {
+            taskCreate.call!({ subject: 'Task 1', description: 'First' });
+            taskCreate.call!({ subject: 'Task 2', description: 'Second' });
+            taskUpdate.call!({ taskId: '1', status: 'deleted' });
+
+            const response = taskList.call!({}) as ToolResponse;
+            const result = getTextFromResponse(response);
+
+            expect(result).not.toContain('Task 1');
+            expect(result).toContain('#2 [pending] Task 2');
+        });
+
+        it('shows blocked tasks with dependencies', () => {
+            taskCreate.call!({ subject: 'Task 1', description: 'First' });
+            taskCreate.call!({ subject: 'Task 2', description: 'Second' });
+            taskUpdate.call!({ taskId: '2', addBlockedBy: ['1'] });
+
+            const response = taskList.call!({}) as ToolResponse;
+            const result = getTextFromResponse(response);
+
+            expect(result).toContain('#2 [pending] Task 2 (blocked by: #1)');
+        });
+
+        it('sorts tasks by ID', () => {
+            taskCreate.call!({ subject: 'Task 1', description: 'First' });
+            taskCreate.call!({ subject: 'Task 2', description: 'Second' });
+            taskCreate.call!({ subject: 'Task 3', description: 'Third' });
+
+            const response = taskList.call!({}) as ToolResponse;
+            const result = getTextFromResponse(response);
+
+            const lines = result.split('\n');
+            expect(lines[0]).toContain('#1');
+            expect(lines[1]).toContain('#2');
+            expect(lines[2]).toContain('#3');
+        });
+
+        it('returns empty when all tasks are completed', () => {
+            taskCreate.call!({ subject: 'Task 1', description: 'First' });
+            taskCreate.call!({ subject: 'Task 2', description: 'Second' });
+            taskUpdate.call!({ taskId: '1', status: 'completed' });
+            taskUpdate.call!({ taskId: '2', status: 'completed' });
+
+            const response = taskList.call!({}) as ToolResponse;
+            const result = getTextFromResponse(response);
+
+            expect(result).toBe('No active tasks found');
+        });
+    });
+});

package/src/tool/task.ts

@@ -0,0 +1,399 @@
+import { z } from 'zod';
+
+import { createToolResponse, ToolResponse } from './response';
+
+// Task type definitions
+export type TaskStatus = 'pending' | 'in_progress' | 'completed' | 'deleted';
+
+export interface Task {
+    id: string;
+    subject: string;
+    description: string;
+    status: TaskStatus;
+    activeForm?: string;
+    owner?: string;
+    metadata?: Record<string, unknown>;
+    blocks: string[];
+    blockedBy: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+
+// Module-level storage
+const taskStore = new Map<string, Task>();
+let nextId = 1;
+
+/**
+ * Generate a unique task ID
+ * @returns A unique task ID as a string
+ */
+function generateId(): string {
+    return String(nextId++);
+}
+
+/**
+ * Reset task store for testing purposes
+ * @internal
+ */
+export function _resetTaskStore(): void {
+    taskStore.clear();
+    nextId = 1;
+}
+
+/**
+ * Tool for creating tasks
+ * @returns A Tool object for creating tasks
+ */
+export function TaskCreate() {
+    return {
+        name: 'TaskCreate',
+        description: `Use this tool to create a structured task list for your current coding session. This helps you track progress, organize complex tasks, and demonstrate thoroughness to the user.
+It also helps the user understand the progress of the task and overall progress of their requests.
+
+## When to Use This Tool
+
+Use this tool proactively in these scenarios:
+
+- Complex multi-step tasks - When a task requires 3 or more distinct steps or actions
+- Non-trivial and complex tasks - Tasks that require careful planning or multiple operations
+- User explicitly requests todo list - When the user directly asks you to use the todo list
+- User provides multiple tasks - When users provide a list of things to be done (numbered or comma-separated)
+
+All tasks are created with status 'pending'.`,
+        inputSchema: z.object({
+            subject: z
+                .string()
+                .describe(
+                    'A brief, actionable title in imperative form (e.g., "Fix authentication bug in login flow")'
+                ),
+            description: z
+                .string()
+                .describe(
+                    'Detailed description of what needs to be done, including context and acceptance criteria'
+                ),
+            activeForm: z
+                .string()
+                .optional()
+                .describe(
+                    'Present continuous form shown in the spinner when the task is in_progress (e.g., "Fixing authentication bug"). If omitted, the spinner shows the subject instead.'
+                ),
+            metadata: z
+                .record(z.string(), z.unknown())
+                .optional()
+                .describe('Arbitrary metadata to attach to the task'),
+        }),
+        requireUserConfirm: false,
+
+        call({
+            subject,
+            description,
+            activeForm,
+            metadata,
+        }: {
+            subject: string;
+            description: string;
+            activeForm?: string;
+            metadata?: Record<string, unknown>;
+        }): ToolResponse {
+            const id = generateId();
+            const now = new Date().toISOString();
+
+            const task: Task = {
+                id,
+                subject,
+                description,
+                status: 'pending',
+                activeForm,
+                metadata,
+                blocks: [],
+                blockedBy: [],
+                createdAt: now,
+                updatedAt: now,
+            };
+
+            taskStore.set(id, task);
+
+            return createToolResponse({
+                content: [
+                    {
+                        id: crypto.randomUUID(),
+                        type: 'text',
+                        text: `Task #${id} created successfully: ${subject}`,
+                    },
+                ],
+                state: 'success',
+            });
+        },
+    };
+}
+
+/**
+ * Tool for updating tasks
+ * @returns A Tool object for updating tasks
+ */
+export function TaskUpdate() {
+    return {
+        name: 'TaskUpdate',
+        description: `Use this tool to update a task in the task list.
+
+## When to Use This Tool
+
+**Mark tasks as resolved:**
+- When you have completed the work described in a task
+- When a task is no longer needed or has been superseded
+- IMPORTANT: Always mark your assigned tasks as resolved when you finish them
+
+**Delete tasks:**
+- When a task is no longer relevant or was created in error
+- Setting status to 'deleted' permanently removes the task
+
+**Update task details:**
+- When requirements change or become clearer
+- When establishing dependencies between tasks`,
+        inputSchema: z.object({
+            taskId: z.string().describe('The ID of the task to update'),
+            status: z
+                .enum(['pending', 'in_progress', 'completed', 'deleted'])
+                .optional()
+                .describe('New status for the task'),
+            subject: z.string().optional().describe('New subject for the task'),
+            description: z.string().optional().describe('New description for the task'),
+            activeForm: z
+                .string()
+                .optional()
+                .describe(
+                    'Present continuous form shown in spinner when in_progress (e.g., "Running tests")'
+                ),
+            owner: z.string().optional().describe('New owner for the task'),
+            metadata: z
+                .record(z.string(), z.unknown())
+                .optional()
+                .describe('Metadata keys to merge into the task. Set a key to null to delete it.'),
+            addBlocks: z.array(z.string()).optional().describe('Task IDs that this task blocks'),
+            addBlockedBy: z.array(z.string()).optional().describe('Task IDs that block this task'),
+        }),
+        requireUserConfirm: false,
+
+        call({
+            taskId,
+            status,
+            subject,
+            description,
+            activeForm,
+            owner,
+            metadata,
+            addBlocks,
+            addBlockedBy,
+        }: {
+            taskId: string;
+            status?: TaskStatus;
+            subject?: string;
+            description?: string;
+            activeForm?: string;
+            owner?: string;
+            metadata?: Record<string, unknown>;
+            addBlocks?: string[];
+            addBlockedBy?: string[];
+        }): ToolResponse {
+            const task = taskStore.get(taskId);
+            if (!task) {
+                throw new Error(`Task not found: ${taskId}`);
+            }
+
+            // Validate dependencies exist
+            if (addBlocks) {
+                for (const depId of addBlocks) {
+                    if (!taskStore.has(depId)) {
+                        throw new Error(`Cannot add dependency: task ${depId} does not exist`);
+                    }
+                }
+            }
+            if (addBlockedBy) {
+                for (const depId of addBlockedBy) {
+                    if (!taskStore.has(depId)) {
+                        throw new Error(`Cannot add dependency: task ${depId} does not exist`);
+                    }
+                }
+            }
+
+            // Update fields
+            if (subject !== undefined) task.subject = subject;
+            if (description !== undefined) task.description = description;
+            if (activeForm !== undefined) task.activeForm = activeForm;
+            if (owner !== undefined) task.owner = owner;
+
+            // Merge metadata
+            if (metadata !== undefined) {
+                if (!task.metadata) {
+                    task.metadata = {};
+                }
+                for (const [key, value] of Object.entries(metadata)) {
+                    if (value === null) {
+                        delete task.metadata[key];
+                    } else {
+                        task.metadata[key] = value;
+                    }
+                }
+            }
+
+            // Add dependencies with deduplication
+            if (addBlocks) {
+                task.blocks = [...new Set([...task.blocks, ...addBlocks])];
+            }
+            if (addBlockedBy) {
+                task.blockedBy = [...new Set([...task.blockedBy, ...addBlockedBy])];
+            }
+
+            task.updatedAt = new Date().toISOString();
+
+            // Handle status change
+            if (status !== undefined) {
+                if (status === 'deleted') {
+                    taskStore.delete(taskId);
+                    return createToolResponse({
+                        content: [
+                            {
+                                id: crypto.randomUUID(),
+                                type: 'text',
+                                text: `Task #${taskId} deleted successfully`,
+                            },
+                        ],
+                        state: 'success',
+                    });
+                }
+                task.status = status;
+            }
+
+            return createToolResponse({
+                content: [
+                    {
+                        id: crypto.randomUUID(),
+                        type: 'text',
+                        text: `Task #${taskId} updated successfully`,
+                    },
+                ],
+                state: 'success',
+            });
+        },
+    };
+}
+
+/**
+ * Tool for retrieving a single task
+ * @returns A Tool object for retrieving a task by ID
+ */
+export function TaskGet() {
+    return {
+        name: 'TaskGet',
+        description: `Use this tool to retrieve a task by its ID from the task list.
+
+## When to Use This Tool
+
+- When you need the full description and context before starting work on a task
+- To understand task dependencies (what it blocks, what blocks it)
+- After being assigned a task, to get complete requirements`,
+        inputSchema: z.object({
+            taskId: z.string().describe('The ID of the task to retrieve'),
+        }),
+        requireUserConfirm: false,
+
+        call({ taskId }: { taskId: string }): ToolResponse {
+            const task = taskStore.get(taskId);
+            if (!task) {
+                throw new Error(`Task not found: ${taskId}`);
+            }
+
+            let text = `Task #${task.id}: ${task.subject}\n`;
+            text += `Status: ${task.status}\n`;
+            text += `Description: ${task.description}\n`;
+
+            if (task.activeForm) {
+                text += `Active Form: ${task.activeForm}\n`;
+            }
+            if (task.owner) {
+                text += `Owner: ${task.owner}\n`;
+            }
+            if (task.blocks.length > 0) {
+                text += `Blocks: ${task.blocks.join(', ')}\n`;
+            }
+            if (task.blockedBy.length > 0) {
+                text += `Blocked By: ${task.blockedBy.join(', ')}\n`;
+            }
+            if (task.metadata && Object.keys(task.metadata).length > 0) {
+                text += `Metadata: ${JSON.stringify(task.metadata, null, 2)}\n`;
+            }
+            text += `Created: ${task.createdAt}\n`;
+            text += `Updated: ${task.updatedAt}`;
+
+            return createToolResponse({
+                content: [
+                    {
+                        id: crypto.randomUUID(),
+                        type: 'text',
+                        text,
+                    },
+                ],
+                state: 'success',
+            });
+        },
+    };
+}
+
+/**
+ * Tool for listing all active tasks
+ * @returns A Tool object for listing all active tasks
+ */
+export function TaskList() {
+    return {
+        name: 'TaskList',
+        description: `Use this tool to list all tasks in the task list.
+
+## When to Use This Tool
+
+- To see what tasks are available to work on (status: 'pending', no owner, not blocked)
+- To check overall progress on the project
+- To find tasks that are blocked and need dependencies resolved
+- After completing a task, to check for newly unblocked work or claim the next available task`,
+        inputSchema: z.object({}),
+        requireUserConfirm: false,
+
+        call(): ToolResponse {
+            // Filter to only pending and in_progress tasks
+            const activeTasks = Array.from(taskStore.values())
+                .filter(task => task.status === 'pending' || task.status === 'in_progress')
+                .sort((a, b) => Number(a.id) - Number(b.id));
+
+            if (activeTasks.length === 0) {
+                return createToolResponse({
+                    content: [
+                        {
+                            id: crypto.randomUUID(),
+                            type: 'text',
+                            text: 'No active tasks found',
+                        },
+                    ],
+                    state: 'success',
+                });
+            }
+
+            const lines = activeTasks.map(task => {
+                let line = `#${task.id} [${task.status}] ${task.subject}`;
+                if (task.blockedBy.length > 0) {
+                    line += ` (blocked by: #${task.blockedBy.join(', #')})`;
+                }
+                return line;
+            });
+
+            return createToolResponse({
+                content: [
+                    {
+                        id: crypto.randomUUID(),
+                        type: 'text',
+                        text: lines.join('\n'),
+                    },
+                ],
+                state: 'success',
+            });
+        },
+    };
+}