digital-tasks 2.0.2 → 2.1.1

package/src/queue.js

@@ -0,0 +1,346 @@
+/**
+ * Task Queue - In-memory task queue implementation
+ *
+ * Provides task queuing, assignment, and execution management.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Priority values for sorting
+ */
+const priorityOrder = {
+    critical: 5,
+    urgent: 4,
+    high: 3,
+    normal: 2,
+    low: 1,
+};
+/**
+ * In-memory task queue implementation
+ */
+class InMemoryTaskQueue {
+    tasks = new Map();
+    options;
+    constructor(options = {}) {
+        this.options = {
+            name: 'default',
+            concurrency: 10,
+            defaultTimeout: 5 * 60 * 1000, // 5 minutes
+            persistent: false,
+            ...options,
+        };
+    }
+    async add(task) {
+        // Add created event
+        const event = {
+            id: `evt_${Date.now()}`,
+            type: 'created',
+            timestamp: new Date(),
+            message: `Task created: ${task.function.name}`,
+        };
+        const taskWithEvent = {
+            ...task,
+            events: [...(task.events || []), event],
+        };
+        this.tasks.set(task.id, taskWithEvent);
+    }
+    async get(id) {
+        return this.tasks.get(id);
+    }
+    async update(id, options) {
+        const task = this.tasks.get(id);
+        if (!task)
+            return undefined;
+        const events = [...(task.events || [])];
+        // Add event if provided
+        if (options.event) {
+            events.push({
+                ...options.event,
+                id: `evt_${Date.now()}`,
+                timestamp: new Date(),
+            });
+        }
+        // Add status change event
+        if (options.status && options.status !== task.status) {
+            events.push({
+                id: `evt_${Date.now()}_status`,
+                type: options.status === 'completed' ? 'completed' :
+                    options.status === 'failed' ? 'failed' :
+                        options.status === 'in_progress' ? 'started' :
+                            options.status === 'blocked' ? 'blocked' : 'progress',
+                timestamp: new Date(),
+                message: `Status changed from ${task.status} to ${options.status}`,
+            });
+        }
+        // Build progress update if provided
+        let progressUpdate = task.progress;
+        if (options.progress) {
+            progressUpdate = {
+                percent: options.progress.percent ?? task.progress?.percent ?? 0,
+                step: options.progress.step ?? task.progress?.step,
+                totalSteps: options.progress.totalSteps ?? task.progress?.totalSteps,
+                currentStep: options.progress.currentStep ?? task.progress?.currentStep,
+                estimatedTimeRemaining: options.progress.estimatedTimeRemaining ?? task.progress?.estimatedTimeRemaining,
+                updatedAt: new Date(),
+            };
+        }
+        const updated = {
+            ...task,
+            ...(options.status && { status: options.status }),
+            ...(options.priority && { priority: options.priority }),
+            ...(options.assignment && { assignment: options.assignment }),
+            ...(progressUpdate && { progress: progressUpdate }),
+            ...(options.metadata && {
+                metadata: { ...task.metadata, ...options.metadata },
+            }),
+            events,
+        };
+        this.tasks.set(id, updated);
+        return updated;
+    }
+    async remove(id) {
+        return this.tasks.delete(id);
+    }
+    async query(options) {
+        let results = Array.from(this.tasks.values());
+        // Filter by status
+        if (options.status) {
+            const statuses = Array.isArray(options.status) ? options.status : [options.status];
+            results = results.filter((t) => statuses.includes(t.status));
+        }
+        // Filter by priority
+        if (options.priority) {
+            const priorities = Array.isArray(options.priority) ? options.priority : [options.priority];
+            results = results.filter((t) => priorities.includes(t.priority));
+        }
+        // Filter by function type
+        if (options.functionType) {
+            results = results.filter((t) => t.function.type === options.functionType);
+        }
+        // Filter by assigned worker
+        if (options.assignedTo) {
+            results = results.filter((t) => t.assignment?.worker.id === options.assignedTo);
+        }
+        // Filter by tags
+        if (options.tags && options.tags.length > 0) {
+            results = results.filter((t) => t.tags && options.tags.some((tag) => t.tags.includes(tag)));
+        }
+        // Filter by project
+        if (options.projectId) {
+            results = results.filter((t) => t.projectId === options.projectId);
+        }
+        // Filter by parent
+        if (options.parentId) {
+            results = results.filter((t) => t.parentId === options.parentId);
+        }
+        // Text search
+        if (options.search) {
+            const search = options.search.toLowerCase();
+            results = results.filter((t) => t.function.name.toLowerCase().includes(search) ||
+                t.function.description?.toLowerCase().includes(search));
+        }
+        // Sort
+        if (options.sortBy) {
+            results.sort((a, b) => {
+                let aVal;
+                let bVal;
+                switch (options.sortBy) {
+                    case 'createdAt':
+                        aVal = a.createdAt.getTime();
+                        bVal = b.createdAt.getTime();
+                        break;
+                    case 'priority':
+                        aVal = priorityOrder[a.priority];
+                        bVal = priorityOrder[b.priority];
+                        break;
+                    case 'deadline':
+                        aVal = a.deadline?.getTime() || Infinity;
+                        bVal = b.deadline?.getTime() || Infinity;
+                        break;
+                    case 'status':
+                        aVal = a.status.charCodeAt(0);
+                        bVal = b.status.charCodeAt(0);
+                        break;
+                    default:
+                        return 0;
+                }
+                return options.sortOrder === 'desc' ? bVal - aVal : aVal - bVal;
+            });
+        }
+        // Pagination
+        const offset = options.offset ?? 0;
+        const limit = options.limit ?? results.length;
+        results = results.slice(offset, offset + limit);
+        return results;
+    }
+    async getNextForWorker(worker) {
+        // Get queued tasks sorted by priority, then by deadline
+        const queuedTasks = await this.query({
+            status: ['pending', 'queued'],
+            sortBy: 'priority',
+            sortOrder: 'desc',
+        });
+        // Find first task the worker can handle
+        for (const task of queuedTasks) {
+            // Check if worker type is allowed
+            if (task.allowedWorkers && !task.allowedWorkers.includes(worker.type) && !task.allowedWorkers.includes('any')) {
+                continue;
+            }
+            // Note: Could check worker skills against task requirements in the future
+            // Check if task is scheduled for later
+            if (task.scheduledFor && task.scheduledFor > new Date()) {
+                continue;
+            }
+            // Check dependencies
+            if (task.dependencies && task.dependencies.length > 0) {
+                const unblockedDeps = task.dependencies.filter((d) => d.type === 'blocked_by' && !d.satisfied);
+                if (unblockedDeps.length > 0) {
+                    continue;
+                }
+            }
+            return task;
+        }
+        return undefined;
+    }
+    async claim(taskId, worker) {
+        const task = await this.get(taskId);
+        if (!task)
+            return false;
+        // Check if already assigned
+        if (task.assignment) {
+            return false;
+        }
+        // Update task with assignment
+        await this.update(taskId, {
+            status: 'assigned',
+            assignment: {
+                worker,
+                assignedAt: new Date(),
+            },
+            event: {
+                type: 'assigned',
+                actor: worker,
+                message: `Assigned to ${worker.name || worker.id}`,
+            },
+        });
+        return true;
+    }
+    async complete(taskId, output) {
+        const task = await this.get(taskId);
+        if (!task)
+            return;
+        await this.update(taskId, {
+            status: 'completed',
+            event: {
+                type: 'completed',
+                actor: task.assignment?.worker,
+                message: 'Task completed successfully',
+                data: { output },
+            },
+        });
+        // Update task output separately since it's not in UpdateTaskOptions
+        const updated = await this.get(taskId);
+        if (updated) {
+            this.tasks.set(taskId, {
+                ...updated,
+                output: {
+                    value: output,
+                    producedAt: new Date(),
+                },
+                completedAt: new Date(),
+            });
+        }
+        // Satisfy dependencies in other tasks
+        for (const [, otherTask] of this.tasks) {
+            if (otherTask.dependencies) {
+                const hasDep = otherTask.dependencies.find((d) => d.taskId === taskId && d.type === 'blocked_by');
+                if (hasDep) {
+                    const updatedDeps = otherTask.dependencies.map((d) => d.taskId === taskId ? { ...d, satisfied: true } : d);
+                    this.tasks.set(otherTask.id, {
+                        ...otherTask,
+                        dependencies: updatedDeps,
+                    });
+                    // Unblock if all dependencies satisfied
+                    const allSatisfied = updatedDeps.filter((d) => d.type === 'blocked_by').every((d) => d.satisfied);
+                    if (allSatisfied && otherTask.status === 'blocked') {
+                        await this.update(otherTask.id, {
+                            status: 'queued',
+                            event: {
+                                type: 'unblocked',
+                                message: 'All dependencies satisfied',
+                            },
+                        });
+                    }
+                }
+            }
+        }
+    }
+    async fail(taskId, error) {
+        const task = await this.get(taskId);
+        if (!task)
+            return;
+        await this.update(taskId, {
+            status: 'failed',
+            event: {
+                type: 'failed',
+                actor: task.assignment?.worker,
+                message: `Task failed: ${error}`,
+                data: { error },
+            },
+        });
+    }
+    async stats() {
+        const tasks = Array.from(this.tasks.values());
+        const byStatus = {
+            pending: 0,
+            queued: 0,
+            assigned: 0,
+            in_progress: 0,
+            blocked: 0,
+            review: 0,
+            completed: 0,
+            failed: 0,
+            cancelled: 0,
+        };
+        const byPriority = {
+            low: 0,
+            normal: 0,
+            high: 0,
+            urgent: 0,
+            critical: 0,
+        };
+        let totalWaitTime = 0;
+        let waitTimeCount = 0;
+        let totalCompletionTime = 0;
+        let completionTimeCount = 0;
+        for (const task of tasks) {
+            byStatus[task.status]++;
+            byPriority[task.priority]++;
+            if (task.startedAt && task.createdAt) {
+                totalWaitTime += task.startedAt.getTime() - task.createdAt.getTime();
+                waitTimeCount++;
+            }
+            if (task.completedAt && task.startedAt) {
+                totalCompletionTime += task.completedAt.getTime() - task.startedAt.getTime();
+                completionTimeCount++;
+            }
+        }
+        return {
+            total: tasks.length,
+            byStatus,
+            byPriority,
+            avgWaitTime: waitTimeCount > 0 ? totalWaitTime / waitTimeCount : undefined,
+            avgCompletionTime: completionTimeCount > 0 ? totalCompletionTime / completionTimeCount : undefined,
+        };
+    }
+}
+/**
+ * Global task queue instance
+ */
+export const taskQueue = new InMemoryTaskQueue();
+/**
+ * Create a new task queue instance
+ */
+export function createTaskQueue(options) {
+    return new InMemoryTaskQueue(options);
+}

package/src/task.js

@@ -0,0 +1,320 @@
+/**
+ * Task - Core task creation and management functions
+ *
+ * @packageDocumentation
+ */
+import { taskQueue } from './queue.js';
+/**
+ * Generate a unique task ID
+ */
+function generateTaskId() {
+    return `task_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+}
+/**
+ * Create a new task from a function definition
+ *
+ * @example
+ * ```ts
+ * const task = await createTask({
+ *   function: {
+ *     type: 'generative',
+ *     name: 'summarize',
+ *     args: { text: 'The text to summarize' },
+ *     output: 'string',
+ *     promptTemplate: 'Summarize: {{text}}',
+ *   },
+ *   input: { text: 'Long article content...' },
+ *   priority: 'high',
+ * })
+ * ```
+ */
+export async function createTask(options) {
+    const now = new Date();
+    // Convert string dependencies to TaskDependency array
+    let dependencies;
+    if (options.dependencies && options.dependencies.length > 0) {
+        dependencies = options.dependencies.map((taskId) => ({
+            type: 'blocked_by',
+            taskId,
+            satisfied: false,
+        }));
+    }
+    // Determine allowed workers from function type
+    let allowedWorkers = options.allowedWorkers;
+    if (!allowedWorkers) {
+        const funcType = options.function.type;
+        if (funcType === 'human') {
+            allowedWorkers = ['human'];
+        }
+        else if (funcType === 'agentic') {
+            allowedWorkers = ['agent'];
+        }
+        else {
+            allowedWorkers = ['any'];
+        }
+    }
+    const task = {
+        id: generateTaskId(),
+        function: options.function,
+        status: options.scheduledFor ? 'pending' : 'queued',
+        priority: options.priority || 'normal',
+        input: options.input,
+        allowedWorkers,
+        dependencies,
+        scheduledFor: options.scheduledFor,
+        deadline: options.deadline,
+        timeout: options.timeout,
+        tags: options.tags,
+        parentId: options.parentId,
+        projectId: options.projectId,
+        metadata: options.metadata,
+        createdAt: now,
+        events: [],
+    };
+    // Auto-assign if specified
+    if (options.assignTo) {
+        task.assignment = {
+            worker: options.assignTo,
+            assignedAt: now,
+        };
+        task.status = 'assigned';
+    }
+    // Check if blocked by dependencies
+    if (dependencies && dependencies.length > 0) {
+        const hasPendingDeps = dependencies.some((d) => d.type === 'blocked_by' && !d.satisfied);
+        if (hasPendingDeps) {
+            task.status = 'blocked';
+        }
+    }
+    // Add to queue
+    await taskQueue.add(task);
+    return task;
+}
+/**
+ * Get a task by ID
+ */
+export async function getTask(id) {
+    return taskQueue.get(id);
+}
+/**
+ * Start working on a task
+ */
+export async function startTask(taskId, worker) {
+    const task = await taskQueue.get(taskId);
+    if (!task)
+        return undefined;
+    // Claim the task if not already assigned
+    if (!task.assignment) {
+        const claimed = await taskQueue.claim(taskId, worker);
+        if (!claimed)
+            return undefined;
+    }
+    // Update status to in_progress
+    return taskQueue.update(taskId, {
+        status: 'in_progress',
+        event: {
+            type: 'started',
+            actor: worker,
+            message: `Started by ${worker.name || worker.id}`,
+        },
+    });
+}
+/**
+ * Update task progress
+ */
+export async function updateProgress(taskId, percent, step) {
+    return taskQueue.update(taskId, {
+        progress: {
+            percent,
+            step,
+            updatedAt: new Date(),
+        },
+        event: {
+            type: 'progress',
+            message: step || `Progress: ${percent}%`,
+            data: { percent, step },
+        },
+    });
+}
+/**
+ * Complete a task with output
+ */
+export async function completeTask(taskId, output) {
+    const task = await taskQueue.get(taskId);
+    if (!task) {
+        return {
+            taskId,
+            success: false,
+            error: {
+                code: 'TASK_NOT_FOUND',
+                message: `Task "${taskId}" not found`,
+            },
+        };
+    }
+    await taskQueue.complete(taskId, output);
+    return {
+        taskId,
+        success: true,
+        output,
+        metadata: {
+            duration: task.startedAt
+                ? Date.now() - task.startedAt.getTime()
+                : 0,
+            startedAt: task.startedAt || new Date(),
+            completedAt: new Date(),
+            worker: task.assignment?.worker,
+        },
+    };
+}
+/**
+ * Fail a task with error
+ */
+export async function failTask(taskId, error) {
+    const task = await taskQueue.get(taskId);
+    if (!task) {
+        return {
+            taskId,
+            success: false,
+            error: {
+                code: 'TASK_NOT_FOUND',
+                message: `Task "${taskId}" not found`,
+            },
+        };
+    }
+    const errorMessage = error instanceof Error ? error.message : error;
+    await taskQueue.fail(taskId, errorMessage);
+    return {
+        taskId,
+        success: false,
+        error: {
+            code: 'TASK_FAILED',
+            message: errorMessage,
+            details: error instanceof Error ? { stack: error.stack } : undefined,
+        },
+        metadata: {
+            duration: task.startedAt
+                ? Date.now() - task.startedAt.getTime()
+                : 0,
+            startedAt: task.startedAt || new Date(),
+            completedAt: new Date(),
+            worker: task.assignment?.worker,
+        },
+    };
+}
+/**
+ * Cancel a task
+ */
+export async function cancelTask(taskId, reason) {
+    const task = await taskQueue.get(taskId);
+    if (!task)
+        return false;
+    await taskQueue.update(taskId, {
+        status: 'cancelled',
+        event: {
+            type: 'cancelled',
+            message: reason || 'Task cancelled',
+        },
+    });
+    return true;
+}
+/**
+ * Add a comment to a task
+ */
+export async function addComment(taskId, comment, author) {
+    return taskQueue.update(taskId, {
+        event: {
+            type: 'comment',
+            actor: author,
+            message: comment,
+        },
+    });
+}
+/**
+ * Create a subtask
+ */
+export async function createSubtask(parentTaskId, options) {
+    return createTask({
+        ...options,
+        parentId: parentTaskId,
+    });
+}
+/**
+ * Get subtasks of a task
+ */
+export async function getSubtasks(parentTaskId) {
+    return taskQueue.query({ parentId: parentTaskId });
+}
+/**
+ * Wait for a task to complete
+ */
+export async function waitForTask(taskId, options) {
+    const timeout = options?.timeout ?? 5 * 60 * 1000; // 5 minutes
+    const pollInterval = options?.pollInterval ?? 1000; // 1 second
+    const startTime = Date.now();
+    while (Date.now() - startTime < timeout) {
+        const task = await taskQueue.get(taskId);
+        if (!task) {
+            return {
+                taskId,
+                success: false,
+                error: {
+                    code: 'TASK_NOT_FOUND',
+                    message: `Task "${taskId}" not found`,
+                },
+            };
+        }
+        if (task.status === 'completed') {
+            return {
+                taskId,
+                success: true,
+                output: task.output,
+                metadata: {
+                    duration: task.completedAt && task.startedAt
+                        ? task.completedAt.getTime() - task.startedAt.getTime()
+                        : 0,
+                    startedAt: task.startedAt || task.createdAt,
+                    completedAt: task.completedAt || new Date(),
+                    worker: task.assignment?.worker,
+                },
+            };
+        }
+        if (task.status === 'failed') {
+            return {
+                taskId,
+                success: false,
+                error: {
+                    code: 'TASK_FAILED',
+                    message: task.error || 'Task failed',
+                },
+                metadata: {
+                    duration: task.completedAt && task.startedAt
+                        ? task.completedAt.getTime() - task.startedAt.getTime()
+                        : 0,
+                    startedAt: task.startedAt || task.createdAt,
+                    completedAt: task.completedAt || new Date(),
+                    worker: task.assignment?.worker,
+                },
+            };
+        }
+        if (task.status === 'cancelled') {
+            return {
+                taskId,
+                success: false,
+                error: {
+                    code: 'TASK_CANCELLED',
+                    message: 'Task was cancelled',
+                },
+            };
+        }
+        // Wait before polling again
+        await new Promise((resolve) => setTimeout(resolve, pollInterval));
+    }
+    return {
+        taskId,
+        success: false,
+        error: {
+            code: 'TIMEOUT',
+            message: `Task did not complete within ${timeout}ms`,
+        },
+    };
+}

package/src/types.js

@@ -0,0 +1,14 @@
+/**
+ * Types for digital-tasks
+ *
+ * Task = Function + metadata (status, progress, assignment, dependencies)
+ *
+ * Every task is a function call. The function can be:
+ * - Code: generates executable code
+ * - Generative: AI generates content (no tools)
+ * - Agentic: AI with tools in a loop
+ * - Human: requires human input
+ *
+ * @packageDocumentation
+ */
+export {};